@astryxdesign/cli 0.4.5 → 0.4.6-canary.cea9ecd

package/foundation/config/project.test.mjs

@@ -24,6 +24,7 @@ function scaffold({
   withCodemods = true,
   brokenComponent = false,
   brokenCodemod = false,
+  docs = null,
   integrationIssuesUrl = 'https://example.com/widgets/issues',
 } = {}) {
   fs.writeFileSync(
@@ -48,6 +49,7 @@ function scaffold({
   if (withComponents) manifest.components = './components';
   if (withTemplates) manifest.templates = './templates';
   if (withCodemods) manifest.codemods = './codemods';
+  if (docs) manifest.docs = './docs';
   if (integrationIssuesUrl) manifest.issuesUrl = integrationIssuesUrl;
   fs.writeFileSync(
     path.join(pkgDir, 'astryx.integration.mjs'),
@@ -99,9 +101,34 @@ function scaffold({
     }
   }
 
+  if (docs) {
+    const docsDir = path.join(pkgDir, 'docs');
+    fs.mkdirSync(docsDir, {recursive: true});
+    for (const [file, doc] of Object.entries(docs)) {
+      fs.writeFileSync(
+        path.join(docsDir, file),
+        typeof doc === 'string'
+          ? doc
+          : `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
+      );
+    }
+  }
+
   return pkgDir;
 }
 
+/** A minimal, valid topic for the docs-root fixtures. */
+function topicDoc(fields) {
+  return {
+    type: 'generic',
+    name: 'deploying',
+    title: 'Deploying',
+    description: 'How to ship it.',
+    sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}],
+    ...fields,
+  };
+}
+
 beforeEach(() => {
   originalCwd = process.cwd();
   tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-project-test-'));
@@ -198,6 +225,45 @@ describe('Project discovery', () => {
     expect(integration[0].codemods[0].id).toBe('drop-foo');
   });
 
+  it('docs() adds an integration topic beside the built-in ones', async () => {
+    scaffold({docs: {'deploying.doc.mjs': topicDoc()}});
+    const project = await Project.load(tmpDir);
+    const catalog = await project.docs();
+    expect(catalog.resolve('deploying')).toMatchObject({
+      name: 'deploying',
+      package: '@acme/widgets',
+    });
+    // The CLI's own topics are still there.
+    expect(catalog.resolve('tokens').package).toBe('@astryxdesign/cli');
+    expect(await project.issues()).toEqual([]);
+  });
+
+  it('docs() lets an integration replace a built-in topic, aliasing the old name', async () => {
+    scaffold({
+      docs: {
+        'setup.doc.mjs': topicDoc({name: 'setup', replaces: 'getting-started'}),
+      },
+    });
+    const project = await Project.load(tmpDir);
+    const catalog = await project.docs();
+    expect(catalog.resolve('setup').package).toBe('@acme/widgets');
+    expect(catalog.resolve('getting-started').name).toBe('setup');
+  });
+
+  it('docs() records an unusable topic as an issue and contributes none', async () => {
+    scaffold({
+      docs: {
+        'ok.doc.mjs': topicDoc(),
+        'broken.doc.mjs': topicDoc({name: 'broken', sections: []}),
+      },
+    });
+    const project = await Project.load(tmpDir);
+    const catalog = await project.docs();
+    expect(catalog.resolve('deploying')).toBeUndefined();
+    const issues = await project.issues();
+    expect(issues.some(i => i.code === 'invalid_doc' && i.severity === 'error')).toBe(true);
+  });
+
   it('memoizes components() — the second call does not re-walk', async () => {
     scaffold();
     const project = await Project.load(tmpDir);

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

@@ -0,0 +1,185 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {object} DocsTopicRecord A doc file discovered under a docs root.
+ * @property {string} name
+ * @property {string} package owner package
+ * @property {string} path absolute path to the doc file
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {string|null} [category]
+ * @property {string} [replaces] topic this doc takes the place of
+ * @property {string} [extendsTopic] topic this doc merges onto (`extends`)
+ */
+/**
+ * @typedef {object} DocsTopicEntry A resolved topic in the catalog.
+ * @property {string} name
+ * @property {string} package owner package
+ * @property {string} path absolute path to the doc file
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {string|null} [category]
+ * @property {string} [replaces] the topic this one took the place of
+ * @property {Array<{package: string, path: string}>} extensions overlays to
+ *   merge onto the base doc, in the order their integrations were configured
+ */
+/**
+ * Discover the CLI's own topics.
+ * @returns {Record<string, string>} topic name → absolute doc path
+ */
+export function discoverBuiltinTopics(): Record<string, string>;
+/**
+ * Load a topic doc from disk. A `.ts` doc is loaded through jiti, the rest
+ * natively; both the historical `export const docs` and the stamped
+ * `export default` forms are accepted, because core authors the first and the
+ * integration guide documents the second.
+ *
+ * @param {string} file absolute path to a doc file
+ * @returns {Promise<unknown>} the authored doc value
+ */
+export function loadTopicModule(file: string): Promise<unknown>;
+/**
+ * Check the fields the docs surfaces actually read. `parseDoc` is the outer
+ * gate, but the reference-doc schema is a passthrough over `{name, type}` —
+ * a doc with no `sections`, or a prose block whose `text` is misspelled,
+ * passes it and reaches a reader as a missing section or a blank gap. Those
+ * are hard to trace back from the rendered output, so they are caught here,
+ * where the file that needs fixing can be named.
+ *
+ * @param {any} doc a parsed doc
+ * @returns {string[]} problems, each already pointed at a place in the doc
+ */
+export function problemsInTopic(doc: any): string[];
+/**
+ * Discover the topics contributed by a single loaded integration. Mirrors
+ * `discoverIntegrationComponents`: walk the resolved root, take every
+ * conventional doc file, and record what it declares. Unlike component
+ * discovery this loads each doc, because a topic's name and its relationship
+ * to an existing topic are fields inside the file.
+ *
+ * Errors are returned, not thrown: one unusable doc is reported as an issue
+ * against its package while the rest of the CLI keeps working.
+ *
+ * @param {{name: string, docs?: string}} integration a loaded integration
+ * @returns {Promise<{records: DocsTopicRecord[], errors: Error[]}>}
+ */
+export function discoverIntegrationDocs(integration: {
+    name: string;
+    docs?: string;
+}): Promise<{
+    records: DocsTopicRecord[];
+    errors: Error[];
+}>;
+/**
+ * Merge an extension onto a base topic: a section whose title matches one in
+ * the base replaces it, a section the base does not have is appended, and the
+ * title/description are taken from the extension when it states them.
+ *
+ * Keyed by section TITLE rather than by position, the way the localization
+ * overlays are — position keying grafts an overlay onto whichever section
+ * happens to share its index, so a partial or reordered overlay corrupts
+ * everything after it (#2182).
+ *
+ * @param {any} base
+ * @param {any} overlay
+ * @returns {any} a new doc; neither input is mutated
+ */
+export function mergeTopic(base: any, overlay: any): any;
+/**
+ * Owner package recorded for the built-in topics. They ship inside the CLI
+ * (assets/docs), not in @astryxdesign/core, so this is the CLI's own name —
+ * unlike component discovery, whose built-ins belong to core.
+ */
+export const BUILTIN_DOCS_PACKAGE: "@astryxdesign/cli";
+/**
+ * Every topic a project can read, and the relationships between them.
+ *
+ * Insertion order is the read order: the built-in topics in discovery order,
+ * then whatever the configured integrations add, in the order they are
+ * configured. A replacement keeps the position of the topic it replaced, so
+ * "the first topic" stays stable for a reader that opens it by default.
+ */
+export class DocsCatalog {
+    /**
+     * Seed a catalog with the CLI's own topics.
+     * @param {Record<string, string>} [builtins] topic name → absolute path
+     * @returns {DocsCatalog}
+     */
+    static fromBuiltins(builtins?: Record<string, string>): DocsCatalog;
+    /**
+     * Add one integration-contributed doc, honoring what it declares. Returns
+     * the issue it caused, or null when it applied cleanly — the caller owns
+     * routing (an `error` skips the contribution, a `warning` keeps it).
+     *
+     * @param {DocsTopicRecord} record
+     * @returns {import('../integrations/issue').AstryxIntegrationIssue | null}
+     */
+    add(record: DocsTopicRecord): import("../integrations/issue").AstryxIntegrationIssue | null;
+    /**
+     * Look a topic up by name, case-insensitively, following the alias a renamed
+     * replacement left behind.
+     * @param {unknown} name
+     * @returns {DocsTopicEntry | undefined}
+     */
+    resolve(name: unknown): DocsTopicEntry | undefined;
+    /** @returns {string[]} every topic name, in read order */
+    names(): string[];
+    /** @returns {DocsTopicEntry[]} every topic, in read order */
+    entries(): DocsTopicEntry[];
+    #private;
+}
+/**
+ * A doc file discovered under a docs root.
+ */
+export type DocsTopicRecord = {
+    name: string;
+    /**
+     * owner package
+     */
+    package: string;
+    /**
+     * absolute path to the doc file
+     */
+    path: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    category?: string | null | undefined;
+    /**
+     * topic this doc takes the place of
+     */
+    replaces?: string | undefined;
+    /**
+     * topic this doc merges onto (`extends`)
+     */
+    extendsTopic?: string | undefined;
+};
+/**
+ * A resolved topic in the catalog.
+ */
+export type DocsTopicEntry = {
+    name: string;
+    /**
+     * owner package
+     */
+    package: string;
+    /**
+     * absolute path to the doc file
+     */
+    path: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    category?: string | null | undefined;
+    /**
+     * the topic this one took the place of
+     */
+    replaces?: string | undefined;
+    /**
+     * overlays to
+     * merge onto the base doc, in the order their integrations were configured
+     */
+    extensions: Array<{
+        package: string;
+        path: string;
+    }>;
+};