Enforce one generated v19 vocabulary contract - #799
Conversation
📝 WalkthroughWalkthroughChangesV19 vocabulary contract
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related issues
Possibly related PRs
Sequence Diagram(s)sequenceDiagram
participant V19GraphQLSchema
participant Wesley
participant V19CapabilityContract
participant GeneratedArtifacts
participant CI
V19GraphQLSchema->>Wesley: Lower schema to vocabulary IR
Wesley->>V19CapabilityContract: Provide registry metadata
V19CapabilityContract->>GeneratedArtifacts: Generate JSON, TypeScript, and glossary artifacts
CI->>GeneratedArtifacts: Check artifact drift
CI->>V19CapabilityContract: Run twelve acceptance gates
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✨ Finishing Touches📝 Generate docstrings
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Release Preflight
If this PR is from a |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@schemas/v19-public-vocabulary.graphql`:
- Around line 34-36: Rename the custom `@oneOf` directive to a project-scoped name
such as `@allowedValues`, then update the argumentJsonSchema lookup and the action
argument usage in schemas/v19-public-vocabulary.graphql to reference the new
directive while preserving its existing values behavior.
In `@scripts/GenerateV19VocabularyIr.ts`:
- Around line 43-50: Update the execFileSync call in lowerVocabularySchema to
set an explicitly larger maxBuffer and a finite timeout, while preserving its
fixed argument array and UTF-8 output handling.
In `@scripts/V19VocabularyArtifacts.ts`:
- Around line 91-109: Update requireCurrent to include the offending artifact
path in the CapabilityContractError message, distinguishing whether the artifact
is missing or its contents differ when possible. Preserve emitArtifact’s
check-mode behavior and ensure the failure identifies the specific path before
emitV19VocabularyArtifacts stops on the first mismatch.
In `@scripts/V19VocabularyConformance.ts`:
- Around line 95-126: Extract containsPhrase, tokenMatches, and vocabularyTokens
from scripts/V19VocabularyConformance.ts lines 95-126 into a shared matching
module, then import and reuse them in both gates. In
scripts/v19-root-declaration-gate.ts lines 92-118, remove
containsForbiddenPhrase and vocabularyTokenMatches; also remove its
vocabularyTokens helper at lines 197-203 and update callers to use the shared
helpers, preserving the existing tokenizer and plural-tolerant matching
behavior.
In `@scripts/V19VocabularyContract.ts`:
- Around line 183-227: Update the field-processing flow so
`field.directives['capability']` is parsed once and the resulting metadata is
passed to `orderedCli` and `orderedMcp` instead of re-parsing inside each
function. Handle a missing capability directive by raising the established
`CapabilityContractError` with the field name, rather than allowing
`CAPABILITY_SCHEMA.parse(undefined)` to expose a raw `ZodError`.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 6fdacaf8-d950-4c0e-94a2-f8cbac0a37c8
⛔ Files ignored due to path filters (6)
bin/cli/capabilities/V19CapabilityContract.generated.tsis excluded by!**/*.generated.*bin/cli/capabilities/V19McpCapabilities.generated.tsis excluded by!**/*.generated.*bin/cli/capabilities/V19PublicVocabulary.generated.tsis excluded by!**/*.generated.*docs/topics/vocabulary.generated.mdis excluded by!**/*.generated.*schemas/v19-public-vocabulary.wesley.generated.jsonis excluded by!**/*.generated.*test/fixtures/generated-sdk/users.generated.tsis excluded by!**/*.generated.*
📒 Files selected for processing (19)
.github/workflows/ci.ymlbin/cli/capabilities/v19-capabilities.jsonbin/cli/v19/V19DomainInput.tsbin/cli/v19/V19SettlementReview.tsdocs/topics/README.mddocs/topics/api/README.mdpackage.jsonschemas/v19-public-vocabulary.graphqlscripts/GenerateV19CapabilityContract.tsscripts/GenerateV19VocabularyIr.tsscripts/RunV19AcceptanceGates.tsscripts/V19VocabularyArtifacts.tsscripts/V19VocabularyConformance.tsscripts/V19VocabularyContract.tsscripts/generated-sdk/RenderUsersSdkFixture.tsscripts/v19-root-declaration-gate.tstest/unit/cli/v19-input-errors.test.tstest/unit/scripts/v19-root-declaration-gate.test.tstest/unit/scripts/v19-vocabulary-contract.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (6)
- GitHub Check: v19 base/head performance
- GitHub Check: test-node (22)
- GitHub Check: coverage-threshold
- GitHub Check: type-firewall-lint
- GitHub Check: type-firewall-generated-sdk
- GitHub Check: preflight
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx,js,jsx}: Do not use direct imports fromsrc/infrastructure/**insrc/domain/**orsrc/ports/**; depend on a port instead.
Do not use direct Node built-ins insrc/domain/**orsrc/ports/**; use a port instead.
Files:
scripts/generated-sdk/RenderUsersSdkFixture.tstest/unit/scripts/v19-root-declaration-gate.test.tsscripts/GenerateV19VocabularyIr.tsscripts/GenerateV19CapabilityContract.tsscripts/V19VocabularyContract.tstest/unit/cli/v19-input-errors.test.tstest/unit/scripts/v19-vocabulary-contract.test.tsscripts/V19VocabularyConformance.tsscripts/V19VocabularyArtifacts.tsbin/cli/v19/V19DomainInput.tsbin/cli/v19/V19SettlementReview.tsscripts/RunV19AcceptanceGates.tsscripts/v19-root-declaration-gate.ts
🧠 Learnings (1)
📚 Learning: 2026-03-04T12:08:30.347Z
Learnt from: flyingrobots
Repo: git-stunts/git-warp PR: 63
File: package.json:126-126
Timestamp: 2026-03-04T12:08:30.347Z
Learning: Vitest 4 removes vite-node as a dependency and rewrites its pool system. Do not flag the absence of vite-node in package.json or lockfiles as an error for Vitest 4 projects. Use this as a general guideline: if a project uses Vitest 4, missing vite-node is expected and correct; only flag issues if there is evidence the project is not using Vitest 4 or if vite-node is explicitly required by the project.
Applied to files:
package.json
🪛 ast-grep (0.44.1)
scripts/GenerateV19VocabularyIr.ts
[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { execFileSync } from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
scripts/RunV19AcceptanceGates.ts
[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { execFileSync } from 'node:child_process';
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').
(detect-child-process-typescript)
🔇 Additional comments (20)
bin/cli/capabilities/v19-capabilities.json (1)
3-158: LGTM!Also applies to: 198-198, 213-224, 234-249, 259-279, 289-305, 315-322, 332-339, 349-366, 376-383, 393-400, 410-424, 434-445
bin/cli/v19/V19DomainInput.ts (1)
8-10: LGTM!Also applies to: 85-88, 115-115, 126-129, 153-156
bin/cli/v19/V19SettlementReview.ts (1)
10-12: LGTM!Also applies to: 84-87, 102-102
docs/topics/README.md (1)
21-22: LGTM!docs/topics/api/README.md (1)
3-10: LGTM!Also applies to: 727-729
package.json (1)
75-76: LGTM!Also applies to: 103-103
test/unit/scripts/v19-vocabulary-contract.test.ts (1)
1-148: LGTM!test/unit/cli/v19-input-errors.test.ts (1)
12-14: LGTM!Also applies to: 50-60
test/unit/scripts/v19-root-declaration-gate.test.ts (1)
7-9: LGTM!Also applies to: 20-48, 128-134
scripts/RunV19AcceptanceGates.ts (1)
1-138: LGTM!.github/workflows/ci.yml (1)
127-143: LGTM!schemas/v19-public-vocabulary.graphql (2)
47-108: LGTM!Also applies to: 267-305
180-215: 🎯 Functional CorrectnessNo change needed. The root declaration gate only evaluates TypeScript declaration files, and the MCP capability schemas containing
receiptRef/planRefare not part of thedist/index.d.tsdeclaration closure.> Likely an incorrect or invalid review comment.scripts/GenerateV19VocabularyIr.ts (1)
17-41: LGTM!Also applies to: 52-66
scripts/V19VocabularyContract.ts (1)
19-181: LGTM!Also applies to: 229-293
scripts/V19VocabularyArtifacts.ts (1)
22-89: LGTM!Also applies to: 111-148
scripts/V19VocabularyConformance.ts (1)
6-93: LGTM!scripts/v19-root-declaration-gate.ts (1)
14-26: LGTM!Also applies to: 61-69, 80-90
scripts/generated-sdk/RenderUsersSdkFixture.ts (1)
9-11: LGTM!Also applies to: 102-102
scripts/GenerateV19CapabilityContract.ts (1)
10-18: 🗄️ Data Integrity & IntegrationNo change needed. CI runs both
npm run check:vocabulary-irandnpm run check:capabilitiesin the sametype-firewalljob, so artifact consistency is checked against the current IR.
Release Preflight
If this PR is from a |
Release Preflight
If this PR is from a |
1 participant
Closes #791.
Generates CLI, MCP, SDK, docs, public-error, and conformance vocabulary from one GraphQL/Wesley contract. Runs all 12 v19 public-API acceptance gates in CI and removes the stale public storage-composition subpath.
Validation: 129/129 acceptance assertions, exact Wesley/capability/SDK checks, packed-consumer smoke, full lint/typecheck/build, v19 BATS 8/8, and all pre-push shards green.