Skip to content

Commit ff2af67

Browse files
ToolboxAidToolboxAid
committed
Split bundled tool contracts into per-tool contract modules - PR_26152_073-split-tool-contracts-by-tool
1 parent c4f0ef7 commit ff2af67

75 files changed

Lines changed: 1795 additions & 454 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dev/reports/split_tool_contracts_by_tool_validation.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Split Tool Contracts By Tool Validation
2+
3+
PR: PR_26152_073-split-tool-contracts-by-tool
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Corrected PR_26152_072 by replacing the single large tool contract bundle with shared primitives plus one contract module per tool/control.
9+
- Added one matching targeted test per tool contract where appropriate.
10+
- Kept shared validation, access, visibility, exportability, and coverage primitives in shared contract files only.
11+
- No database implementation, authentication implementation, UI/page changes, CSS changes, or HTML changes.
12+
13+
## Files Validated
14+
15+
- `src/shared/contracts/toolContractPrimitives.js`
16+
- `src/shared/contracts/tools/*.js`
17+
- `tests/shared/tools/*.mjs`
18+
- `tests/fixtures/tools/tool-contract-scenarios.json`
19+
- Existing compatibility contract tests:
20+
- `tests/shared/IdentityPermissionsContract.test.mjs`
21+
- `tests/shared/ProjectContract.test.mjs`
22+
- `tests/shared/ToolStateContract.test.mjs`
23+
- `tests/shared/VectorAssetContract.test.mjs`
24+
- `tests/shared/PaletteContract.test.mjs`
25+
- `tests/shared/AssetContract.test.mjs`
26+
27+
## Validation Commands
28+
29+
```powershell
30+
node ./scripts/run-node-test-files.mjs tests/shared/tools/ToolContractCoverage.test.mjs tests/shared/tools/WorldVectorStudioV2ToolContract.test.mjs
31+
```
32+
33+
Result: PASS, 2/2 targeted node test files passed.
34+
35+
```powershell
36+
$toolContractTests = Get-ChildItem -Path tests/shared/tools -Filter '*ToolContract.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName }
37+
node ./scripts/run-node-test-files.mjs $toolContractTests tests/shared/tools/ToolContractCoverage.test.mjs tests/shared/AssetContract.test.mjs tests/shared/PaletteContract.test.mjs tests/shared/VectorAssetContract.test.mjs tests/shared/ToolStateContract.test.mjs tests/shared/ProjectContract.test.mjs tests/shared/IdentityPermissionsContract.test.mjs
38+
```
39+
40+
Result: PASS, 41/41 targeted node test files passed.
41+
42+
```powershell
43+
git diff --check -- src/shared/contracts tests/shared tests/fixtures/tools docs/dev/reports docs/dev/commit_comment.txt
44+
```
45+
46+
Result: PASS, no whitespace or patch errors.
47+
48+
```powershell
49+
rg "toolContractBundle|TOOL_CONTRACT_BUNDLE|ToolContractBundle|tool-contract-bundle" -n src tests
50+
```
51+
52+
Result: PASS, no remaining source/test references.
53+
54+
```powershell
55+
git diff --name-only -- '*.css' '*.html'
56+
```
57+
58+
Result: PASS, no CSS or HTML files changed.
59+
60+
## Contract Coverage Result
61+
62+
- Per-tool contract modules added: 34.
63+
- Per-tool matching tests added: 34.
64+
- Active visible registered first-class tools covered: 23/23.
65+
- Root Tools Index cards reviewed: 18.
66+
- Root Tools Index cards skipped with reason as non-tool surfaces: 2 (`Marketplace`, `Arcade`).
67+
- Shared primitive/access/export/visibility behavior covered by `ToolContractCoverage.test.mjs`.
68+
69+
## Lane Report
70+
71+
- Lanes executed: contract lane for tool contracts and compatibility contract models.
72+
- Lanes skipped: runtime, integration, engine, samples, recovery/UAT because this PR changes only contract modules/tests and does not change runtime, handoff, engine, sample, or UI behavior.
73+
- Samples decision: SKIP because samples are not in scope and no sample JSON/runtime behavior changed.
74+
- Playwright impacted: No. This PR is contract/test structure only and does not change browser UI or runtime behavior.
75+
- Blocker scope: targeted contract lane only.
76+
77+
## Expected PASS/WARN Behavior
78+
79+
- PASS when every per-tool module validates independently, every registered first-class tool has a contract, skipped Tools Index cards are documented, and existing identity/project/tool-state/asset/vector/palette contracts remain compatible.
80+
- WARN only for unrelated historical reports that still describe prior PR_26152_072 artifacts.

‎docs/dev/reports/tool_contract_coverage.md‎

Lines changed: 52 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,78 @@
11
# Tool Contract Coverage
22

3-
PR: PR_26152_072-tool-contract-bundle-tests
3+
PR: PR_26152_073-split-tool-contracts-by-tool
44
Date: 2026-06-02
55

66
## Discovery Sources
77

88
- Root Tools Index page: `tools/index.html`
99
- Root Tools Index card data: `tools/tools-page-accordions.js`
1010
- Active first-class tool registry: `tools/toolRegistry.js`
11-
- Contract bundle: `src/shared/contracts/toolContractBundle.js`
11+
- Shared contract primitives: `src/shared/contracts/toolContractPrimitives.js`
12+
- Per-tool contracts: `src/shared/contracts/tools/*ToolContract.js`
13+
- Contract index: `src/shared/contracts/tools/toolContractsIndex.js`
1214

1315
## Active Registered First-Class Tools
1416

1517
All active visible registered first-class tools discovered through `getVisibleActiveToolRegistry()` have matching contracts.
1618

17-
| Tool ID | Coverage |
18-
|---|---|
19-
| `world-vector-studio-v2` | Contracted |
20-
| `object-vector-studio-v2` | Contracted |
21-
| `tile-map-editor` | Contracted |
22-
| `parallax-editor` | Contracted |
23-
| `sprite-editor` | Contracted |
24-
| `asset-manager-v2` | Contracted |
25-
| `workspace-manager-v2` | Contracted |
26-
| `palette-manager-v2` | Contracted |
27-
| `preview-generator-v2` | Contracted |
28-
| `text2speech-V2` | Contracted |
29-
| `audio-sfx-playground-v2` | Contracted |
30-
| `midi-studio-v2` | Contracted |
31-
| `collision-inspector-v2` | Contracted |
32-
| `storage-inspector-v2` | Contracted |
33-
| `input-mapping-v2` | Contracted |
34-
| `state-inspector` | Contracted |
35-
| `replay-visualizer` | Contracted |
36-
| `performance-profiler` | Contracted |
37-
| `physics-sandbox` | Contracted |
38-
| `asset-pipeline` | Contracted |
39-
| `3d-json-payload` | Contracted |
40-
| `3d-asset-viewer` | Contracted |
41-
| `3d-camera-path-editor` | Contracted |
19+
| Tool ID | Contract Module | Matching Test |
20+
|---|---|---|
21+
| `world-vector-studio-v2` | `src/shared/contracts/tools/worldVectorStudioV2ToolContract.js` | `tests/shared/tools/WorldVectorStudioV2ToolContract.test.mjs` |
22+
| `object-vector-studio-v2` | `src/shared/contracts/tools/objectVectorStudioV2ToolContract.js` | `tests/shared/tools/ObjectVectorStudioV2ToolContract.test.mjs` |
23+
| `tile-map-editor` | `src/shared/contracts/tools/tileMapEditorToolContract.js` | `tests/shared/tools/TileMapEditorToolContract.test.mjs` |
24+
| `parallax-editor` | `src/shared/contracts/tools/parallaxEditorToolContract.js` | `tests/shared/tools/ParallaxEditorToolContract.test.mjs` |
25+
| `sprite-editor` | `src/shared/contracts/tools/spriteEditorToolContract.js` | `tests/shared/tools/SpriteEditorToolContract.test.mjs` |
26+
| `asset-manager-v2` | `src/shared/contracts/tools/assetManagerV2ToolContract.js` | `tests/shared/tools/AssetManagerV2ToolContract.test.mjs` |
27+
| `workspace-manager-v2` | `src/shared/contracts/tools/workspaceManagerV2ToolContract.js` | `tests/shared/tools/WorkspaceManagerV2ToolContract.test.mjs` |
28+
| `palette-manager-v2` | `src/shared/contracts/tools/paletteManagerV2ToolContract.js` | `tests/shared/tools/PaletteManagerV2ToolContract.test.mjs` |
29+
| `preview-generator-v2` | `src/shared/contracts/tools/previewGeneratorV2ToolContract.js` | `tests/shared/tools/PreviewGeneratorV2ToolContract.test.mjs` |
30+
| `text2speech-V2` | `src/shared/contracts/tools/text2speechV2ToolContract.js` | `tests/shared/tools/Text2SpeechV2ToolContract.test.mjs` |
31+
| `audio-sfx-playground-v2` | `src/shared/contracts/tools/audioSfxPlaygroundV2ToolContract.js` | `tests/shared/tools/AudioSfxPlaygroundV2ToolContract.test.mjs` |
32+
| `midi-studio-v2` | `src/shared/contracts/tools/midiStudioV2ToolContract.js` | `tests/shared/tools/MidiStudioV2ToolContract.test.mjs` |
33+
| `collision-inspector-v2` | `src/shared/contracts/tools/collisionInspectorV2ToolContract.js` | `tests/shared/tools/CollisionInspectorV2ToolContract.test.mjs` |
34+
| `storage-inspector-v2` | `src/shared/contracts/tools/storageInspectorV2ToolContract.js` | `tests/shared/tools/StorageInspectorV2ToolContract.test.mjs` |
35+
| `input-mapping-v2` | `src/shared/contracts/tools/inputMappingV2ToolContract.js` | `tests/shared/tools/InputMappingV2ToolContract.test.mjs` |
36+
| `state-inspector` | `src/shared/contracts/tools/stateInspectorToolContract.js` | `tests/shared/tools/StateInspectorToolContract.test.mjs` |
37+
| `replay-visualizer` | `src/shared/contracts/tools/replayVisualizerToolContract.js` | `tests/shared/tools/ReplayVisualizerToolContract.test.mjs` |
38+
| `performance-profiler` | `src/shared/contracts/tools/performanceProfilerToolContract.js` | `tests/shared/tools/PerformanceProfilerToolContract.test.mjs` |
39+
| `physics-sandbox` | `src/shared/contracts/tools/physicsSandboxToolContract.js` | `tests/shared/tools/PhysicsSandboxToolContract.test.mjs` |
40+
| `asset-pipeline` | `src/shared/contracts/tools/assetPipelineToolContract.js` | `tests/shared/tools/AssetPipelineToolContract.test.mjs` |
41+
| `3d-json-payload` | `src/shared/contracts/tools/threeDJsonPayloadToolContract.js` | `tests/shared/tools/ThreeDJsonPayloadToolContract.test.mjs` |
42+
| `3d-asset-viewer` | `src/shared/contracts/tools/threeDAssetViewerToolContract.js` | `tests/shared/tools/ThreeDAssetViewerToolContract.test.mjs` |
43+
| `3d-camera-path-editor` | `src/shared/contracts/tools/threeDCameraPathEditorToolContract.js` | `tests/shared/tools/ThreeDCameraPathEditorToolContract.test.mjs` |
4244

4345
## Root Tools Index Card Coverage
4446

45-
The root Tools Index card data includes public/root cards that are not all active registered first-class tools. The contract bundle covers registered tools directly, maps legacy/root card names to their first-class contract where applicable, and documents non-tool cards.
47+
The root Tools Index card data includes public/root cards that are not all active registered first-class tools. Split contracts cover registered tools directly, map legacy/root card names to their first-class contract where applicable, and document non-tool cards.
4648

47-
| Root Card | Coverage | Contract ID | Notes |
48-
|---|---|---|---|
49-
| Asset Studio | Contracted | `asset-studio` | Root planning/tool card contract. |
50-
| Object Vector Studio | Mapped | `object-vector-studio-v2` | Root card links `object-vector-studio.html`; first-class contract is `object-vector-studio-v2`. |
51-
| World Vector Studio | Mapped | `world-vector-studio-v2` | Root card links `world-vector-studio.html`; first-class contract is `world-vector-studio-v2`. |
52-
| Palette Manager | Mapped | `palette-manager-v2` | Root card links `palette-manager.html`; first-class contract is `palette-manager-v2`. |
53-
| Game Builder | Contracted | `game-builder` | Root planning/tool card contract. |
54-
| Game Design Studio | Contracted | `game-design-studio` | Root planning/tool card contract. |
55-
| Publish Studio | Contracted | `publish-studio` | Root planning/tool card contract. |
56-
| Animation Studio | Contracted | `animation-studio` | Root planning/tool card contract. |
57-
| Particle Studio | Contracted | `particle-studio` | Root planning/tool card contract. |
58-
| MIDI Studio | Mapped | `midi-studio-v2` | Root card links `midi-studio.html`; first-class contract is `midi-studio-v2`. |
59-
| Sound Studio | Contracted | `sound-studio` | Root planning/tool card contract. |
60-
| AI Assistant | Contracted | `ai-assistant` | Root planning/tool card contract. |
61-
| Code Studio | Contracted | `code-studio` | Root planning/tool card contract. |
62-
| Input Studio | Contracted | `input-studio` | Root planning/tool card contract. |
63-
| Marketplace | Skipped | n/a | Targets `marketplace/index.html`, which is a marketplace page rather than a first-class tool contract. |
64-
| Localization Studio | Contracted | `localization-studio` | Root planning/tool card contract. |
65-
| Arcade | Skipped | n/a | Targets `arcade/index.html`, which is a play surface rather than a first-class tool contract. |
66-
| Storage Inspector | Mapped | `storage-inspector-v2` | Root card links `storage-inspector.html`; first-class contract is `storage-inspector-v2`. |
49+
| Root Card | Coverage | Contract ID | Contract Module | Matching Test | Notes |
50+
|---|---|---|---|---|---|
51+
| Asset Studio | Contracted | `asset-studio` | `src/shared/contracts/tools/assetStudioToolContract.js` | `tests/shared/tools/AssetStudioToolContract.test.mjs` | Root planning/tool card contract. |
52+
| Object Vector Studio | Mapped | `object-vector-studio-v2` | `src/shared/contracts/tools/objectVectorStudioV2ToolContract.js` | `tests/shared/tools/ObjectVectorStudioV2ToolContract.test.mjs` | Root card links `object-vector-studio.html`; first-class contract is `object-vector-studio-v2`. |
53+
| World Vector Studio | Mapped | `world-vector-studio-v2` | `src/shared/contracts/tools/worldVectorStudioV2ToolContract.js` | `tests/shared/tools/WorldVectorStudioV2ToolContract.test.mjs` | Root card links `world-vector-studio.html`; first-class contract is `world-vector-studio-v2`. |
54+
| Palette Manager | Mapped | `palette-manager-v2` | `src/shared/contracts/tools/paletteManagerV2ToolContract.js` | `tests/shared/tools/PaletteManagerV2ToolContract.test.mjs` | Root card links `palette-manager.html`; first-class contract is `palette-manager-v2`. |
55+
| Game Builder | Contracted | `game-builder` | `src/shared/contracts/tools/gameBuilderToolContract.js` | `tests/shared/tools/GameBuilderToolContract.test.mjs` | Root planning/tool card contract. |
56+
| Game Design Studio | Contracted | `game-design-studio` | `src/shared/contracts/tools/gameDesignStudioToolContract.js` | `tests/shared/tools/GameDesignStudioToolContract.test.mjs` | Root planning/tool card contract. |
57+
| Publish Studio | Contracted | `publish-studio` | `src/shared/contracts/tools/publishStudioToolContract.js` | `tests/shared/tools/PublishStudioToolContract.test.mjs` | Root planning/tool card contract. |
58+
| Animation Studio | Contracted | `animation-studio` | `src/shared/contracts/tools/animationStudioToolContract.js` | `tests/shared/tools/AnimationStudioToolContract.test.mjs` | Root planning/tool card contract. |
59+
| Particle Studio | Contracted | `particle-studio` | `src/shared/contracts/tools/particleStudioToolContract.js` | `tests/shared/tools/ParticleStudioToolContract.test.mjs` | Root planning/tool card contract. |
60+
| MIDI Studio | Mapped | `midi-studio-v2` | `src/shared/contracts/tools/midiStudioV2ToolContract.js` | `tests/shared/tools/MidiStudioV2ToolContract.test.mjs` | Root card links `midi-studio.html`; first-class contract is `midi-studio-v2`. |
61+
| Sound Studio | Contracted | `sound-studio` | `src/shared/contracts/tools/soundStudioToolContract.js` | `tests/shared/tools/SoundStudioToolContract.test.mjs` | Root planning/tool card contract. |
62+
| AI Assistant | Contracted | `ai-assistant` | `src/shared/contracts/tools/aiAssistantToolContract.js` | `tests/shared/tools/AiAssistantToolContract.test.mjs` | Root planning/tool card contract. |
63+
| Code Studio | Contracted | `code-studio` | `src/shared/contracts/tools/codeStudioToolContract.js` | `tests/shared/tools/CodeStudioToolContract.test.mjs` | Root planning/tool card contract. |
64+
| Input Studio | Contracted | `input-studio` | `src/shared/contracts/tools/inputStudioToolContract.js` | `tests/shared/tools/InputStudioToolContract.test.mjs` | Root planning/tool card contract. |
65+
| Marketplace | Skipped | n/a | n/a | n/a | Targets `marketplace/index.html`, which is a marketplace page rather than a first-class tool contract. |
66+
| Localization Studio | Contracted | `localization-studio` | `src/shared/contracts/tools/localizationStudioToolContract.js` | `tests/shared/tools/LocalizationStudioToolContract.test.mjs` | Root planning/tool card contract. |
67+
| Arcade | Skipped | n/a | n/a | n/a | Targets `arcade/index.html`, which is a play surface rather than a first-class tool contract. |
68+
| Storage Inspector | Mapped | `storage-inspector-v2` | `src/shared/contracts/tools/storageInspectorV2ToolContract.js` | `tests/shared/tools/StorageInspectorV2ToolContract.test.mjs` | Root card links `storage-inspector.html`; first-class contract is `storage-inspector-v2`. |
6769

6870
## Summary
6971

7072
- Active visible registered first-class tools discovered: 23
7173
- Tool contracts defined: 34
74+
- Per-tool contract modules: 34
75+
- Matching per-tool tests: 34
7276
- Registered first-class tools without contract: 0
7377
- Root Tools Index cards reviewed: 18
7478
- Root Tools Index cards skipped as non-tool surfaces: 2

0 commit comments

Comments
 (0)