@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/discovery/runner-allowlist.d.mts

@@ -0,0 +1,40 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file Where a runner may stand in front of an Astryx command in Astryx's own
+ * docs. Docs write commands bare (`astryx <command>`): the CLI prefixes each
+ * one with the reader's command when it prints a doc, and the docsite with
+ * `npx @astryxdesign/cli`. A few files show a runner on purpose, and some files
+ * are not docs at all. The rules, checked by test/runner-commands.test.mjs:
+ *
+ * - npx (or another download runner) with the unscoped name `astryx` is never
+ *   written outside `skip`: it fetches an unrelated npm package.
+ * - In a doc (`*.doc.mjs`, and Core's docs.mjs), no runner precedes an Astryx
+ *   command, except in `runnerExamples`, where `npx @astryxdesign/cli …` and a
+ *   project's runner may (still never the unscoped name through npx).
+ *
+ * TODO(doctor-runner-check): the Doctor lane's integration-docs runner check
+ * (foundation/discovery/runner-commands.mjs) becomes the single rule; then the
+ * repo test runs that check over Core's and the CLI's own docs with this
+ * allowlist.
+ *
+ * @input  nothing
+ * @output the allowlist
+ * @position packages/cli/foundation/discovery — data shared by the repo test
+ *   and the Doctor runner check
+ */
+export const RUNNER_COMMAND_ALLOWLIST: Readonly<{
+    /** Files never scanned: release notes, tests, and the helpers that build runner forms. */
+    skip: readonly RegExp[];
+    /** Docs that show a runner on purpose, and why. */
+    runnerExamples: Readonly<{
+        'packages/core/docs.mjs': "Core's setup banner, for a project that has no CLI installed yet";
+        'packages/cli/assets/docs/tree/updates.doc.mjs': "quotes the CLI's own update notice, which names the project's runner";
+        'packages/cli/assets/docs/tree/cli-command.doc.mjs': "explains how printed commands start, the pinned `npx @astryxdesign/cli@<version>` among them";
+        'packages/cli/assets/docs/tree/who-answers.doc.mjs': "explains how printed commands start, the pinned `npx @astryxdesign/cli@<version>` among them";
+        'packages/cli/assets/docs/tree/project-global-or-both.doc.mjs': "compares running the CLI with npx to installing it, and is found by searching for that command";
+        'packages/cli/assets/docs/tree/install-once.doc.mjs': "names a pinned release, `npx @astryxdesign/cli@<version>`, which answers as that version";
+        'packages/cli/clients/cli/commands/upgrade.doc.mjs': "quotes the command upgrade prints when the CLI is older than Core, pinned to the matching release";
+    }>;
+}>;

package/foundation/discovery/runner-allowlist.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Where a runner may stand in front of an Astryx command in Astryx's own
+ * docs. Docs write commands bare (`astryx <command>`): the CLI prefixes each
+ * one with the reader's command when it prints a doc, and the docsite with
+ * `npx @astryxdesign/cli`. A few files show a runner on purpose, and some files
+ * are not docs at all. The rules, checked by test/runner-commands.test.mjs:
+ *
+ * - npx (or another download runner) with the unscoped name `astryx` is never
+ *   written outside `skip`: it fetches an unrelated npm package.
+ * - In a doc (`*.doc.mjs`, and Core's docs.mjs), no runner precedes an Astryx
+ *   command, except in `runnerExamples`, where `npx @astryxdesign/cli …` and a
+ *   project's runner may (still never the unscoped name through npx).
+ *
+ * TODO(doctor-runner-check): the Doctor lane's integration-docs runner check
+ * (foundation/discovery/runner-commands.mjs) becomes the single rule; then the
+ * repo test runs that check over Core's and the CLI's own docs with this
+ * allowlist.
+ *
+ * @input  nothing
+ * @output the allowlist
+ * @position packages/cli/foundation/discovery — data shared by the repo test
+ *   and the Doctor runner check
+ */
+
+export const RUNNER_COMMAND_ALLOWLIST = Object.freeze({
+  /** Files never scanned: release notes, tests, and the helpers that build runner forms. */
+  skip: Object.freeze([
+    /(^|\/)CHANGELOG\.md$/u,
+    /\.test\.[cm]?[jt]sx?$/u,
+    /(^|\/)__tests__\//u,
+    /^packages\/cli\/test\//u,
+    /^packages\/cli\/foundation\/env\/package-manager\.mjs$/u,
+  ]),
+  /** Docs that show a runner on purpose, and why. */
+  runnerExamples: Object.freeze({
+    'packages/core/docs.mjs':
+      "Core's setup banner, for a project that has no CLI installed yet",
+    'packages/cli/assets/docs/tree/updates.doc.mjs':
+      "quotes the CLI's own update notice, which names the project's runner",
+    'packages/cli/assets/docs/tree/cli-command.doc.mjs':
+      'explains how printed commands start, the pinned `npx @astryxdesign/cli@<version>` among them',
+    'packages/cli/assets/docs/tree/who-answers.doc.mjs':
+      'explains how printed commands start, the pinned `npx @astryxdesign/cli@<version>` among them',
+    'packages/cli/assets/docs/tree/project-global-or-both.doc.mjs':
+      'compares running the CLI with npx to installing it, and is found by searching for that command',
+    'packages/cli/assets/docs/tree/install-once.doc.mjs':
+      'names a pinned release, `npx @astryxdesign/cli@<version>`, which answers as that version',
+    'packages/cli/clients/cli/commands/upgrade.doc.mjs':
+      'quotes the command upgrade prints when the CLI is older than Core, pinned to the matching release',
+  }),
+});

package/foundation/discovery/stray-pointers.d.mts

@@ -0,0 +1,52 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The strings of a doc the CLI resolves links in (spec:AST-047 FR9). In a
+ * topic: its description and summary, then the text of prose and heading
+ * blocks, list items, and table cells in each section's content, with the
+ * section's title. In a component doc (any doc with no sections): every text
+ * field, such as its description, usage, best practices, and each prop's and
+ * example's description, with the field's path. Code is never read.
+ *
+ * @param {unknown} doc an authored doc object
+ * @returns {{text: string, section: string | null, field: string | null}[]}
+ */
+export function linkableStrings(doc: unknown): {
+    text: string;
+    section: string | null;
+    field: string | null;
+}[];
+/**
+ * Every pointer span in one prose string, in order.
+ * @param {string} text
+ * @returns {string[]} the doc name each one points at
+ */
+export function pointersIn(text: string): string[];
+/**
+ * Each stray pointer in a package's topics and component docs.
+ *
+ * @param {{records: {name: string, path: string}[], guides?: {name: string, ref?: {topicFile?: string}}[], namespaces?: {doc?: {name?: string}}[], components?: {name: string, file: string}[]}} discovered
+ * @returns {Promise<import('../../api/integration/authoring-checks.type.mjs').StrayPointer[]>}
+ */
+export function findStrayPointers(discovered: {
+    records: {
+        name: string;
+        path: string;
+    }[];
+    guides?: {
+        name: string;
+        ref?: {
+            topicFile?: string;
+        };
+    }[];
+    namespaces?: {
+        doc?: {
+            name?: string;
+        };
+    }[];
+    components?: {
+        name: string;
+        file: string;
+    }[];
+}): Promise<import("../../api/integration/authoring-checks.type.mjs").StrayPointer[]>;

package/foundation/discovery/stray-pointers.mjs

@@ -0,0 +1,293 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stray doc pointers (architecture:cli-surface DEC-8): a code span in
+ * prose that is exactly `astryx docs <name>` for a doc that exists. The doc's
+ * `{@link}` prints the command that opens the doc and is checked by doctor's
+ * link check, so a written command is a pointer nothing checks.
+ *
+ * @input the docs a package ships, as discoverIntegrationDocs returns them
+ * @output each stray pointer, with the link that replaces it
+ * @position foundation/discovery, called through api/integration/_adapter.mjs
+ */
+
+import fs from 'node:fs';
+
+import {textFields} from '../doc-compiler/links.mjs';
+import {builtinGuideFiles} from './docs-discovery.mjs';
+import {
+  fileWords,
+  lineAtOffset,
+  loadQuietly,
+  locateWords,
+  textWords,
+} from './copied-passages.mjs';
+
+/**
+ * A code span that is exactly the command opening one doc. A command with
+ * more words, a flag, or a route is a walkthrough, not a pointer. A name holds
+ * what a topic name may (letters, digits, `_` and `-`), never opening with `-`.
+ */
+const POINTER = /`astryx docs ([A-Za-z0-9_][A-Za-z0-9_-]*)`/g;
+
+/** @type {Promise<Map<string, string>> | undefined} */
+let coreKinds;
+
+/**
+ * The CLI's own docs by name, each with the kind a link names it by: a
+ * namespace doc as `namespace`, a topic or guide as `generic`.
+ * @returns {Promise<Map<string, string>>}
+ */
+function loadCoreKinds() {
+  coreKinds ??= (async () => {
+    const kinds = new Map();
+    for (const file of builtinGuideFiles()) {
+      const doc = await loadQuietly(file);
+      if (typeof doc?.name === 'string') {
+        kinds.set(doc.name, doc.type === 'namespace' ? 'namespace' : 'generic');
+      }
+    }
+    return kinds;
+  })();
+  return coreKinds;
+}
+
+/**
+ * The strings of a doc the CLI resolves links in (spec:AST-047 FR9). In a
+ * topic: its description and summary, then the text of prose and heading
+ * blocks, list items, and table cells in each section's content, with the
+ * section's title. In a component doc (any doc with no sections): every text
+ * field, such as its description, usage, best practices, and each prop's and
+ * example's description, with the field's path. Code is never read.
+ *
+ * @param {unknown} doc an authored doc object
+ * @returns {{text: string, section: string | null, field: string | null}[]}
+ */
+export function linkableStrings(doc) {
+  /** @type {{text: string, section: string | null, field: string | null}[]} */
+  const strings = [];
+  if (doc == null || typeof doc !== 'object') return strings;
+  const top = /** @type {Record<string, any>} */ (doc);
+  if (!Array.isArray(top.sections)) {
+    for (const {field, text} of textFields(doc)) {
+      strings.push({text, section: null, field});
+    }
+    return strings;
+  }
+  for (const field of ['description', 'summary']) {
+    if (typeof top[field] === 'string') {
+      strings.push({text: top[field], section: null, field});
+    }
+  }
+  /**
+   * @param {unknown} value
+   * @param {string | null} section
+   */
+  const walk = (value, section) => {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, section);
+      return;
+    }
+    if (value == null || typeof value !== 'object') return;
+    const record = /** @type {Record<string, any>} */ (value);
+    const title = typeof record.title === 'string' ? record.title : section;
+    if (Array.isArray(record.sections)) walk(record.sections, section);
+    if (!Array.isArray(record.content)) return;
+    for (const block of record.content) {
+      const add = (/** @type {unknown} */ text) => {
+        if (typeof text === 'string') {
+          strings.push({text, section: title, field: null});
+        }
+      };
+      switch (block?.type) {
+        case 'prose':
+        case 'heading':
+          add(block.text);
+          break;
+        case 'list':
+          (block.items ?? []).forEach(add);
+          break;
+        case 'table':
+          (block.headers ?? []).forEach(add);
+          for (const row of block.rows ?? []) row.forEach(add);
+          break;
+        default:
+          walk(block, title);
+      }
+    }
+  };
+  walk(doc, null);
+  return strings;
+}
+
+/**
+ * Every pointer span in one prose string, in order.
+ * @param {string} text
+ * @returns {string[]} the doc name each one points at
+ */
+export function pointersIn(text) {
+  return [...text.matchAll(POINTER)].map(match => match[1]);
+}
+
+/**
+ * Where a string's words start among a file's words, from `from` on. A
+ * one-line string the file holds as a quoted literal is found at that
+ * literal, so a list item that is only `astryx docs theme` is not placed at a
+ * summary or code block that writes the same words.
+ *
+ * @param {string[]} lines the file's lines
+ * @param {{word: string, line: number}[]} file the file's words
+ * @param {string} text
+ * @param {{word: string}[]} words the string's words
+ * @param {number} from
+ * @returns {number}
+ */
+function locateString(lines, file, text, words, from) {
+  /** @type {number[]} */
+  const starts = [];
+  for (let at = locateWords(file, words); at >= 0;) {
+    starts.push(at);
+    at = locateWords(file, words, at + 1);
+  }
+  if (starts.length === 0) return -1;
+  const literals = text.includes('\n')
+    ? []
+    : [`'${text}'`, `"${text}"`, `'${text.replace(/'/g, "\\'")}'`];
+  const quoted = starts.filter(at =>
+    literals.some(literal => lines[file[at].line - 1]?.includes(literal)),
+  );
+  const pool = quoted.length > 0 ? quoted : starts;
+  return pool.find(at => at >= from) ?? pool[0];
+}
+
+/**
+ * Each stray pointer in a package's topics and component docs.
+ *
+ * @param {{records: {name: string, path: string}[], guides?: {name: string, ref?: {topicFile?: string}}[], namespaces?: {doc?: {name?: string}}[], components?: {name: string, file: string}[]}} discovered
+ * @returns {Promise<import('../../api/integration/authoring-checks.type.mjs').StrayPointer[]>}
+ */
+export async function findStrayPointers(discovered) {
+  /** @type {{name: string, file: string | undefined, kind: 'topic' | 'component'}[]} */
+  const topics = [
+    ...discovered.records.map(record => ({
+      name: record.name,
+      file: record.path,
+      kind: /** @type {const} */ ('topic'),
+    })),
+    ...(discovered.guides ?? []).map(guide => ({
+      name: guide.name,
+      file: guide.ref?.topicFile,
+      kind: /** @type {const} */ ('topic'),
+    })),
+  ];
+  /** @type {Map<string, string>} */
+  const own = new Map(topics.map(topic => [topic.name, 'generic']));
+  for (const namespace of discovered.namespaces ?? []) {
+    const name = namespace?.doc?.name;
+    if (typeof name === 'string' && !own.has(name)) own.set(name, 'namespace');
+  }
+  for (const component of discovered.components ?? []) {
+    topics.push({
+      name: component.name,
+      file: component.file,
+      kind: 'component',
+    });
+  }
+  const core = await loadCoreKinds();
+  // A topic that extends another has no route of its own: a link to it names
+  // the page it shows on, the topic it extends.
+  /** @type {Map<string, string>} */
+  const extendsOf = new Map();
+  for (const topic of topics) {
+    if (!topic.file) continue;
+    const doc = /** @type {any} */ (await loadQuietly(topic.file));
+    if (typeof doc?.extends === 'string')
+      extendsOf.set(topic.name, doc.extends);
+  }
+  /** @param {string} target */
+  const linkFor = target => {
+    const page = extendsOf.get(target);
+    if (page != null) {
+      if (own.has(page) && !extendsOf.has(page)) {
+        return `{@link ${own.get(page)}:${page}}`;
+      }
+      return core.has(page)
+        ? `{@link @astryxdesign/cli:${core.get(page)}:${page}}`
+        : null;
+    }
+    return own.has(target)
+      ? `{@link ${own.get(target)}:${target}}`
+      : core.has(target)
+        ? `{@link @astryxdesign/cli:${core.get(target)}:${target}}`
+        : null;
+  };
+  /** @type {import('../../api/integration/authoring-checks.type.mjs').StrayPointer[]} */
+  const found = [];
+  for (const topic of topics) {
+    if (!topic.file) continue;
+    const doc = await loadQuietly(topic.file);
+    if (!doc) continue;
+    /** @type {{word: string, line: number}[]} */
+    let source = [];
+    /** @type {string[]} */
+    let lines = [];
+    try {
+      const raw = fs.readFileSync(topic.file, 'utf8');
+      source = fileWords(raw);
+      lines = raw.split('\n');
+    } catch {
+      // No line numbers; the finding still names the section.
+    }
+    // A component doc is named by its own name: a family doc by the family.
+    const name =
+      topic.kind === 'component' && typeof doc.name === 'string'
+        ? doc.name
+        : topic.name;
+    const label =
+      topic.kind === 'component' ? `component "${name}"` : `"${name}"`;
+    // Each string is found by its whole run of words, from where the last
+    // one was found, so two strings that open alike keep their own lines.
+    let cursor = 0;
+    for (const {text, section, field} of linkableStrings(doc)) {
+      const words = textWords(text);
+      const index = locateString(lines, source, text, words, cursor);
+      if (index >= 0) cursor = index + words.length;
+      for (const match of text.matchAll(POINTER)) {
+        const target = match[1];
+        const link = linkFor(target);
+        if (!link) continue;
+        const command = `astryx docs ${target}`;
+        const line =
+          index < 0
+            ? null
+            : lineAtOffset(
+                source,
+                index,
+                words,
+                /** @type {number} */ (match.index) + 1,
+              );
+        const where = [
+          section ? `section "${section}"` : null,
+          field ? `field ${field}` : null,
+          line == null ? null : `line ${line}`,
+        ]
+          .filter(Boolean)
+          .join(', ');
+        found.push({
+          topic: name,
+          kind: topic.kind,
+          section,
+          field,
+          file: topic.file,
+          line,
+          pointer: command,
+          link,
+          message:
+            `${label}${where ? ` (${where})` : ''} points at a doc with the written command \`${command}\`. ` +
+            `Replace \`${command}\`, code ticks included, with ${link}: the CLI prints the command that opens the doc, and doctor checks the link.`,
+        });
+      }
+    }
+  }
+  return found;
+}

package/foundation/discovery/stray-pointers.test.mjs

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+
+import {linkableStrings, pointersIn} from './stray-pointers.mjs';
+
+describe('pointersIn', () => {
+  it('finds a code span that is exactly the command opening one doc', () => {
+    expect(
+      pointersIn(
+        'Read `astryx docs theme`, then `astryx docs layout-spacing`.',
+      ),
+    ).toEqual(['theme', 'layout-spacing']);
+  });
+
+  it('leaves a walkthrough alone: more words, a flag, or a route', () => {
+    expect(
+      pointersIn(
+        'Run `astryx docs theme overview`, `astryx docs --json`, `astryx docs cli/integrations`, or `astryx docs`.',
+      ),
+    ).toEqual([]);
+  });
+
+  it('leaves the bare name and a runner-written command alone', () => {
+    expect(
+      pointersIn('See astryx docs theme, or `pnpm astryx docs theme`.'),
+    ).toEqual([]);
+  });
+});
+
+describe('linkableStrings', () => {
+  it("reads a topic's description and summary, then prose, headings, list items and table cells, not code", () => {
+    const strings = linkableStrings({
+      name: 'acme',
+      description: 'Read `astryx docs theme`.',
+      summary: 'In short.',
+      sections: [
+        {
+          title: 'Use it',
+          content: [
+            {type: 'prose', text: 'prose'},
+            {type: 'heading', level: 3, text: 'heading'},
+            {type: 'list', style: 'unordered', items: ['item']},
+            {type: 'table', headers: ['head'], rows: [['cell']]},
+            {type: 'code', lang: 'bash', code: 'astryx docs theme'},
+          ],
+        },
+      ],
+    });
+    expect(strings).toEqual([
+      {text: 'Read `astryx docs theme`.', section: null, field: 'description'},
+      {text: 'In short.', section: null, field: 'summary'},
+      {text: 'prose', section: 'Use it', field: null},
+      {text: 'heading', section: 'Use it', field: null},
+      {text: 'item', section: 'Use it', field: null},
+      {text: 'head', section: 'Use it', field: null},
+      {text: 'cell', section: 'Use it', field: null},
+    ]);
+  });
+
+  it("reads a component doc's text fields, not its names, types, defaults, or code", () => {
+    const strings = linkableStrings({
+      type: 'component',
+      name: 'AcmeButton',
+      displayName: 'Acme Button',
+      usage: {
+        description: 'usage',
+        bestPractices: [{guidance: true, description: 'practice'}],
+      },
+      props: [
+        {name: 'tone', type: 'string', default: "'a'", description: 'prop'},
+      ],
+      examples: [{label: 'example', code: 'astryx docs theme'}],
+    });
+    expect(strings).toEqual([
+      {text: 'usage', section: null, field: 'usage.description'},
+      {
+        text: 'practice',
+        section: null,
+        field: 'usage.bestPractices[0].description',
+      },
+      {text: 'prop', section: null, field: 'props[0].description'},
+      {text: 'example', section: null, field: 'examples[0].label'},
+    ]);
+  });
+});

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/template-needs.mjs

@@ -20,7 +20,10 @@ import * as path from 'node:path';
 import module from 'node:module';
 import {CLI_ROOT} from '../fs/paths.mjs';
 import {detectStylingSystem} from '../agent-docs/agent-docs.mjs';
-import {decidePackageManagerIn} from '../env/package-manager.mjs';
+import {
+  decidePackageManagerIn,
+  formatCliCommand,
+} from '../env/package-manager.mjs';
 
 // ── Known packages that a template may import without the user installing them.
 // react and react-dom are the framework; @astryxdesign/* is the design system
@@ -230,7 +233,7 @@ export function analyzeTemplateNeeds(source, cwd) {
   }
   if (stylexCompilerNeeded) {
     notes.push(
-      'This template uses StyleX. Your project needs a StyleX compiler plugin \u2014 see `astryx docs styling-overview` for setup steps.',
+      `This template uses StyleX. Your project needs a StyleX compiler plugin \u2014 see \`${formatCliCommand('docs styling-overview')}\` for setup steps.`,
     );
   }