@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9e4c545

package/foundation/discovery/docs-discovery.mjs

@@ -138,7 +138,14 @@ const BLOCK_FIELDS = {
 };
 
 /** Blocks that are valid authoring but require the compiled graph renderer. */
-const GRAPH_BLOCK_TYPES = new Set(['workflow', 'collection', 'reference']);
+export const GRAPH_BLOCK_TYPES = new Set([
+  'workflow',
+  'collection',
+  'reference',
+]);
+
+/** Doc fields only the docs graph reads; a topic that sets one fails to load. */
+export const GRAPH_ONLY_FIELDS = ['placement', 'aliases', 'audience'];
 
 /**
  * Fields a block kind may carry but does not need. Kept per kind rather than
@@ -176,6 +183,13 @@ const SECTION_FIELDS = ['id', 'title', 'category', 'content', 'previewType'];
  * @returns {string[]} problems, each already pointed at a place in the doc
  */
 export function problemsInTopic(doc) {
+  // A namespace doc is valid authoring that only the docs graph reads. Said
+  // plainly, instead of as the topic fields it does not have.
+  if (doc?.type === 'namespace') {
+    return [
+      `"${doc.name}" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.`,
+    ];
+  }
   /** @type {string[]} */
   const problems = [];
   for (const field of ['name', 'title', 'description']) {
@@ -188,7 +202,7 @@ export function problemsInTopic(doc) {
       `name: "${doc.name}" is not URL-safe. A topic name is its CLI argument and its docsite path, so it may hold only letters, digits, "_" and "-".`,
     );
   }
-  for (const field of ['placement', 'aliases', 'audience']) {
+  for (const field of GRAPH_ONLY_FIELDS) {
     if (doc?.[field] != null) {
       problems.push(
         `${field}: requires the compiled graph reader and is not supported by legacy topic readers`,

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

@@ -182,6 +182,26 @@ describe('discoverIntegrationDocs', () => {
     expect(records).toEqual([]);
     expect(errors[0].message).toContain('requires the compiled graph renderer');
   });
+
+  it('names a namespace doc instead of listing topic fields it lacks', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/namespace', {
+        'guides.doc.mjs': {
+          type: 'namespace',
+          name: 'guides',
+          title: 'Guides',
+          summary: 'Every guide.',
+          slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},
+        },
+      }),
+    );
+    expect(records).toEqual([]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain(
+      '"guides" is a namespace doc. Only the docs graph reads namespace docs',
+    );
+    expect(errors[0].message).not.toContain('sections:');
+  });
 });
 
 describe('problemsInTopic', () => {
@@ -500,7 +520,10 @@ describe('problemsInTopic section keys', () => {
     name: 'keys',
     title: 'Keys',
     description: 'Section keys.',
-    sections: sections.map(s => ({content: [{type: 'prose', text: 'x'}], ...s})),
+    sections: sections.map(s => ({
+      content: [{type: 'prose', text: 'x'}],
+      ...s,
+    })),
   });
 
   it('rejects two sections that derive the same key', () => {
@@ -512,18 +535,18 @@ describe('problemsInTopic section keys', () => {
   });
 
   it('rejects an unsafe id', () => {
-    expect(problemsInTopic(doc([{id: 'Quick Start', title: 'Quick Start'}]))).toEqual(
-      [expect.stringContaining('is not a stable key')],
-    );
+    expect(
+      problemsInTopic(doc([{id: 'Quick Start', title: 'Quick Start'}])),
+    ).toEqual([expect.stringContaining('is not a stable key')]);
   });
 
   it('rejects a title no key derives from, unless it has an id', () => {
     expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([
       expect.stringContaining('Give the section an id'),
     ]);
-    expect(problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}]))).toEqual(
-      [],
-    );
+    expect(
+      problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}])),
+    ).toEqual([]);
   });
 });
 
@@ -535,12 +558,17 @@ describe('mergeTopic by section key', () => {
       {title: 'Light/Dark Mode', content: [{type: 'prose', text: 'base'}]},
     ],
   };
-  const titles = doc => doc.sections.map(s => [s.id ?? null, s.title, s.content[0].text]);
+  const titles = doc =>
+    doc.sections.map(s => [s.id ?? null, s.title, s.content[0].text]);
 
   it('replaces the section whose derived key an extension id names', () => {
     const merged = mergeTopic(base, {
       sections: [
-        {id: 'quick-start', title: 'Quick Start with Acme', content: [{type: 'prose', text: 'acme'}]},
+        {
+          id: 'quick-start',
+          title: 'Quick Start with Acme',
+          content: [{type: 'prose', text: 'acme'}],
+        },
       ],
     });
     expect(titles(merged)).toEqual([
@@ -551,7 +579,9 @@ describe('mergeTopic by section key', () => {
 
   it('replaces the section a title variant derives the same key as', () => {
     const merged = mergeTopic(base, {
-      sections: [{title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]}],
+      sections: [
+        {title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]},
+      ],
     });
     expect(titles(merged)).toEqual([
       [null, 'Quick Start', 'base'],
@@ -561,7 +591,13 @@ describe('mergeTopic by section key', () => {
 
   it('prefers the key over a legacy title for an extension with an id', () => {
     const merged = mergeTopic(base, {
-      sections: [{id: 'light-dark-mode', title: 'Quick Start', content: [{type: 'prose', text: 'acme'}]}],
+      sections: [
+        {
+          id: 'light-dark-mode',
+          title: 'Quick Start',
+          content: [{type: 'prose', text: 'acme'}],
+        },
+      ],
     });
     expect(titles(merged)).toEqual([
       [null, 'Quick Start', 'base'],

package/foundation/doc-compiler/compile.d.mts

@@ -0,0 +1,162 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * One authored file, as discovery loaded it.
+ * @typedef {object} AuthoredFile
+ * @property {string} file the file's name, for messages only
+ * @property {any} [doc] the parsed doc, when it loaded
+ * @property {unknown} [error] why it did not load or parse
+ * @property {any} [overlay] the language overlay's export, when one applies
+ * @property {unknown} [overlayError] why the overlay did not load
+ */
+/**
+ * @typedef {object} ReferenceTopicInput
+ * @property {string} id the topic's name in the catalog
+ * @property {string} provider the package that owns the topic
+ * @property {string | null} replaces the topic it took the place of
+ * @property {string | null} lang the overlay language, or null for authored text
+ * @property {AuthoredFile} base
+ * @property {Array<AuthoredFile & {provider: string}>} extensions in merge order
+ */
+/**
+ * A token reference after linking: the target section's content, or why it
+ * has none.
+ * @typedef {{status: 'resolved', topic: string, section: string, previewType?: string, content: any[]}
+ *   | {status: 'unknown-topic'}
+ *   | {status: 'unknown-section'}} TokenRefResolution
+ */
+/**
+ * @typedef {object} CompiledReferenceNode
+ * @property {number} schemaVersion
+ * @property {'reference'} kind
+ * @property {'lowered' | 'linked'} stage `linked` once every token reference
+ *   carries its resolution; a lowered node carries none
+ * @property {string} id the topic's name in the catalog
+ * @property {string | null} lang
+ * @property {{provider: string, replaces: string | null, extensions: string[]}} provenance
+ * @property {Record<string, string>} sourceTitles section key -> authored title
+ * @property {any} doc the topic: authored fields in authored order, every
+ *   section keyed; a linked node's token references carry `resolved`
+ */
+/**
+ * Lower one topic: overlay each file, merge the extensions in order, and stamp
+ * every section with its key.
+ * @param {ReferenceTopicInput} input
+ * @returns {CompiledReferenceNode}
+ */
+export function lowerReferenceTopic(input: ReferenceTopicInput): CompiledReferenceNode;
+/**
+ * Link every section of a lowered node.
+ * @param {CompiledReferenceNode} node
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ *   the lowered node a reference names, or null when no topic has that name
+ * @returns {Promise<CompiledReferenceNode>}
+ */
+export function linkReferenceTopic(node: CompiledReferenceNode, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<CompiledReferenceNode>;
+/**
+ * Resolve the token references in one section. A section with none comes back
+ * as it went in.
+ * @template {{content: any[]}} S
+ * @param {S} section
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ * @returns {Promise<S>}
+ */
+export function linkReferenceSection<S extends {
+    content: any[];
+}>(section: S, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<S>;
+/** Bumped whenever the shape of a compiled node changes. */
+export const COMPILED_DOC_SCHEMA_VERSION: 1;
+/**
+ * One authored file, as discovery loaded it.
+ */
+export type AuthoredFile = {
+    /**
+     * the file's name, for messages only
+     */
+    file: string;
+    /**
+     * the parsed doc, when it loaded
+     */
+    doc?: any;
+    /**
+     * why it did not load or parse
+     */
+    error?: unknown;
+    /**
+     * the language overlay's export, when one applies
+     */
+    overlay?: any;
+    /**
+     * why the overlay did not load
+     */
+    overlayError?: unknown;
+};
+export type ReferenceTopicInput = {
+    /**
+     * the topic's name in the catalog
+     */
+    id: string;
+    /**
+     * the package that owns the topic
+     */
+    provider: string;
+    /**
+     * the topic it took the place of
+     */
+    replaces: string | null;
+    /**
+     * the overlay language, or null for authored text
+     */
+    lang: string | null;
+    base: AuthoredFile;
+    /**
+     * in merge order
+     */
+    extensions: Array<AuthoredFile & {
+        provider: string;
+    }>;
+};
+/**
+ * A token reference after linking: the target section's content, or why it
+ * has none.
+ */
+export type TokenRefResolution = {
+    status: "resolved";
+    topic: string;
+    section: string;
+    previewType?: string;
+    content: any[];
+} | {
+    status: "unknown-topic";
+} | {
+    status: "unknown-section";
+};
+export type CompiledReferenceNode = {
+    schemaVersion: number;
+    kind: "reference";
+    /**
+     * `linked` once every token reference
+     * carries its resolution; a lowered node carries none
+     */
+    stage: "lowered" | "linked";
+    /**
+     * the topic's name in the catalog
+     */
+    id: string;
+    lang: string | null;
+    provenance: {
+        provider: string;
+        replaces: string | null;
+        extensions: string[];
+    };
+    /**
+     * section key -> authored title
+     */
+    sourceTitles: Record<string, string>;
+    /**
+     * the topic: authored fields in authored order, every
+     * section keyed; a linked node's token references carry `resolved`
+     */
+    doc: any;
+};

package/foundation/doc-compiler/compile.mjs

@@ -0,0 +1,262 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Doc compiler — authored reference topics in, compiled nodes out.
+ *
+ * @input A {@link ReferenceTopicInput}: one topic's own file and the files of
+ *   the extensions merged onto it, each already through the authored-doc parser
+ *   and each carrying the overlay for the language being read. Discovery
+ *   assembles it, and records a file that failed to load instead of throwing,
+ *   so problems surface here in the order a reader meets them.
+ * @output A compiled reference node: plain JSON carrying a schema version, the
+ *   topic after overlay, extension merge and key stamping, and the authored
+ *   title of every section. Linking then resolves each token reference against
+ *   its target. Nothing in a node is a function, a symbol, or a file path: an
+ *   authored value JSON cannot hold (a function, a Date, `undefined`) takes its
+ *   JSON form, the one `--json` output has always shown.
+ * @position The one step between authored docs and every docs reader. The docs
+ *   API, doctor and search read compiled nodes, and ./lenses.mjs turns them into
+ *   response shapes. Internal to the CLI: the public way in is `docs()`.
+ */
+
+import {mergeTopic, problemsInTopic} from '../discovery/docs-discovery.mjs';
+import {
+  sectionKey,
+  sectionKeyProblems,
+  sourceTitle,
+  withSectionKeys,
+  withSourceTitle,
+} from '../discovery/docs-section-key.mjs';
+
+/** Bumped whenever the shape of a compiled node changes. */
+export const COMPILED_DOC_SCHEMA_VERSION = 1;
+
+/**
+ * One authored file, as discovery loaded it.
+ * @typedef {object} AuthoredFile
+ * @property {string} file the file's name, for messages only
+ * @property {any} [doc] the parsed doc, when it loaded
+ * @property {unknown} [error] why it did not load or parse
+ * @property {any} [overlay] the language overlay's export, when one applies
+ * @property {unknown} [overlayError] why the overlay did not load
+ */
+
+/**
+ * @typedef {object} ReferenceTopicInput
+ * @property {string} id the topic's name in the catalog
+ * @property {string} provider the package that owns the topic
+ * @property {string | null} replaces the topic it took the place of
+ * @property {string | null} lang the overlay language, or null for authored text
+ * @property {AuthoredFile} base
+ * @property {Array<AuthoredFile & {provider: string}>} extensions in merge order
+ */
+
+/**
+ * A token reference after linking: the target section's content, or why it
+ * has none.
+ * @typedef {{status: 'resolved', topic: string, section: string, previewType?: string, content: any[]}
+ *   | {status: 'unknown-topic'}
+ *   | {status: 'unknown-section'}} TokenRefResolution
+ */
+
+/**
+ * @typedef {object} CompiledReferenceNode
+ * @property {number} schemaVersion
+ * @property {'reference'} kind
+ * @property {'lowered' | 'linked'} stage `linked` once every token reference
+ *   carries its resolution; a lowered node carries none
+ * @property {string} id the topic's name in the catalog
+ * @property {string | null} lang
+ * @property {{provider: string, replaces: string | null, extensions: string[]}} provenance
+ * @property {Record<string, string>} sourceTitles section key -> authored title
+ * @property {any} doc the topic: authored fields in authored order, every
+ *   section keyed; a linked node's token references carry `resolved`
+ */
+
+/**
+ * Lower one topic: overlay each file, merge the extensions in order, and stamp
+ * every section with its key.
+ * @param {ReferenceTopicInput} input
+ * @returns {CompiledReferenceNode}
+ */
+export function lowerReferenceTopic(input) {
+  let doc = readAuthoredFile(input.base);
+  for (const extension of input.extensions) {
+    doc = mergeTopic(doc, readAuthoredFile(extension));
+    // Merging matches on keys, so this holds unless merge itself regresses.
+    const problems = sectionKeyProblems(doc.sections);
+    if (problems.length > 0) {
+      throw new Error(
+        `${extension.file}, extending ${input.id}, leaves two sections with one key: ${problems.join('; ')}`,
+      );
+    }
+  }
+  // Derived keys are stamped only now, so they never take part in merging.
+  const keyed = withSectionKeys(doc);
+  /** @type {Record<string, string>} */
+  const sourceTitles = {};
+  for (const section of keyed.sections) {
+    sourceTitles[section.id] = sourceTitle(section);
+  }
+  return {
+    schemaVersion: COMPILED_DOC_SCHEMA_VERSION,
+    kind: 'reference',
+    stage: 'lowered',
+    id: input.id,
+    lang: input.lang,
+    provenance: {
+      provider: input.provider,
+      replaces: input.replaces,
+      extensions: input.extensions.map(extension => extension.provider),
+    },
+    sourceTitles,
+    // The authored title travels in sourceTitles; JSON drops the symbol.
+    doc: asJson(keyed, input.id),
+  };
+}
+
+/**
+ * Link every section of a lowered node.
+ * @param {CompiledReferenceNode} node
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ *   the lowered node a reference names, or null when no topic has that name
+ * @returns {Promise<CompiledReferenceNode>}
+ */
+export async function linkReferenceTopic(node, lowerTarget) {
+  const sections = [];
+  for (const section of node.doc.sections) {
+    sections.push(await linkReferenceSection(section, lowerTarget));
+  }
+  return {...node, stage: 'linked', doc: {...node.doc, sections}};
+}
+
+/**
+ * Resolve the token references in one section. A section with none comes back
+ * as it went in.
+ * @template {{content: any[]}} S
+ * @param {S} section
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ * @returns {Promise<S>}
+ */
+export async function linkReferenceSection(section, lowerTarget) {
+  if (!section.content.some(block => block?.type === 'token-ref')) {
+    return section;
+  }
+  const content = [];
+  for (const block of section.content) {
+    content.push(
+      block?.type === 'token-ref'
+        ? {...block, resolved: await resolveTokenRef(block, lowerTarget)}
+        : block,
+    );
+  }
+  return {...section, content};
+}
+
+/**
+ * The section a token reference names — by key, or by authored title in any
+ * letter case — in the target topic lowered for the same language.
+ * @param {any} block
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ * @returns {Promise<TokenRefResolution>}
+ */
+async function resolveTokenRef(block, lowerTarget) {
+  const target = await lowerTarget(block.topic);
+  if (!target) return {status: 'unknown-topic'};
+  const wanted = block.section.toLowerCase();
+  const found = target.doc.sections.find(
+    (/** @type {any} */ section) =>
+      sectionKey(section) === block.section ||
+      (target.sourceTitles[section.id] ?? section.title).toLowerCase() ===
+        wanted,
+  );
+  if (!found) return {status: 'unknown-section'};
+  return {
+    status: 'resolved',
+    topic: target.id,
+    section: found.id,
+    ...(found.previewType ? {previewType: found.previewType} : {}),
+    content: found.content,
+  };
+}
+
+/**
+ * A value as JSON carries it: functions, symbols and `undefined` dropped,
+ * Dates as ISO strings.
+ * @param {any} value
+ * @param {string} topic for the message when the value cannot be serialized
+ * @returns {any}
+ */
+function asJson(value, topic) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (err) {
+    throw new Error(
+      `${topic} cannot be compiled: ${err instanceof Error ? err.message : String(err)}`,
+      {cause: err},
+    );
+  }
+}
+
+/**
+ * One file's doc, checked and in the reading language. Problems throw in the
+ * order a reader meets them: the file itself, then its overlay.
+ * @param {AuthoredFile} file
+ * @returns {any}
+ */
+function readAuthoredFile(file) {
+  if ('error' in file) throw file.error;
+  const parsed = file.doc;
+  if (!('sections' in parsed)) {
+    throw new Error(`${file.file} is not a reference document.`);
+  }
+  const problems = problemsInTopic(parsed);
+  if (problems.length > 0) {
+    throw new Error(`${file.file} is invalid: ${problems.join('; ')}`);
+  }
+  if ('overlayError' in file) throw file.overlayError;
+  return file.overlay ? applyOverlay(parsed, file.overlay) : parsed;
+}
+
+/**
+ * Lay a translation over a doc. Overlays are keyed to a base section by title
+ * (`section`), not by array position: position keying grafted each overlay
+ * title onto whatever base section shared its index, so an overlay that omitted
+ * or reordered a section corrupted every section after it (#2182). An overlay
+ * may cover any subset of sections, in any order; the rest keep their base
+ * content.
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
+function applyOverlay(docs, translation) {
+  /** @type {Map<string, any>} */
+  const bySection = new Map();
+  for (const ts of translation.sections ?? []) {
+    if (ts?.section != null) bySection.set(ts.section, ts);
+  }
+  return {
+    ...docs,
+    description: translation.description || docs.description,
+    sections: docs.sections.map((/** @type {any} */ section) => {
+      const ts = bySection.get(section.title);
+      if (!ts) return section;
+      const localized = {
+        ...section,
+        title: ts.title || section.title,
+        content: section.content.map(
+          (/** @type {any} */ block, /** @type {number} */ bi) => {
+            const tb = ts.content?.[bi];
+            if (!tb) return block;
+            if (tb.type === 'prose' && block.type === 'prose')
+              return {...block, text: tb.text};
+            if (tb.type === 'list' && block.type === 'list')
+              return {...block, items: tb.items};
+            return block;
+          },
+        ),
+      };
+      return withSourceTitle(localized, section.title);
+    }),
+  };
+}