Validate package spec rules

[mk3008]

Summary

• Update the Concept Spec guide layering to include Package Scope, Test Policy, Review Authority Model, Technology Policy, and their review-plan role.
• Extend ddl-docs check with authority-rules and technology-rules validation for schema, duplicate IDs, known kinds, empty statements, and metadata language policy.
• Wire transfer metadata verification to pass authority and technology rule metadata through both generated docs and direct verify scripts.

Verification

• pnpm --filter @rawsql-ts/ddl-docs-cli test -- check.integration.test.ts
• pnpm --filter @rawsql-ts/ddl-docs-cli build
• pnpm --filter @rawsql-ts/ddl-docs-cli lint
• pnpm verify:transfer-ddl-metadata
• pnpm verify:transfer-docs
• pnpm --filter @rawsql-ts/ddl-docs-cli test
• git diff --check
• pre-commit hook: workspace typecheck, tests, build, and lint

Merge Readiness

• No baseline exception requested.
• Baseline exception requested and linked below.

Tracking issue: not needed; no baseline exception requested.
Scoped checks run: not needed; no baseline exception requested.
Why full baseline is not required: full baseline exception path not used for this PR.

Self Review

Self-review workflow: concept-spec-review and verification checks applied before PR authoring.
Self-review result: no unresolved blockers; package authority and technology rule metadata are now checked by ddl-docs check and transfer verification.

CLI Surface Migration

• No migration packet required for this CLI change.
• CLI/user-facing surface change and migration packet completed.

No-migration rationale: not selected for this PR.
Upgrade note: not selected for this PR.
Deprecation/removal plan or issue: not selected for this PR.
Docs/help/examples updated: not selected for this PR.
Release/changeset wording: not selected for this PR.

Scaffold Contract Proof

• No scaffold contract proof required for this PR.
• Scaffold contract proof completed.

No-proof rationale: not selected for this PR.
Non-edit assertion: not selected for this PR.
Fail-fast input-contract proof: not selected for this PR.
Generated-output viability proof: not selected for this PR.

Summary by CodeRabbit

• New Features

  • CLI check command now accepts --authority-rules and --technology-rules flags for validating authority and technology rule registries.

• Documentation

  • Updated guidance on review-plan specifications to clarify package-level inputs and review authority model governance.

• Tests

  • Added comprehensive integration tests for authority and technology rules validation scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4f17554a-31ec-4b2d-a890-7ef4725be6f7

📥 Commits

Reviewing files that changed from the base of the PR and between dcf02d8 and 0308bec.

📒 Files selected for processing (7)

• docs/guide/concept-spec-overview.md
• package.json
• packages/ddl-docs-cli/src/cli.ts
• packages/ddl-docs-cli/src/commands/check.ts
• packages/ddl-docs-cli/src/types.ts
• packages/ddl-docs-cli/tests/check.integration.test.ts
• scripts/generate-transfer-docs.mjs

---

📝 Walkthrough

Walkthrough

Added authority rules and technology rules validation to the ddl-docs CLI check command. Introduces JSON metadata registries with rule kinds, CLI option parsing for rule file paths, schema and entry validation, integration into the checkDocs flow, and six integration tests covering success and failure paths.

Changes

Authority and Technology Rules Validation

Layer / File(s)	Summary
Authority and Technology Rules Data Types packages/ddl-docs-cli/src/commands/check.ts, packages/ddl-docs-cli/src/types.ts	Defines AuthorityRulesMetadata, TechnologyRulesMetadata, AuthorityRuleEntry, TechnologyRuleEntry interfaces with schemaVersion, optional metadataLanguagePolicy, and per-entry id, kind, statement, reviewRisk, probes fields. Runtime allowlists AUTHORITY_RULE_KINDS and TECHNOLOGY_RULE_KINDS enumerate allowed kinds. Extended CheckDocsOptions and REVIEW_PLAN_ARTIFACT_KINDS to include new artifact kinds.
CLI Option Parsing for Rule Paths packages/ddl-docs-cli/src/cli.ts	Extended parseCheckOptions to recognize --authority-rules and --technology-rules flags, populate authorityRulesPath and technologyRulesPath fields in the options object, and updated check command help text to document these new optional parameters.
Rule Registry Validation Functions packages/ddl-docs-cli/src/commands/check.ts	Implemented readAuthorityRuleRegistry and readTechnologyRuleRegistry loader functions that read JSON files, validate via type guards, emit issues for duplicate rule ids, unknown kinds, and empty statements, and return validated rule id sets. Type guards isAuthorityRulesMetadata and isTechnologyRulesMetadata enforce schema structure, array presence, and per-entry field typing.
checkDocs Integration and Test Coverage packages/ddl-docs-cli/src/commands/check.ts, packages/ddl-docs-cli/tests/check.integration.test.ts	Updated checkDocs to conditionally invoke rule registry loaders when paths are provided. Added six integration tests: authority/technology rules success cases, validation failures (duplicate ids, unknown kinds, empty statements), and schema errors for invalid metadataLanguagePolicy language fields.
Documentation and Script Wiring docs/guide/concept-spec-overview.md, package.json, scripts/generate-transfer-docs.mjs	Expanded review-plan coverage guidance to explicitly include Package Review Authority Model and Package Technology Policy, defining authority ownership distinctions and clarifying that Package Technology Policy is not a Concept Spec. Updated verify:transfer-ddl-metadata script and generate-transfer-docs.mjs to forward --authority-rules and --technology-rules to the ddl-docs check command.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• mk3008/rawsql-ts#819: Both PRs modify the ddl-docs check implementation—PR #819 introduces the core checkDocs/runCheckDocs metadata validation harness, while this PR extends that flow by adding --authority-rules/--technology-rules registry loading and validation.
• mk3008/rawsql-ts#829: Both PRs extend the transfer pipeline to incorporate technology-rule artifacts: this PR adds runtime loading/validation in commands/check.ts, while the referenced PR wires those artifacts into commands/reviewPlan.ts.

Poem

🐰 A rabbit hops through rules with care,
Authority defined, technology fair,
Each kind is checked, no dupes allowed,
Validation echoes—clear and loud!
From CLI flags to checkDocs' flight,
The rules are wired, the tests shine bright! 🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Validate package spec rules' directly summarizes the main change—adding validation for authority-rules and technology-rules in the ddl-docs check command.
Description check	✅ Passed	The PR description includes all required template sections: Summary (3 bullet points), Verification (7 verification steps), Merge Readiness (all checkboxes addressed), Self Review (workflow and result provided), and CLI Surface/Scaffold Contract sections (all marked as not selected).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/package-spec-check-rules

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}