@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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-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.`,
     );
   }
 

package/foundation/discovery/theme-imports.mjs

@@ -19,6 +19,7 @@ import {moduleExportsName} from './module-exports.mjs';
 import {inspectPackageExport} from './package-exports.mjs';
 import {themeImportPackage} from './theme-discovery.mjs';
 import {isLocalThemeOwner, projectPath} from '../config/theme-state.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 export class ThemeImportError extends Error {}
 
@@ -59,7 +60,7 @@ function resolveLocalTheme(theme, cwd) {
       path.relative(cwd, path.join(theme.sourceDir, theme.entry)),
     );
     throw new ThemeImportError(
-      `Local theme "${theme.slug}" is not built. Run \`astryx theme build ${source}\` and try again. Missing: ${missing
+      `Local theme "${theme.slug}" is not built. Run \`${formatCliCommand(`theme build ${source}`, cwd)}\` and try again. Missing: ${missing
         .map(file => projectPath(path.relative(cwd, file)))
         .join(', ')}.`,
     );
@@ -68,8 +69,11 @@ function resolveLocalTheme(theme, cwd) {
     throw new ThemeImportError(
       `Local theme "${theme.slug}" built module ${projectPath(
         path.relative(cwd, moduleFile),
-      )} does not export "${theme.exportName}". Rebuild it with \`astryx theme build ${projectPath(
-        path.relative(cwd, path.join(theme.sourceDir, theme.entry)),
+      )} does not export "${theme.exportName}". Rebuild it with \`${formatCliCommand(
+        `theme build ${projectPath(
+          path.relative(cwd, path.join(theme.sourceDir, theme.entry)),
+        )}`,
+        cwd,
       )}\`.`,
     );
   }
@@ -130,7 +134,7 @@ function resolvePackageTheme(theme, cwd, ownerThemeCount) {
     findInstalledPackage(cwd, importPackage);
   if (!packageDir) {
     throw new ThemeImportError(
-      `Theme package "${importPackage}" is not installed. Run \`npm install ${importPackage}\` (or yarn/pnpm/bun), then run \`astryx theme add ${theme.slug}\`.`,
+      `Theme package "${importPackage}" is not installed. Run \`npm install ${importPackage}\` (or yarn/pnpm/bun), then run \`${formatCliCommand(`theme add ${theme.slug}`, cwd)}\`.`,
     );
   }
   const pkg = readPackage(path.join(packageDir, 'package.json'));

package/foundation/discovery/theme-imports.test.mjs

@@ -148,7 +148,7 @@ describe('resolveThemeImports', () => {
     });
 
     expect(() => resolveThemeImports(theme, {cwd: dir})).toThrow(
-      /astryx theme build src\/themes\/ocean\/oceanTheme\.ts/i,
+      / theme build src\/themes\/ocean\/oceanTheme\.ts`/i,
     );
     fs.writeFileSync(
       path.join(sourceDir, 'ocean.js'),

package/foundation/discovery/type-text.mjs

@@ -46,7 +46,7 @@ export function typeTextTooOld(ts) {
   const [major, minor] = String(ts.version).split('.').map(Number);
   return major > 4 || (major === 4 && minor >= 8)
     ? null
-    : `TypeScript ${ts.version} is older than 4.8, the oldest the type comparison reads`;
+    : `TypeScript ${ts.version} is older than 4.8, the oldest the type comparison reads; install TypeScript 5.0 through 6 (\`npm install -D typescript@6\`), or on TypeScript 7 add \`@typescript/typescript6\`, to judge them`;
 }
 
 /** How tightly a printed type binds: a slot needs at least its level. */

package/foundation/discovery/type-text.test.mjs

@@ -176,7 +176,7 @@ describe('normalizeTypeText', () => {
       'string[]',
     ]);
     expect(typeTextTooOld({version: '4.7.4'})).toBe(
-      'TypeScript 4.7.4 is older than 4.8, the oldest the type comparison reads',
+      'TypeScript 4.7.4 is older than 4.8, the oldest the type comparison reads; install TypeScript 5.0 through 6 (`npm install -D typescript@6`), or on TypeScript 7 add `@typescript/typescript6`, to judge them',
     );
     for (const version of ['4.8.4', '5.0.4', '6.0.3', ts.version]) {
       expect(typeTextTooOld({version})).toBeNull();

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -248,17 +248,41 @@ const RUNNERS = {
     runs: 'astryx.config, through the config parser',
     sites: ['loadModuleWithParser(..., parseConfig)'],
   },
+  'foundation/fs/file-protection.mjs': {
+    runs: 'the ignore matcher (CommonJS), loaded when a resolver first reads an ignore file',
+    sites: ['require(ignore)'],
+  },
   'foundation/discovery/component-discovery.mjs': {
     runs: '@babel/parser, on first use, to read the members a family doc lists in its components without running the doc',
     sites: ['require(@babel/parser)'],
   },
+  'foundation/discovery/copied-passages.mjs': {
+    runs: "the CLI's own guides and the package's topics, to compare their prose for passages two topics repeat",
+    sites: ['builtinGuideFiles', 'loadTopicModule'],
+  },
+  'foundation/discovery/doc-consistency.mjs': {
+    runs: "a package's component docs and topics, to read the props, overlays, sections, and replaces/extends they declare",
+    sites: ['importDocModule ×2'],
+  },
+  'foundation/discovery/doc-fluff.mjs': {
+    runs: "the CLI's own guides, to measure the median share of content words a topic's density is compared with",
+    sites: ['builtinGuideFiles'],
+  },
   'foundation/discovery/docs-discovery.mjs': {
     runs: 'a contributed topic, for its catalog fields: name, title, description, category, and relationships',
     sites: ['importDocModule'],
   },
+  'foundation/discovery/stray-pointers.mjs': {
+    runs: "the CLI's own guides, for their names, to tell which written `astryx docs <name>` points at a doc that exists",
+    sites: ['builtinGuideFiles'],
+  },
   'foundation/discovery/project-typescript.mjs': {
-    runs: "the project's own typescript, for the author checks that read source and docs with it, and its package.json for the version of one they cannot use",
-    sites: ['require(typescript)', 'require(typescript/package.json)'],
+    runs: "the project's own typescript, for the author checks that read source and docs with it, and its package.json for the version of one they cannot use; beside TypeScript 7, which has no compiler API, the TypeScript 6 API package @typescript/typescript6",
+    sites: [
+      'require(<computed>)',
+      'require(typescript)',
+      'require(typescript/package.json)',
+    ],
   },
   'foundation/discovery/template-adapter.mjs': {
     runs: '@babel/parser, to find the fixture references and page-local bindings in template source; and a template doc that does not validate, to read the replacement it declares',
@@ -299,6 +323,22 @@ const RUNNERS = {
     runs: "each installed integration's manifest",
     sites: ['importUserModule'],
   },
+  'foundation/release/cache.mjs': {
+    runs: 'npm (under npm-guard.mjs), to install and look up CLI releases in the per-user cache; each installed release once, to check it starts and reports its version; and ps (tasklist on Windows), to confirm the process a stale lock records is node or npm before ending it',
+    sites: ['child_process.spawnSync ×5'],
+  },
+  'foundation/release/npm-guard.mjs': {
+    runs: 'npm, in a process group of its own that it ends at the time limit, on Ctrl-C, or when the run that started it goes away',
+    sites: ['child_process.spawn'],
+  },
+  'foundation/release/global-state.mjs': {
+    runs: "the background check of the registry's `latest` release, the agent-text step, and the step that installs the global copy's own Core into the release cache, each detached",
+    sites: ['child_process.spawn'],
+  },
+  'foundation/release/handoff.mjs': {
+    runs: "the CLI release that answers a project's run, when it is not this copy",
+    sites: ['child_process.spawn'],
+  },
   'scripts/generate-cli-readme.mjs': {
     runs: '`astryx manifest` and the error-code and response-type docs, to write the README tables (build time, not shipped)',
     sites: ['child_process.spawnSync', 'import(<computed>)'],

package/foundation/doc-compiler/inputs.mjs

@@ -109,7 +109,10 @@ export async function collectDocInputs(project) {
     list.add('components', record.name, record.package, record.docPath);
   }
 
-  const coreDir = findCoreDir(project.cwd);
+  const coreDir =
+    typeof project.coreDir === 'function'
+      ? project.coreDir()
+      : findCoreDir(project.cwd);
   if (coreDir != null) {
     for (const name of Object.values(discoverHooks(coreDir)).flat()) {
       const file = findHookDoc(coreDir, name);