@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.e26723d

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

@@ -132,6 +132,35 @@ export const GRAPH_BLOCK_TYPES: Set<string>;
  * load; a guide the tree places may set `placement` (spec:AST-046).
  */
 export const GRAPH_ONLY_FIELDS: string[];
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ * @typedef {object} LinkableComponent
+ * @property {string} providerId
+ * @property {string} package
+ * @property {string} name
+ * @property {string | null} docPath
+ * @property {string} [replaces] the Core component whose name it answers to
+ *   in unqualified lookups (spec:AST-035 FR11)
+ */
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ * @typedef {object} LinkableTemplate
+ * @property {string} providerId
+ * @property {string} package
+ * @property {'page' | 'block'} type
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [replaces] the Core template id it answers to in
+ *   unqualified lookups
+ */
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
+ */
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -181,6 +210,18 @@ export class DocsCatalog {
         namespaces: import("../doc-compiler/tree.mjs").TreeNamespaceInput[];
         guides: import("../doc-compiler/tree.mjs").TreeDocInput[];
     }>;
+    /**
+     * Say where links find component, page, and block docs: the records
+     * `astryx component` and `astryx template` read, loaded on first use.
+     * @param {() => Promise<LinkableContributions>} load
+     */
+    setContributions(load: () => Promise<LinkableContributions>): void;
+    /**
+     * The component and template docs links can name, or null when nothing set
+     * them, so no link to one resolves.
+     * @returns {Promise<LinkableContributions | null>}
+     */
+    contributions(): Promise<LinkableContributions | null>;
     /**
      * Add one integration-contributed doc, honoring what it declares. Returns
      * the issue it caused, or null when it applied cleanly — the caller owns
@@ -290,4 +331,44 @@ export type DocsTopicEntry = {
      */
     tree?: boolean | undefined;
 };
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ */
+export type LinkableComponent = {
+    providerId: string;
+    package: string;
+    name: string;
+    docPath: string | null;
+    /**
+     * the Core component whose name it answers to
+     * in unqualified lookups (spec:AST-035 FR11)
+     */
+    replaces?: string | undefined;
+};
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ */
+export type LinkableTemplate = {
+    providerId: string;
+    package: string;
+    type: "page" | "block";
+    id: string;
+    name: string;
+    displayName?: string | undefined;
+    description?: string | undefined;
+    /**
+     * the Core template id it answers to in
+     * unqualified lookups
+     */
+    replaces?: string | undefined;
+};
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ */
+export type LinkableContributions = {
+    components: LinkableComponent[];
+    templates: LinkableTemplate[];
+};
 import { withSourceTitle } from './docs-section-key.mjs';

package/foundation/discovery/docs-discovery.mjs

@@ -633,6 +633,38 @@ function findMergeTarget(sections, section) {
   return sections.findIndex(candidate => candidate.id === key);
 }
 
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ * @typedef {object} LinkableComponent
+ * @property {string} providerId
+ * @property {string} package
+ * @property {string} name
+ * @property {string | null} docPath
+ * @property {string} [replaces] the Core component whose name it answers to
+ *   in unqualified lookups (spec:AST-035 FR11)
+ */
+
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ * @typedef {object} LinkableTemplate
+ * @property {string} providerId
+ * @property {string} package
+ * @property {'page' | 'block'} type
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [replaces] the Core template id it answers to in
+ *   unqualified lookups
+ */
+
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
+ */
+
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -644,6 +676,10 @@ function findMergeTarget(sections, section) {
 export class DocsCatalog {
   /** @type {Map<string, DocsTopicEntry>} */
   #topics = new Map();
+  /** @type {(() => Promise<LinkableContributions>) | null} */
+  #contributions = null;
+  /** @type {Promise<LinkableContributions> | null} */
+  #contributionsLoaded = null;
   /** @type {Map<string, string>} old topic name → the name that replaced it */
   #aliases = new Map();
   /** @type {Array<{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>} */
@@ -687,6 +723,27 @@ export class DocsCatalog {
     return this.#treeInputs;
   }
 
+  /**
+   * Say where links find component, page, and block docs: the records
+   * `astryx component` and `astryx template` read, loaded on first use.
+   * @param {() => Promise<LinkableContributions>} load
+   */
+  setContributions(load) {
+    this.#contributions = load;
+    this.#contributionsLoaded = null;
+  }
+
+  /**
+   * The component and template docs links can name, or null when nothing set
+   * them, so no link to one resolves.
+   * @returns {Promise<LinkableContributions | null>}
+   */
+  contributions() {
+    if (!this.#contributions) return Promise.resolve(null);
+    this.#contributionsLoaded ??= this.#contributions();
+    return this.#contributionsLoaded;
+  }
+
   /**
    * Seed a catalog with the CLI's own topics.
    * @param {Record<string, string>} [builtins] topic name → absolute path

package/foundation/discovery/module-exports.d.mts

@@ -6,5 +6,32 @@
  * @param {string} file
  * @param {string} exportName
  * @param {Set<string>} [seen]
+ * @returns {boolean}
  */
 export function moduleExportsName(file: string, exportName: string, seen?: Set<string>): boolean;
+/**
+ * The file that declares a module's runtime export, without executing it (the
+ * module, or where a local re-export leads); null when it cannot be proved.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {string | null}
+ */
+export function moduleExportSource(file: string, exportName: string, seen?: Set<string>): string | null;
+/**
+ * The object a module exports, as plain data, read without running it: the
+ * first of `exportNames` it exports, an object literal in place or a top-level
+ * binding (under `satisfies` or `as` too). Only literal values are kept;
+ * anything computed, or overridable by a later spread, is left out.
+ *
+ * @param {string} file
+ * @param {readonly string[]} exportNames `default` or named exports, in order
+ * @returns {Record<string, unknown> | null}
+ */
+export function staticExportObject(file: string, exportNames: readonly string[]): Record<string, unknown> | null;
+/**
+ * Marks an object {@link staticExportObject} returns (or one inside it) whose
+ * source also has properties or spreads it could not read as literals. Not
+ * enumerable, so the object compares and serializes as its literal properties.
+ */
+export const HAS_COMPUTED: unique symbol;

package/foundation/discovery/module-exports.mjs

@@ -6,14 +6,16 @@
  * Proves a runtime export without executing package code. Local ESM re-exports
  * are followed recursively; unresolved or unparsable modules fail closed.
  *
- * @input A module path and runtime export name
- * @output Whether that export can be proved statically
+ * @input A module path and runtime export name, or a module path and the
+ *   exports to try
+ * @output Whether that export can be proved statically and the file that
+ *   declares it, or the exported object literal as plain data
  * @position packages/cli/foundation/discovery — shared package inspection
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import jscodeshift from 'jscodeshift';
+import {parse} from '@babel/parser';
 
 const MODULE_EXTENSIONS = [
   '.mjs',
@@ -25,7 +27,141 @@ const MODULE_EXTENSIONS = [
   '.tsx',
   '.jsx',
 ];
-const parser = jscodeshift.withParser('tsx');
+// The options jscodeshift's tsx parser passes to Babel, so the same sources
+// parse, without tokens or the recast layer: these reads only look at the tree.
+/** @type {import('@babel/parser').ParserOptions} */
+const PARSE_OPTIONS = /** @type {any} */ ({
+  sourceType: 'module',
+  allowImportExportEverywhere: true,
+  allowReturnOutsideFunction: true,
+  plugins: [
+    'jsx',
+    'asyncGenerators',
+    'decoratorAutoAccessors',
+    'bigInt',
+    'classPrivateMethods',
+    'classPrivateProperties',
+    'classProperties',
+    'decorators-legacy',
+    'doExpressions',
+    'dynamicImport',
+    'exportDefaultFrom',
+    'exportExtensions',
+    'exportNamespaceFrom',
+    'functionBind',
+    'functionSent',
+    'importAttributes',
+    'importMeta',
+    'nullishCoalescingOperator',
+    'numericSeparator',
+    'objectRestSpread',
+    'optionalCatchBinding',
+    'optionalChaining',
+    ['pipelineOperator', {proposal: 'minimal'}],
+    'throwExpressions',
+    'typescript',
+  ],
+});
+
+/**
+ * Modules parsed in this process, by path, reused while the file is unchanged:
+ * one command can ask about the same module more than once.
+ * @type {Map<string, {stamp: string, ast: any}>}
+ */
+const parsedModules = new Map();
+
+/**
+ * Module texts read in this process, by path, reused while the file is
+ * unchanged.
+ * @type {Map<string, {stamp: string, text: string}>}
+ */
+const moduleTexts = new Map();
+
+/**
+ * A file's identity for these caches: size and mtime, plus ctime and inode,
+ * which change when a file is rewritten even if npm stamps the same mtime on it.
+ * @param {string} file
+ */
+function fileStamp(file) {
+  const {size, mtimeMs, ctimeMs, ino} = fs.statSync(file);
+  return `${size}:${mtimeMs}:${ctimeMs}:${ino}`;
+}
+
+/** @param {string} file */
+function moduleText(file) {
+  const stamp = fileStamp(file);
+  const cached = moduleTexts.get(file);
+  if (cached?.stamp === stamp) return cached.text;
+  const text = fs.readFileSync(file, 'utf-8');
+  moduleTexts.set(file, {stamp, text});
+  return text;
+}
+
+/** @param {string} file */
+function parseModule(file) {
+  const stamp = fileStamp(file);
+  const cached = parsedModules.get(file);
+  if (cached?.stamp === stamp) return cached.ast;
+  const ast = parse(moduleText(file), PARSE_OPTIONS);
+  parsedModules.set(file, {stamp, ast});
+  return ast;
+}
+
+// `export *`: the one way a module exports a name it never writes.
+const EXPORT_ALL_RE = /\bexport\s*\*/;
+
+/**
+ * Whether `text` has `word` with no identifier character on either side.
+ * @param {string} text
+ * @param {string} word
+ */
+function writesWord(text, word) {
+  for (
+    let at = text.indexOf(word);
+    at !== -1;
+    at = text.indexOf(word, at + 1)
+  ) {
+    const before = text[at - 1] ?? '';
+    const after = text[at + word.length] ?? '';
+    if (!/[\w$]/.test(before) && !/[\w$]/.test(after)) return true;
+  }
+  return false;
+}
+
+const NOT_CHILDREN = new Set([
+  'loc',
+  'start',
+  'end',
+  'extra',
+  'comments',
+  'leadingComments',
+  'trailingComments',
+  'innerComments',
+]);
+
+/**
+ * Every node of `type` in the tree, at any depth, in source order.
+ * @param {any} node
+ * @param {string} type
+ * @param {any[]} [found]
+ * @returns {any[]}
+ */
+function nodesOfType(node, type, found = []) {
+  if (Array.isArray(node)) {
+    for (const child of node) nodesOfType(child, type, found);
+    return found;
+  }
+  if (node == null || typeof node !== 'object') return found;
+  if (node.type === type) found.push(node);
+  for (const key in node) {
+    if (NOT_CHILDREN.has(key)) continue;
+    const child = node[key];
+    if (child != null && typeof child === 'object') {
+      nodesOfType(child, type, found);
+    }
+  }
+  return found;
+}
 
 /** @param {unknown} specifier @param {string} fromFile */
 function resolveLocalModule(specifier, fromFile) {
@@ -76,32 +212,56 @@ function runtimeDefault(declaration) {
  * @param {string} file
  * @param {string} exportName
  * @param {Set<string>} [seen]
+ * @returns {boolean}
  */
 export function moduleExportsName(file, exportName, seen = new Set()) {
+  return moduleExportSource(file, exportName, seen) != null;
+}
+
+/**
+ * The file that declares a module's runtime export, without executing it (the
+ * module, or where a local re-export leads); null when it cannot be proved.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {string | null}
+ */
+export function moduleExportSource(file, exportName, seen = new Set()) {
   const identity = `${file}\0${exportName}`;
-  if (seen.has(identity)) return false;
+  if (seen.has(identity)) return null;
   seen.add(identity);
+  let text;
   try {
-    if (!fs.statSync(file).isFile()) return false;
+    if (!fs.statSync(file).isFile()) return null;
+    text = moduleText(file);
   } catch {
-    return false;
+    return null;
+  }
+  // A module whose text writes neither the export's name as a word nor
+  // `export *` cannot export it, so it is not parsed. Any `export *` text, even
+  // in a comment, leaves the answer to the parsed tree below.
+  if (
+    exportName !== 'default' &&
+    !writesWord(text, exportName) &&
+    !EXPORT_ALL_RE.test(text)
+  ) {
+    return null;
   }
 
-  let root;
+  let ast;
   try {
-    root = parser(fs.readFileSync(file, 'utf-8'));
+    ast = parseModule(file);
   } catch {
-    return false;
+    return null;
   }
 
-  let found = false;
-  root
-    .find(parser.ExportNamedDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      if (found || exportPath.node.exportKind === 'type') return;
-      const node = exportPath.node;
+  /** @type {string | null} */
+  let found = null;
+  nodesOfType(ast.program, 'ExportNamedDeclaration').forEach(
+    (/** @type {any} */ node) => {
+      if (found || node.exportKind === 'type') return;
       if (declarationExports(node.declaration, exportName)) {
-        found = true;
+        found = file;
         return;
       }
       for (const specifier of node.specifiers ?? []) {
@@ -114,33 +274,198 @@ export function moduleExportsName(file, exportName, seen = new Set()) {
         const exported = specifier.exported?.name ?? specifier.exported?.value;
         if (exported !== exportName) continue;
         if (!node.source) {
-          found = true;
+          found = file;
           return;
         }
         const target = resolveLocalModule(node.source.value, file);
         const imported =
           specifier.local?.name ?? specifier.local?.value ?? exportName;
-        if (target && moduleExportsName(target, imported, seen)) {
-          found = true;
+        const declared = target
+          ? moduleExportSource(target, imported, seen)
+          : null;
+        if (declared) {
+          found = declared;
           return;
         }
       }
-    });
-  if (found) return true;
+    },
+  );
+  if (found) return found;
 
   if (exportName === 'default') {
-    const defaults = root.find(parser.ExportDefaultDeclaration).nodes();
+    const defaults = nodesOfType(ast.program, 'ExportDefaultDeclaration');
     if (defaults.some((/** @type {any} */ node) => runtimeDefault(node.declaration))) {
-      return true;
+      return file;
     }
   }
 
-  root
-    .find(parser.ExportAllDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      if (found || exportPath.node.exportKind === 'type') return;
-      const target = resolveLocalModule(exportPath.node.source?.value, file);
-      if (target && moduleExportsName(target, exportName, seen)) found = true;
-    });
+  nodesOfType(ast.program, 'ExportAllDeclaration').forEach(
+    (/** @type {any} */ node) => {
+      if (found || node.exportKind === 'type') return;
+      const target = resolveLocalModule(node.source?.value, file);
+      if (target) found = moduleExportSource(target, exportName, seen);
+    },
+  );
   return found;
 }
+
+/**
+ * Marks an object {@link staticExportObject} returns (or one inside it) whose
+ * source also has properties or spreads it could not read as literals. Not
+ * enumerable, so the object compares and serializes as its literal properties.
+ */
+export const HAS_COMPUTED = Symbol('hasComputed');
+
+const TS_WRAPPERS = new Set([
+  'TSSatisfiesExpression',
+  'TSAsExpression',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+/** @param {any} node */
+function withoutTypeWrappers(node) {
+  let current = node;
+  while (current && TS_WRAPPERS.has(current.type)) current = current.expression;
+  return current;
+}
+
+/**
+ * The object a module exports, as plain data, read without running it: the
+ * first of `exportNames` it exports, an object literal in place or a top-level
+ * binding (under `satisfies` or `as` too). Only literal values are kept;
+ * anything computed, or overridable by a later spread, is left out.
+ *
+ * @param {string} file
+ * @param {readonly string[]} exportNames `default` or named exports, in order
+ * @returns {Record<string, unknown> | null}
+ */
+export function staticExportObject(file, exportNames) {
+  /** @type {any[]} */
+  let body;
+  try {
+    body = parseModule(file).program.body;
+  } catch {
+    return null;
+  }
+
+  /** @type {Map<string, any>} top-level bindings to their initializers */
+  const bindings = new Map();
+  for (const statement of body) {
+    const declaration =
+      statement.type === 'ExportNamedDeclaration'
+        ? statement.declaration
+        : statement;
+    if (declaration?.type !== 'VariableDeclaration') continue;
+    for (const declarator of declaration.declarations) {
+      if (declarator.id?.type === 'Identifier' && declarator.init) {
+        bindings.set(declarator.id.name, declarator.init);
+      }
+    }
+  }
+
+  /** @param {string} name @returns {any} undefined when not exported */
+  const exported = name => {
+    for (const statement of body) {
+      if (name === 'default' && statement.type === 'ExportDefaultDeclaration') {
+        return statement.declaration;
+      }
+      if (
+        statement.type !== 'ExportNamedDeclaration' ||
+        statement.exportKind === 'type'
+      ) {
+        continue;
+      }
+      if (statement.declaration?.type === 'VariableDeclaration') {
+        const declarator = statement.declaration.declarations.find(
+          (/** @type {any} */ item) =>
+            item.id?.type === 'Identifier' && item.id.name === name,
+        );
+        if (declarator) return declarator.init ?? null;
+      }
+      if (statement.source) continue;
+      for (const specifier of statement.specifiers ?? []) {
+        const as = specifier.exported?.name ?? specifier.exported?.value;
+        if (specifier.type === 'ExportSpecifier' && as === name) {
+          return {type: 'Identifier', name: specifier.local?.name};
+        }
+      }
+    }
+    return undefined;
+  };
+
+  /**
+   * @param {any} node
+   * @param {Set<string>} following bindings being followed, against cycles
+   * @returns {unknown} undefined when the value is not a literal
+   */
+  const literal = (node, following) => {
+    const value = withoutTypeWrappers(node);
+    switch (value?.type) {
+      case 'StringLiteral':
+      case 'NumericLiteral':
+      case 'BooleanLiteral':
+        return value.value;
+      case 'NullLiteral':
+        return null;
+      case 'TemplateLiteral':
+        return value.expressions.length === 0
+          ? value.quasis[0]?.value.cooked
+          : undefined;
+      case 'Identifier': {
+        if (!bindings.has(value.name) || following.has(value.name)) {
+          return undefined;
+        }
+        const next = new Set(following).add(value.name);
+        return literal(bindings.get(value.name), next);
+      }
+      case 'ArrayExpression':
+        return value.elements
+          .map((/** @type {any} */ element) =>
+            element == null || element.type === 'SpreadElement'
+              ? undefined
+              : literal(element, following),
+          )
+          .filter((/** @type {unknown} */ item) => item !== undefined);
+      case 'ObjectExpression': {
+        /** @type {Record<string, unknown>} */
+        let object = {};
+        let computed = false;
+        for (const property of value.properties) {
+          if (property.type === 'SpreadElement') {
+            object = {};
+            computed = true;
+            continue;
+          }
+          const key = property.computed
+            ? undefined
+            : (property.key?.name ?? property.key?.value);
+          const item =
+            typeof key === 'string' && property.type === 'ObjectProperty'
+              ? literal(property.value, following)
+              : undefined;
+          if (item === undefined) computed = true;
+          if (typeof key !== 'string') continue;
+          if (item === undefined) delete object[key];
+          else object[key] = item;
+        }
+        if (computed) {
+          Object.defineProperty(object, HAS_COMPUTED, {value: true});
+        }
+        return object;
+      }
+      default:
+        return undefined;
+    }
+  };
+
+  for (const exportName of exportNames) {
+    const node = exported(exportName);
+    if (node === undefined) continue;
+    const value = literal(node, new Set());
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+      ? /** @type {Record<string, unknown>} */ (value)
+      : null;
+  }
+  return null;
+}