ci(docs): guard skills/docs against bare metadata literals (#2035)#2127
Merged
Conversation
Closes the drift root cause found while updating the docs (#2124): TypeScript code blocks in Markdown/MDX are not type-checked or ESLinted, so skills/ and content/docs/ silently drifted back to teaching the bare `: Page = {}` literal while the example apps — which the ESLint guard polices — stayed clean. Skills are the corpus AI authors from, so a stale sample there is the worst place for it. `scripts/check-doc-authoring.mjs` (dependency-free) scans every ```ts/typescript/ tsx fenced block under skills/ and content/ for an exported metadata literal annotated with one of the 16 factory domains (or its Input alias) instead of the `defineX(...)` factory, and fails with file:line + guidance. Generated files (references/, the frontmatter-generated skills.mdx) are skipped. Wired into lint.yml's ESLint job via `pnpm check:doc-authoring` (no build, no new dep). Verified: 160 files clean on current main (#2124 migration holds); teeth confirmed — flags a bare `: Page` block, ignores `definePage({...})`. CI-only — no package code, no changeset.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
ci/cd
dependencies
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.
Follow-up to #2124 — closes the drift root cause found while updating the docs.
Why
The example apps are kept on the
defineXfactories by an ESLintno-restricted-syntaxrule. But TypeScript code blocks inside Markdown/MDX are not type-checked or ESLinted by anything — which is exactly howskills/andcontent/docs/drifted back to teaching: Page = {}while the examples stayed clean (the 23 stale spots fixed in #2124). Skills are the corpus AI authors from, so a stale sample there is the worst place for it. Without a guard, it drifts again.What
scripts/check-doc-authoring.mjs(dependency-free, ~70 lines) scans every```ts / ```typescript / ```tsxfenced block underskills/andcontent/for an exported metadata literal annotated with one of the 16 factory domains (or itsInputalias) instead of thedefineX(...)factory, and fails withfile:line+ guidance. Generated files (references/, the frontmatter-generatedskills.mdx) are skipped.Wired into lint.yml's ESLint job via
pnpm check:doc-authoring— no build, no new dependency, mirrors the existing standalone-check pattern (check:api-surface,check:skill-docs).Verification
pnpm check:doc-authoring→ 160 files clean on current main (confirms the docs(skills): author the 16 factory domains via defineX, not bare literals (#2035) #2124 migration holds).export const MyPage: Page = {→ exit 1 withfile:line;definePage({...})in the same file → not flagged; clean after removal.The gate family this completes
no-restricted-syntaxexamples/**,packages/apps/**check:doc-authoringskills/**,content/**check:api-surface(names + signatures)@objectstack/specexportsdownstream-smoke.shCI-only — no package code, no changeset.
🤖 Generated with Claude Code