@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/foundation/config/project.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import {Project, DEFAULT_ISSUES_URL, findConfigPath} from './project.mjs';
 import {InMemoryConfigCache} from './config-cache.mjs';
 import * as componentDiscovery from '../discovery/component-discovery.mjs';
+import {discoverCoreTemplates} from '../discovery/template-adapter.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -21,6 +22,9 @@ function scaffold({
   issuesUrl,
   withComponents = true,
   withTemplates = true,
+  templateId = 'hero',
+  templateType = 'block',
+  templateReplaces = null,
   withCodemods = true,
   brokenComponent = false,
   brokenCodemod = false,
@@ -65,7 +69,7 @@ function scaffold({
     fs.mkdirSync(compDir, {recursive: true});
     fs.writeFileSync(
       path.join(compDir, 'Widget.doc.mjs'),
-      `export const docs = { name: 'Widget', usage: {description: 'A widget'} };\n`,
+      `export const docs = { name: 'Widget', usage: {description: 'A widget'}, props: [] };\n`,
     );
     if (!brokenComponent) {
       fs.writeFileSync(
@@ -80,12 +84,12 @@ function scaffold({
     const tDir = path.join(pkgDir, 'templates');
     fs.mkdirSync(tDir, {recursive: true});
     fs.writeFileSync(
-      path.join(tDir, 'hero.doc.mjs'),
-      `export default { type: 'block', name: 'Hero', description: 'A hero' };\n`,
+      path.join(tDir, `${templateId}.doc.mjs`),
+      `export default { type: '${templateType}', name: 'Fixture template', description: 'A fixture template'${templateReplaces == null ? '' : `, replaces: ${JSON.stringify(templateReplaces)}`} };\n`,
     );
     fs.writeFileSync(
-      path.join(tDir, 'hero.tsx'),
-      `export default function Hero() { return null; }\n`,
+      path.join(tDir, `${templateId}.tsx`),
+      `export default function FixtureTemplate() { return null; }\n`,
     );
   }
 
@@ -163,7 +167,7 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'templates'));
   fs.writeFileSync(
-    path.join(tmpDir, 'templates', 'local-page.template.mjs'),
+    path.join(tmpDir, 'templates', 'local-page.doc.mjs'),
     `export default {type: 'page', name: 'Local page', description: 'Local page.'};\n`,
   );
   fs.writeFileSync(
@@ -181,21 +185,8 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
   fs.writeFileSync(
-    path.join(tmpDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          displayName: 'Ocean',
-          description: 'Ocean theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Ocean theme.', maintained: true};\n`,
   );
   fs.writeFileSync(
     path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
@@ -337,6 +328,91 @@ describe('Project discovery', () => {
     expect(hero.type).toBe('block');
   });
 
+  it('templates() projects a valid integration replacement instead of its Core target', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    scaffold({
+      templateId: 'acme-app-shell',
+      templateType: 'page',
+      templateReplaces: corePage.dirName,
+    });
+    const project = await Project.load(tmpDir);
+
+    const templates = await project.templates();
+
+    expect(
+      templates.find(template => template.dirName === 'acme-app-shell'),
+    ).toMatchObject({
+      package: '@acme/widgets',
+      replaces: corePage.dirName,
+    });
+    expect(
+      templates.find(
+        template =>
+          template.dirName === corePage.dirName &&
+          template.package !== '@acme/widgets',
+      ),
+    ).toBeUndefined();
+    expect(await project.issues()).toEqual([]);
+  });
+
+  it('reports replacement issues regardless of discovery call order without hiding other contributions', async () => {
+    scaffold({
+      templateReplaces: 'missing-core-template',
+    });
+
+    const componentsFirst = await Project.load(tmpDir);
+    expect(
+      (await componentsFirst.components()).some(
+        component => component.package === '@acme/widgets',
+      ),
+    ).toBe(true);
+    expect(await componentsFirst.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+
+    const issuesFirst = await Project.load(tmpDir, {fresh: true});
+    expect(await issuesFirst.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+    expect(
+      (await issuesFirst.components()).some(
+        component => component.package === '@acme/widgets',
+      ),
+    ).toBe(true);
+    const ownTemplate = (await issuesFirst.templates()).find(
+      template =>
+        template.package === '@acme/widgets' && template.dirName === 'hero',
+    );
+    expect(ownTemplate).toBeDefined();
+    expect(ownTemplate).not.toHaveProperty('replaces');
+
+    const sharedCache = new InMemoryConfigCache();
+    const warm = await Project.load(tmpDir, {cache: sharedCache});
+    await warm.templates();
+    const cached = await Project.load(tmpDir, {cache: sharedCache});
+    expect(await cached.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+  });
+
   it('codemods() returns core registry groups + integration groups', async () => {
     scaffold();
     const project = await Project.load(tmpDir);
@@ -481,6 +557,53 @@ describe('Project issues (skip + warn)', () => {
     expect(issues.some(i => i.package === '@acme/widgets')).toBe(true);
   });
 
+  it('keeps valid contribution kinds and siblings when others are broken', async () => {
+    const pkgDir = scaffold({brokenComponent: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'broken.template.mjs'),
+      `export default {type: 'block', name: 'Broken', description: 'Missing source'};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'ValidWidget.doc.mjs'),
+      `export default {type: 'component', name: 'ValidWidget', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'ValidWidget.tsx'),
+      `export function ValidWidget() { return null; }\n`,
+    );
+    const project = await Project.load(tmpDir);
+
+    const templates = await project.templates();
+    const components = await project.components();
+    const issues = await project.issues();
+
+    expect(
+      templates.find(
+        template =>
+          template.dirName === 'hero' && template.package === '@acme/widgets',
+      ),
+    ).toBeDefined();
+    expect(
+      components.find(
+        component =>
+          component.name === 'ValidWidget' &&
+          component.package === '@acme/widgets',
+      ),
+    ).toBeDefined();
+    expect(
+      components.find(
+        component =>
+          component.name === 'Widget' && component.package === '@acme/widgets',
+      ),
+    ).toBeUndefined();
+    expect(issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({code: 'invalid_component'}),
+        expect.objectContaining({code: 'invalid_template'}),
+      ]),
+    );
+  });
+
   it('does not throw when an integration codemod is broken', async () => {
     scaffold({brokenCodemod: true});
     const project = await Project.load(tmpDir);

package/foundation/discovery/authoring-self-docs.d.mts

@@ -24,6 +24,24 @@ export function loadAuthoringSelfDocs(sources?: string[], root?: string): Promis
         error: string;
     }[];
 }>;
+/**
+ * A schema's fields as the table its section prints, each nested field on the
+ * row after its parent; null when there are none. A reference block that
+ * names some of a schema's fields includes this table of just those.
+ * @param {any[]} fields
+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}
+ */
+export function schemaFieldTable(fields: any[]): {
+    type: "table";
+    headers: string[];
+    rows: string[][];
+} | null;
+/**
+ * One self-doc as a topic section, keyed by the doc's own name.
+ * @param {any} doc
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
+ */
+export function selfDocSection(doc: any): import("../../authoring/doctypes/reference/type").ReferenceSection;
 /**
  * The `authoring` topic: one section per self-doc, in the order given.
  * @param {any[]} docs

package/foundation/discovery/authoring-self-docs.mjs

@@ -17,8 +17,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {CLI_ROOT} from '../fs/paths.mjs';
+import {readDocView} from '../doc-compiler/read.mjs';
 import {
   DOC_OUTPUT_BUDGET_BYTES,
   oversizedDocSections,
@@ -31,6 +31,8 @@ export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
 export const AUTHORING_SELF_DOCS = [
   'integration/integration.doc.mjs',
   'config/config.doc.mjs',
+  'debug/debug.doc.mjs',
+  'gap-report/gap-report.doc.mjs',
   'codemod/codemod.doc.mjs',
   'identity/identity.doc.mjs',
   'doctypes/base/graph-fields.doc.mjs',
@@ -43,6 +45,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/theme/theme.doc.mjs',
 ];
 
 /** Blocks a self-doc note may carry that a topic section can render. */
@@ -59,7 +62,8 @@ export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
   /** @param {string} dir */
   const walk = dir => {
     for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
-      if (entry.name === 'node_modules' || entry.name.startsWith('__')) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('__'))
+        continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.name.endsWith('.doc.mjs')) {
@@ -86,9 +90,14 @@ export async function loadAuthoringSelfDocs(
   const failed = [];
   for (const source of sources) {
     try {
-      const mod = await import(pathToFileURL(path.join(root, source)).href);
-      const doc = mod.doc ?? mod.docs ?? mod.default;
-      if (typeof doc?.name !== 'string' || typeof doc?.description !== 'string') {
+      const doc = await readDocView(path.join(root, source), {
+        root: 'self-docs',
+        loader: 'native',
+      });
+      if (
+        typeof doc?.name !== 'string' ||
+        typeof doc?.description !== 'string'
+      ) {
         throw new Error('exports no doc with a name and a description');
       }
       loaded.push({source, doc});
@@ -124,27 +133,40 @@ function fieldRows(fields) {
   ]);
 }
 
+/**
+ * A schema's fields as the table its section prints, each nested field on the
+ * row after its parent; null when there are none. A reference block that
+ * names some of a schema's fields includes this table of just those.
+ * @param {any[]} fields
+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}
+ */
+export function schemaFieldTable(fields) {
+  const rows = fieldRows(fields);
+  return rows.length > 0
+    ? {
+        type: 'table',
+        headers: ['Field', 'Type', 'Required', 'Description'],
+        rows,
+      }
+    : null;
+}
+
 /**
  * One self-doc as a topic section, keyed by the doc's own name.
  * @param {any} doc
  * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
  */
-function selfDocSection(doc) {
+export function selfDocSection(doc) {
   /** @type {any[]} */
   const content = [{type: 'prose', text: doc.description}];
   if (doc.appliesTo) {
     content.push({type: 'prose', text: `Applies to: ${doc.appliesTo}`});
   }
-  const rows = fieldRows(doc.fields ?? []);
-  if (rows.length > 0) {
-    content.push({
-      type: 'table',
-      headers: ['Field', 'Type', 'Required', 'Description'],
-      rows,
-    });
-  }
+  const table = schemaFieldTable(doc.fields ?? []);
+  if (table) content.push(table);
   for (const example of doc.examples ?? []) {
-    if (typeof example?.code !== 'string' || example.code.trim() === '') continue;
+    if (typeof example?.code !== 'string' || example.code.trim() === '')
+      continue;
     content.push({
       type: 'code',
       lang: example.lang ?? 'js',

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -60,32 +60,48 @@ describe('authoring self-docs', () => {
   );
 });
 
-describe('what the authoring docs say about the unbuilt docs graph', () => {
-  it('marks exactly the fields topic loading rejects as not read yet', () => {
+describe('what the authoring docs say about the docs tree', () => {
+  it('marks exactly the fields the docs tree does not read yet', () => {
     const notReadYet = graphFieldsDoc.fields
       .filter(field => /Not read yet/.test(field.description))
       .map(field => field.name);
-    expect(notReadYet.sort()).toEqual([...GRAPH_ONLY_FIELDS].sort());
+    // The tree reads `placement` for every guide (spec:AST-046); the other
+    // graph fields are still refused by every topic reader.
+    expect(notReadYet.sort()).toEqual(
+      GRAPH_ONLY_FIELDS.filter(field => field !== 'placement').sort(),
+    );
     for (const field of graphFieldsDoc.fields) {
-      if (notReadYet.includes(field.name)) {
+      if (GRAPH_ONLY_FIELDS.includes(field.name)) {
         expect(field.description).toMatch(/fails to load/);
       }
     }
+    const placement = graphFieldsDoc.fields.find(f => f.name === 'placement');
+    expect(placement.description).toMatch(
+      /Read for every guide, the CLI's and each integration's/,
+    );
     expect(graphFieldsDoc.description).toMatch(/not built yet/);
   });
 
-  it('says a topic using a graph block fails to load', () => {
+  it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {
     const content = referenceDoc.fields
       .flatMap(field => [field, ...(field.fields ?? [])])
       .find(field => field.name === 'sections[].content');
+    expect(content.type).toBe('(ReferenceContentBlock | ReferenceDocBlock)[]');
+    expect(content.description).toContain('GraphContentBlock');
     for (const type of GRAPH_BLOCK_TYPES) {
       expect(content.description).toContain(type);
     }
-    expect(content.description).toMatch(/fails to load/);
+    // A section's reference block reads as the doc it includes.
+    expect(GRAPH_BLOCK_TYPES.has('reference')).toBe(false);
+    expect(content.description).toMatch(
+      /A `reference` block .* includes another doc/,
+    );
   });
 
-  it('says namespace docs are not loaded yet', () => {
-    expect(namespaceDoc.description).toMatch(/Not loaded yet/);
+  it('says where namespace docs live: the CLI tree, and each integration', () => {
+    expect(namespaceDoc.description).toMatch(
+      /an integration ships its own in its docs directory/,
+    );
     expect(
       problemsInTopic({
         ...namespaceDoc.examples?.[0],
@@ -93,7 +109,7 @@ describe('what the authoring docs say about the unbuilt docs graph', () => {
         name: 'x',
       }),
     ).toEqual([
-      '"x" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.',
+      '"x" is a namespace doc, which the docs tree reads, not the topic list. The CLI keeps its own in assets/docs/tree; an integration ships its namespace docs in its docs directory.',
     ]);
   });
 });

package/foundation/discovery/authoring-surface.d.mts

@@ -0,0 +1,74 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every type `@astryxdesign/cli/authoring` exports, in the order index.d.ts
+ * lists them, each traced to the module that declares it. A value export that
+ * traces to a JavaScript module (a parser) is not a type and is left out;
+ * anything else that cannot be traced is reported, never dropped.
+ * @param {string} [root]
+ * @returns {{
+ *   types: {name: string, module: string}[],
+ *   untraced: {name: string, reason: string}[],
+ * }} `module` is relative to `root`
+ */
+export function tracePublicAuthoringTypes(root?: string): {
+    types: {
+        name: string;
+        module: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+};
+/**
+ * What stands between each type `@astryxdesign/cli/authoring` exports and a
+ * reader of `astryx docs authoring`. A type is readable when a self-doc beside
+ * the module that declares it is listed in AUTHORING_SELF_DOCS, loads, and
+ * renders a section the topic's index lists. A registered self-doc must
+ * document something public: a public type declared beside it, and, when its
+ * title is the name of a type declared beside it, that type.
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   that comparison.
+ * @returns {Promise<{
+ *   types: number,
+ *   unreadable: {module: string, names: string[], reason: UnreadableReason, source?: string, key?: string}[],
+ *   untraced: {name: string, reason: string}[],
+ *   unmatched: {source: string, key?: string, subject?: string}[],
+ * }>}
+ */
+export function auditAuthoringSurface({ root, sources, topicKeys, }?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<{
+    types: number;
+    unreadable: {
+        module: string;
+        names: string[];
+        reason: UnreadableReason;
+        source?: string;
+        key?: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+    unmatched: {
+        source: string;
+        key?: string;
+        subject?: string;
+    }[];
+}>;
+/** The barrel the `types` condition of `@astryxdesign/cli/authoring` names. */
+export const AUTHORING_SURFACE: "index.d.ts";
+export type Tracer = {
+    root: string;
+    /**
+     * top-level statements by absolute path
+     */
+    parsed: Map<string, any[]>;
+};
+export type UnreadableReason = "no-self-doc" | "unregistered" | "failed" | "missing-section";