@astryxdesign/cli 0.6.3-canary.8f908ec → 0.6.3-canary.98a2e4e

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, lowerTopic} from '../../_adapter.mjs';
+import {loadDocsCatalog, loadTopicDoc} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -42,8 +42,7 @@ describe('docs.detail.section leaf', () => {
   }, SLOW);
 
   it('reads a section by its stable key', async () => {
-    const catalog = await loadDocsCatalog();
-    const {doc} = await lowerTopic(catalog, catalog.resolve('theme'));
+    const doc = await loadTopicDoc((await loadDocsCatalog()).resolve('theme'));
     const target = doc.sections[doc.sections.length - 1];
     const res = await section('theme', target.id);
     expect(res.data.title).toBe(target.title);
@@ -64,7 +63,7 @@ describe('docs.detail.section leaf', () => {
       const catalog = await loadDocsCatalog();
       let checked = 0;
       for (const entry of catalog.entries()) {
-        const {doc} = await lowerTopic(catalog, entry);
+        const doc = await loadTopicDoc(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,9 +3,8 @@
 /**
  * @file docs.index leaf — the section index of one topic.
  *
- * @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.
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves and loads
+ *   the topic via the shared adapter.
  * @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`.
@@ -14,7 +13,7 @@
  *   read, is the detail leaf.
  */
 
-import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
+import {buildDocsIndexData} from '../../../foundation/discovery/docs-section-key.mjs';
 import {resolveTopicDocs} from '../_adapter.mjs';
 
 /**
@@ -27,6 +26,6 @@ import {resolveTopicDocs} from '../_adapter.mjs';
  * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
  */
 export async function index(topic, options = {}) {
-  const {node} = await resolveTopicDocs(topic, options);
-  return {type: 'docs.index', data: indexView(node)};
+  const {docsData} = await resolveTopicDocs(topic, options);
+  return {type: 'docs.index', data: buildDocsIndexData(docsData)};
 }

package/api/doctor/doctor.mjs

@@ -34,8 +34,8 @@ import {
   docsIndexBytes,
   oversizedDocSections,
 } from '../../foundation/discovery/docs-output-budget.mjs';
-import {compileTopic, overlayLanguages} from '../docs/_adapter.mjs';
-import {detailView} from '../../foundation/doc-compiler/lenses.mjs';
+import {loadTopicDoc, overlayLanguages} from '../docs/_adapter.mjs';
+import {resolveTokenRefs} from '../docs/detail/detail.mjs';
 import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 /**
@@ -798,7 +798,11 @@ export async function checkDocsProgressiveDisclosure(ctx) {
       for (const lang of [null, ...overlayLanguages(entry)]) {
         const where = lang ? `${entry.name} [${lang}]` : entry.name;
         try {
-          const doc = detailView(await compileTopic(catalog, entry, lang));
+          const doc = await resolveTokenRefs(
+            await loadTopicDoc(entry, {lang}),
+            catalog,
+            {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, lowerTopic} from '../docs/_adapter.mjs';
+import {loadDocsCatalog, loadTopicDoc} 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 catalog;
+  let entries;
   try {
-    catalog = await loadDocsCatalog(cwd);
+    entries = (await loadDocsCatalog(cwd)).entries();
   } catch {
     return candidates;
   }
-  for (const entry of catalog.entries()) {
+  for (const entry of entries) {
     let doc = null;
     try {
-      doc = (await lowerTopic(catalog, entry)).doc;
+      doc = await loadTopicDoc(entry);
     } 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,8 +3,7 @@
 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: () => {}};
@@ -19,7 +18,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:');
   });
@@ -133,34 +132,13 @@ 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,9 +5,8 @@
  *
  * 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 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:
+ * rewrites every factory call 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' }
@@ -26,9 +25,8 @@
  *
  * 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). Same-named imports from other packages
- * remain untouched. Run this BEFORE `migrate-authoring-imports`, which repoints
- * the surviving type imports.
+ * if nothing else was imported from it). Run this BEFORE
+ * `migrate-authoring-imports`, which repoints the surviving type imports.
  */
 
 export const meta = {
@@ -37,24 +35,13 @@ 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).
@@ -121,7 +108,6 @@ 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;
@@ -177,7 +163,6 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.6.3-canary.8f908ec",
+  "version": "0.6.3-canary.98a2e4e",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -100,10 +100,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.6.3-canary.8f908ec",
-    "@astryxdesign/core": "0.6.3-canary.8f908ec",
-    "@astryxdesign/lab": "0.6.3-canary.8f908ec",
-    "@astryxdesign/theme-neutral": "0.6.3-canary.8f908ec",
+    "@astryxdesign/charts": "0.6.3-canary.98a2e4e",
+    "@astryxdesign/core": "0.6.3-canary.98a2e4e",
+    "@astryxdesign/lab": "0.6.3-canary.98a2e4e",
+    "@astryxdesign/theme-neutral": "0.6.3-canary.98a2e4e",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.6.3-canary.8f908ec",
-    "@astryxdesign/core": "0.6.3-canary.8f908ec",
-    "@astryxdesign/lab": "0.6.3-canary.8f908ec",
-    "@astryxdesign/theme-neutral": "0.6.3-canary.8f908ec",
+    "@astryxdesign/charts": "0.6.3-canary.98a2e4e",
+    "@astryxdesign/core": "0.6.3-canary.98a2e4e",
+    "@astryxdesign/lab": "0.6.3-canary.98a2e4e",
+    "@astryxdesign/theme-neutral": "0.6.3-canary.98a2e4e",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",

package/api/docs/compiled-topics.test.mjs

@@ -1,78 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Every shipped topic compiles to a plain-JSON node that answers every
- * docs read exactly as the live one does, and no read can change another read
- * of the same catalog.
- */
-
-import {describe, expect, it} from 'vitest';
-import {parseCompiledReferenceNode} from '../../foundation/doc-compiler/ir.mjs';
-import {detailView, indexView} from '../../foundation/doc-compiler/lenses.mjs';
-import {
-  compileTopic,
-  loadDocsCatalog,
-  lowerTopic,
-  overlayLanguages,
-} from './_adapter.mjs';
-
-const SLOW = 60_000;
-
-describe('every shipped topic compiles to plain JSON', () => {
-  it(
-    'survives a JSON round trip with identical responses in every language',
-    async () => {
-      const catalog = await loadDocsCatalog();
-      let compiled = 0;
-      for (const entry of catalog.entries()) {
-        for (const lang of [null, ...overlayLanguages(entry)]) {
-          const lowered = await lowerTopic(catalog, entry, lang);
-          expect(parseCompiledReferenceNode(lowered)).toBe(lowered);
-          const node = await compileTopic(catalog, entry, lang);
-          expect(parseCompiledReferenceNode(node)).toBe(node);
-          const copy = parseCompiledReferenceNode(
-            JSON.parse(JSON.stringify(node)),
-          );
-          expect(JSON.stringify(detailView(copy))).toBe(
-            JSON.stringify(detailView(node)),
-          );
-          expect(JSON.stringify(indexView(copy))).toBe(
-            JSON.stringify(indexView(node)),
-          );
-          compiled += 1;
-        }
-      }
-      expect(compiled).toBeGreaterThan(catalog.entries().length);
-    },
-    SLOW,
-  );
-});
-
-describe('reads that share a catalog', () => {
-  it(
-    'never let one read change another',
-    async () => {
-      const catalog = await loadDocsCatalog();
-      const tokens = catalog.resolve('tokens');
-      const first = detailView(await compileTopic(catalog, tokens));
-      for (const section of first.sections) {
-        section.title = 'EDITED';
-        for (const block of section.content) {
-          if (typeof block.text === 'string') block.text = 'EDITED';
-          if (Array.isArray(block.rows)) block.rows.push(['EDITED']);
-        }
-      }
-      const again = detailView(await compileTopic(catalog, tokens));
-      const index = indexView(await lowerTopic(catalog, tokens));
-      const spacing = detailView(
-        await compileTopic(catalog, catalog.resolve('spacing')),
-      );
-      for (const read of [again, index, spacing]) {
-        expect(JSON.stringify(read)).not.toContain('EDITED');
-      }
-      const lowered = await lowerTopic(catalog, tokens);
-      expect(Object.isFrozen(lowered.doc.sections[0].content)).toBe(true);
-    },
-    SLOW,
-  );
-});

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

@@ -1,162 +0,0 @@
-// @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;
-};