docs(scripts): catalog public-interface validation + name aliases#3469
Merged
Conversation
…and names
Documentation-first cleanup of the type-checking system. No behavior
change. Existing scripts keep working under their existing names.
Adds:
- packages/superdoc/scripts/README.md: one place to learn the system.
Covers the TL;DR command, vocabulary (SuperDoc package vs Document
API), command catalog, per-script gates, consumer-typecheck
infrastructure, document-api scripts, dataflow diagram, and the
CI-vs-local split.
- Six aliased commands in root package.json, following the convention
check:* = non-mutating, generate:* = mutates, report:* = read-only:
check:types -> pnpm run type-check
check:public:superdoc -> pnpm run check:public-contract
check:public:docapi -> pnpm run docapi:check
check:public -> check:public:superdoc && check:public:docapi
generate:docapi -> pnpm run docapi:sync
report:public:superdoc -> pnpm run report:public-contract
- Rewritten Commands section in AGENTS.md (CLAUDE.md symlinks to it)
pointing at pnpm check:public as the canonical pre-merge command
and explaining the naming convention.
The legacy names stay verbatim per the agreed migration plan: add new
names first, switch CI in a later PR, mark old names as legacy after
that. No new behavior, no removed behavior, no new gates.
Verified:
- pnpm run check:types passes (alias of type-check)
- pnpm run report:public:superdoc prints the tier report
- pnpm run check:public:docapi fails with the same stale-generated-
file error as docapi:check (expected, same passthrough)
Review-feedback corrections to the prior docs commit: - "Am I safe to ship a PR?" -> "Are public interfaces safe?" in the scripts README TL;DR. The original framing implied check:public validates full product correctness; it only validates the public type/interface surface. Tests and build are separate concerns. - Add a sentence under the TL;DR clarifying check:public is "the public type/interface preflight" and is not a replacement for test or build. - Fix the generate:docapi wording in both the scripts README and AGENTS.md. Previous text said the command "writes packages/document-api/generated/**; commit the changes." Verified that path is gitignored via the root .gitignore (line "packages/document-api/generated/"), so there is nothing to commit. New wording: "Writes to packages/document-api/generated/ (gitignored). Run before check:public:docapi if it fails on missing files." - Tighten the generate:all wording in the scripts README to distinguish gitignored vs tracked generator targets (e.g. apps/docs/document-api/reference/ stays committed per the .gitignore comment). No alias or behavior change.
Contributor
Agent docs auditAll changed agent-doc files are clean (in-file checks) as of Checked: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation-first cleanup of the type-checking system. No behavior change. Existing scripts keep working under their existing names.
Why this PR
The repo has 8+ scripts that gate the public TypeScript surface, plus parallel Document API gates, plus consumer-typecheck infrastructure. Today, "are public interfaces safe?" doesn't have a single documented answer. Command names (
check:public-contract,docapi:sync,report:public-contract,type-check) grew organically over different tickets and don't follow a consistent verb convention. This PR introduces vocabulary first; later PRs will fold separate CI steps into the umbrella and tighten the gates.Additions
packages/superdoc/scripts/README.md: the canonical reference. Covers the TL;DR command, vocabulary (SuperDoc package vs Document API), command catalog, per-script gates (what each one guards / what would fail if it stopped running), consumer-typecheck infrastructure, document-api scripts, dataflow diagram, and CI-vs-local split.Six aliased commands in root
package.jsonfollowing the conventioncheck:*= non-mutating,generate:*= mutates,report:*= read-only:check:typestype-checkcheck:public:superdoccheck:public-contractcheck:public:docapidocapi:checkcheck:public(umbrella)generate:docapidocapi:syncreport:public:superdocreport:public-contractRewritten Commands section in
AGENTS.md(CLAUDE.md symlinks to it) pointing atpnpm check:publicas the canonical pre-merge command and explaining the naming convention.What's deferred
Per the agreed migration plan ("don't hard-rename everything in one PR"):
release-superdoc.ymlstill duplicates the consumer-typecheck matrix, deep-type audit, package-shape, snapshot, and closure steps. Folding those intocheck:public:superdocis also tracked separately (the README documents this gap explicitly).check:public:docapistill requiresgenerate:docapito run first if generated files are missing. Making the check self-contained (in-memory generate + compare) is deferred.verify-public-facade-emit.cjshand-maintainedexpectedNamesallowlist (426 symbols across 10 facades) is documented but not consolidated.check-jsdoc.cjs's 6-file ratchet is documented as historical; reframing it as a public-reachability ratchet is deferred.Verified
pnpm run check:types→tsc -b tsconfig.references.jsonruns cleanly (alias resolves correctly)pnpm run report:public:superdoc→ prints the tier report (alias ofreport:public-contract)pnpm run check:public:docapi→ fails with the same missing/stale generated-file error asdocapi:check(expected — same passthrough behavior)packages/document-api/generated/is gitignored (root.gitignore), so thegenerate:docapidocs correctly say "gitignored" and don't tell contributors to commit untracked artifacts.