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

package/foundation/discovery/template-adapter.mjs

@@ -15,7 +15,8 @@
  * needs it: `Project` assembles templates from it. While this sat in api/, that
  * made a cycle across the layer boundary — Project reached up for discovery and
  * this module imported Project back. Nothing here depends on api/; every import
- * is node:*, jiti, foundation/*, or authoring/*.
+ * is node:*, jiti, foundation/*, or authoring/*, plus a lazily required
+ * @babel/parser for extractComponents' local-declaration scan.
  *
  * @position packages/cli/foundation/discovery — shared template discovery/IO;
  *   consumed by Project and by the api/template leaves.
@@ -512,6 +513,19 @@ function expressionUse(source, open, close) {
   return null;
 }
 
+/** @type {typeof import('@babel/parser') | undefined} */
+let babelParser;
+
+/**
+ * The template source parser, loaded on first use so listing templates
+ * never pays for it.
+ * @returns {typeof import('@babel/parser')}
+ */
+function templateSourceParser() {
+  babelParser ??= require('@babel/parser');
+  return /** @type {typeof import('@babel/parser')} */ (babelParser);
+}
+
 /**
  * The [start, end) range of every comment in `source`, or none when it does
  * not parse as TSX.
@@ -520,8 +534,7 @@ function expressionUse(source, open, close) {
  */
 function commentRanges(source) {
   try {
-    const {parse} = require('@babel/parser');
-    const {comments} = parse(source, {
+    const {comments} = templateSourceParser().parse(source, {
       sourceType: 'module',
       plugins: ['jsx', 'typescript'],
     });
@@ -1267,7 +1280,8 @@ export async function discoverIntegrationTemplatesForOne(integration) {
         template: id,
         message: `Template "${id}" is missing a "type" of "page" or "block". Stamp the default export with type: 'page' or type: 'block'.`,
       });
-      const declared = doc?.replaces ?? (await declaredReplacement(docPath, id));
+      const declared =
+        doc?.replaces ?? (await declaredReplacement(docPath, id));
       if (declared != null) {
         errors.push({
           code: 'invalid_template_replacement',
@@ -1423,6 +1437,51 @@ const UBIQUITOUS = new Set([
   'Icon',
 ]);
 
+/**
+ * Names bound by top-level `function`, `class`, `const`, `let` or `var`
+ * declarations (exported or not). Returns an empty set when the source does
+ * not parse, so a parse failure never drops a real component.
+ *
+ * @param {string} src
+ * @returns {Set<string>}
+ */
+function topLevelBindingNames(src) {
+  /** @type {Set<string>} */
+  const names = new Set();
+  let program;
+  try {
+    program = templateSourceParser().parse(src, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+      errorRecovery: true,
+    }).program;
+  } catch {
+    return names;
+  }
+  for (const statement of program.body) {
+    const node =
+      statement.type === 'ExportNamedDeclaration' ||
+      statement.type === 'ExportDefaultDeclaration'
+        ? statement.declaration
+        : statement;
+    if (node == null) continue;
+    if (
+      (node.type === 'FunctionDeclaration' ||
+        node.type === 'ClassDeclaration') &&
+      node.id
+    ) {
+      names.add(node.id.name);
+    } else if (node.type === 'VariableDeclaration') {
+      for (const declarator of node.declarations) {
+        if (declarator.id.type === 'Identifier') {
+          names.add(declarator.id.name);
+        }
+      }
+    }
+  }
+  return names;
+}
+
 /**
  * @param {string} pagePath
  * @returns {string[]}
@@ -1449,14 +1508,24 @@ export function extractComponents(pagePath) {
   while ((m = tagRegex.exec(src)) !== null) {
     matches.push(m[2]);
   }
+
+  // Exclude names bound by a top-level declaration in the same file: those are
+  // page-local helpers (e.g. `function TimelineSection()`), not components a
+  // builder can import. Read real bindings from the syntax tree so comments,
+  // strings and type annotations cannot add or hide a name.
+  const localDeclNames = topLevelBindingNames(src);
+
   return [
     ...new Set(
       matches
+        .filter(n => !localDeclNames.has(n))
         .filter(n => !['Theme', 'ThemeProvider'].includes(n))
         .filter(n => !UBIQUITOUS.has(n))
         .map(n =>
           n.replace(
-            /(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/,
+            // Strip only when a stem remains, so a bare `<Section>` keeps its
+            // own name instead of emptying out.
+            /(?<=.)(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/,
             '',
           ),
         )

package/foundation/discovery/type-match.d.mts

@@ -0,0 +1,53 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Judge a documented type. A doc may name an alias and spell out what it
+ * stands for, as `Name = expansion` or `Name (expansion)` (text that is not a
+ * type by itself): both parts are judged, and a mismatch in either is one;
+ * with one value after it (`Size = 'md'`, `Size = Size.Md`), or after a
+ * keyword, that part may be a default, and only the name is judged.
+ * @param {string} docType
+ * @param {any[]} codeTypes the prop's type in each member of the props type
+ * @param {JudgeContext} ctx
+ * @returns {TypeVerdict}
+ */
+export function judgeType(docType: string, codeTypes: any[], ctx: JudgeContext): TypeVerdict;
+export type TypeVerdict = "match" | "mismatch" | "not_compared";
+export type JudgeContext = {
+    ts: any;
+    checker: any;
+    /**
+     * where names in the documented type resolve (the
+     * prop's declaration, else the component's source file)
+     */
+    location: any;
+    /**
+     * the prop is optional, so `undefined` is set
+     * aside on both sides
+     */
+    optional: boolean;
+    /**
+     * whether a source
+     * file is one of TypeScript's own libraries
+     */
+    isDefaultLibrary?: ((file: any) => boolean) | undefined;
+    /**
+     * the project checks without strict null
+     * checks, so the compiler drops `null` and `undefined` from every type and
+     * both are set aside on both sides
+     */
+    nullable?: boolean | undefined;
+    /**
+     * the project sets
+     * `exactOptionalPropertyTypes`: an optional prop takes `undefined` only when
+     * its type says so, and the compiler's mark for an absent prop is not a
+     * type the prop takes
+     */
+    exactOptional?: boolean | undefined;
+    /**
+     * the code's type as the source writes it and
+     * as the compiler prints it, each a list of union members
+     */
+    written: string[][];
+};