An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): doctor integration validate checks each doc against its published authoring type (#7673)
Joeyc2e0a594e83f
diff --git a/.changeset/doctor-doc-types.md b/.changeset/doctor-doc-types.mdnew file mode 100644index 0000000000..8046862bcd--- /dev/null+++ b/.changeset/doctor-doc-types.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx doctor integration validate` now checks every doc an integration ships under its roots (components, templates, docs topics, themes, and their translations, served or not) against the published authoring type for its kind, with the project's own TypeScript, the way `tsc` would. Each unknown field, missing required field, or value outside its field's type is a warning that names the doc, the line, the field, and a fix; the exit code is unchanged. A doc it cannot fully check, or a themes root that does not load, is listed with the reason; test fixtures under `__tests__` in the components or docs root are counted, not checked. JSON adds `data.docTypes`. Without TypeScript the check prints one `[skip]` line instead of passing silently; with a TypeScript it cannot read types with (one with no JavaScript compiler API, such as TypeScript 7), that line names the installed version. With no doc files, it says there is nothing to check.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex bef4460b96..301bcb360c 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -476,7 +476,7 @@ Every response has a `type` discriminant. The full set is below (generated from| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status. || `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. || `integration.pack-check` | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |-| `integration.validate` | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. |+| `integration.validate` | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked). || `integration.template-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}. || `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings), unchecked, typesNotCompared, and propsNotChecked. || `integration.doc-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`). |diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex b11a7b24b9..51d82e81d7 100644--- a/packages/cli/api/docs/_adapter.mjs+++ b/packages/cli/api/docs/_adapter.mjs@@ -17,8 +17,11 @@* foundation/discovery/docs-discovery, which the catalog comes from.*/+import * as path from 'node:path';import {Project} from '../../foundation/config/project.mjs';import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';+import {checkDocTypes} from '../../foundation/discovery/doc-types.mjs';+import {integrationDocFiles} from '../../foundation/discovery/integration-doc-files.mjs';import {linkReferenceTopic,lowerReferenceTopic,@@ -1331,3 +1334,37 @@ export async function resolveTopicDocs(topic, options = {}) {const node = await lowerTopic(catalog, entry, effectiveLang);return {catalog, node, lang: effectiveLang, entry};}++/**+ * Each doc one integration package ships, checked against the published+ * authoring type for its kind with the project's own TypeScript (spec:AST-039+ * FR13). Without TypeScript the report says nothing was checked.+ * @param {any} integration a loaded integration+ * @param {string} cwd+ * @returns {Promise<import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}>}+ */+export async function integrationDocTypes(integration, cwd) {+ const packageDir = /** @type {{__packageDir?: string}} */ (integration)+ .__packageDir;+ const {files, unread, fixtures} = await integrationDocFiles(integration);+ const checked = await checkDocTypes(files, {+ packageDir: packageDir ?? cwd,+ resolveFrom: [cwd, packageDir],+ });+ // Test fixtures no reader serves don't ship as docs: only counted.+ const report =+ checked.status === 'checked' && fixtures > 0+ ? {...checked, fixtures}+ : checked;+ if (report.status !== 'checked' || unread.length === 0) return report;+ // A root its reader cannot read serves no doc; say so rather than skip it.+ const rel = (/** @type {string} */ file) =>+ path.relative(packageDir ?? cwd, file).split(path.sep).join('/') || '.';+ return {+ ...report,+ unchecked: [+ ...report.unchecked,+ ...unread.map(entry => ({doc: rel(entry.path), reason: entry.reason})),+ ].sort((a, b) => a.doc.localeCompare(b.doc)),+ };+}diff --git a/packages/cli/api/integration/add-contribution.mjs b/packages/cli/api/integration/add-contribution.mjsindex e5c061b2f9..0cc81b445c 100644--- a/packages/cli/api/integration/add-contribution.mjs+++ b/packages/cli/api/integration/add-contribution.mjs@@ -695,7 +695,7 @@ async function addTemplate(name, options) {const sourcePath = projectPath(path.relative(packageDir, sourceFile));const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');const blockFields = templateType === 'block' ? '\n aspectRatio: 1,' : '';- const specContents = `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n type: '${templateType}',\n name: '${name}',\n displayName: '${kebabToTitle(name)}',\n description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;+ const specContents = `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */\nexport default {\n type: '${templateType}',\n name: '${name}',\n displayName: '${kebabToTitle(name)}',\n description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;const sourceContents = `export default function ${pascalName}() {\n return <div>${kebabToTitle(name)}</div>;\n}\n`;/** @type {import('./add-helpers.mjs').WritePlan[]} */diff --git a/packages/cli/api/integration/add-contribution.test.mjs b/packages/cli/api/integration/add-contribution.test.mjsindex 82ce1590dc..a0430ae707 100644--- a/packages/cli/api/integration/add-contribution.test.mjs+++ b/packages/cli/api/integration/add-contribution.test.mjs@@ -536,7 +536,9 @@ describe('integrationAdd template', () => {path.join(tmpDir, 'templates/my-widget.doc.mjs'),'utf-8',);- expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");+ expect(spec).toContain(+ "@astryxdesign/cli/authoring').IntegrationTemplateDoc",+ );expect(spec).toContain("type: 'page'");expect(spec).toContain("name: 'my-widget'");@@ -830,7 +832,7 @@ describe('typed descriptor conformance', () => {for (const [relativePath, type] of [['components/MyWidget.doc.mjs', 'ComponentDoc'],['docs/my-guide.doc.mjs', 'ReferenceDoc'],- ['templates/my-page.doc.mjs', 'TemplateDoc'],+ ['templates/my-page.doc.mjs', 'IntegrationTemplateDoc'],['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],]) {const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');diff --git a/packages/cli/api/integration/validate-integration.mjs b/packages/cli/api/integration/validate-integration.mjsindex 9de89f1d50..6169a1fd26 100644--- a/packages/cli/api/integration/validate-integration.mjs+++ b/packages/cli/api/integration/validate-integration.mjs@@ -34,6 +34,7 @@import * as fs from 'node:fs';import * as path from 'node:path';import {assertWithin} from '../../foundation/fs/path-safety.mjs';+import {integrationDocTypes} from '../docs/_adapter.mjs';import {THEME_SLUG_RE,unreadThemeFolders,@@ -461,6 +462,12 @@ export async function validateIntegration(pkg, options = {}) {const result = pkg? await validateInstalledIntegration(pkg, cwd): await validateLocalIntegration(cwd);+ // Each doc the package ships, against the published authoring type for its+ // kind, read with the project's own compiler. Findings are warnings only.+ const integration = result.found ? result.integration : undefined;+ const docTypes = integration+ ? await integrationDocTypes(integration, cwd)+ : undefined;return {type: 'integration.validate',data: {@@ -472,6 +479,7 @@ export async function validateIntegration(pkg, options = {}) {issues: result.reason === 'no_package_json'? [{code: 'no_package', severity: 'error', message: 'No package.json found. Run this command inside a package directory.'}]: result.issues,+ ...(docTypes ? {docTypes} : {}),},};}diff --git a/packages/cli/api/integration/validate-integration.type.mjs b/packages/cli/api/integration/validate-integration.type.mjsindex 749e61c732..29346e935b 100644--- a/packages/cli/api/integration/validate-integration.type.mjs+++ b/packages/cli/api/integration/validate-integration.type.mjs@@ -38,7 +38,18 @@* "healthy" — the two are otherwise byte-identical.* @typedef {object} ValidateIntegrationResponse* @property {'integration.validate'} type- * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data+ * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], docTypes?: DocTypesReport}} data+ */++/**+ * Each doc the package ships, checked against the published authoring type+ * for its kind. Present when the manifest loads. `status: 'skipped'`+ * means nothing was checked (no TypeScript in the project) and `reason` says+ * why. Every finding is a warning.+ *+ * @typedef {import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}} DocTypesReport+ * `fixtures`: how many test fixture docs (under `__tests__` in the+ * components or docs root, which those readers skip) were not checked*/export {};diff --git a/packages/cli/api/integration/validateIntegration.doc.mjs b/packages/cli/api/integration/validateIntegration.doc.mjsindex 1b6aff5941..ed81df7a52 100644--- a/packages/cli/api/integration/validateIntegration.doc.mjs+++ b/packages/cli/api/integration/validateIntegration.doc.mjs@@ -23,11 +23,25 @@ export const doc = {'declared contribution root exists, and runs the codemod/template/component/' +'docs/theme validators, returning every finding as an AstryxIntegrationIssue. A missing ' +'local manifest is guidance (name null, no issues), not an error, so callers ' +- 'can stay exit-0 in a non-integration directory.',+ 'can stay exit-0 in a non-integration directory. It also checks every doc the ' ++ 'package ships under its roots (component, template, docs topic, theme, and translation, served or not) against ' ++ "the published authoring type for its kind, as `tsc` would, with the project's " ++ 'own `typescript`: an unknown field, a missing required field, or a value outside ' ++ "a field's type is a warning in `docTypes` naming the field and a fix. A test " ++ 'fixture under `__tests__` in the components or docs root is counted, not checked. ' ++ 'Without TypeScript, `docTypes` is `skipped` with a reason.',importPath: '@astryxdesign/cli/api',signature:'validateIntegration(pkg?: string, options?: ValidateIntegrationOptions): Promise<ValidateIntegrationResponse>',- keywords: ['integration', 'validate', 'manifest', 'lint', 'check'],+ keywords: [+ 'integration',+ 'validate',+ 'manifest',+ 'lint',+ 'check',+ 'types',+ 'typecheck',+ ],params: [{name: 'pkg',@@ -46,7 +60,7 @@ export const doc = {{type: 'integration.validate',description:- 'The result envelope: `data.validated`, false when nothing was validated — with no `package.json` at all, `data.issues` carries one `no_package` error-severity issue so the command exits 1; with a `package.json` but no integration manifest, `data.issues` is empty, which means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',+ 'The result envelope: `data.validated`, false when nothing was validated — with no `package.json` at all, `data.issues` carries one `no_package` error-severity issue so the command exits 1; with a `package.json` but no integration manifest, `data.issues` is empty, which means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}. When the manifest loads, `data.docTypes` holds the doc type check: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `docs` (doc values checked), `findings` ({doc, line, export, type, field, problem: `unknown_field` | `missing_field` | `wrong_type`, severity: `warning`, message, fix}), `unchecked` ({doc, reason}: a doc that could not be fully checked, or a root its reader cannot read), and `fixtures` when the components or docs root holds test fixture docs under `__tests__`: how many, none of them checked.',},],examples: [diff --git a/packages/cli/assets/docs/tree/block-template.doc.mjs b/packages/cli/assets/docs/tree/block-template.doc.mjsindex 330f07db84..a8d660f89c 100644--- a/packages/cli/assets/docs/tree/block-template.doc.mjs+++ b/packages/cli/assets/docs/tree/block-template.doc.mjs@@ -31,7 +31,7 @@ export const docs = {type: 'code',lang: 'javascript',label: 'templates/acme-stat-card.doc.mjs',- code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+ code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */export default {type: 'block',name: 'acme-stat-card',@@ -75,7 +75,7 @@ export default {type: 'code',lang: 'javascript',label: 'templates/acme-status-card-showcase.doc.mjs',- code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+ code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */export default {type: 'block',name: 'acme-status-card-showcase',diff --git a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs b/packages/cli/assets/docs/tree/check-your-docs.doc.mjsindex 3737f4cffa..9ecb21fd30 100644--- a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs+++ b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs@@ -2,8 +2,8 @@/*** @file `astryx docs cli/integrations/docs/check-your-docs`: what each check- * proves about an integration's docs: the docs check, the read size, and the- * CLI peer.+ * proves about an integration's docs: the docs check, each doc's fields, the+ * read size, and the CLI peer.*//** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */@@ -13,7 +13,8 @@ export const docs = {placement: {parent: 'namespace:docs', slot: 'guides', order: 60},title: 'Check your docs',category: 'guide',- description: 'Check the docs tree, links, overlaps, read size, and CLI peer.',+ description:+ 'Check the docs tree, links, overlaps, doc fields, read size, and CLI peer.',sections: [{id: 'run-the-docs-check',@@ -80,6 +81,46 @@ export const docs = {},],},+ {+ id: 'check-each-doc-against-its-type',+ title: 'Check each doc against its type',+ content: [+ {+ type: 'prose',+ text: "`doctor integration validate` reads every doc your package ships against the type `@astryxdesign/cli/authoring` publishes for its kind, the way `tsc` would: a `hidden` doc and a second doc for one name too. Test fixtures under `__tests__` in the components or docs root, which those readers skip, are counted, not checked. It reports a field the type does not have (`unknown_field`), a missing required field (`missing_field`), and a value outside the field's type (`wrong_type`).",+ },+ {+ type: 'code',+ lang: 'bash',+ code: 'npx astryx doctor integration validate',+ },+ {+ type: 'code',+ lang: 'text',+ code: `Checking 1 doc(s) against the authoring types (TypeScript 6.0.3)++severity: [warn]+doc: components/AcmeCarousel.doc.mjs+line: 7+export: default+type: ComponentDoc+field: summary+problem: unknown_field+message: Object literal may only specify known properties, and 'summary' does not exist in type 'SingleComponentDoc'.+fix: Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ "The folder decides the type: `ComponentDoc` in your components root, `IntegrationTemplateDoc` in your templates root, `ThemeDoc` in your themes root, and in your docs root the type the doc's `type` names. Keep the `@type` comment above each doc's export too, so your editor shows the same problems as you type.",+ 'Every finding is a warning, so the exit code stays 0. With `--json`, they are in `data.docTypes.findings`.',+ 'It uses the `typescript` your package installs. Without it, it prints `[skip] Docs not type-checked` and the reason.',+ 'Every field of every doc type is in `astryx docs authoring`.',+ ],+ },+ ],+ },{id: 'check-read-size',title: 'Check read size',diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjsindex caf053b5f7..0d6beba586 100644--- a/packages/cli/assets/docs/tree/checks.doc.mjs+++ b/packages/cli/assets/docs/tree/checks.doc.mjs@@ -30,9 +30,9 @@ export const docs = {rows: [['`npx astryx doctor integration validate`',- 'The manifest loads, and each root holds contributions the CLI can read',+ 'The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type','A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',- 'The manifest has a key this CLI does not know (`unknown_manifest_key`). With no `astryx.integration.mjs` it prints a hint and exits 0',+ "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It checks docs with your installed `typescript`; without it, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",],['`npx astryx doctor integration components`',diff --git a/packages/cli/assets/docs/tree/page-template.doc.mjs b/packages/cli/assets/docs/tree/page-template.doc.mjsindex 9bc5055519..aaf14a2676 100644--- a/packages/cli/assets/docs/tree/page-template.doc.mjs+++ b/packages/cli/assets/docs/tree/page-template.doc.mjs@@ -31,7 +31,7 @@ export const docs = {type: 'code',lang: 'javascript',label: 'templates/acme-dashboard.doc.mjs',- code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+ code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */export default {type: 'page',name: 'acme-dashboard',diff --git a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjsindex e03e3dc61d..4eb38724a1 100644--- a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs+++ b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs@@ -54,7 +54,7 @@ export const docs = {type: 'code',lang: 'javascript',label: 'templates/acme-app-shell.doc.mjs',- code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+ code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */export default {type: 'page',name: 'acme-app-shell',diff --git a/packages/cli/authoring/doctypes/template/integration-template.doc.mjs b/packages/cli/authoring/doctypes/template/integration-template.doc.mjsindex 91c5083b6e..bd002aa2da 100644--- a/packages/cli/authoring/doctypes/template/integration-template.doc.mjs+++ b/packages/cli/authoring/doctypes/template/integration-template.doc.mjs@@ -43,7 +43,7 @@ export default {notes: [{type: 'prose',- text: "Every other field, and the page and block variants, are TemplateDoc's. Core's own templates use TemplateDoc, whose `category` is a TemplateCategory value.",+ text: "Every other field, and the page and block variants, are TemplateDoc's. Core's own templates use TemplateDoc, whose `category` is a TemplateCategory value. `astryx doctor integration validate` checks an integration's template docs against IntegrationTemplateDoc.",},],};diff --git a/packages/cli/authoring/doctypes/template/template.doc.mjs b/packages/cli/authoring/doctypes/template/template.doc.mjsindex 10b4c2799a..df95f19b6b 100644--- a/packages/cli/authoring/doctypes/template/template.doc.mjs+++ b/packages/cli/authoring/doctypes/template/template.doc.mjs@@ -162,7 +162,7 @@ export default {notes: [{type: 'prose',- text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',+ text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract, and `astryx doctor integration validate` warns about an integration template that leaves out `displayName` or `aspectRatio`.',},{type: 'prose',diff --git a/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjsindex 327ce515ab..3816c1e533 100644--- a/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs+++ b/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs@@ -14,7 +14,13 @@ export const doc = {description:'Validates one integration at a time: the local package rooted at cwd, or an ' +'installed package resolved by name. It schema-checks the manifest, verifies ' +- 'every declared contribution root, and reports every finding. Safe as a CI gate.',+ 'every declared contribution root, and reports every finding. Safe as a CI gate. ' ++ 'It then checks every doc the package ships under its roots against the ' ++ "published authoring type for its kind, with the project's own `typescript`, and " ++ 'warns about each field that does not match, naming the field and a fix. A doc ' ++ 'it cannot fully check is listed with the reason, and test fixtures under ' ++ '`__tests__` in the components or docs root are counted, not checked. Without ' ++ 'TypeScript it prints one line saying the docs were not type-checked.',fn: 'validateIntegration',args: [{@@ -36,7 +42,10 @@ export const doc = {},],exitCodes: [- {code: 0, when: 'no error-severity issues (warnings are allowed)'},+ {+ code: 0,+ when: 'no error-severity issues (warnings, including doc type findings, are allowed)',+ },{code: 1, when: 'one or more error-severity issues'},],related: ['doctor integration templates', 'template'],diff --git a/packages/cli/clients/cli/commands/doctor-integration.test.mjs b/packages/cli/clients/cli/commands/doctor-integration.test.mjsindex 799b03939c..4762d05a4b 100644--- a/packages/cli/clients/cli/commands/doctor-integration.test.mjs+++ b/packages/cli/clients/cli/commands/doctor-integration.test.mjs@@ -210,6 +210,425 @@ describe('doctor integration — command', () => {expect(process.exitCode).toBeUndefined();});+ it('validate warns about each doc field that does not match its authoring type, and still exits 0', async () => {+ writeIntegration({id: 'hero', name: 'Hero', type: 'block'});+ process.chdir(tmpDir);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ 'doctor',+ 'integration',+ 'validate',+ ]);++ const output = logCalls.join('\n');+ expect(output).toContain('[ok] No integration issues found.');+ expect(output).toMatch(+ /Checking 1 doc\(s\) against the authoring types \(TypeScript \d+\.\d+/,+ );+ expect(output).toContain('templates/hero.doc.mjs');+ expect(output).toMatch(/export:\s+default/);+ expect(output).toMatch(/type:\s+IntegrationTemplateDoc/);+ expect(output).toContain(+ 'Add `aspectRatio`: IntegrationBlockTemplateDoc requires it.',+ );+ expect(output).toContain(+ 'Add `displayName`: IntegrationBlockTemplateDoc requires it.',+ );+ expect(output).toContain(+ '2 doc field(s) in 1 file(s) do not match the authoring types.',+ );+ expect(process.exitCode).toBeUndefined();+ });++ it('validate says there is no doc to type-check, rather than asking for TypeScript', async () => {+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-docs-'));+ try {+ fs.writeFileSync(+ path.join(outside, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),+ );+ fs.writeFileSync(+ path.join(outside, 'astryx.integration.mjs'),+ "export default {components: './components'};\n",+ );+ fs.mkdirSync(path.join(outside, 'components'));+ fs.writeFileSync(+ path.join(outside, 'components', 'Widget.tsx'),+ 'export function Widget() { return null; }\n',+ );+ process.chdir(outside);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ 'doctor',+ 'integration',+ 'validate',+ ]);++ const output = logCalls.join('\n');+ expect(output).toContain('[info] No doc files to type-check.');+ expect(output).not.toContain('Docs not type-checked');+ expect(output).not.toContain('against the authoring types');+ } finally {+ process.chdir(previousCwd);+ fs.rmSync(outside, {recursive: true, force: true});+ }+ });++ it('validate says the docs matched even when another check failed', async () => {+ writeIntegration({id: 'hero', missingRoot: true});+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ "export default {templates: './missing', components: './components'};\n",+ );+ fs.mkdirSync(path.join(tmpDir, 'components'), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeBadge.doc.mjs'),+ "export default {type: 'component', name: 'AcmeBadge', displayName: 'Badge', usage: {description: 'A badge.'}, props: []};\n",+ );+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeBadge.tsx'),+ 'export function AcmeBadge() { return null; }\n',+ );+ process.chdir(tmpDir);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ 'doctor',+ 'integration',+ 'validate',+ ]);++ const output = logCalls.join('\n');+ expect(process.exitCode).toBe(1);+ expect(output).toContain(+ '[info] No doc field differs from its authoring type (1 checked).',+ );+ expect(output).not.toContain('[ok] Every doc');+ });++ it('validate prints every field of the doc type check that JSON carries', async () => {+ writeIntegration({id: 'hero', name: 'Hero', type: 'block'});+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ "export default {templates: './templates', components: './components'};\n",+ );+ fs.mkdirSync(path.join(tmpDir, 'components'), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeBadge.doc.mjs'),+ "export default {type: 'component', name: 'AcmeBadge', displayName: 5, usage: {description: 'A badge.'}, props: [], keyword: ['x']};\n",+ );+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeBadge.tsx'),+ 'export function AcmeBadge() { return null; }\n',+ );+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'shared.mjs'),+ `export default {type: 'component', name: 'AcmeAgain', displayName: 'Again', usage: {description: 'x'}, props: []};\n`,+ );+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeAgain.doc.mjs'),+ "export {default} from './shared.mjs';\n",+ );+ fs.writeFileSync(+ path.join(tmpDir, 'components', 'AcmeAgain.tsx'),+ 'export function AcmeAgain() { return null; }\n',+ );+ process.chdir(tmpDir);+ const run = async (/** @type {string[]} */ flags) => {+ logCalls.length = 0;+ await createProgram().parseAsync([+ 'node',+ 'astryx',+ ...flags,+ 'doctor',+ 'integration',+ 'validate',+ ]);+ return logCalls.join('\n');+ };++ const report = JSON.parse(await run(['--json'])).data.docTypes;+ const output = await run([]);++ expect([...new Set(report.findings.map(f => f.problem))].sort()).toEqual([+ 'missing_field',+ 'unknown_field',+ 'wrong_type',+ ]);+ expect(report.unchecked).toHaveLength(1);+ expectRecordsCarry(output, report.findings, ['doc', 'field', 'problem']);+ expectRecordsCarry(output, report.unchecked, ['doc', 'reason']);+ expect(output).toContain(+ `Checking ${report.docs} doc(s) against the authoring types (TypeScript ${report.typescript})`,+ );+ });++ it('validate type-checks each doc component discovery serves, in __fixtures__, in a dot-folder or behind a symlink', async () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ `export default {components: './components'};\n`,+ );+ for (const [rel, name] of [+ ['components/__fixtures__/AcmeFixture.doc.mjs', 'AcmeFixture'],+ ['components/.drafts/AcmeDraft.doc.mjs', 'AcmeDraft'],+ ['shared/AcmeLinked.doc.mjs', 'AcmeLinked'],+ ]) {+ fs.mkdirSync(path.dirname(path.join(tmpDir, rel)), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, rel),+ `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: 'Fixture.'}, props: [], keyword: []};\n`,+ );+ }+ fs.symlinkSync(+ path.join(tmpDir, 'shared', 'AcmeLinked.doc.mjs'),+ path.join(tmpDir, 'components', 'AcmeLinked.doc.mjs'),+ );+ process.chdir(tmpDir);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ '--json',+ 'doctor',+ 'integration',+ 'validate',+ ]);++ const {docTypes} = JSON.parse(logCalls.join('\n')).data;+ expect(docTypes).toMatchObject({status: 'checked', docs: 3, unchecked: []});+ expect(+ docTypes.findings.map(+ (/** @type {any} */ f) => `${f.doc} ${f.field} ${f.problem}`,+ ),+ ).toEqual([+ 'components/__fixtures__/AcmeFixture.doc.mjs keyword unknown_field',+ 'components/.drafts/AcmeDraft.doc.mjs keyword unknown_field',+ 'components/AcmeLinked.doc.mjs keyword unknown_field',+ ]);+ });++ it('validate type-checks a hidden doc and a second doc for one name, and counts a test fixture', async () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ `export default {components: './components'};\n`,+ );+ for (const [rel, name, extra] of [+ ['components/AcmeBadge.doc.mjs', 'AcmeBadge', ''],+ ['components/again/AcmeBadge.doc.mjs', 'AcmeBadge', ', keyword: []'],+ [+ 'components/AcmeHidden.doc.mjs',+ 'AcmeHidden',+ ', hidden: true, keyword: []',+ ],+ [+ 'components/__tests__/AcmeTested.doc.mjs',+ 'AcmeTested',+ ', keyword: []',+ ],+ ]) {+ fs.mkdirSync(path.dirname(path.join(tmpDir, rel)), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, rel),+ `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: 'Fixture.'}, props: []${extra}};\n`,+ );+ fs.writeFileSync(+ path.join(tmpDir, rel.replace('.doc.mjs', '.tsx')),+ 'export default function Fixture() { return null; }\n',+ );+ }+ process.chdir(tmpDir);+ const run = async (/** @type {string[]} */ flags) => {+ logCalls.length = 0;+ await createProgram().parseAsync([+ 'node',+ 'astryx',+ ...flags,+ 'doctor',+ 'integration',+ 'validate',+ ]);+ return logCalls.join('\n');+ };++ const {docTypes} = JSON.parse(await run(['--json'])).data;+ const output = await run([]);++ expect(docTypes).toMatchObject({docs: 3, fixtures: 1, unchecked: []});+ expect(+ docTypes.findings.map(+ (/** @type {any} */ f) => `${f.doc} ${f.field} ${f.problem}`,+ ),+ ).toEqual([+ 'components/AcmeHidden.doc.mjs keyword unknown_field',+ 'components/again/AcmeBadge.doc.mjs keyword unknown_field',+ ]);+ expect(output).toContain('[info] 1 test fixture doc(s) not checked.');+ expect(output).not.toContain('[ok] Every doc matches');+ });++ it('validate keeps the fixture count when test fixtures are the only docs', async () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ `export default {components: './components'};\n`,+ );+ const rel = 'components/__tests__/AcmeTested.doc.mjs';+ fs.mkdirSync(path.dirname(path.join(tmpDir, rel)), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, rel),+ `export default {type: 'component', name: 'AcmeTested', displayName: 'AcmeTested', usage: {description: 'Fixture.'}, props: []};\n`,+ );+ process.chdir(tmpDir);+ const run = async (/** @type {string[]} */ flags) => {+ logCalls.length = 0;+ await createProgram().parseAsync([+ 'node',+ 'astryx',+ ...flags,+ 'doctor',+ 'integration',+ 'validate',+ ]);+ return logCalls.join('\n');+ };++ const {docTypes} = JSON.parse(await run(['--json'])).data;+ const output = await run([]);++ expect(docTypes).toMatchObject({docs: 0, fixtures: 1, findings: []});+ expect(output).toContain('[info] No doc files to type-check.');+ expect(output).toContain('[info] 1 test fixture doc(s) not checked.');+ });++ it("validate keeps main's issue for a root it cannot read, and lists a root with a folder it cannot read", async () => {+ fs.writeFileSync(+ path.join(tmpDir, 'package.json'),+ JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),+ );+ fs.writeFileSync(+ path.join(tmpDir, 'astryx.integration.mjs'),+ `export default {components: './components', docs: './docs'};\n`,+ );+ fs.mkdirSync(path.join(tmpDir, 'components', 'locked'), {recursive: true});+ fs.mkdirSync(path.join(tmpDir, 'docs'));+ const locked = [+ path.join(tmpDir, 'components', 'locked'),+ path.join(tmpDir, 'docs'),+ ];+ for (const dir of locked) fs.chmodSync(dir, 0o000);+ process.chdir(tmpDir);+ try {+ await createProgram().parseAsync([+ 'node',+ 'astryx',+ '--json',+ 'doctor',+ 'integration',+ 'validate',+ ]);+ } finally {+ for (const dir of locked) fs.chmodSync(dir, 0o755);+ }++ const {data} = JSON.parse(logCalls.join('\n'));+ expect(data.issues.map((/** @type {any} */ i) => i.code).sort()).toEqual([+ 'invalid_component',+ 'unreadable_root',+ ]);+ expect(data.docTypes.unchecked).toEqual([+ {+ doc: 'components',+ reason: expect.stringMatching(+ /^the components root does not load, so no doc in it was checked: .*EACCES/,+ ),+ },+ ]);+ });++ it('validate reports the doc type check as additive JSON', async () => {+ writeIntegration({id: 'hero', name: 'Hero', type: 'block'});+ process.chdir(tmpDir);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ '--json',+ 'doctor',+ 'integration',+ 'validate',+ ]);++ const parsed = JSON.parse(logCalls.join('\n'));+ expect(parsed.data.issues).toEqual([]);+ expect(parsed.data.docTypes).toMatchObject({+ status: 'checked',+ docs: 1,+ unchecked: [],+ });+ expect(parsed.data.docTypes.typescript).toMatch(/^\d+\.\d+/);+ expect(parsed.data.docTypes.findings).toEqual([+ expect.objectContaining({+ doc: 'templates/hero.doc.mjs',+ export: 'default',+ type: 'IntegrationTemplateDoc',+ field: 'aspectRatio',+ problem: 'missing_field',+ severity: 'warning',+ }),+ expect.objectContaining({field: 'displayName', problem: 'missing_field'}),+ ]);+ expect(process.exitCode).toBeUndefined();+ });++ it('validate says, in one visible line, that docs were not type-checked when the project has no TypeScript', async () => {+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-ts-'));+ const inside = tmpDir;+ try {+ // The fixture helpers write to tmpDir; point it outside the repository,+ // where no TypeScript resolves, and restore it for afterEach.+ tmpDir = outside;+ writeIntegration({id: 'hero', name: 'Hero', type: 'block'});+ tmpDir = inside;+ process.chdir(outside);++ await createProgram().parseAsync([+ 'node',+ 'astryx',+ 'doctor',+ 'integration',+ 'validate',+ ]);++ const output = logCalls.join('\n');+ expect(output).toContain(+ '[skip] Docs not type-checked: TypeScript is not installed in this project',+ );+ expect(output).not.toMatch(+ /Checking \d+ doc\(s\) against the authoring types/,+ );+ expect(process.exitCode).toBeUndefined();+ } finally {+ process.chdir(previousCwd);+ fs.rmSync(outside, {recursive: true, force: true});+ }+ });+it('templates warns on a Core id and writes the exact --package command', async () => {const [core] = await discoverCoreTemplates();expect(core).toBeDefined();diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjsindex 37aa98084c..5e1b11a83e 100644--- a/packages/cli/clients/cli/commands/doctor.mjs+++ b/packages/cli/clients/cli/commands/doctor.mjs@@ -98,6 +98,85 @@ function issueBlocks(issues) {];}+/**+ * The docs checked against the authoring types: a visible line when it was+ * skipped, the findings (all warnings), the files it could not check, or an+ * [ok] (never after a failed check).+ * @param {import('../../../api/integration/validate-integration.type.mjs').DocTypesReport | undefined} report+ * @param {boolean} failed+ */+function docTypesBlocks(report, failed) {+ if (!report) return [];+ if (+ report.status === 'checked' &&+ report.docs === 0 &&+ report.findings.length === 0 &&+ report.unchecked.length === 0+ ) {+ return [+ text('[info] No doc files to type-check.'),+ ...(report.fixtures+ ? [text(`[info] ${report.fixtures} test fixture doc(s) not checked.`)]+ : []),+ ];+ }+ if (report.status === 'skipped') {+ return [text(`[skip] Docs not type-checked: ${report.reason}`)];+ }+ const blocks = [+ section(+ `Checking ${report.docs} doc(s) against the authoring types${report.typescript ? ` (TypeScript ${report.typescript})` : ''}`,+ ),+ ];+ if (report.findings.length > 0) {+ const files = new Set(report.findings.map(f => f.doc)).size;+ blocks.push(+ records(report.findings, {+ fields: [+ 'severity',+ 'doc',+ 'line',+ 'export',+ 'type',+ 'field',+ 'problem',+ 'message',+ 'fix',+ ],+ format: {severity: statusToken},+ }),+ text(+ `${report.findings.length} doc field(s) in ${files} file(s) do not match the authoring types. ` ++ 'These are warnings; `astryx docs authoring` lists every field.',+ ),+ );+ }+ if (report.unchecked.length > 0) {+ blocks.push(+ text(`[info] Not type-checked: ${report.unchecked.length} doc file(s):`),+ records(report.unchecked, {fields: ['doc', 'reason']}),+ );+ }+ if (report.fixtures) {+ blocks.push(+ text(`[info] ${report.fixtures} test fixture doc(s) not checked.`),+ );+ }+ if (report.findings.length === 0 && report.docs > 0) {+ // After a failed check an [ok] reads as a pass, but the result still shows.+ blocks.push(+ text(+ failed+ ? `[info] No doc field differs from its authoring type (${report.docs} checked).`+ : report.unchecked.length > 0+ ? `[ok] Every doc that was checked matches its authoring type (${report.docs} checked).`+ : `[ok] Every doc matches its authoring type (${report.docs} checked).`,+ ),+ );+ }+ return blocks;+}+/*** @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data*/@@ -119,6 +198,7 @@ function printIntegrationValidation(data) {`Summary: ${errors} error${errors === 1 ? '' : 's'}, ` +`${warnings} warning${warnings === 1 ? '' : 's'}`,),+ ...docTypesBlocks(data.docTypes, errors > 0),);}diff --git a/packages/cli/foundation/discovery/doc-types.mjs b/packages/cli/foundation/discovery/doc-types.mjsindex 095f51fbc5..7c9452b0bd 100644--- a/packages/cli/foundation/discovery/doc-types.mjs+++ b/packages/cli/foundation/discovery/doc-types.mjs@@ -32,8 +32,8 @@* @input Doc files with the root each was found in, the package root, and the* directories to resolve `typescript` from.* @output A DocTypesReport.- * @position Foundation discovery: it reads doc files and returns a report,- * and prints nothing itself.+ * @position The check `astryx doctor integration validate` runs on an+ * integration's docs, and the Astryx repository's test runs on Core's own.*/import * as fs from 'node:fs';diff --git a/packages/cli/foundation/discovery/integration-doc-files.mjs b/packages/cli/foundation/discovery/integration-doc-files.mjsnew file mode 100644index 0000000000..16550b6fce--- /dev/null+++ b/packages/cli/foundation/discovery/integration-doc-files.mjs@@ -0,0 +1,231 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The doc files an integration package ships, by root: every doc its+ * roots hold, so the doc type check covers each one an agent can open.+ *+ * Each root's reader names the docs it serves, with the kind it reads each+ * as:+ * - components: the doc each component discovery records;+ * - templates: the doc of each template template discovery serves;+ * - docs: the file of each topic, namespace and placed guide docs discovery+ * serves, and each topic's and guide's `zh` and `dense` overlay that a docs+ * read applies;+ * - themes: each theme's descriptor, as theme discovery resolves it. A themes+ * root that discovery cannot read serves no theme, and is listed with the+ * reason.+ * A doc no reader serves still ships: a `hidden` one, a second doc for one+ * name, an overlay without its topic. It goes to its root's kind. A test+ * fixture does not ship as a doc, and is only counted: a doc under+ * `__tests__` in the components or docs root, which those readers skip.+ * A file two roots hold goes to the deepest.+ *+ * @input A loaded integration and its resolved roots.+ * @output DocFile entries for checkDocTypes, each with the root it belongs to,+ * the roots a reader could not read, and how many test fixtures it left+ * out.+ * @position Read by `astryx doctor integration validate` before it checks+ * each doc against its authoring type.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {OVERLAY_LANGUAGES, overlayPath} from '../doc-compiler/read.mjs';+import {discoverIntegrationComponents} from './component-discovery.mjs';+import {discoverIntegrationDocs} from './docs-discovery.mjs';+import {discoverIntegrationTemplatesForOne} from './template-adapter.mjs';+import {discoverThemeDirectory} from './theme-discovery.mjs';+import {rootProblem} from '../integrations/validate-contributions.mjs';++/** @typedef {import('./doc-types.mjs').DocFile} DocFile */+/** @typedef {import('./doc-types.mjs').DocRoot} DocRoot */++/**+ * Every doc file an integration's roots hold, each assigned to the deepest+ * root that holds it, each root a reader could not read, and how many test+ * fixtures no reader serves.+ * @param {any} integration a loaded integration+ * @returns {Promise<{files: DocFile[], unread: Array<{path: string, reason: string}>, fixtures: number}>}+ */+export async function integrationDocFiles(integration) {+ const {components, templates, docs, themes} = integration ?? {};+ /** @type {Array<[DocRoot, string, string[]]>} */+ const read = [];+ /** @type {Array<{path: string, reason: string}>} */+ const unread = [];+ // A root `validate` already reports (missing, a file, unreadable) is left+ // to that issue. A reader that fails inside a root, such as on a folder it+ // cannot read, leaves the root listed with the reason.+ /** @type {(root: string | undefined, label: string, files: () => Promise<Array<[DocRoot, string[]]>>) => Promise<void>} */+ const take = async (root, label, files) => {+ if (!root || rootProblem(root)) return;+ try {+ for (const [kind, list] of await files()) read.push([kind, root, list]);+ } catch (err) {+ unread.push({+ path: root,+ reason: `the ${label} root does not load, so no doc in it was checked: ${err instanceof Error ? err.message : String(err)}`,+ });+ }+ };+ await take(components, 'components', async () => [+ [+ 'components',+ discoverIntegrationComponents(integration).map(c => c.docPath),+ ],+ ]);+ await take(templates, 'templates', async () => [+ [+ 'templates',+ (await discoverIntegrationTemplatesForOne(integration)).templates.map(+ t => t.docPath,+ ),+ ],+ ]);+ await take(docs, 'docs', async () => {+ const found = await discoverIntegrationDocs(integration);+ // Topics and placed guides are read with their overlays; a namespace+ // names its file `<package name>/<path in the root>`.+ const withOverlays = [+ ...found.records.map(record => record.path),+ ...found.guides.map(guide => guide.ref.topicFile),+ ];+ const prefix = `${integration.name}/`;+ const namespaces = found.namespaces.map(entry =>+ path.join(+ /** @type {string} */ (docs),+ ...(entry.source.startsWith(prefix)+ ? entry.source.slice(prefix.length)+ : entry.source+ ).split('/'),+ ),+ );+ return [+ ['docs', [...withOverlays, ...namespaces]],+ [+ 'docs-overlay',+ withOverlays.flatMap(file =>+ OVERLAY_LANGUAGES.map(lang => overlayPath(file, lang)).filter(+ overlay => fs.existsSync(overlay),+ ),+ ),+ ],+ ];+ });+ await take(themes, 'themes', async () => [+ [+ 'themes',+ discoverThemeDirectory(+ /** @type {string} */ (themes),+ integration?.name ?? 'the package',+ ).map(theme => theme.docPath),+ ],+ ]);+ /** @type {Map<string, {root: DocRoot, dir: string}>} */+ const owners = new Map();+ /** @type {(table: Map<string, {root: DocRoot, dir: string}>, root: DocRoot, dir: string, file: string) => void} */+ const own = (table, root, dir, file) => {+ const owner = table.get(file);+ if (!owner || dir.length > owner.dir.length) table.set(file, {root, dir});+ };+ for (const [root, dir, files] of read) {+ for (const file of files) own(owners, root, dir, file);+ }+ // The docs no reader serves, in each root a reader could read.+ /** @type {Map<string, {root: DocRoot, dir: string}>} */+ const shipped = new Map();+ const readable = new Set(read.map(([, dir]) => dir));+ for (const [+ kind,+ dir,+ ] of /** @type {Array<[DocRoot, string | undefined]>} */ ([+ ['components', components],+ ['templates', templates],+ ['docs', docs],+ ['themes', themes],+ ])) {+ if (!dir || !readable.has(dir)) continue;+ for (const file of docFilesUnder(dir)) {+ const overlay = OVERLAY_LANGUAGES.some(lang =>+ file.endsWith(`.doc.${lang}.mjs`),+ );+ if (overlay && kind !== 'docs') continue;+ own(shipped, overlay ? 'docs-overlay' : kind, dir, file);+ }+ }+ let fixtures = 0;+ for (const [file, owner] of shipped) {+ if (owners.has(file)) continue;+ if (isFixture(path.relative(owner.dir, file), owner.root)) fixtures++;+ else owners.set(file, owner);+ }+ return {+ files: [...owners]+ .map(([file, {root}]) => ({path: file, root}))+ .sort((a, b) => a.path.localeCompare(b.path)),+ unread,+ fixtures,+ };+}++/**+ * Whether a doc file is a test fixture: under `__tests__` in a root whose+ * reader skips that folder (components and docs). The template reader reads+ * it, so a template doc there is the package's like any other.+ * @param {string} file its path relative to its root+ * @param {DocRoot} root+ */+function isFixture(file, root) {+ return (+ root !== 'templates' &&+ root !== 'themes' &&+ file.split(path.sep).includes('__tests__')+ );+}++/**+ * Every doc file under a folder: a `.doc.ts`, `.doc.mjs` or `.doc.js` file,+ * or a `zh` or `dense` overlay, through its folders and linked files, but not+ * `node_modules`, `.git` or a linked folder.+ * @param {string} dir+ * @returns {string[]}+ */+function docFilesUnder(dir) {+ /** @type {string[]} */+ const found = [];+ /** @type {(folder: string) => void} */+ const walk = folder => {+ /** @type {fs.Dirent[]} */+ let entries;+ try {+ entries = fs.readdirSync(folder, {withFileTypes: true});+ } catch {+ return;+ }+ for (const entry of entries) {+ if (entry.name === 'node_modules' || entry.name === '.git') continue;+ const full = path.join(folder, entry.name);+ if (entry.isDirectory()) {+ walk(full);+ continue;+ }+ if (entry.isSymbolicLink()) {+ try {+ if (!fs.statSync(full).isFile()) continue;+ } catch {+ continue;+ }+ } else if (!entry.isFile()) {+ continue;+ }+ if (+ /\.doc\.(ts|mjs|js)$/.test(entry.name) ||+ OVERLAY_LANGUAGES.some(lang => entry.name.endsWith(`.doc.${lang}.mjs`))+ ) {+ found.push(full);+ }+ }+ };+ walk(dir);+ return found;+}diff --git a/packages/cli/foundation/discovery/integration-doc-files.test.mjs b/packages/cli/foundation/discovery/integration-doc-files.test.mjsnew file mode 100644index 0000000000..a3312d74b6--- /dev/null+++ b/packages/cli/foundation/discovery/integration-doc-files.test.mjs@@ -0,0 +1,246 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file integrationDocFiles(): exactly the docs each root's reader serves, a+ * nested root's files given to that root, and a root its reader cannot read.+ */++import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import {discoverIntegrationComponents} from './component-discovery.mjs';+import {integrationDocFiles} from './integration-doc-files.mjs';++/** @type {string} */+let pkg;++beforeEach(() => {+ pkg = fs.realpathSync(+ fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doc-files-')),+ );+});++afterEach(() => {+ fs.rmSync(pkg, {recursive: true, force: true});+});++/**+ * @param {string} rel+ * @param {string} text+ */+function write(rel, text) {+ const file = path.join(pkg, rel);+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(file, text);+ return file;+}++/** @param {string} name */+const component = name =>+ `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: 'x'}, props: []};\n`;+/** @param {string} name */+const topic = name =>+ `export default {type: 'generic', name: '${name}', title: 'T', description: 'D', sections: [{title: 'S', content: [{type: 'prose', text: 'x'}]}]};\n`;+/** @param {string} rel a template doc, with its same-stem source */+const template = rel => {+ write(rel.replace(/\.doc\.mjs$/, '.tsx'), 'export default () => null;\n');+ return write(+ rel,+ `export default {type: 'block', name: '${path.basename(rel, '.doc.mjs')}', description: 'D'};\n`,+ );+};++/** @param {Awaited<ReturnType<typeof integrationDocFiles>>['files']} files */+const listed = files =>+ files+ .map(f => [path.relative(pkg, f.path).split(path.sep).join('/'), f.root])+ .sort();++describe('integrationDocFiles', () => {+ it('reads a fixture folder relative to its root, so a package under a `__tests__` folder is checked', async () => {+ write(+ '__tests__/acme/components/Hidden.doc.mjs',+ `${component('Hidden')}\n hidden: true\n`,+ );+ write(+ '__tests__/acme/components/__tests__/Tested.doc.mjs',+ component('Tested'),+ );++ const {files, fixtures} = await integrationDocFiles({+ name: '@acme/widgets',+ components: path.join(pkg, '__tests__', 'acme', 'components'),+ });++ expect(listed(files)).toEqual([+ ['__tests__/acme/components/Hidden.doc.mjs', 'components'],+ ]);+ expect(fixtures).toBe(1);+ });++ it("gives a nested root's files to that root", async () => {+ write('src/Badge.doc.mjs', component('Badge'));+ write('src/docs/guide.doc.mjs', topic('guide'));+ write('src/docs/guide.doc.zh.mjs', 'export const docsZh = {};\n');+ template('templates/hero.doc.mjs');++ const {files, unread} = await integrationDocFiles({+ name: '@acme/widgets',+ components: path.join(pkg, 'src'),+ docs: path.join(pkg, 'src', 'docs'),+ templates: path.join(pkg, 'templates'),+ });++ expect(unread).toEqual([]);+ expect(listed(files)).toEqual([+ ['src/Badge.doc.mjs', 'components'],+ ['src/docs/guide.doc.mjs', 'docs'],+ ['src/docs/guide.doc.zh.mjs', 'docs-overlay'],+ ['templates/hero.doc.mjs', 'templates'],+ ]);+ });++ it('takes every doc the roots hold, served or not, and counts a test fixture no reader serves', async () => {+ write('components/__fixtures__/Fixture.doc.mjs', component('Fixture'));+ write('components/.drafts/Draft.doc.mjs', component('Draft'));+ write('components/__tests__/Tested.doc.mjs', component('Tested'));+ write(+ 'components/Hidden.doc.mjs',+ `${component('Hidden')}\n hidden: true\n`,+ );+ write('components/Twice.doc.mjs', component('Twice'));+ write('components/again/Twice.doc.mjs', component('Twice'));+ write('shared/Linked.doc.mjs', component('Linked'));+ fs.symlinkSync(+ path.join(pkg, 'shared', 'Linked.doc.mjs'),+ path.join(pkg, 'components', 'Linked.doc.mjs'),+ );+ template('templates/__tests__/tested.doc.mjs');+ write('templates/orphan.doc.mjs', "export default {type: 'block'};\n");+ // The template reader reads `__fixtures__`: a template doc there without+ // its source is the package's, so it is checked.+ write(+ 'templates/__fixtures__/bad.doc.mjs',+ "export default {type: 'block'};\n",+ );+ write('docs/__tests__/sample.doc.mjs', topic('sample'));+ write('docs/.drafts/topic.doc.mjs', topic('topic'));+ write('docs/.drafts/topic.doc.zh.mjs', 'export const docsZh = {};\n');+ write('docs/copy.doc.mjs', topic('topic'));+ write('docs/orphan.doc.dense.mjs', 'export const docsDense = {};\n');+ write('themes/oceanTheme.doc.mjs', 'export default {};\n');+ const integration = {+ name: '@acme/widgets',+ components: path.join(pkg, 'components'),+ templates: path.join(pkg, 'templates'),+ docs: path.join(pkg, 'docs'),+ themes: path.join(pkg, 'themes'),+ };++ const {files, unread, fixtures} = await integrationDocFiles(integration);++ // Component discovery skips `__tests__` and a `hidden` doc, and serves the+ // first doc of a name; a template without its source, a second topic of+ // a name, and an overlay without its topic are not served either. All of+ // them ship, so all are checked, but a test fixture no reader serves.+ const served = discoverIntegrationComponents(integration).map(c =>+ path.relative(pkg, c.docPath),+ );+ expect(served.filter(file => file.endsWith('Twice.doc.mjs'))).toHaveLength(+ 1,+ );+ expect(listed(files)).toEqual(+ [+ ...served.map(file => [file, 'components']),+ ['components/Hidden.doc.mjs', 'components'],+ ['components/again/Twice.doc.mjs', 'components'],+ ['docs/.drafts/topic.doc.mjs', 'docs'],+ ['docs/.drafts/topic.doc.zh.mjs', 'docs-overlay'],+ ['docs/copy.doc.mjs', 'docs'],+ ['docs/orphan.doc.dense.mjs', 'docs-overlay'],+ ['templates/__fixtures__/bad.doc.mjs', 'templates'],+ ['templates/__tests__/tested.doc.mjs', 'templates'],+ ['templates/orphan.doc.mjs', 'templates'],+ ].sort(),+ );+ // `components/__tests__/Tested` and `docs/__tests__/sample`.+ expect(fixtures).toBe(2);+ expect(served.sort()).toEqual(+ expect.arrayContaining([+ 'components/.drafts/Draft.doc.mjs',+ 'components/Linked.doc.mjs',+ 'components/__fixtures__/Fixture.doc.mjs',+ ]),+ );+ expect(served.some(file => /Tested|Hidden/.test(file))).toBe(false);+ // Theme discovery serves no theme from this root, so none is checked,+ // and the root says why.+ expect(unread).toEqual([+ {+ path: integration.themes,+ reason: expect.stringMatching(+ /^the themes root does not load, so no doc in it was checked: .*lower-kebab/,+ ),+ },+ ]);+ });++ it("takes a scoped package's namespace docs and placed guides where they are, with each guide's overlays", async () => {+ write(+ 'docs/guides/guides.doc.mjs',+ `export const docs = ${JSON.stringify({type: 'namespace', name: 'guides', title: 'Guides', summary: 'Every guide.', slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}}})};\n`,+ );+ write(+ 'docs/guides/setup.doc.mjs',+ `export const docs = ${JSON.stringify({type: 'generic', name: 'setup', title: 'Set up', description: 'D', placement: {parent: 'namespace:guides', slot: 'guides', order: 1}, sections: [{title: 'S', content: [{type: 'prose', text: 'x'}]}]})};\n`,+ );+ write('docs/guides/setup.doc.zh.mjs', 'export const docsZh = {};\n');+ write('docs/guides/setup.doc.dense.mjs', 'export const docsDense = {};\n');++ const {files, unread} = await integrationDocFiles({+ name: '@acme/widgets',+ docs: path.join(pkg, 'docs'),+ });++ expect(unread).toEqual([]);+ expect(listed(files)).toEqual([+ ['docs/guides/guides.doc.mjs', 'docs'],+ ['docs/guides/setup.doc.dense.mjs', 'docs-overlay'],+ ['docs/guides/setup.doc.mjs', 'docs'],+ ['docs/guides/setup.doc.zh.mjs', 'docs-overlay'],+ ]);+ });++ it('leaves a root validate reports to that issue, and lists a root whose reader fails inside it', async () => {+ write('components/Badge.doc.mjs', component('Badge'));+ write('components/locked/Inner.doc.mjs', component('Inner'));+ write('docs/guide.doc.mjs', topic('guide'));+ const locked = path.join(pkg, 'components', 'locked');+ fs.chmodSync(path.join(pkg, 'docs'), 0o000);+ fs.chmodSync(locked, 0o000);+ try {+ const {files, unread} = await integrationDocFiles({+ name: '@acme/widgets',+ components: path.join(pkg, 'components'),+ docs: path.join(pkg, 'docs'),+ templates: path.join(pkg, 'missing'),+ });++ // `validate` reports the unreadable docs root and the missing templates+ // root itself; the components root reads until its locked folder.+ expect(files).toEqual([]);+ expect(unread).toEqual([+ {+ path: path.join(pkg, 'components'),+ reason: expect.stringMatching(+ /^the components root does not load, so no doc in it was checked: .*EACCES/,+ ),+ },+ ]);+ } finally {+ fs.chmodSync(path.join(pkg, 'docs'), 0o755);+ fs.chmodSync(locked, 0o755);+ }+ });+});diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex edfab0dff7..41ec57b228 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -332,7 +332,7 @@ export const doc = {{value: 'integration.validate',description:- 'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}.',+ 'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).',},{value: 'integration.template-conflicts',diff --git a/packages/cli/test/core-doc-types.known-drift.json b/packages/cli/test/core-doc-types.known-drift.jsonnew file mode 100644index 0000000000..ca5b66abbe--- /dev/null+++ b/packages/cli/test/core-doc-types.known-drift.json@@ -0,0 +1,309 @@+[+ "packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs docsDense name unknown_field",+ "packages/core/src/Avatar/AvatarStatusDot.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Avatar/AvatarStatusDot.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Avatar/AvatarStatusDot.doc.mjs docsDense name unknown_field",+ "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsDense name unknown_field",+ "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs docsZh name unknown_field",+ "packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatComposer.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatComposer.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatComposer.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatComposer.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatComposerDrawer.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatComposerInput.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatComposerInput.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatComposerInput.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatComposerInput.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatComposerInput.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatComposerInput.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatComposerTokenElement.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatLayout.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatLayout.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatLayout.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatLayout.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatMessage.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatMessage.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatMessage.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatMessage.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatMessageBubble.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatMessageList.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatMessageList.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatMessageList.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatMessageList.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatMessageList.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatMessageList.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatMessageMetadata.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatSendButton.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatSendButton.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatSendButton.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatSendButton.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatSendButton.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatSendButton.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatSystemMessage.doc.mjs docsZh theming unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsDense name unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh name unknown_field",+ "packages/core/src/Chat/ChatTokenizedText.doc.mjs docsZh theming unknown_field",+ "packages/core/src/CheckboxList/CheckboxListItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CheckboxList/CheckboxListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CheckboxList/CheckboxListItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/Collapsible/CollapsibleGroup.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Collapsible/CollapsibleGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Collapsible/CollapsibleGroup.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs docsZh name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs docsZh name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs docsZh name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs docsZh name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs docsZh name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsDense name unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/CommandPalette/CommandPaletteList.doc.mjs docsZh name unknown_field",+ "packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense category unknown_field",+ "packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense group unknown_field",+ "packages/core/src/ComplexSelector/ComplexSelector.doc.mjs docsDense name unknown_field",+ "packages/core/src/ContextMenu/ContextMenuItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/ContextMenu/ContextMenuItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/ContextMenu/ContextMenuItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/Dialog/DialogHeader.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Dialog/DialogHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Dialog/DialogHeader.doc.mjs docsDense name unknown_field",+ "packages/core/src/Dialog/useImperativeDialog.doc.mjs docsDense name unknown_field",+ "packages/core/src/Drawer/DrawerHeader.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Drawer/DrawerHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Drawer/DrawerHeader.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuGroup.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuGroup.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh name unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense name unknown_field",+ "packages/core/src/Field/FieldLabel.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Field/FieldLabel.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Field/FieldLabel.doc.mjs docsDense name unknown_field",+ "packages/core/src/Grid/GridSpan.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Grid/GridSpan.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Grid/GridSpan.doc.mjs docsDense name unknown_field",+ "packages/core/src/InputGroup/InputGroupText.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/InputGroup/InputGroupText.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/InputGroup/InputGroupText.doc.mjs docsDense name unknown_field",+ "packages/core/src/Layout/LayoutContent.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Layout/LayoutContent.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Layout/LayoutContent.doc.mjs docsDense name unknown_field",+ "packages/core/src/Layout/LayoutFooter.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Layout/LayoutFooter.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Layout/LayoutFooter.doc.mjs docsDense name unknown_field",+ "packages/core/src/Layout/LayoutHeader.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Layout/LayoutHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Layout/LayoutHeader.doc.mjs docsDense name unknown_field",+ "packages/core/src/Layout/LayoutPanel.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Layout/LayoutPanel.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Layout/LayoutPanel.doc.mjs docsDense name unknown_field",+ "packages/core/src/List/ListItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/List/ListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/List/ListItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[1].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[2].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[3].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[4].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[5].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[6].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[7].description unknown_field",+ "packages/core/src/Markdown/Markdown.doc.mjs docsZh theming.targets[8].description unknown_field",+ "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/MetadataList/MetadataListItem.doc.mjs docsZh name unknown_field",+ "packages/core/src/RadioList/RadioListItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/RadioList/RadioListItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/RadioList/RadioListItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsZh isHiddenFromOverview unknown_field",+ "packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs docsZh name unknown_field",+ "packages/core/src/Selector/SelectorOption.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Selector/SelectorOption.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Selector/SelectorOption.doc.mjs docsDense name unknown_field",+ "packages/core/src/SideNav/SideNavCollapseButton.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/SideNav/SideNavCollapseButton.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/SideNav/SideNavCollapseButton.doc.mjs docsDense name unknown_field",+ "packages/core/src/SideNav/SideNavHeading.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/SideNav/SideNavHeading.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/SideNav/SideNavHeading.doc.mjs docsDense name unknown_field",+ "packages/core/src/SideNav/SideNavItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/SideNav/SideNavItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/SideNav/SideNavItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/SideNav/SideNavSection.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/SideNav/SideNavSection.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/SideNav/SideNavSection.doc.mjs docsDense name unknown_field",+ "packages/core/src/TabList/Tab.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TabList/Tab.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/TabList/Tab.doc.mjs docsDense name unknown_field",+ "packages/core/src/TabList/TabMenu.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TabList/TabMenu.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/TabList/TabMenu.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableBody.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableBody.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/TableBody.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableCell.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableCell.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/TableCell.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableFooter.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableFooter.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/TableFooter.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableHeader.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableHeader.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/TableHeader.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableHeaderCell.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableHeaderCell.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/TableHeaderCell.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableRow.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableRow.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/TableRow.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/TableSelectionToolbar.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/TableSelectionToolbar.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableColumnResize.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableColumnResize.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableColumnSettings.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableColumnSettings.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableFilterState.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableFilterState.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/useTableFilterState.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableFiltering.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableFiltering.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Table/useTableFiltering.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTablePagination.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTablePagination.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableSelection.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableSelection.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableSelectionState.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableSelectionState.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableSortable.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableSortable.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableStickyColumns.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableStickyColumns.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableTreeData.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableTreeData.doc.mjs docsDense name unknown_field",+ "packages/core/src/Table/useTableTreeState.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Table/useTableTreeState.doc.mjs docsDense name unknown_field",+ "packages/core/src/Text/Heading.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Text/Heading.doc.mjs docsDense name unknown_field",+ "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsDense name unknown_field",+ "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsZh displayName unknown_field",+ "packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs docsZh name unknown_field",+ "packages/core/src/TopNav/TopNavHeading.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TopNav/TopNavHeading.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/TopNav/TopNavHeading.doc.mjs docsDense name unknown_field",+ "packages/core/src/TopNav/TopNavItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TopNav/TopNavItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/TopNav/TopNavItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenu.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenu.doc.mjs docsDense name unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs docsDense name unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs docsDense name unknown_field",+ "packages/core/src/TopNav/TopNavMenu.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/TopNav/TopNavMenu.doc.mjs docsDense name unknown_field",+ "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense isHiddenFromOverview unknown_field",+ "packages/core/src/Typeahead/BaseTypeahead.doc.mjs docsDense name unknown_field",+ "packages/core/src/Typeahead/TypeaheadItem.doc.mjs docsDense displayName unknown_field",+ "packages/core/src/Typeahead/TypeaheadItem.doc.mjs docsDense name unknown_field"+]diff --git a/packages/cli/test/core-doc-types.test.mjs b/packages/cli/test/core-doc-types.test.mjsnew file mode 100644index 0000000000..111a3a093a--- /dev/null+++ b/packages/cli/test/core-doc-types.test.mjs@@ -0,0 +1,114 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Core's own docs against the published authoring types.+ *+ * The same check `astryx doctor integration validate` runs over an+ * integration's docs, here over Core's: its component and hook docs with their+ * translations, the bundled templates and themes, and the docs topics with+ * their overlays. A doc's root is decided as the readers decide it: a Core+ * `use*` doc is a hook doc unless its own annotation says ComponentDoc.+ *+ * Every finding must be listed in core-doc-types.known-drift.json, and every+ * entry there must still be found, so the list only shrinks: a new mismatch+ * fails until the doc (or the type) is fixed, and a fixed one fails until its+ * entry is removed.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import {checkDocTypes} from '../foundation/discovery/doc-types.mjs';++const CLI = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const REPO = path.resolve(CLI, '..', '..');+const KNOWN = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'core-doc-types.known-drift.json',+);+const SKIP = new Set(['node_modules', '__tests__', '__fixtures__']);++/**+ * @param {string} dir+ * @returns {string[]}+ */+function walk(dir) {+ /** @type {string[]} */+ const out = [];+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ if (entry.name.startsWith('.') || SKIP.has(entry.name)) continue;+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) out.push(...walk(full));+ else if (entry.isFile()) out.push(full);+ }+ return out;+}++/** @returns {import('../foundation/discovery/doc-types.mjs').DocFile[]} */+function coreDocFiles() {+ /** @type {import('../foundation/discovery/doc-types.mjs').DocFile[]} */+ const files = [];+ for (const file of walk(path.join(REPO, 'packages', 'core', 'src'))) {+ if (!/\.doc\.mjs$/.test(file)) continue;+ const annotated = /authoring'\)\.(\w+)/.exec(+ fs.readFileSync(file, 'utf8'),+ )?.[1];+ const hook =+ annotated != null+ ? annotated === 'HookDoc'+ : /^use[A-Z]/.test(path.basename(file));+ files.push({path: file, root: hook ? 'hooks' : 'components'});+ }+ for (const file of walk(path.join(CLI, 'assets', 'templates'))) {+ if (!/\.(?:doc|template)\.(?:mjs|ts)$/.test(file)) continue;+ const theme = /type:\s*'theme'/.test(fs.readFileSync(file, 'utf8'));+ files.push({path: file, root: theme ? 'themes' : 'templates'});+ }+ for (const file of walk(path.join(CLI, 'assets', 'docs'))) {+ if (/\.doc\.(?:zh|dense)\.mjs$/.test(file)) {+ files.push({path: file, root: 'docs-overlay'});+ } else if (/\.doc\.mjs$/.test(file)) {+ files.push({path: file, root: 'docs'});+ }+ }+ return files;+}++describe("Core's docs against the authoring types", () => {+ it('match, apart from the known drift, which only shrinks', async () => {+ const report = await checkDocTypes(coreDocFiles(), {+ packageDir: REPO,+ resolveFrom: [REPO],+ core: true,+ });+ expect(report.status).toBe('checked');+ expect(report.unchecked).toEqual([]);++ const found = report.findings.map(+ f => `${f.doc} ${f.export} ${f.field} ${f.problem}`,+ );+ /** @type {string[]} */+ const known = JSON.parse(fs.readFileSync(KNOWN, 'utf8'));+ const knownSet = new Set(known);+ const foundSet = new Set(found);++ const added = report.findings+ .filter(+ f => !knownSet.has(`${f.doc} ${f.export} ${f.field} ${f.problem}`),+ )+ .map(+ f => `${f.doc}:${f.line} ${f.export} ${f.field}: ${f.message} ${f.fix}`,+ );+ expect(+ added,+ 'These doc fields do not match the authoring types. Fix the doc, or the type if the doc is right.',+ ).toEqual([]);++ const fixed = known.filter(entry => !foundSet.has(entry));+ expect(+ fixed,+ 'These no longer mismatch. Remove them from core-doc-types.known-drift.json.',+ ).toEqual([]);+ }, 60_000);+});