@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.b333c39

package/api/docs/detail/section/section.mjs

@@ -4,14 +4,15 @@
  * @file docs.detail.section leaf — load a single section of a topic.
  *
  * @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- *   and loads the topic via the shared adapter, then finds the section by its
- *   stable key, then by exact title, then by a title that contains the query.
+ *   the topic via the shared adapter, finds the section in its lowered compiled
+ *   node by its stable key, then by exact title, then by a title that contains
+ *   the query, and links only that section.
  * @output { type: 'docs.detail.section', data: ReferenceSection } with any
  *   token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
  *   Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
  *   more than one section (the candidates come back as suggestions).
- * @position Leaf nested under api/docs/detail. Shares discovery/loading/
- *   topic-resolution with the detail leaf via _adapter.mjs.
+ * @position Leaf nested under api/docs/detail. Shares topic resolution with the
+ *   detail leaf via _adapter.mjs and reads through the compiler's lenses.
  */
 
 import {AstryxError} from '../../../error.mjs';
@@ -20,8 +21,12 @@ import {
   findDocSection,
   sectionKey,
 } from '../../../../foundation/discovery/docs-section-key.mjs';
-import {resolveTopicDocs} from '../../_adapter.mjs';
-import {resolveTokenRefs} from '../detail.mjs';
+import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
+import {
+  readerSections,
+  sectionView,
+} from '../../../../foundation/doc-compiler/lenses.mjs';
+import {referenceTargets, resolveTopicDocs} from '../../_adapter.mjs';
 
 /**
  * @param {string} topic
@@ -44,31 +49,30 @@ export async function section(topic, sectionName, options = {}) {
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
-  const {catalog, docsData, lang} = await resolveTopicDocs(topic, options);
 
-  const {section: match, candidates} = findDocSection(
-    docsData.sections,
-    sectionName,
-  );
+  const {catalog, node, lang} = await resolveTopicDocs(topic, options);
+  const sections = readerSections(node);
+  const {section: match, candidates} = findDocSection(sections, sectionName);
   if (!match) {
     const ambiguous = candidates.length > 1;
     throw new AstryxError(
       ambiguous
         ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
         : `Section "${sectionName}" not found in "${topic}"`,
-      (ambiguous ? candidates : docsData.sections).map(s => ({
+      (ambiguous ? candidates : sections).map(s => ({
         name: sectionKey(s),
         reason: s.title,
       })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
+
   // A section read on its own inlines its token refs, as the whole topic does;
-  // otherwise a section that is only a token-ref prints blank.
-  const {sections} = await resolveTokenRefs(
-    {...docsData, sections: [match]},
-    catalog,
-    {lang},
+  // otherwise a section that is only a token-ref prints blank. Only this
+  // section is linked, so a broken reference elsewhere cannot fail the read.
+  const linked = await linkReferenceSection(
+    match,
+    referenceTargets(catalog, lang),
   );
-  return {type: 'docs.detail.section', data: sections[0]};
+  return {type: 'docs.detail.section', data: sectionView(node, linked)};
 }

package/api/docs/detail/section/section.test.mjs

@@ -10,7 +10,7 @@
 import {describe, it, expect} from 'vitest';
 import {section} from './section.mjs';
 import {AstryxError} from '../../../error.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../../_adapter.mjs';
+import {loadDocsCatalog, lowerTopic} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -42,7 +42,8 @@ describe('docs.detail.section leaf', () => {
   }, SLOW);
 
   it('reads a section by its stable key', async () => {
-    const doc = await loadTopicDoc((await loadDocsCatalog()).resolve('theme'));
+    const catalog = await loadDocsCatalog();
+    const {doc} = await lowerTopic(catalog, catalog.resolve('theme'));
     const target = doc.sections[doc.sections.length - 1];
     const res = await section('theme', target.id);
     expect(res.data.title).toBe(target.title);
@@ -63,7 +64,7 @@ describe('docs.detail.section leaf', () => {
       const catalog = await loadDocsCatalog();
       let checked = 0;
       for (const entry of catalog.entries()) {
-        const doc = await loadTopicDoc(entry);
+        const {doc} = await lowerTopic(catalog, entry);
         for (const own of doc.sections) {
           if (!own.content.some(block => block.type === 'token-ref')) continue;
           const res = await section(entry.name, own.id, lang ? {lang} : {});

package/api/docs/index/index.mjs

@@ -3,8 +3,9 @@
 /**
  * @file docs.index leaf — the section index of one topic.
  *
- * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves and loads
- *   the topic via the shared adapter.
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves the topic
+ *   via the shared adapter and reads its lowered compiled node; nothing is
+ *   linked, since the index never inlines a token reference.
  * @output { type: 'docs.index', data: DocsIndex } — the topic's name, title and
  *   description and, for each section, the key it is read by, its title, and a
  *   one-line summary. Matches `astryx --json docs <topic> --index`.
@@ -13,7 +14,7 @@
  *   read, is the detail leaf.
  */
 
-import {buildDocsIndexData} from '../../../foundation/discovery/docs-section-key.mjs';
+import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
 import {resolveTopicDocs} from '../_adapter.mjs';
 
 /**
@@ -26,6 +27,6 @@ import {resolveTopicDocs} from '../_adapter.mjs';
  * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
  */
 export async function index(topic, options = {}) {
-  const {docsData} = await resolveTopicDocs(topic, options);
-  return {type: 'docs.index', data: buildDocsIndexData(docsData)};
+  const {node} = await resolveTopicDocs(topic, options);
+  return {type: 'docs.index', data: indexView(node)};
 }

package/api/doctor/doctor.mjs

@@ -34,8 +34,8 @@ import {
   docsIndexBytes,
   oversizedDocSections,
 } from '../../foundation/discovery/docs-output-budget.mjs';
-import {loadTopicDoc, overlayLanguages} from '../docs/_adapter.mjs';
-import {resolveTokenRefs} from '../docs/detail/detail.mjs';
+import {compileTopic, overlayLanguages} from '../docs/_adapter.mjs';
+import {detailView} from '../../foundation/doc-compiler/lenses.mjs';
 import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 /**
@@ -798,11 +798,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
       for (const lang of [null, ...overlayLanguages(entry)]) {
         const where = lang ? `${entry.name} [${lang}]` : entry.name;
         try {
-          const doc = await resolveTokenRefs(
-            await loadTopicDoc(entry, {lang}),
-            catalog,
-            {lang},
-          );
+          const doc = detailView(await compileTopic(catalog, entry, lang));
           if (lang == null) topics += 1;
           const indexBytes = docsIndexBytes(buildDocsIndexData(doc));
           if (indexBytes > DOC_OUTPUT_BUDGET_BYTES) {

package/api/search/search.mjs

@@ -66,7 +66,7 @@ import {
 import {loadIntegrationsSafely} from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
+import {loadDocsCatalog, lowerTopic} from '../docs/_adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {setResultCoverage} from './coverage.mjs';
@@ -732,16 +732,16 @@ async function gatherHooks(coreDir) {
 async function gatherDocs(cwd) {
   /** @type {Candidate[]} */
   const candidates = [];
-  let entries;
+  let catalog;
   try {
-    entries = (await loadDocsCatalog(cwd)).entries();
+    catalog = await loadDocsCatalog(cwd);
   } catch {
     return candidates;
   }
-  for (const entry of entries) {
+  for (const entry of catalog.entries()) {
     let doc = null;
     try {
-      doc = await loadTopicDoc(entry);
+      doc = (await lowerTopic(catalog, entry)).doc;
     } catch {
       // A topic that cannot be loaded is reported by the commands that own
       // integration issues; search just cannot index it.

package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs

@@ -3,7 +3,8 @@
 import {describe, it, expect} from 'vitest';
 
 async function applyTransform(source, path = 'test.ts') {
-  const {default: transform} = await import('../unwrap-authoring-factories.mjs');
+  const {default: transform} =
+    await import('../unwrap-authoring-factories.mjs');
   const jscodeshift = (await import('jscodeshift')).default;
   const j = jscodeshift.withParser('tsx');
   const api = {jscodeshift: j, stats: () => {}, report: () => {}};
@@ -18,7 +19,7 @@ export default createConfig({integrations: ['@acme/widgets']});
 `;
     const output = await applyTransform(input);
     expect(output).not.toContain('createConfig');
-    expect(output).toContain("export default {");
+    expect(output).toContain('export default {');
     expect(output).toContain("integrations: ['@acme/widgets']");
     expect(output).not.toContain('type:');
   });
@@ -132,13 +133,34 @@ export default createComponentDoc();
     expect(output).toContain("type: 'component'");
   });
 
+  it('leaves same-named factories from unrelated packages unchanged', async () => {
+    const input = `import {createConfig} from '@acme/eslint';
+export default createConfig({strict: true});
+`;
+    expect(await applyTransform(input)).toBe(input);
+  });
+
+  it('keeps an unrelated same-named import when another factory is migrated', async () => {
+    const input = `import {createConfig as createLintConfig} from '@acme/eslint';
+import {createDoc} from '@astryxdesign/cli/doc';
+export const lintConfig = createLintConfig({strict: true});
+export const doc = createDoc({name: 'Theming', description: 'How theming works.'});
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import {createConfig as createLintConfig} from '@acme/eslint'",
+    );
+    expect(output).toContain('createLintConfig({strict: true})');
+    expect(output).not.toContain('createDoc');
+    expect(output).toContain("type: 'generic'");
+  });
+
   it('is a no-op when no authoring factory is imported', async () => {
     const input = `import {Button} from '@astryxdesign/core';
 export default Button;
 `;
-    const {default: transform} = await import(
-      '../unwrap-authoring-factories.mjs'
-    );
+    const {default: transform} =
+      await import('../unwrap-authoring-factories.mjs');
     const jscodeshift = (await import('jscodeshift')).default;
     const j = jscodeshift.withParser('tsx');
     const api = {jscodeshift: j, stats: () => {}, report: () => {}};

package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs

@@ -5,8 +5,9 @@
  *
  * v0.3.0 removes the authoring factories. Authoring is now types + parsers: an
  * author writes a plain object and stamps its `type` directly. This transform
- * rewrites every factory call to the plain object the factory used to return,
- * then drops the now-dead factory imports:
+ * rewrites factory calls imported from the retired Astryx authoring entrypoints
+ * to the plain object the factory used to return, then drops the now-dead
+ * factory imports:
  *
  *   createConfig(o) / createIntegration(o)        -> o        (no discriminant)
  *   createComponentDoc(o)                         -> { ...o, type: 'component' }
@@ -25,8 +26,9 @@
  *
  * Import aliases are followed (`import {createDoc as mk}` → calls to `mk`), and
  * the factory specifiers are removed afterward (the whole import statement goes
- * if nothing else was imported from it). Run this BEFORE
- * `migrate-authoring-imports`, which repoints the surviving type imports.
+ * if nothing else was imported from it). Same-named imports from other packages
+ * remain untouched. Run this BEFORE `migrate-authoring-imports`, which repoints
+ * the surviving type imports.
  */
 
 export const meta = {
@@ -35,13 +37,24 @@ export const meta = {
     'Rewrites createConfig/createIntegration/createComponentDoc/' +
     'createFunctionDoc/createDoc/createPageTemplate/createBlockTemplate/' +
     'createCodemod/createConfigCodemod calls to the plain object they returned ' +
-    "(stamping the doc/template/codemod `type` discriminant), and removes the " +
+    '(stamping the doc/template/codemod `type` discriminant), and removes the ' +
     'now-dead factory imports. Authoring is types + parsers in v0.3.0 — there ' +
     'are no factories.',
   pr: '#4612',
   fileExtensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],
 };
 
+/** Legacy Astryx authoring entrypoints that exported the removed factories. */
+const AUTHORING_SOURCES = new Set([
+  '@astryxdesign/cli/config',
+  '@astryxdesign/cli/doc',
+  '@astryxdesign/cli/integration',
+  '@astryxdesign/cli/template',
+  '@astryxdesign/cli/codemod',
+  '@astryxdesign/core/authoring',
+  '@astryxdesign/core/config',
+]);
+
 /**
  * Factory name → the `type` discriminant it stamped, or `null` for the config /
  * integration factories, which were pure typed-identity (no discriminant).
@@ -108,6 +121,7 @@ export default function transformer(file, api) {
   /** @type {Map<string, string>} */
   const localToFactory = new Map();
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     for (const spec of path.node.specifiers ?? []) {
       if (spec.type !== 'ImportSpecifier') continue;
       const importedName = spec.imported?.name;
@@ -163,6 +177,7 @@ export default function transformer(file, api) {
   // Drop the now-dead factory import specifiers; remove any import statement
   // left empty.
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     const specs = path.node.specifiers ?? [];
     const kept = specs.filter(
       (/** @type {any} */ spec) =>

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;
+};