-
Notifications
You must be signed in to change notification settings - Fork 0
PR_26177_DELTA_054-random-utility #206
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,40 +1,46 @@ | ||
| # PLAN_PR: PR_26177_DELTA_053-random-shared-helpers | ||
| # PLAN_PR: PR_26177_DELTA_054-random-utility | ||
|
|
||
| ## Purpose | ||
|
|
||
| Create shared internal helper logic for random utility operations. | ||
| Add a nondeterministic `Random` utility with the same public convenience API shape as `RandomSeed`. | ||
|
|
||
| ## Owner And Assignment | ||
|
|
||
| - Team: Delta | ||
| - OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_053-random-shared-helpers`. | ||
| - Ownership fit: Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage. | ||
| - OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_054-random-utility`. | ||
| - Stack base: `PR_26177_DELTA_053-random-shared-helpers`. | ||
|
|
||
| ## Scope | ||
|
|
||
| - Add internal/shared helper functions for: | ||
| - `nextInt(randomNext, min, max)` | ||
| - `nextFloat(randomNext, min, max)` | ||
| - `pick(randomNext, array)` | ||
| - `shuffle(randomNext, array)` | ||
| - `chance(randomNext, percent)` | ||
| - `weightedPick(randomNext, weightedItems)` | ||
| - Helper functions must consume a `randomNext` function returning a float `>= 0` and `< 1`. | ||
| - Do not expose these helpers as Creator-facing API. | ||
| - Do not change existing `RandomSeed` behavior. | ||
| - Add `Random` utility. | ||
| - Include: | ||
| - `Random.next()` | ||
| - `Random.nextInt(min, max)` | ||
| - `Random.nextFloat(min, max)` | ||
| - `Random.pick(array)` | ||
| - `Random.shuffle(array)` | ||
| - `Random.chance(percent)` | ||
| - `Random.weightedPick(weightedItems)` | ||
| - `Random.uuid()` | ||
| - Prefer `crypto.getRandomValues()` when available. | ||
| - Use `Math.random()` only as compatibility fallback. | ||
| - No deterministic seed support in `Random`. | ||
| - No browser storage. | ||
| - No UI changes. | ||
| - Add JSDoc. | ||
| - Add targeted unit tests. | ||
|
|
||
| ## Implementation Plan | ||
|
|
||
| 1. Add `src/shared/math/randomHelpers.js`. | ||
| 2. Add `tests/shared/RandomHelpers.test.mjs`. | ||
| 3. Validate helper behavior and input guards with targeted unit tests. | ||
| 4. Preserve current `RandomSeed` implementation and tests unchanged. | ||
| 1. Add `src/shared/math/Random.js`. | ||
| 2. Reuse internal helper functions from `src/shared/math/randomHelpers.js`. | ||
| 3. Add `tests/shared/Random.test.mjs`. | ||
| 4. Validate crypto preference, Math fallback, utility methods, UUID shape, and absence of seed API. | ||
| 5. Produce required PR reports and repo-structured ZIP. | ||
|
|
||
| ## Acceptance Criteria | ||
|
|
||
| - Helpers use only the supplied `randomNext` source. | ||
| - Integer, float, pick, shuffle, chance, and weighted pick operations are covered. | ||
| - Invalid `randomNext`, ranges, arrays, percentages, and weighted item inputs reject predictably. | ||
| - Existing `RandomSeed` behavior remains unchanged. | ||
| - `Random` exposes the required static convenience methods. | ||
| - `Random` does not expose deterministic seed support. | ||
| - `Random` uses `crypto.getRandomValues()` when available. | ||
| - `Math.random()` is used only when crypto random values are unavailable. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
50 changes: 50 additions & 0 deletions
50
docs_build/dev/reports/PR_26177_DELTA_054-random-utility.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # PR_26177_DELTA_054-random-utility | ||
|
|
||
| Date: 2026-06-26 | ||
| Team: Delta | ||
| Scope: Nondeterministic shared Random utility and targeted unit tests | ||
| Status: PASS | ||
|
|
||
| ## Summary | ||
|
|
||
| - Added `Random` as a nondeterministic shared random utility in `src/shared/math/Random.js`. | ||
| - Added static convenience methods matching the public shape requested: `next`, `nextInt`, `nextFloat`, `pick`, `shuffle`, `chance`, `weightedPick`, and `uuid`. | ||
| - Reused internal helper logic from PR_053. | ||
| - Preferred `crypto.getRandomValues()` when available. | ||
| - Used `Math.random()` only as compatibility fallback when crypto random values are unavailable. | ||
| - Did not add deterministic seed support to `Random`. | ||
| - Added targeted unit tests in `tests/shared/Random.test.mjs`. | ||
| - No browser storage, UI, API, database, or existing game logic adoption changes were made. | ||
|
|
||
| ## Branch Validation | ||
|
|
||
| PASS. Branch `PR_26177_DELTA_054-random-utility` was created from `PR_26177_DELTA_053-random-shared-helpers`. | ||
|
|
||
| ## Changed Files | ||
|
|
||
| - `docs_build/dev/PLAN_PR.md` | ||
| - `docs_build/dev/BUILD_PR.md` | ||
| - `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md` | ||
| - `docs_build/dev/ProjectInstructions/team_assignments/ACTIVE_TEAM_REGISTRY.md` | ||
| - `src/shared/math/Random.js` | ||
| - `tests/shared/Random.test.mjs` | ||
| - `docs_build/dev/reports/PR_26177_DELTA_054-random-utility.md` | ||
| - `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_branch-validation.md` | ||
| - `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_requirement-checklist.md` | ||
| - `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_validation-lane.md` | ||
| - `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_manual-validation-notes.md` | ||
| - `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_instruction-compliance-checklist.md` | ||
| - `docs_build/dev/reports/codex_changed_files.txt` | ||
| - `docs_build/dev/reports/codex_review.diff` | ||
|
|
||
| ## Validation | ||
|
|
||
| - PASS: `node ./scripts/run-node-test-files.mjs tests/shared/Random.test.mjs tests/shared/RandomHelpers.test.mjs` | ||
| - PASS: `node --check src/shared/math/Random.js` | ||
| - PASS: `node --check tests/shared/Random.test.mjs` | ||
| - PASS: `git diff --check` | ||
| - SKIP: Playwright was not run because this PR does not change UI or browser runtime flows. | ||
|
|
||
| ## Artifact | ||
|
|
||
| - `tmp/PR_26177_DELTA_054-random-utility_delta.zip` |
15 changes: 15 additions & 0 deletions
15
docs_build/dev/reports/PR_26177_DELTA_054-random-utility_branch-validation.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # PR_26177_DELTA_054-random-utility Branch Validation | ||
|
|
||
| Status: PASS | ||
|
|
||
| ## Start Gates | ||
|
|
||
| - PASS: PR_054 branch was created from `PR_26177_DELTA_053-random-shared-helpers`. | ||
| - PASS: Stack base was clean before branch creation. | ||
| - PASS: Branch name is `PR_26177_DELTA_054-random-utility`. | ||
|
|
||
| ## Scope Confirmation | ||
|
|
||
| - PASS: Work is assigned to Team Delta. | ||
| - PASS: Work is limited to nondeterministic Random utility, targeted tests, PR docs, reports, and ZIP packaging. | ||
| - PASS: No deterministic seed support, UI, browser storage, API, database, or unrelated cleanup changes were made. |
11 changes: 11 additions & 0 deletions
11
...v/reports/PR_26177_DELTA_054-random-utility_instruction-compliance-checklist.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # PR_26177_DELTA_054-random-utility Instruction Compliance Checklist | ||
|
|
||
| | Instruction | Status | Notes | | ||
| |---|---:|---| | ||
| | Continue stacked Random PR sequence | PASS | Branch was created from PR_053. | | ||
| | Keep one PR purpose only | PASS | Scope is nondeterministic Random utility. | | ||
| | Use shared helper logic from PR_053 | PASS | Random delegates convenience methods to `randomHelpers.js`. | | ||
| | Do not add deterministic seed support | PASS | No seed API or seed state was added. | | ||
| | No UI/browser storage/API/database changes | PASS | No such files or behaviors changed. | | ||
| | Produce required reports | PASS | Reports were added under `docs_build/dev/reports/`. | | ||
| | Produce repo-structured ZIP under `tmp/` | PASS | ZIP path is `tmp/PR_26177_DELTA_054-random-utility_delta.zip`. | |
11 changes: 11 additions & 0 deletions
11
..._build/dev/reports/PR_26177_DELTA_054-random-utility_manual-validation-notes.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # PR_26177_DELTA_054-random-utility Manual Validation Notes | ||
|
|
||
| Status: PASS | ||
|
|
||
| Manual review confirmed: | ||
|
|
||
| - `Random` is nondeterministic and does not support seeding. | ||
| - `Random` prefers `crypto.getRandomValues()` and falls back to `Math.random()` only when crypto random values are unavailable. | ||
| - Public methods match the requested convenience API shape. | ||
| - `Random` does not use browser storage and is not wired into UI or existing game logic. | ||
| - Tests mock crypto and Math fallback sources and restore globals after assertions. |
20 changes: 20 additions & 0 deletions
20
docs_build/dev/reports/PR_26177_DELTA_054-random-utility_requirement-checklist.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # PR_26177_DELTA_054-random-utility Requirement Checklist | ||
|
|
||
| | Requirement | Status | Notes | | ||
| |---|---:|---| | ||
| | Add `Random` utility | PASS | Added `src/shared/math/Random.js`. | | ||
| | Include `Random.next()` | PASS | Static method added. | | ||
| | Include `Random.nextInt(min, max)` | PASS | Static method added using shared helper. | | ||
| | Include `Random.nextFloat(min, max)` | PASS | Static method added using shared helper. | | ||
| | Include `Random.pick(array)` | PASS | Static method added using shared helper. | | ||
| | Include `Random.shuffle(array)` | PASS | Static method added using shared helper. | | ||
| | Include `Random.chance(percent)` | PASS | Static method added using shared helper. | | ||
| | Include `Random.weightedPick(weightedItems)` | PASS | Static method added using shared helper. | | ||
| | Include `Random.uuid()` | PASS | Static RFC 4122 v4 UUID method added. | | ||
| | Prefer `crypto.getRandomValues()` when available | PASS | `Random.next()` and `Random.uuid()` use crypto random values when present. | | ||
| | Use `Math.random()` only as compatibility fallback | PASS | Fallback path is used only when crypto random values are unavailable. | | ||
| | No deterministic seed support in `Random` | PASS | No `seed` method or seed state added. | | ||
| | No browser storage | PASS | No storage usage added. | | ||
| | No UI changes | PASS | No UI files changed. | | ||
| | Add JSDoc | PASS | Added class and public method JSDoc. | | ||
| | Add targeted unit tests | PASS | Added `tests/shared/Random.test.mjs`. | |
24 changes: 24 additions & 0 deletions
24
docs_build/dev/reports/PR_26177_DELTA_054-random-utility_validation-lane.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # PR_26177_DELTA_054-random-utility Validation Lane | ||
|
|
||
| Status: PASS | ||
|
|
||
| ## Commands | ||
|
|
||
| ```powershell | ||
| node ./scripts/run-node-test-files.mjs tests/shared/Random.test.mjs tests/shared/RandomHelpers.test.mjs | ||
| node --check src/shared/math/Random.js | ||
| node --check tests/shared/Random.test.mjs | ||
| git diff --check | ||
| ``` | ||
|
|
||
| ## Results | ||
|
|
||
| - PASS: `tests/shared/Random.test.mjs` | ||
| - PASS: `tests/shared/RandomHelpers.test.mjs` | ||
| - PASS: `src/shared/math/Random.js` syntax check | ||
| - PASS: `tests/shared/Random.test.mjs` syntax check | ||
| - PASS: `git diff --check` | ||
|
|
||
| ## Playwright | ||
|
|
||
| SKIP. Playwright was not run because this PR does not change UI or browser runtime flows. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This updated Team Alfa section now assigns
PR_26177_DELTA_054-random-utilityto Alfa even though the table above lists Team Alfa as Available and Team Delta as the active owner for that same PR, and the Team Delta section below still saysnone/Available. Since this file declares the registry must matchTEAM_ASSIGNMENTS.md, readers get contradictory ownership for PR_054; these updated assignment/branch/PR lines should be under Team Delta or Alfa should remain unassigned.Useful? React with 👍 / 👎.