Add PowerShell audit for sample JSON references in sample JS - PR 11.45

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,73 +1,46 @@
 MODEL: GPT-5.3-codex
-REASONING: high
+REASONING: medium
 
 TASK:
-Apply PR 11.44.
+Apply PR 11.45.
 
-Proceed automatically. Do not ask for confirmation.
+Add the PowerShell script:
+scripts/audit-sample-json-js-references.ps1
 
-Use the current repo state and reports from:
-- docs/dev/reports/PR_11_41_sample_json_ownership_audit.md
-- docs/dev/reports/PR_11_43_cleanup_batch_1.md
-- docs/dev/reports/PR_11_43_validation.txt
+Purpose:
+Recursively walk the samples directory looking for JSON files, then validate each JSON file is referenced by JS files in the same owning sample subtree.
 
-Goal:
-Resolve the next smallest safe batch of deferred sample JSON ownership findings.
+Owning sample root:
+samples/<group>/<sample>/
 
-Batch rules:
-- Select 2–4 deferred items only.
-- Select items with obvious ownership and low blast radius.
-- Prefer sample-local JSON/sample-local executable fixes.
-- Preserve sample-to-tool/use-case coverage.
-- Do not touch sample 1902 except to confirm exemption.
-- If an item becomes ambiguous during inspection, defer it and choose another safe item.
+For each:
+samples/<group>/<sample>/**/*.json
 
-Allowed actions:
-- KEEP + WIRE: JSON belongs to this sample and can be visibly used there.
-- MOVE / REHOME: JSON clearly belongs to another sample/tool.
-- DELETE: JSON is stale/obsolete and coverage remains elsewhere.
-- CREATE / UPDATE CORRECT SAMPLE: needed to preserve coverage.
-- DEFER: ownership uncertain.
+Scan:
+samples/<group>/<sample>/**/*.js
+samples/<group>/<sample>/**/*.mjs
+samples/<group>/<sample>/**/*.cjs
 
-Hard rules:
-- Do not blindly force JSON into a mismatched sample.
-- Do not create hidden fallback/default data.
-- Do not create decorative JSON.
-- Do not run full samples smoke by default.
-- Do not undo SVG Asset Studio rename.
-- Do not rename tools.
-- Do not modify start_of_day folders.
-- Do not change shared sample launch infrastructure unless unavoidable.
+Check references by:
+- JSON filename
+- JSON basename
+- JSON path relative to sample root with slash styles
 
-Testing policy:
-Full samples smoke takes about 20 minutes.
-Do NOT run it unless this PR changes shared sample loader/framework or impacts many samples broadly.
+Output:
+docs/dev/reports/sample_json_js_reference_audit.csv
 
-Run targeted validation only:
-- node --check for changed JS files
-- targeted sample/tool smoke for changed samples only
+Do NOT:
+- run full sample smoke
+- modify samples
+- delete JSON
+- change runtime code
 
-If full suite is required, document the reason before running it.
+Validation:
+Run:
+powershell -ExecutionPolicy Bypass -File scripts/audit-sample-json-js-references.ps1
 
-Reports:
-Write:
-docs/dev/reports/PR_11_44_cleanup_batch_2.md
-docs/dev/reports/PR_11_44_validation.txt
+Document:
+docs/dev/reports/PR_11_45_validation.txt
 
-The cleanup report must include:
-- source 11.41 deferred findings used
-- items selected
-- action taken for each
-- files changed
-- coverage preserved statement
-- sample 1902 exemption confirmed
-- deferred items remaining
-
-The validation report must include:
-- exact targeted tests run
-- full samples smoke skipped/run
-- reason for skip/run
-- results
-
-Commit comment:
-Use docs/dev/commit_comment.txt
+Full samples smoke:
+Skip. This is a utility script only.

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Resolve second targeted sample JSON ownership cleanup batch - PR 11.44
+Add PowerShell audit for sample JSON references in sample JS - PR 11.45

docs/dev/reports/PR_11_45_validation_template.txt

@@ -0,0 +1,16 @@
+# PR 11.45 Validation
+
+## Changed Files
+- scripts/audit-sample-json-js-references.ps1
+
+## Targeted Tests Run
+- powershell -ExecutionPolicy Bypass -File scripts/audit-sample-json-js-references.ps1
+
+## Full Samples Smoke
+Skipped.
+
+Reason:
+- Utility script only; no runtime/sample behavior changed.
+
+## Result
+-

docs/dev/reports/sample_json_js_reference_audit.csv

@@ -0,0 +1,99 @@
+"SampleRoot","JsonPath","Referenced","ReferencedBy","Match","Note"
+"samples\metadata\samples.index.metadata.json","samples\metadata\samples.index.metadata.json","False","","",""
+"samples\phase-02\0201","samples\phase-02\0201\sample.0201.3d-camera-path-editor.json","False","","",""
+"samples\phase-02\0202","samples\phase-02\0202\sample.0202.3d-camera-path-editor.json","False","","",""
+"samples\phase-02\0204","samples\phase-02\0204\sample.0204.3d-asset-viewer.json","True","sample.0204.asset-browser.json","sample\.0204\.3d-asset-viewer\.json",""
+"samples\phase-02\0204","samples\phase-02\0204\sample.0204.asset-browser.json","True","main.js","sample\.0204\.asset-browser\.json",""
+"samples\phase-02\0205","samples\phase-02\0205\sample.0205.state-inspector.json","False","","",""
+"samples\phase-02\0207","samples\phase-02\0207\sample.0207.palette.json","False","","",""
+"samples\phase-02\0207","samples\phase-02\0207\sample.0207.sprite-editor.json","True","AnimationSystemScene.js","sample\.0207\.sprite-editor\.json",""
+"samples\phase-02\0208","samples\phase-02\0208\sample.0208.state-inspector.json","False","","",""
+"samples\phase-02\0210","samples\phase-02\0210\sample.0210.physics-sandbox.json","False","","",""
+"samples\phase-02\0213","samples\phase-02\0213\sample.0213.palette.json","False","","",""
+"samples\phase-02\0213","samples\phase-02\0213\sample.0213.sprite-editor.json","True","SpriteRenderLayerScene.js","sample\.0213\.sprite-editor\.json",""
+"samples\phase-02\0214","samples\phase-02\0214\sample.0214.palette.json","False","","",""
+"samples\phase-02\0214","samples\phase-02\0214\sample.0214.sprite-editor.json","True","AnimationSpriteBindingScene.js","sample\.0214\.sprite-editor\.json",""
+"samples\phase-02\0217","samples\phase-02\0217\sample.0217.state-inspector.json","False","","",""
+"samples\phase-02\0219","samples\phase-02\0219\sample.0219.palette.json","False","","",""
+"samples\phase-02\0219","samples\phase-02\0219\sample.0219.sprite-editor.json","True","SpriteAtlasImageRenderingScene.js","sample\.0219\.sprite-editor\.json",""
+"samples\phase-02\0220","samples\phase-02\0220\sample.0220.3d-camera-path-editor.json","False","","",""
+"samples\phase-02\0221","samples\phase-02\0221\sample.0221.3d-json-payload-normalizer.json","False","","",""
+"samples\phase-02\0221","samples\phase-02\0221\sample.0221.palette.json","False","","",""
+"samples\phase-02\0221","samples\phase-02\0221\sample.0221.tile-map-editor.json","True","TilemapSystemScene.js","sample\.0221\.tile-map-editor\.json",""
+"samples\phase-02\0221","samples\phase-02\0221\sample.0221.tile-model-converter.json","False","","",""
+"samples\phase-02\0221","samples\phase-02\0221\sample-0221-tile-map-editor-document.json","True","sample.0221.tile-model-converter.json","sample-0221-tile-map-editor-document\.json",""
+"samples\phase-02\0224","samples\phase-02\0224\sample.0224.palette.json","False","","",""
+"samples\phase-02\0224","samples\phase-02\0224\sample.0224.sprite-editor.json","True","TileCameraSpriteSliceScene.js","sample\.0224\.sprite-editor\.json",""
+"samples\phase-02\0224","samples\phase-02\0224\sample.0224.tile-map-editor.json","True","TileCameraSpriteSliceScene.js","sample\.0224\.tile-map-editor\.json",""
+"samples\phase-02\0224","samples\phase-02\0224\sample-0224-tile-map-editor-document.json","False","","",""
+"samples\phase-02\0226","samples\phase-02\0226\sample.0226.skin-editor.json","True","PrimitiveSkinEditorBreakoutReadinessScene.js","sample\.0226\.skin-editor\.json",""
+"samples\phase-02\0227","samples\phase-02\0227\sample.0227.skin-editor.json","True","PrimitiveSkinEditorPongReadinessScene.js","sample\.0227\.skin-editor\.json",""
+"samples\phase-03\0301","samples\phase-03\0301\sample.0301.palette.json","False","","",""
+"samples\phase-03\0301","samples\phase-03\0301\sample.0301.sprite-editor.json","True","RealSpriteRenderingScene.js","sample\.0301\.sprite-editor\.json",""
+"samples\phase-03\0302","samples\phase-03\0302\sample.0302.palette.json","False","","",""
+"samples\phase-03\0302","samples\phase-03\0302\sample.0302.sprite-editor.json","True","AnimationSystemScene.js","sample\.0302\.sprite-editor\.json",""
+"samples\phase-03\0303","samples\phase-03\0303\sample.0303.physics-sandbox.json","False","","",""
+"samples\phase-03\0305","samples\phase-03\0305\sample.0305.3d-json-payload-normalizer.json","False","","",""
+"samples\phase-03\0305","samples\phase-03\0305\sample.0305.palette.json","False","","",""
+"samples\phase-03\0305","samples\phase-03\0305\sample.0305.tile-map-editor.json","True","TileMetadataScene.js","sample\.0305\.tile-map-editor\.json",""
+"samples\phase-03\0305","samples\phase-03\0305\sample.0305.tile-model-converter.json","False","","",""
+"samples\phase-03\0305","samples\phase-03\0305\sample-0305-tile-map-editor-document.json","True","sample.0305.tile-model-converter.json","sample-0305-tile-map-editor-document\.json",""
+"samples\phase-03\0306","samples\phase-03\0306\sample.0306.parallax-editor.json","False","","",""
+"samples\phase-03\0308","samples\phase-03\0308\sample.0308.palette.json","False","","",""
+"samples\phase-03\0313","samples\phase-03\0313\sample.0313.palette.json","False","","",""
+"samples\phase-05\0510","samples\phase-05\0510\sample.0510.asset-pipeline-tool.json","False","","",""
+"samples\phase-05\0512","samples\phase-05\0512\sample.0512.performance-profiler.json","False","","",""
+"samples\phase-07\0708","samples\phase-07\0708\sample.0708.replay-visualizer.json","False","","",""
+"samples\phase-09\0901","samples\phase-09\0901\sample.0901.palette.json","False","","",""
+"samples\phase-09\0901","samples\phase-09\0901\sample.0901.svg-asset-studio.json","False","","",""
+"samples\phase-09\0901","samples\phase-09\0901\sample.0901.vector-map-editor.json","False","","",""
+"samples\phase-09\0905","samples\phase-09\0905\sample.0905.palette.json","False","","",""
+"samples\phase-09\0905","samples\phase-09\0905\sample.0905.sprite-editor.json","True","PixelPerfectCollisionScene.js","sample\.0905\.sprite-editor\.json",""
+"samples\phase-12\1204","samples\phase-12\1204\sample.1204.palette.json","False","","",""
+"samples\phase-12\1204","samples\phase-12\1204\sample.1204.parallax-editor.json","False","","",""
+"samples\phase-12\1204","samples\phase-12\1204\sample.1204.svg-asset-studio.json","False","","",""
+"samples\phase-12\1204","samples\phase-12\1204\sample.1204.vector-map-editor.json","False","","",""
+"samples\phase-12\1205","samples\phase-12\1205\sample.1205.palette.json","False","","",""
+"samples\phase-12\1205","samples\phase-12\1205\sample.1205.parallax-editor.json","False","","",""
+"samples\phase-12\1205","samples\phase-12\1205\sample.1205.vector-map-editor.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\assets\data\tileset\demo1208-terrain-tileset.sprite-editor.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\data\toolFormattedParallax.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\data\toolFormattedTileMap.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\sample.1208.3d-asset-viewer.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\sample.1208.3d-json-payload-normalizer.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\sample.1208.palette.json","False","","",""
+"samples\phase-12\1208","samples\phase-12\1208\sample.1208.parallax-editor.json","True","index.html","sample\.1208\.parallax-editor\.json",""
+"samples\phase-12\1208","samples\phase-12\1208\sample.1208.svg-asset-studio.json","True","index.html","sample\.1208\.svg-asset-studio\.json",""
+"samples\phase-12\1208","samples\phase-12\1208\sample.1208.tile-map-editor.json","True","index.html","sample\.1208\.tile-map-editor\.json",""
+"samples\phase-12\1209","samples\phase-12\1209\sample.1209.palette.json","False","","",""
+"samples\phase-12\1209","samples\phase-12\1209\sample.1209.tile-map-editor.json","True","index.html","sample\.1209\.tile-map-editor\.json",""
+"samples\phase-12\1209","samples\phase-12\1209\sample.1209.tile-model-converter.json","False","","",""
+"samples\phase-12\1209","samples\phase-12\1209\sample-1209-tile-map-editor-document.json","True","sample.1209.tile-model-converter.json","sample-1209-tile-map-editor-document\.json",""
+"samples\phase-12\1210","samples\phase-12\1210\sample.1210.palette.json","False","","",""
+"samples\phase-12\1210","samples\phase-12\1210\sample.1210.tile-map-editor.json","True","index.html","sample\.1210\.tile-map-editor\.json",""
+"samples\phase-12\1210","samples\phase-12\1210\sample-1210-tile-map-editor-document.json","False","","",""
+"samples\phase-12\1211","samples\phase-12\1211\sample.1211.palette.json","False","","",""
+"samples\phase-12\1211","samples\phase-12\1211\sample.1211.tile-map-editor.json","True","index.html","sample\.1211\.tile-map-editor\.json",""
+"samples\phase-12\1211","samples\phase-12\1211\sample-1211-tile-map-editor-document.json","False","","",""
+"samples\phase-12\1212","samples\phase-12\1212\sample-1212-vector-map-editor.json","True","index.html","sample-1212-vector-map-editor\.json",""
+"samples\phase-12\1213","samples\phase-12\1213\sample-1213-vector-map-editor.json","True","index.html","sample-1213-vector-map-editor\.json",""
+"samples\phase-12\1214","samples\phase-12\1214\sample-1214-vector-map-editor.json","True","index.html","sample-1214-vector-map-editor\.json",""
+"samples\phase-12\1215","samples\phase-12\1215\sample-1215-svg-asset-studio.json","True","index.html","sample-1215-svg-asset-studio\.json",""
+"samples\phase-12\1216","samples\phase-12\1216\sample-1216-svg-asset-studio.json","True","index.html","sample-1216-svg-asset-studio\.json",""
+"samples\phase-12\1217","samples\phase-12\1217\sample-1217-svg-asset-studio.json","True","index.html","sample-1217-svg-asset-studio\.json",""
+"samples\phase-12\1218","samples\phase-12\1218\sample-1218-parallax-editor.json","True","index.html","sample-1218-parallax-editor\.json",""
+"samples\phase-12\1219","samples\phase-12\1219\sample-1219-parallax-editor.json","True","index.html","sample-1219-parallax-editor\.json",""
+"samples\phase-12\1220","samples\phase-12\1220\sample-1220-parallax-editor.json","True","index.html","sample-1220-parallax-editor\.json",""
+"samples\phase-13\1315","samples\phase-13\1315\sample.1315.replay-visualizer.json","False","","",""
+"samples\phase-13\1319","samples\phase-13\1319\sample.1319.performance-profiler.json","False","","",""
+"samples\phase-14\1406","samples\phase-14\1406\sample.1406.replay-visualizer.json","False","","",""
+"samples\phase-14\1407","samples\phase-14\1407\sample.1407.performance-profiler.json","False","","",""
+"samples\phase-14\1413","samples\phase-14\1413\sample.1413.3d-asset-viewer.json","True","sample.1413.asset-browser.json","sample\.1413\.3d-asset-viewer\.json",""
+"samples\phase-14\1413","samples\phase-14\1413\sample.1413.asset-browser.json","True","sample.1413.asset-browser.json","sample\.1413\.asset-browser\.json",""
+"samples\phase-14\1413","samples\phase-14\1413\sample.1413.asset-pipeline-tool.json","True","main.js","sample\.1413\.asset-pipeline-tool\.json",""
+"samples\phase-14\1414","samples\phase-14\1414\sample.1414.palette.json","False","","",""
+"samples\phase-14\1414","samples\phase-14\1414\sample.1414.sprite-editor.json","True","TextureSpritePreprocessPipelineScene.js","sample\.1414\.sprite-editor\.json",""
+"samples\phase-14\1417","samples\phase-14\1417\sample.1417.asset-pipeline-tool.json","False","","",""
+"samples\phase-15\1505","samples\phase-15\1505\sample.1505.asset-browser.json","True","main.js","sample\.1505\.asset-browser\.json",""
+"samples\phase-16\1606","samples\phase-16\1606\sample.1606.physics-sandbox.json","False","","",""
+"samples\phase-19\1902","samples\phase-19\1902\sample.1902.workspace-all-tools.json","True","main.js","sample\.1902\.workspace-all-tools\.json",""

docs/pr/PR_11_45_ADD_SAMPLE_JSON_JS_REFERENCE_AUDIT_SCRIPT.md

@@ -0,0 +1,34 @@
+# PR 11.45 — Add Sample JSON to JS Reference Audit Script
+
+## Purpose
+Add a PowerShell utility that recursively scans sample directories for JSON files and verifies each JSON file is referenced by JavaScript files in the same sample subtree.
+
+## Required Behavior
+For each JSON file under `samples/**`:
+- resolve the owning sample root as `samples/<group>/<sample>/`
+- recursively scan JS files under that sample root
+- check whether the JSON filename, basename, or relative path is referenced
+- write a CSV report to `docs/dev/reports/sample_json_js_reference_audit.csv`
+
+## Usage
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/audit-sample-json-js-references.ps1
+```
+
+Optional failure mode:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/audit-sample-json-js-references.ps1 -FailOnMissing
+```
+
+## Scope
+- Adds script only.
+- No sample cleanup in this PR.
+- No runtime behavior change.
+- No full sample smoke test required.
+
+## Acceptance
+- Script runs from repo root.
+- CSV report is created.
+- Missing references are printed.
+- `-FailOnMissing` exits non-zero when unreferenced JSON exists.