An open source design system that's fully customizable and agent ready
TypeScript
[feat] doctor: warn when a template source has no doc (#7768)
Joeyacfd1ffe47ef
diff --git a/.changeset/template-source-without-doc.md b/.changeset/template-source-without-doc.mdnew file mode 100644index 0000000000..116db756b4--- /dev/null+++ b/.changeset/template-source-without-doc.md@@ -0,0 +1,6 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx doctor integration validate` and `astryx integration check` now warn `source_without_template_doc` when a `.tsx` directly in an integration's templates root has no same-stem template doc, so `astryx template` would never list it. The warning names the file and the doc to add. Files in subfolders, such as helpers a template imports, and test, spec or story files such as `stray.test.tsx` are not checked; a dotted template id such as `landing.page.tsx` is, and `integration check --strict` fails on the warning.+@josephfarinadiff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 7c5035628d..78e74e7ef9 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -188,6 +188,13 @@ and remains available through explicit Core package selection.MUST publish an additional integration type for that kind, and Core's typeMUST stay unchanged. Without the project's TypeScript it MUST say that thedescriptors were not type-checked and why, and MUST NOT report a pass.+- **INV37 — Every item source has its descriptor.** `astryx doctor integration+ validate` MUST warn on a PascalCase `.tsx` at the top of the components root+ with no same-stem component doc (`source_without_component_doc`), and on a+ `.tsx` at the top of the templates root with no same-stem template doc+ (`source_without_template_doc`). Test, spec and story files (`.test`,+ `.spec` and `.stories` stems) and subfolders are skipped, and a helper+ belongs in a subfolder.- **INV35 — One command checks an integration, and can gate its build.** The`astryx integration check` command, which takes no package argument, MUST runthe `validate`, `components`, `templates`, and `docs` checks against the@@ -789,6 +796,7 @@ the destination.| INV34 | `foundation/discovery/doc-types.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. || INV35 | `api/integration/check/check.test.mjs`, `clients/cli/commands/integration-check.test.mjs`, `test/integration-check-failures.test.mjs`, `api/search/search.integration-check.test.mjs`, `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-match.test.mjs`, `foundation/discovery/doc-types.test.mjs`, `api/integration/authoring-checks.test.mjs` | The default exit differs from a check's own, a warning or a skipped comparison passes `--strict`, text and JSON exit differently, a new failing finding is added without the list changing, a search for ci does not find the command first, a finding is reported on a doc the code does not contradict (for a type, one TypeScript accepts), or a copied passage or a fluff finding passes `--strict`, or a function-word run or shared boilerplate is reported as a copy. || INV36 | `api/gap-report/gap-report.test.mjs`, `clients/cli/commands/gap-report.test.mjs` | A run without `--to` reaches an `issuesUrl` the handlers did not choose, `--to` runs a handler or files on GitHub without `--confirm-public`, an unknown `--to` sends anything, or the destinations list or its line telling the agent to ask the person is missing while a destination exists. |+| INV37 | `api/integration/validate-integration.test.mjs`, `api/integration/validate-integration-fixes.test.mjs`, `api/integration/pack-check.test.mjs` | A top-level source with no doc passes `--strict` (a dotted template id such as `landing.page` included), or a test, spec or story file or a subfolder helper is flagged. |## Open questionsdiff --git a/packages/cli/api/integration/pack-check.test.mjs b/packages/cli/api/integration/pack-check.test.mjsindex 9e116e7272..a6bc5c0cbe 100644--- a/packages/cli/api/integration/pack-check.test.mjs+++ b/packages/cli/api/integration/pack-check.test.mjs@@ -213,6 +213,7 @@ function writePackage({themeExports = false,npmignore,components = false,+ templates = false,scripts,} = {}) {const pkg = {name, version};@@ -272,6 +273,14 @@ export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description:'export default function Card() { return null; }\n',);}+ if (templates) {+ const root = path.join(tmpDir, 'templates');+ fs.mkdirSync(root, {recursive: true});+ fs.writeFileSync(+ path.join(root, 'stray.tsx'),+ 'export default function Stray() { return null; }\n',+ );+ }if (npmignore) {fs.writeFileSync(path.join(tmpDir, '.npmignore'), npmignore);}@@ -1899,6 +1908,23 @@ describe('integrationPackCheck', () => {expect(sourceWarnings[0].message).toContain('Card.tsx');});+ it('reports template sources without metadata as warnings', async () => {+ writePackage({+ manifest:+ "export default {themes: './themes', templates: './templates'};\n",+ files: ['astryx.integration.mjs', 'themes', 'templates'],+ templates: true,+ });+ const result = await integrationPackCheck({cwd: tmpDir});++ const sourceWarnings = result.data.issues.filter(+ issue => issue.code === 'source_without_template_doc',+ );+ expect(sourceWarnings).toHaveLength(1);+ expect(sourceWarnings[0].severity).toBe('warning');+ expect(sourceWarnings[0].message).toContain('stray.tsx');+ });+it('cleans up its scratch consumer when npm pack fails', async () => {writePackage({files: ['astryx.integration.mjs', 'themes'],diff --git a/packages/cli/api/integration/validate-integration-fixes.test.mjs b/packages/cli/api/integration/validate-integration-fixes.test.mjsindex e0b40bfd9e..ce7b15fabd 100644--- a/packages/cli/api/integration/validate-integration-fixes.test.mjs+++ b/packages/cli/api/integration/validate-integration-fixes.test.mjs@@ -37,6 +37,8 @@ const componentDoc = name =>`export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: '${name}.'}, props: []};\n`;/** @param {string} name */const componentSource = name => `export function ${name}() { return null; }\n`;+const templateSource = name =>+ `export default function ${name}() { return null; }\n`;/** @param {string} name */const topic = name =>`export default ${JSON.stringify({@@ -1131,6 +1133,71 @@ describe('source_without_component_doc fixes hold when followed', () => {});});+describe('source_without_template_doc fixes hold when followed', () => {+ it('adds the named doc, which resolves the warning', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/hero.tsx': templateSource('Hero'),+ 'templates/hero.test.tsx': templateSource('HeroTest'),+ });++ const message = only(await issuesOf(dir), 'source_without_template_doc');+ expect(message).toBe(+ "Template source \"hero.tsx\" has no same-stem metadata file hero.doc.mjs, so `astryx template` never lists it. Fix: add hero.doc.mjs beside it with type: 'page' or 'block'; `astryx docs authoring integration-template-doc` lists its fields. If it is not a template, move it out of the templates root.",+ );++ const fixed = follow(dir, {+ write: {+ 'templates/hero.doc.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,+ },+ });+ expect(await issuesOf(fixed)).toEqual([]);+ });++ it('checks a dotted template id, but no test, spec or story file', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/landing.page.tsx': templateSource('LandingPage'),+ 'templates/hero.test.tsx': templateSource('HeroTest'),+ 'templates/hero.spec.tsx': templateSource('HeroSpec'),+ 'templates/hero.stories.tsx': templateSource('HeroStories'),+ });++ const message = only(await issuesOf(dir), 'source_without_template_doc');+ expect(message).toContain(+ 'Template source "landing.page.tsx" has no same-stem metadata file landing.page.doc.mjs',+ );++ const fixed = follow(dir, {+ write: {+ 'templates/landing.page.doc.mjs': `export default {type: 'page', name: 'landing.page', displayName: 'Landing'};\n`,+ },+ });+ expect(await issuesOf(fixed)).toEqual([]);+ });++ it('never flags a helper in a subfolder of the templates root', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/hero.doc.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,+ 'templates/hero.tsx': templateSource('Hero'),+ 'templates/hero/HeroCard.tsx': templateSource('HeroCard'),+ });++ expect(await issuesOf(dir)).toEqual([]);+ });++ it('accepts a released .template.mjs spec as the metadata', async () => {+ const dir = writePackage({+ [MANIFEST]: manifest({templates: './templates'}),+ 'templates/hero.tsx': templateSource('Hero'),+ 'templates/hero.template.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,+ });++ expect(await issuesOf(dir)).toEqual([]);+ });+});+describe('codemod fixes hold when followed', () => {it('moves a stray codemod into a version folder, and renames a mis-named one', async () => {const dir = writePackage({diff --git a/packages/cli/api/integration/validate-integration.test.mjs b/packages/cli/api/integration/validate-integration.test.mjsindex ac7a9f9b79..c5c78bd2f1 100644--- a/packages/cli/api/integration/validate-integration.test.mjs+++ b/packages/cli/api/integration/validate-integration.test.mjs@@ -321,6 +321,36 @@ export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description:);});+ it('warns when a template source has no same-stem metadata, skipping test files', async () => {+ const pkgDir = path.join(tmpDir, 'pkg');+ writePackage(pkgDir, {+ manifest: `export default { templates: './templates' };\n`,+ });+ fs.mkdirSync(path.join(pkgDir, 'templates'));+ fs.writeFileSync(+ path.join(pkgDir, 'templates', 'stray.tsx'),+ 'export default function Stray() { return null; }\n',+ );+ fs.writeFileSync(+ path.join(pkgDir, 'templates', 'stray.test.tsx'),+ "import {it} from 'vitest';\nit('renders', () => {});\n",+ );++ const result = await validateLocalIntegration(pkgDir);++ const warnings = byCode(result.issues, 'source_without_template_doc');+ expect(warnings).toEqual([+ expect.objectContaining({+ severity: 'warning',+ message: expect.stringContaining('"stray.tsx"'),+ }),+ ]);+ expect(warnings[0].message).not.toContain('stray.test.tsx');+ expect(warnings[0].message).toContain(+ "Fix: add stray.doc.mjs beside it with type: 'page' or 'block'",+ );+ });+it('reports codemods outside semver folders and invalid folder names', async () => {const pkgDir = path.join(tmpDir, 'pkg');writePackage(pkgDir, {diff --git a/packages/cli/foundation/integrations/contribution-inventory.mjs b/packages/cli/foundation/integrations/contribution-inventory.mjsindex 3b7e88b5d8..aceffa3d76 100644--- a/packages/cli/foundation/integrations/contribution-inventory.mjs+++ b/packages/cli/foundation/integrations/contribution-inventory.mjs@@ -319,8 +319,11 @@ export async function collectIdentities(loaded) {if (loaded.docs && fs.existsSync(loaded.docs)) {try {- const {records, guides, errors: docErrors} =- await discoverIntegrationDocs(loaded);+ const {+ records,+ guides,+ errors: docErrors,+ } = await discoverIntegrationDocs(loaded);for (const docError of docErrors) {errors.push({kind: 'docs', message: docError.message});}@@ -503,3 +506,48 @@ export function findSourceOnlyCandidates(componentsRoot, registeredNames) {}return candidates.sort();}++/**+ * Metadata suffixes that pair a template source with its spec: the canonical+ * `.doc.*` family and the released `.template.*` compatibility family.+ */+const TEMPLATE_DOC_SUFFIXES = [+ '.doc.ts',+ '.doc.mjs',+ '.doc.js',+ '.template.ts',+ '.template.mjs',+ '.template.js',+];++/** A `.tsx` source and its stem, which may hold a dot (`landing.page`). */+const TSX_SOURCE = /^(.+)\.tsx$/u;++/** A test, spec or story stem: never a template. */+const NOT_A_TEMPLATE = /\.(?:test|spec|stories)$/u;++/**+ * Find `.tsx` files directly in a templates root that have no same-stem+ * template metadata, so template discovery never lists them. Like the+ * component check, it scans only direct children of the root: a file in a+ * subfolder may be a helper a template imports. A file with a dotted stem (a+ * test, story, or similar companion) is never a candidate.+ *+ * @param {string|undefined} templatesRoot absolute path+ * @returns {string[]} basenames of the unpaired sources, sorted+ */+export function findTemplateSourceOnlyCandidates(templatesRoot) {+ if (!templatesRoot || !fs.existsSync(templatesRoot)) return [];+ /** @type {string[]} */+ const candidates = [];+ for (const entry of fs.readdirSync(templatesRoot, {withFileTypes: true})) {+ if (!entry.isFile() && !entry.isSymbolicLink()) continue;+ const match = entry.name.match(TSX_SOURCE);+ if (!match || NOT_A_TEMPLATE.test(match[1])) continue;+ const paired = TEMPLATE_DOC_SUFFIXES.some(suffix =>+ fs.existsSync(path.join(templatesRoot, `${match[1]}${suffix}`)),+ );+ if (!paired) candidates.push(entry.name);+ }+ return candidates.sort();+}diff --git a/packages/cli/foundation/integrations/validate-contributions.mjs b/packages/cli/foundation/integrations/validate-contributions.mjsindex 3c05fa990d..1ec498918c 100644--- a/packages/cli/foundation/integrations/validate-contributions.mjs+++ b/packages/cli/foundation/integrations/validate-contributions.mjs@@ -24,7 +24,10 @@import * as fs from 'node:fs';import * as path from 'node:path';import {isValidSemver} from '../env/semver.mjs';-import {findSourceOnlyCandidates} from './contribution-inventory.mjs';+import {+ findSourceOnlyCandidates,+ findTemplateSourceOnlyCandidates,+} from './contribution-inventory.mjs';import {CODEMOD_FILE_RE,CODEMOD_SKIP_DIRS,@@ -295,6 +298,32 @@ async function checkTemplates(integration, issues) {issueError('invalid_template', /** @type {any} */ (err).message),);}+ checkTemplateSourcesWithoutDoc(integration, issues);+}++/**+ * Warn about a `.tsx` directly in the templates root with no same-stem template+ * metadata: template discovery pairs sources with docs, so `astryx template`+ * never lists it. A PascalCase file directly in a shared components root is+ * left to the component check, which already warns about it.+ * @param {LoadedIntegration} integration loaded-integration-shaped object+ * @param {Issue[]} issues+ */+function checkTemplateSourcesWithoutDoc(integration, issues) {+ const root = /** @type {string} */ (integration.templates);+ const sharedComponents =+ integration.components != null &&+ path.resolve(integration.components) === path.resolve(root);+ for (const file of findTemplateSourceOnlyCandidates(root)) {+ if (sharedComponents && /^[A-Z]/u.test(file)) continue;+ const stem = file.slice(0, -'.tsx'.length);+ issues.push(+ issueWarning(+ 'source_without_template_doc',+ `Template source "${file}" has no same-stem metadata file ${stem}.doc.mjs, so \`astryx template\` never lists it. Fix: add ${stem}.doc.mjs beside it with type: 'page' or 'block'; \`astryx docs authoring integration-template-doc\` lists its fields. If it is not a template, move it out of the templates root.`,+ ),+ );+ }}/**diff --git a/packages/cli/test/integration-check-failures.json b/packages/cli/test/integration-check-failures.jsonindex e6f905a2dc..d92f4bcf40 100644--- a/packages/cli/test/integration-check-failures.json+++ b/packages/cli/test/integration-check-failures.json@@ -54,6 +54,7 @@"root_outside_package","shadowed_component_name","source_without_component_doc",+ "source_without_template_doc","template_id_conflict","type_mismatch","unknown_field",