From bef178f5729b011645ab9b62ca5bd8f47531ffa5 Mon Sep 17 00:00:00 2001 From: Nighthawk42 <6307495+Nighthawk42@users.noreply.github.com> Date: Sun, 23 Aug 2026 12:19:27 -0400 Subject: [PATCH] docs: analyze legacy lines 2001-2500 --- README.md | 2 +- docs/analysis/batch-schedule.md | 2 +- docs/analysis/identifier-ledger.md | 51 ++++++++++++++++- docs/analysis/lines-2001-2500.md | 91 ++++++++++++++++++++++++++++++ tools/verify-bootstrap.ps1 | 3 +- 5 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 docs/analysis/lines-2001-2500.md diff --git a/README.md b/README.md index 41430bd..34c2d9e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This branch is an analysis-only bootstrap for a Mainline-first modernization of The preserved 8,401-line Mainline source must be analyzed sequentially, in evidence-backed batches, before runtime work begins. All behavior-critical shortened symbols must be resolved and all batches must be complete before any public Lua API, runtime module, modern TOC, packaging, or release work is added. -Batches 01–04 (lines 1–2,000) are documented. The remaining batches are scheduled but not analyzed. +Batches 01–05 (lines 1–2,500) are documented. The remaining batches are scheduled but not analyzed. ## Goal diff --git a/docs/analysis/batch-schedule.md b/docs/analysis/batch-schedule.md index 72f9b32..a821d05 100644 --- a/docs/analysis/batch-schedule.md +++ b/docs/analysis/batch-schedule.md @@ -8,7 +8,7 @@ The immutable analysis source is `Legacy/Bejeweled_Mainline.lua` from commit `6f | 02 | 0501–1000 | 500 | `lines-0501-1000.md` | complete | | 03 | 1001–1500 | 500 | `lines-1001-1500.md` | complete | | 04 | 1501–2000 | 500 | `lines-1501-2000.md` | complete | -| 05 | 2001–2500 | 500 | `lines-2001-2500.md` | pending | +| 05 | 2001–2500 | 500 | `lines-2001-2500.md` | complete | | 06 | 2501–3000 | 500 | `lines-2501-3000.md` | pending | | 07 | 3001–3500 | 500 | `lines-3001-3500.md` | pending | | 08 | 3501–4000 | 500 | `lines-3501-4000.md` | pending | diff --git a/docs/analysis/identifier-ledger.md b/docs/analysis/identifier-ledger.md index d056e0e..cb912bd 100644 --- a/docs/analysis/identifier-ledger.md +++ b/docs/analysis/identifier-ledger.md @@ -396,12 +396,57 @@ The completed `M`, flight loader, rotation helper, and pause helper are resolved | `e`,`n`,`o` / `Q` parameters | 1952 | Gem, column, row; coordinates/keys assigned after cleanup (1965–1979). | `gem`, `column`, `row` | resolved | High. | 04–04 | UI/GemPool | None. | | `t` / `Q` local | 1953 | Receives each value's type and gates removal of numeric-valued keys (1954–1958). | `valueType` | resolved | High. | 04–04 | UI/GemPool | None. | | `n`,`o` / `Q` generic loop | 1954 | Shadow parameters inside loop as key/value; removes numeric values (1955–1958). | `key`, `value` | resolved | High. | 04–04 | UI/GemPool | None. | -| `Ke` / chunk function | 1984 | Begins board-wide gem transition; continues after 2000. | `startGameOverGemAnimation` | working | Medium: prefix only. | 04–04 | UI/Animations | Complete in batch 05. | +| `Ke` / chunk function | 1984 | Applies game-over movement/effects and queues every gem (1985–2002). | `startGameOverGemAnimation` | resolved | High: complete body. | 04–05 | UI/Animations | Dispatcher remains ahead. | | `n` / `Ke` duplicate preliminary bindings 1–2 | 1985 | Hidden by animator local at 1986. | — | dead | High. | 04–04 | Unassigned | Minifier artifact. | -| `t` / `Ke` local | 1985 | Receives each gem and mutates animation fields (1989–1999). | `gem` | working | High for prefix. | 04–04 | UI/Animations | Continuation pending. | -| `n` / `Ke` animator local | 1986 | Aliases animator and receives every gem via `Add` (1999). | `animator` | working | High for prefix. | 04–04 | UI/Animations | Continuation pending. | +| `t` / `Ke` local | 1985 | Receives/mutates each gem before queueing (1989–2000). | `gem` | resolved | High. | 04–05 | UI/Animations | None. | +| `n` / `Ke` animator local | 1986 | Receives every grid gem (1999–2002). | `animator` | resolved | High. | 04–05 | UI/Animations | None. | | `i`,`e` / `Ke` grid loops | 1987, 1988 | Iterate grid rows/columns and index gem grid (1989). | `row`, `column` | resolved | High. | 04–04 | Engine/Grid | None. | ## Batch 04 resolution policy Completed event callbacks and helpers are resolved by full local data flow. Legacy positional API fields remain `working` where modern contracts are unverified. Duplicate declarations and proven-unused callback parameters are `dead`; accidental global writes remain explicit `working`/`unresolved` evidence. `Ke` and its transition-state constants stay working across the batch boundary. + +## Batch 05 declarations and scopes + +| Legacy identifier / lexical scope | Decl. | Observed interactions | Proposed name | Status | Confidence/evidence | First–last | Target | Open question | +| --- | ---: | --- | --- | --- | --- | --- | --- | --- | +| `de` / chunk function | 2004 | Randomly assigns color and optionally avoids initial matches (2005–2057). | `assignRandomGem` | resolved | High: complete body. | 05–05 | Engine/Grid | None. | +| `t`,`n`,`f`,`i` / `de` parameters | 2004 | Column, row, avoidance flag, skip-reset flag. | `column`,`row`,`avoidMatches`,`skipReset` | resolved | High. | 05–05 | Engine/Grid | None. | +| `p` / `de` duplicate locals 1–5 | 2005 | Hidden by later bindings or unread. | — | dead | High. | 05–05 | Unassigned | Minifier artifact. | +| `s`,`c`,`d`,`S`,`e` / `de` locals | 2005 | Match count, safe flag, two scan steps, chosen color (2006–2049). | `matchCount`,`safe`,`xStep`,`yStep`,`color` | resolved | High. | 05–05 | Engine/Grid | None. | +| `i`,`l` / `de` loops | 2012, 2014, 2020, 2025 | Attempts, pattern, row offset, column offset. | `attempt/pattern`,`rowOffset`,`columnOffset` | resolved | High. | 05–05 | Engine/Grid | None. | +| `t` / `de` gem local | 2049 | Shadows column after indexing and receives rendered gem. | `gem` | resolved | High. | 05–05 | UI/GemPool | None. | +| `R` / chunk renderer | 2059 | Shadows type alias; renders normal/hyper/empty gem (2060–2075). | `renderGem` | resolved | High. | 05–05 | UI/GemPool | Earlier reset closure retains old alias. | +| `t` / renderer parameter | 2059 | Gem/content receiver. | `gem` | resolved | High. | 05–05 | UI/GemPool | None. | +| `j` / chunk game function | 2077 | Shadows leaderboard merger; initializes/restores game (2078–2245). | `startGame` | resolved | High. | 05–05 | Engine/Grid | Attachment pending. | +| `l`,`s`,`r` / game parameters | 2077 | Mode, duration, resume flag. | `mode`,`duration`,`resume` | resolved | High. | 05–05 | Engine/Grid | None. | +| `d`,`i`,`t` / game locals | 2078–2079 | Player name (after dead duplicate), object temporary, game-state alias. | `playerName`,`object`,`gameState` | resolved | High. | 05–05 | Engine/Grid | None. | +| `t`,`e` / game loops | 2099, 2129–2130, 2184–2192, 2202–2203 | Animation/grid indices. | `index/row/column` | resolved | High. | 05–05 | Engine/Grid, UI/Animations | None. | +| `n`,`l`,`r` / resume locals | 2199–2201 | Saved state, encoded gem, animator. | `savedState`,`encodedGem`,`animator` | resolved | High. | 05–05 | Core/SavedVariables | None. | +| `ee` / chunk function | 2247 | Creates power gem/big star and achievement (2248–2264). | `createPowerGem` | resolved | High. | 05–05 | Engine/Matches | None. | +| `Z` / chunk function | 2266 | Creates hyper gem and achievement (2267–2283). | `createHyperGem` | resolved | High. | 05–05 | Engine/Matches | None. | +| `t`,`i`,`o` / `ee` and `Z` bindings | 2247–2267 | Gem, forced flag, created result in each helper. | `gem`,`forced`,`created` | resolved | High. | 05–05 | Engine/Matches | None. | +| `Le` / chunk function | 2285 | Marks directional clear/explosion and queues animation (2286–2300). | `markGemForClear` | resolved | High. | 05–05 | Engine/Matches | Direction enum pending. | +| `t`,`o` / `Le` parameters | 2285 | Gem and direction; `Ne` selects X. | `gem`,`direction` | resolved | High. | 05–05 | Engine/Matches | None. | +| `Q` / chunk move finder | 2302 | Shadows reset helper; transactional swaps detect legal match (2303–2347). | `findLegalMove` | resolved | High. | 05–05 | Engine/Matches | Returns one candidate gem. | +| `e`,`t`,`p` / move loops | 2304–2306 | Row, column, cardinal direction. | `row`,`column`,`direction` | resolved | High. | 05–05 | Engine/Matches | None. | +| `n`,`i`,`c`,`f`,`d`,`s`,`S`,`l` / move locals | 2303 | Neighbor row/column, swapped gem, validity and four run bounds. | `neighborRow`,`neighborColumn`,`gem`,`valid`,`left`,`right`,`top`,`bottom` | resolved | High. | 05–05 | Engine/Matches | Preliminary duplicate `e` bindings dead. | +| `e` / `TotalTime` local | 2350 | Accumulates duration text. | `text` | resolved | High. | 05–05 | UI/HUD | None. | +| `Se` / chunk function | 2384 | Clears current/next selection and selector UI (2385–2401). | `clearSelection` | resolved | High. | 05–05 | Engine/Grid | None. | +| `t`,`e` / `Se` bindings | 2384–2385 | Next flag and selected gem. | `next`,`gem` | resolved | High. | 05–05 | Engine/Grid | None. | +| `Me` / chunk function | 2403 | Finalizes game and starts board wipe (2404–2456). | `endGame` | resolved | High. | 05–05 | Engine/Scoring | Summary follows later. | +| `o`,`t` / `Me` locals | 2404–2405 | Animator and status text. | `animator`,`statusText` | resolved | High. | 05–05 | UI/HUD | None. | +| `e` / `Me` duplicate/loop bindings | 2423–2429 | Dead duplicate locals; live loops clear saved state. | `column/index` | resolved | High. | 05–05 | Core/SavedVariables | None. | +| `At` / chunk function | 2458 | Creates positioned layered BackdropTemplate frame (2459–2482). | `createImageFrame` | resolved | High. | 05–05 | UI/GemPool | First parameter unused. | +| `a`,`o`,`i`,`n`,`t`,`e`,`l` / `At` parameters | 2458 | Unused, X, Y, width, height, parent, overlay flag. | —,`x`,`y`,`width`,`height`,`parent`,`overlay` | working | High except unused first. | 05–05 | UI/GemPool | Identify first argument. | +| `e` / `At` frame local | 2459 | Shadows parent after initializer; returned frame. | `frame` | resolved | High. | 05–05 | UI/GemPool | None. | +| `tt` / chunk function | 2484 | Begins gem-frame creation; continues after 2500. | `createGemFrame` | working | High for prefix. | 05–05 | UI/GemPool | Complete in batch 06. | +| `n`,`i`,`o`,`t`,`e` / `tt` bindings | 2484–2485 | X, Y, parent, color, created frame. | `x`,`y`,`parent`,`color`,`gem` | working | High for prefix. | 05–05 | UI/GemPool | Continue in batch 06. | +| `t` / `TotalTime` parameter | 2349 | Floored and reduced by day/hour/minute moduli (2351–2375). | `seconds` | resolved | High. | 05–05 | UI/HUD | None. | +| `o`,`n`,`e`,`t` / `Print` parameters | 2380 | Passed directly to chat-frame message plus RGB values (2381). | `message`,`red`,`green`,`blue` | resolved | High. | 05–05 | UI/HUD | None. | +| `t`,`e` / `Me` saved-grid loops | 2424–2425 | Row/column indices clearing saved grid. | `row`,`column` | resolved | High. | 05–05 | Core/SavedVariables | None. | +| `e` / `Me` metadata loop | 2429 | Index clearing saved metadata row. | `index` | resolved | High. | 05–05 | Core/SavedVariables | None. | + +## Batch 05 resolution policy + +Complete helpers are resolved from full bodies. Same-spelling functions are separate entries because earlier closures retain prior bindings. `tt` and dispatcher-dependent constants remain working. diff --git a/docs/analysis/lines-2001-2500.md b/docs/analysis/lines-2001-2500.md new file mode 100644 index 0000000..8b142ef --- /dev/null +++ b/docs/analysis/lines-2001-2500.md @@ -0,0 +1,91 @@ +# Batch 05: lines 2001–2500 + +Source: `Legacy/Bejeweled_Mainline.lua` at Git commit `6faec1c` +Physical coverage: lines 2001–2500 inclusive (500 lines) +Blank lines: 2003, 2058, 2076, 2246, 2265, 2284, 2301, 2348, 2379, 2383, 2402, 2457, and 2483 +Status: complete; `Ke` closes at 2002 and `tt` continues into batch 06 + +## Line-indexed coverage audit + +| Lines | Evidence represented | +| ---: | --- | +| 2001–2002 | Closes `Ke`: every grid gem was added to the animator. | +| 2003 | Blank separator. | +| 2004–2010 | `de(column,row,avoidMatches,skipReset)` chooses random gem type 1–7 and optionally resets/empties target gem. Five duplicate `p` locals are dead. | +| 2011–2048 | When avoiding matches, tries up to seven colors; scans six offset patterns from `r`, counts matching neighbors within bounds, cycles color when count exceeds one, and stops on a safe color. Nested `i` loop bindings intentionally shadow each other. | +| 2049–2057 | Assigns chosen contents and gem/shine textures; normal (non-avoidance) calls increment total matched-gem statistic. | +| 2058 | Blank separator. | +| 2059–2075 | New chunk function `R(gem)` shadows the earlier `type` alias for later declarations. It renders normal colors, creates hyper gem for contents 9, or hides empty/other texture/glow coordinates. Earlier `Q(resetGem)` retains old `R=type`. | +| 2076 | Blank separator. | +| 2077–2098 | New chunk function `j(mode,duration,resume)` shadows leaderboard merger and initializes current-game state/counters, level threshold, mode, splash, and player name. Earlier inbound-sync helper retains old `j`. | +| 2099–2128 | Drains animator stack from index 1, returning known effect types to big-star, explosion, floating-text, shard, lightwave, or lightning pools; clears parent links/visibility and animation flag. | +| 2129–2140 | Resets every 8×8 gem via captured old `Q`, clears hyper marker, and updates optional FuBar/Titan current mode. | +| 2141–2166 | Selects classic/timed stats, initializes maxima/flags/HUD mode/countdown, and handles timed timer stop versus flight-learning immediate state. | +| 2167–2183 | Hides status/summary/about/skill/options controls, configures Return-to-Game button, sets spawn animation state, resets hint, and reseeds RNG from random plus `GetTime`. | +| 2184–2195 | Populates board diagonally/triangularly with `de(...,true)` while temporarily clearing each generated contents, ensuring initial colors avoid matches before spawn. | +| 2196–2218 | Resume branch disables spawning, reads saved grid, restores normal gems, hyper gems, or big-star gems from `<9`, `==9`, or `>9` encodings, renders each via `R`. | +| 2219–2238 | Restores metadata row, validates signed score, decodes it or uses zero, restores timer/multiplier/bar/text, and updates HUD. | +| 2239–2245 | Sets `we` according to restored level and unpauses via `T(false)`; closes new-game helper. | +| 2246 | Blank separator. | +| 2247–2264 | `ee(gem,forced)` creates hidden queued big star for selected/swapped/forced gem unless exploding, increments power-gem total, checks 100-power achievement, and returns truthy creation marker. | +| 2265 | Blank separator. | +| 2266–2283 | `Z(gem,forced)` marks hyper-gem spawn/effect, queues gem, increments hyper total, reports match-5 through `M`, checks 50-hyper achievement, and returns creation marker. | +| 2284 | Blank separator. | +| 2285–2300 | `Le(gem,direction)` marks X when direction equals `Ne`, otherwise Y; big-star gems increment explosions; sets animation effect/frame/highlight and returns explosion count. | +| 2301 | Blank separator. | +| 2302–2347 | New chunk function `Q()` shadows reset helper and searches for any legal move. It tries each gem against four cardinal neighbors, temporarily swaps nonempty neighbor, expands horizontal/vertical equal-color runs, restores swap, and returns the candidate gem when run length reaches three. Contents 9 is automatically considered viable. | +| 2348 | Blank separator. | +| 2349–2378 | `TotalTime(seconds)` formats floored duration into days, hours, minutes, seconds with spaces; zero becomes `0 s`. | +| 2379 | Blank separator. | +| 2380–2382 | `Print` delegates four arguments to `DEFAULT_CHAT_FRAME:AddMessage`. | +| 2383 | Blank separator. | +| 2384–2401 | `Se(next)` clears current or next selected gem, ends non-hyper effect, hides selector, clears mouse coordinates. | +| 2402 | Blank separator. | +| 2403–2419 | `Me` begins game-over: hides/reset hint, marks state, stores last mode, updates optional integrations, and stops timer. | +| 2420–2436 | Classic path shows/plays no-more-moves and zeroes all saved-state cells/metadata; nonclassic shows/plays time-up. | +| 2437–2456 | Increments total games, checks 100/1000-game achievements, shows status, deselects both gems, sets game-over animation, calls `Ke`, plays board-wipe, and closes `Me`. | +| 2457 | Blank separator. | +| 2458–2482 | `At(unused,x,y,width,height,parent,overlay)` creates `BackdropTemplate` frame, texture/highlight layers, stores position, and returns it. Local frame `e` shadows parent parameter after initializer. | +| 2483 | Blank separator. | +| 2484–2500 | `tt(x,y,parent,color)` begins gem-frame creation via animator image, assigns color textures, selector and glow geometry. Function continues in batch 06. | + +## Control/data flow and shapes + +- Board creation deliberately chooses colors that avoid pre-existing three-in-a-row patterns, then uses the spawn animator to reveal them. +- New-game initialization drains pooled animation objects by effect type, resets grid/state/HUD, and optionally restores the nine-row signed SavedVariables snapshot documented in batch 04. +- Lua lexical capture remains critical: renderer `R`, new-game `j`, and move finder `Q` shadow earlier helpers, while previously declared closures retain the old bindings. +- Legal-move detection is transactional: swap, scan both axes, restore, return candidate. Hyper contents 9 short-circuits viability. +- Game over clears classic resumable state, updates lifetime game achievements, deselects input, and starts a board-wide wipe. +- `At` correctly uses `BackdropTemplate`; `tt` constructs layered gem visuals and remains open. + +| Object | Proven shape/invariant | +| --- | --- | +| Gem contents | 1–7 normal colors, 9 hyper, >9 saved big-star encoding, 0 empty. | +| Effect pools | Animator owns queues for big stars, explosions, text, shards, lightwaves, and lightning. | +| Initial grid | 8×8; colors 1–7; avoidance scan uses six patterns from `r`. | +| Legal move | Candidate swap must yield horizontal or vertical span difference ≥2 (three gems). | +| Restored metadata | Saved row 9 maps score, threshold, level, moves, maxima, elapsed, multiplier, signed score. | + +## WoW API contracts + +- `GetTime` contributes to RNG reseeding (2181–2183); deterministic future engine state must not inherit this global randomness without an explicit compatibility decision. +- Frame/texture calls include `SetTexture`, `SetTexCoord`, pooling visibility, alpha, anchoring, and `CreateFrame(...,"BackdropTemplate")`. +- `DEFAULT_CHAT_FRAME:AddMessage` is the legacy print target (2380–2382). +- No `C_Timer`, metadata, animation-group, or compartment API appears. + +## Symbol resolutions and forward dependencies + +- `de` resolves as random gem assignment, new `R` as gem renderer, new `j` as game initializer/restorer, `ee` as power-gem creator, `Z` as hyper-gem creator, `Le` as clear marker, new `Q` as legal-move finder, `Se` as deselector, and `Me` as game-over transition. +- `Ke` resolves as board-wipe starter; effect constants remain tied to dispatcher evidence still ahead. +- Batch 06 must finish `tt`, identify created gem-frame fields, and continue animation/grid ownership. +- `I` is used as the restored authenticated-score field on current game state, but its concrete later purpose still needs assignment evidence. + +## Architecture mapping + +- `Engine/Grid.lua`: generation, reset, restore, legal-move search, selection state. +- `Engine/Matches.lua`: power/hyper creation and directional clear marking. +- `Engine/Scoring.lua`: new-game counters, restored scoring, lifetime achievements, game over. +- `Core/SavedVariables.lua`: signed saved-state validation/decoding. +- `UI/GemPool.lua`: gem rendering and frame construction. +- `UI/Animations.lua`: pool draining, spawn/wipe effects, floating skill/rank messages. +- `UI/HUD.lua`: mode setup, status, timers, summaries, duration/chat presentation. diff --git a/tools/verify-bootstrap.ps1 b/tools/verify-bootstrap.ps1 index da07eb4..132b5d0 100644 --- a/tools/verify-bootstrap.ps1 +++ b/tools/verify-bootstrap.ps1 @@ -133,9 +133,10 @@ Assert-ReportCoverage 'docs/analysis/lines-0001-0500.md' 1 500 Assert-ReportCoverage 'docs/analysis/lines-0501-1000.md' 501 1000 Assert-ReportCoverage 'docs/analysis/lines-1001-1500.md' 1001 1500 Assert-ReportCoverage 'docs/analysis/lines-1501-2000.md' 1501 2000 +Assert-ReportCoverage 'docs/analysis/lines-2001-2500.md' 2001 2500 $lineCount = (Get-Content -LiteralPath 'Legacy/Bejeweled_Mainline.lua').Count Assert-True ($lineCount -eq 8401) "Legacy source has $lineCount lines, expected 8401" Write-Output "Verified: forbidden files absent; legacy and $($assetPaths.Count) asset hashes match $SourceCommit." -Write-Output "Verified: strict UTF-8 text, exact 8,401-line schedule, and complete batch-01/02/03/04 line coverage." +Write-Output "Verified: strict UTF-8 text, exact 8,401-line schedule, and complete batch-01/02/03/04/05 line coverage."