Skip to content

Commit c4f0ef7

Browse files
ToolboxAidToolboxAid
committed
Add bundled first-class tool contract tests for GameFoundryStudio - PR_26152_072-tool-contract-bundle-tests
1 parent 8e81984 commit c4f0ef7

5 files changed

Lines changed: 1914 additions & 0 deletions

File tree

‎docs/dev/reports/tool_contract_bundle_tests_validation.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Tool Contract Bundle Tests Validation
2+
3+
PR: PR_26152_072-tool-contract-bundle-tests
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Added reusable Tool Contract Bundle data under `src/shared/contracts/toolContractBundle.js`.
9+
- Added Tool Contract Bundle fixtures under `tests/fixtures/tools/tool-contract-bundle-scenarios.json`.
10+
- Added targeted contract tests under `tests/shared/ToolContractBundle.test.mjs`.
11+
- Added coverage report under `docs/dev/reports/tool_contract_coverage.md`.
12+
- No database implementation was added.
13+
- No authentication implementation was added.
14+
- No UI/page/tool runtime behavior was changed.
15+
- No CSS or HTML files were changed.
16+
- No dependencies were added.
17+
18+
## Contract Coverage
19+
20+
Targeted tests prove:
21+
22+
- every tool contract requires owner
23+
- every saved tool contract requires project
24+
- every tool contract has valid tool type
25+
- every tool contract has valid import/export formats
26+
- every tool contract declares produced outputs
27+
- every tool contract declares supported asset types when applicable
28+
- saved tool state links back to the tool contract
29+
- visibility rules are enforced
30+
- archived tool outputs are immutable unless policy allows edits
31+
- tool exports remain portable
32+
- every registered Tools Index first-class tool has a matching contract or documented skip
33+
34+
The shared Tool contract defines:
35+
36+
- `toolId`
37+
- `toolType`
38+
- `ownerId`
39+
- `projectId`
40+
- `visibility`
41+
- `requiredInputs`
42+
- `producedOutputs`
43+
- `sourceToolState`
44+
- `supportedAssetTypes`
45+
- `importFormats`
46+
- `exportFormats`
47+
- `status`
48+
- `version`
49+
50+
## Validation Lanes
51+
52+
- lanes executed: contract - Tool Contract Bundle tests plus existing Asset, Palette, Vector Asset, Tool State, Project, and Identity/Permissions contract tests were required by the PR.
53+
- lanes skipped: runtime, integration, engine, recovery/UAT - no runtime, handoff, engine, or recovery behavior changed.
54+
- samples decision: SKIP because samples were explicitly out of scope and no sample contracts or runtime paths changed.
55+
- Playwright impacted: No. This PR changes contract data and targeted Node tests only.
56+
- blocker scope: targeted contract lane only.
57+
58+
## Commands
59+
60+
```powershell
61+
node ./scripts/run-node-test-files.mjs tests/shared/ToolContractBundle.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
62+
```
63+
64+
Result: PASS
65+
66+
```text
67+
PASS tests/shared/ToolContractBundle.test.mjs
68+
PASS tests/shared/AssetContract.test.mjs
69+
PASS tests/shared/PaletteContract.test.mjs
70+
PASS tests/shared/VectorAssetContract.test.mjs
71+
PASS tests/shared/ToolStateContract.test.mjs
72+
PASS tests/shared/ProjectContract.test.mjs
73+
PASS tests/shared/IdentityPermissionsContract.test.mjs
74+
75+
7/7 targeted node test file(s) passed.
76+
```
77+
78+
```powershell
79+
git diff --check -- src/shared/contracts/toolContractBundle.js tests/shared/ToolContractBundle.test.mjs tests/fixtures/tools/tool-contract-bundle-scenarios.json
80+
```
81+
82+
Result: PASS with no output.
83+
84+
```powershell
85+
node --input-type=module - <tool-contract-coverage-readback>
86+
```
87+
88+
Result: PASS
89+
90+
- Active visible registered first-class tools discovered: 23
91+
- Tool contracts defined: 34
92+
- Registered first-class tools without contract: 0
93+
- Root Tools Index cards reviewed: 18
94+
- Root Tools Index cards skipped as non-tool surfaces: 2
95+
96+
## Expected PASS Behavior
97+
98+
- All active visible registered first-class tools have matching contracts.
99+
- Root Tools Index card entries are contracted, mapped, or documented as skipped.
100+
- Valid tool contracts pass without errors.
101+
- Invalid tool contract fixtures return the exact expected contract error codes.
102+
- Saved tool contracts require owner and project.
103+
- Produced outputs are required.
104+
- Import/export formats and supported asset types use approved values.
105+
- Tool state payloads link back to their owning tool contract by `toolType`.
106+
- Private tool contracts deny ungranted viewers and allow granted project viewers.
107+
- Collaborators can edit granted active project tool contracts.
108+
- Viewers cannot edit tool contracts.
109+
- Marketplace tool contracts are visible.
110+
- Archived tool outputs reject edits unless policy explicitly allows archived output edits.
111+
- Portable tool contract exports preserve portable fields and remove owner/project/database identifiers.
112+
113+
## Expected WARN Behavior
114+
115+
- Root Marketplace and Arcade cards are documented as skipped because they target non-tool surfaces.
116+
- Repo-wide, samples, UI, CSS, HTML, database, authentication, and tool runtime validation were intentionally not run because they are outside this PR scope.

‎docs/dev/reports/tool_contract_coverage.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Tool Contract Coverage
2+
3+
PR: PR_26152_072-tool-contract-bundle-tests
4+
Date: 2026-06-02
5+
6+
## Discovery Sources
7+
8+
- Root Tools Index page: `tools/index.html`
9+
- Root Tools Index card data: `tools/tools-page-accordions.js`
10+
- Active first-class tool registry: `tools/toolRegistry.js`
11+
- Contract bundle: `src/shared/contracts/toolContractBundle.js`
12+
13+
## Active Registered First-Class Tools
14+
15+
All active visible registered first-class tools discovered through `getVisibleActiveToolRegistry()` have matching contracts.
16+
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 |
42+
43+
## Root Tools Index Card Coverage
44+
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.
46+
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`. |
67+
68+
## Summary
69+
70+
- Active visible registered first-class tools discovered: 23
71+
- Tool contracts defined: 34
72+
- Registered first-class tools without contract: 0
73+
- Root Tools Index cards reviewed: 18
74+
- Root Tools Index cards skipped as non-tool surfaces: 2

0 commit comments

Comments
 (0)