@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/foundation/discovery/docs-discovery.mjs

@@ -117,6 +117,23 @@ export function discoverBuiltinTopics() {
   return topics;
 }
 
+/**
+ * The CLI's own guide files: every flat topic and every doc in its docs tree,
+ * without the dense, translated, and draft variants.
+ *
+ * @returns {string[]}
+ */
+export function builtinGuideFiles() {
+  const files = Object.values(discoverBuiltinTopics());
+  const tree = path.join(BUILTIN_DOCS_DIR, 'tree');
+  if (fs.existsSync(tree)) {
+    for (const file of fs.readdirSync(tree).sort()) {
+      if (BUILTIN_TOPIC_FILE_RE.test(file)) files.push(path.join(tree, file));
+    }
+  }
+  return files;
+}
+
 /**
  * Load a topic doc from disk. A `.ts` doc is loaded through jiti, the rest
  * natively; both the historical `export const docs` and the stamped
@@ -384,7 +401,11 @@ export function problemsInNamespace(doc) {
     }
   }
   const slots = doc?.slots;
-  if (slots == null || typeof slots !== 'object' || Object.keys(slots).length === 0) {
+  if (
+    slots == null ||
+    typeof slots !== 'object' ||
+    Object.keys(slots).length === 0
+  ) {
     problems.push('slots: expected at least one slot');
     return problems;
   }
@@ -392,7 +413,10 @@ export function problemsInNamespace(doc) {
     if (typeof slot?.title !== 'string' || slot.title === '') {
       problems.push(`slots.${name}.title: expected a non-empty string`);
     }
-    if (!Array.isArray(slot?.accepts?.kinds) || slot.accepts.kinds.length === 0) {
+    if (
+      !Array.isArray(slot?.accepts?.kinds) ||
+      slot.accepts.kinds.length === 0
+    ) {
       problems.push(`slots.${name}.accepts.kinds: expected at least one kind`);
     }
   }

package/foundation/discovery/project-typescript.d.mts

@@ -2,7 +2,9 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Resolve the project's own `typescript`, trying each directory in order.
+ * Resolve the project's own `typescript`, trying each directory in order;
+ * where it has no JavaScript compiler API (TypeScript 7), the TypeScript 6
+ * API package installed beside it.
  * @param {Array<string | null | undefined>} dirs
  * @returns {{ts: any, version: string} | {ts: null, version: string} | null}
  *   `ts: null` when a TypeScript is installed but has no `createProgram`
@@ -16,8 +18,15 @@ export function resolveProjectTypeScript(dirs: Array<string | null | undefined>)
 } | null;
 /**
  * Why a check that needs the compiler did not run, when the TypeScript
- * installed has no JavaScript compiler API.
+ * installed has no JavaScript compiler API, and what to do.
  * @param {string} version
  * @param {string} outcome what was not done, such as `docs were not checked`
  */
 export function unusableTypeScriptReason(version: string, outcome: string): string;
+/**
+ * What to do when the project's TypeScript is missing or cannot be used:
+ * beside TypeScript 7, the TypeScript 6 API package it ships for tools;
+ * otherwise a version every check here reads, 5.0 (the oldest that checks a
+ * JavaScript doc) through 6.
+ */
+export const TYPESCRIPT_FIX: "On TypeScript 7, add its TypeScript 6 API package (`npm install -D @typescript/typescript6`); otherwise install TypeScript 5.0 through 6 (`npm install -D typescript@6`). Then run this check again.";

package/foundation/discovery/project-typescript.mjs

@@ -15,7 +15,16 @@ import * as path from 'node:path';
 import {createRequire} from 'node:module';
 
 /**
- * Resolve the project's own `typescript`, trying each directory in order.
+ * The package TypeScript publishes beside TypeScript 7 for tools that need a
+ * JavaScript compiler API: TypeScript 6's. Kept in a constant so the type
+ * check does not treat the load as a static import of an uninstalled package.
+ */
+const TYPESCRIPT_6_API = '@typescript/typescript6';
+
+/**
+ * Resolve the project's own `typescript`, trying each directory in order;
+ * where it has no JavaScript compiler API (TypeScript 7), the TypeScript 6
+ * API package installed beside it.
  * @param {Array<string | null | undefined>} dirs
  * @returns {{ts: any, version: string} | {ts: null, version: string} | null}
  *   `ts: null` when a TypeScript is installed but has no `createProgram`
@@ -43,19 +52,38 @@ export function resolveProjectTypeScript(dirs) {
       unusable ??= installed();
     } catch {
       // Not installed from here, or installed without an entry this CLI can
-      // load; try the next directory.
+      // load.
       unusable ??= installed();
     }
+    // TypeScript 7 has no JavaScript compiler API; the package TypeScript
+    // ships beside it for tools that need one carries TypeScript 6's.
+    try {
+      const ts = require(TYPESCRIPT_6_API);
+      if (ts && typeof ts.createProgram === 'function') {
+        return {ts, version: String(ts.version)};
+      }
+    } catch {
+      // Not installed from here; try the next directory.
+    }
   }
   return unusable ? {ts: null, version: unusable} : null;
 }
 
+/**
+ * What to do when the project's TypeScript is missing or cannot be used:
+ * beside TypeScript 7, the TypeScript 6 API package it ships for tools;
+ * otherwise a version every check here reads, 5.0 (the oldest that checks a
+ * JavaScript doc) through 6.
+ */
+export const TYPESCRIPT_FIX =
+  'On TypeScript 7, add its TypeScript 6 API package (`npm install -D @typescript/typescript6`); otherwise install TypeScript 5.0 through 6 (`npm install -D typescript@6`). Then run this check again.';
+
 /**
  * Why a check that needs the compiler did not run, when the TypeScript
- * installed has no JavaScript compiler API.
+ * installed has no JavaScript compiler API, and what to do.
  * @param {string} version
  * @param {string} outcome what was not done, such as `docs were not checked`
  */
 export function unusableTypeScriptReason(version, outcome) {
-  return `TypeScript ${version} is installed in this project, but it has no JavaScript compiler API (\`createProgram\`) to read types with, so ${outcome}.`;
+  return `TypeScript ${version} is installed in this project, but it has no JavaScript compiler API (\`createProgram\`) to read types with (TypeScript 7 ships none), so ${outcome}. ${TYPESCRIPT_FIX}`;
 }

package/foundation/discovery/prop-drift.d.mts

@@ -25,7 +25,7 @@ export function comparePropDocs(components: PropDriftComponent[], options: {
     loadDoc?: (docPath: string) => Promise<any>;
 }): Promise<PropDriftReport>;
 /**
- * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch'} PropDriftKind
+ * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch' | 'default_mismatch'} PropDriftKind
  */
 /**
  * @typedef {object} PropDriftFinding
@@ -40,6 +40,9 @@ export function comparePropDocs(components: PropDriftComponent[], options: {
  * @property {string} [codeType] the type as the source declares it
  * @property {boolean} [docRequired]
  * @property {boolean} [codeRequired]
+ * @property {string} [docDefault] the documented default, as written
+ * @property {string} [codeDefault] the literal default the code writes
+ * @property {string} [fix] what to change, ready to paste
  */
 /**
  * @typedef {object} PropDriftUnchecked
@@ -53,8 +56,10 @@ export function comparePropDocs(components: PropDriftComponent[], options: {
  * @property {string} doc the doc file, relative to the package root
  * @property {string} reason why: not a form the check judges exactly, a
  *   field the prop's variants give different types, a standard prop
- *   (`className`, `style`, …), or a prop declared outside the package
- * @property {string[]} props documented props whose types were not compared
+ *   (`className`, `style`, …), a prop declared outside the package, or a
+ *   default that is not a literal on one side
+ * @property {string[]} props documented props whose types, or defaults, were
+ *   not compared
  */
 /**
  * @typedef {object} PropDriftReport
@@ -96,7 +101,7 @@ export function comparePropDocs(components: PropDriftComponent[], options: {
  */
 export const PROPS_NOT_DOCUMENTED: readonly string[];
 /** The line both surfaces print when the compiler is missing. */
-export const TYPESCRIPT_MISSING_REASON: "TypeScript is not installed in this project, so documented props were not compared with the code. Install typescript and run this check again.";
+export const TYPESCRIPT_MISSING_REASON: "TypeScript is not installed in this project, so documented props were not compared with the code. On TypeScript 7, add its TypeScript 6 API package (`npm install -D @typescript/typescript6`); otherwise install TypeScript 5.0 through 6 (`npm install -D typescript@6`). Then run this check again.";
 export type CodeProp = {
     name: string;
     /**
@@ -146,7 +151,7 @@ export type CodeProp = {
      */
     location: any;
 };
-export type PropDriftKind = "not_in_code" | "not_in_doc" | "required_mismatch" | "type_mismatch";
+export type PropDriftKind = "not_in_code" | "not_in_doc" | "required_mismatch" | "type_mismatch" | "default_mismatch";
 export type PropDriftFinding = {
     /**
      * the documented component (export) name
@@ -174,6 +179,18 @@ export type PropDriftFinding = {
     codeType?: string | undefined;
     docRequired?: boolean | undefined;
     codeRequired?: boolean | undefined;
+    /**
+     * the documented default, as written
+     */
+    docDefault?: string | undefined;
+    /**
+     * the literal default the code writes
+     */
+    codeDefault?: string | undefined;
+    /**
+     * what to change, ready to paste
+     */
+    fix?: string | undefined;
 };
 export type PropDriftUnchecked = {
     component: string;
@@ -195,11 +212,13 @@ export type PropDriftTypesNotCompared = {
     /**
      * why: not a form the check judges exactly, a
      * field the prop's variants give different types, a standard prop
-     * (`className`, `style`, …), or a prop declared outside the package
+     * (`className`, `style`, …), a prop declared outside the package, or a
+     * default that is not a literal on one side
      */
     reason: string;
     /**
-     * documented props whose types were not compared
+     * documented props whose types, or defaults, were
+     * not compared
      */
     props: string[];
 };

package/foundation/discovery/prop-drift.mjs

@@ -31,7 +31,11 @@
  *   each);
  * - `type_mismatch`: for a prop declared in the package, the documented type
  *   differs from the code's where both sides read exactly (type-match.mjs
- *   states the rules); every other type is listed as not compared.
+ *   states the rules); every other type is listed as not compared;
+ * - `default_mismatch`: the doc's `default` and the literal default the
+ *   component writes in its props parameter's destructuring (`size = 'md'`)
+ *   differ, quotes and whitespace aside; where both write a default and
+ *   either is not a literal, it is listed under `typesNotCompared`.
  *
  * @input Component records (name, docPath, sourcePath), or prop tables, the
  *   package root, and the directories to resolve `typescript` from.
@@ -47,6 +51,7 @@ import {loadComponentDoc} from './component-loader.mjs';
 import {readPackageTsconfig} from './package-tsconfig.mjs';
 import {
   resolveProjectTypeScript,
+  TYPESCRIPT_FIX,
   unusableTypeScriptReason,
 } from './project-typescript.mjs';
 import {judgeType} from './type-match.mjs';
@@ -57,7 +62,7 @@ import {
 } from './unresolved-references.mjs';
 
 /**
- * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch'} PropDriftKind
+ * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch' | 'default_mismatch'} PropDriftKind
  */
 
 /**
@@ -73,6 +78,9 @@ import {
  * @property {string} [codeType] the type as the source declares it
  * @property {boolean} [docRequired]
  * @property {boolean} [codeRequired]
+ * @property {string} [docDefault] the documented default, as written
+ * @property {string} [codeDefault] the literal default the code writes
+ * @property {string} [fix] what to change, ready to paste
  */
 
 /**
@@ -88,8 +96,10 @@ import {
  * @property {string} doc the doc file, relative to the package root
  * @property {string} reason why: not a form the check judges exactly, a
  *   field the prop's variants give different types, a standard prop
- *   (`className`, `style`, …), or a prop declared outside the package
- * @property {string[]} props documented props whose types were not compared
+ *   (`className`, `style`, …), a prop declared outside the package, or a
+ *   default that is not a literal on one side
+ * @property {string[]} props documented props whose types, or defaults, were
+ *   not compared
  */
 
 /**
@@ -148,6 +158,15 @@ const SKIP_TAGS = new Set(['internal']);
 const NOT_EXACT = 'not a form the check judges exactly';
 /** A field documented with one variant's type, where they differ. */
 const VARIANTS = "the prop's variants give this field different types";
+
+/** A default the code writes that is not a literal (a constant, a call). */
+const NOT_LITERAL = Symbol('not a literal');
+
+/** Why a documented default was not compared with the code's. */
+const CODE_DEFAULT_NOT_LITERAL =
+  'its default in the code is not a literal, so the documented default was not compared';
+const DOC_DEFAULT_NOT_LITERAL =
+  "its documented default is not a literal, so it was not compared with the code's";
 /** @type {(name: string, code?: CodeProp) => string} why a prop is not judged */
 const outside = (name, code) =>
   code?.untraced
@@ -158,8 +177,7 @@ const outside = (name, code) =>
 const HOOK_NAME = /^use[A-Z0-9]/;
 
 /** The line both surfaces print when the compiler is missing. */
-export const TYPESCRIPT_MISSING_REASON =
-  'TypeScript is not installed in this project, so documented props were not compared with the code. Install typescript and run this check again.';
+export const TYPESCRIPT_MISSING_REASON = `TypeScript is not installed in this project, so documented props were not compared with the code. ${TYPESCRIPT_FIX}`;
 
 /**
  * @template T
@@ -252,7 +270,7 @@ function ownFileTest(root) {
  * @param {import('./unresolved-references.mjs').UnresolvedReference | null} ambient
  *   what the program's other roots cannot resolve, which any component may
  *   use
- * @returns {{ok: true, props: Map<string, CodeProp>, accepts: (name: string) => any} | {ok: false, reason: string}}
+ * @returns {{ok: true, props: Map<string, CodeProp>, accepts: (name: string) => any, defaults?: Map<string, string | number | boolean | null | symbol>} | {ok: false, reason: string}}
  */
 function readCodeProps(
   ts,
@@ -580,7 +598,118 @@ function readCodeProps(
   /** The index signatures of the props type that take this name. */
   const accepts = (/** @type {string} */ name) =>
     indexesFor(ts, checker, members, name);
-  return {ok: true, props, accepts};
+  return {ok: true, props, accepts, defaults: literalDefaults(ts, symbol)};
+}
+
+/**
+ * The defaults a component writes in its props parameter's destructuring
+ * (`{size = 'md'}`), by prop name, each as its value: a string, number,
+ * boolean, or null, or NOT_LITERAL for any other default (a constant, a call,
+ * an object), which is listed as not compared.
+ * @param {any} ts
+ * @param {any} symbol the component
+ * @returns {Map<string, string | number | boolean | null | symbol>}
+ */
+function literalDefaults(ts, symbol) {
+  /** @type {Map<string, string | number | boolean | null | symbol>} */
+  const out = new Map();
+  /** @param {any} node @param {number} depth @returns {any} */
+  const fnOf = (node, depth) => {
+    if (!node || depth > 4) return null;
+    if (
+      ts.isFunctionDeclaration(node) ||
+      ts.isArrowFunction(node) ||
+      ts.isFunctionExpression(node)
+    ) {
+      return node;
+    }
+    if (ts.isVariableDeclaration(node))
+      return fnOf(node.initializer, depth + 1);
+    if (
+      ts.isParenthesizedExpression(node) ||
+      ts.isAsExpression(node) ||
+      (ts.isSatisfiesExpression && ts.isSatisfiesExpression(node))
+    ) {
+      return fnOf(node.expression, depth + 1);
+    }
+    // `forwardRef(function …)`, `memo(…)`: the function they wrap.
+    if (ts.isCallExpression(node)) {
+      for (const argument of node.arguments) {
+        const found = fnOf(argument, depth + 1);
+        if (found) return found;
+      }
+    }
+    return null;
+  };
+  const fn = fnOf(symbol?.valueDeclaration, 0);
+  const pattern = fn?.parameters?.[0]?.name;
+  if (!pattern || !ts.isObjectBindingPattern(pattern)) return out;
+  for (const element of pattern.elements) {
+    if (element.dotDotDotToken || !element.initializer) continue;
+    const key = element.propertyName ?? element.name;
+    if (!(
+      ts.isIdentifier(key) ||
+      ts.isStringLiteral(key) ||
+      ts.isNumericLiteral(key)
+    )) {
+      continue;
+    }
+    const value = literalValue(ts, element.initializer);
+    out.set(key.text, value === undefined ? NOT_LITERAL : value);
+  }
+  return out;
+}
+
+/**
+ * A literal expression's value, or undefined for anything else.
+ * @param {any} ts
+ * @param {any} node
+ * @returns {string | number | boolean | null | undefined}
+ */
+function literalValue(ts, node) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (
+    ts.isPrefixUnaryExpression(node) &&
+    node.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(node.operand)
+  ) {
+    return -Number(node.operand.text);
+  }
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  return undefined;
+}
+
+/**
+ * A documented default as a literal value: a quoted string (quotes of any
+ * kind, whitespace around it ignored), a number, `true`, `false`, or
+ * `null`; undefined for prose or an expression, which is never compared.
+ * @param {unknown} written
+ * @returns {string | number | boolean | null | undefined}
+ */
+function documentedDefault(written) {
+  if (typeof written === 'number' || typeof written === 'boolean') {
+    return written;
+  }
+  if (written === null) return null;
+  if (typeof written !== 'string') return undefined;
+  const text = written.trim();
+  const quoted = /^(['"`])([^'"`]*)\1$/.exec(text);
+  if (quoted) return quoted[2];
+  if (/^-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(text)) return Number(text);
+  if (text === 'true') return true;
+  if (text === 'false') return false;
+  if (text === 'null') return null;
+  return undefined;
+}
+
+/** @param {string | number | boolean | null} value */
+function defaultText(value) {
+  return typeof value === 'string' ? `'${value}'` : String(value);
 }
 
 /**
@@ -1952,6 +2081,42 @@ export function comparePropTables(tables, options) {
             codeRequired: code.required,
           });
         }
+        // A literal default the code writes in its props destructuring and a
+        // literal the doc writes must agree; where both write a default and
+        // either is not a literal, the default is listed as not compared.
+        const codeDefault = read.defaults?.get(propName);
+        const docWrites =
+          entries.length === 1 &&
+          raw.default !== undefined &&
+          raw.default !== '';
+        const docDefault = docWrites
+          ? documentedDefault(raw.default)
+          : undefined;
+        if (codeDefault !== undefined && docWrites) {
+          if (codeDefault === NOT_LITERAL) {
+            skip(CODE_DEFAULT_NOT_LITERAL, propName);
+          } else if (docDefault === undefined) {
+            skip(DOC_DEFAULT_NOT_LITERAL, propName);
+          }
+        }
+        if (
+          codeDefault !== undefined &&
+          codeDefault !== NOT_LITERAL &&
+          docDefault !== undefined &&
+          codeDefault !== docDefault
+        ) {
+          const shown = defaultText(
+            /** @type {string | number | boolean | null} */ (codeDefault),
+          );
+          findings.push({
+            ...base,
+            kind: 'default_mismatch',
+            message: `"${propName}" is documented with default ${String(raw.default).trim()}, but the code defaults it to ${shown}.`,
+            fix: `In ${table.doc}, set the "${propName}" prop's default to the code's: default: ${JSON.stringify(shown)}.`,
+            docDefault: String(raw.default),
+            codeDefault: shown,
+          });
+        }
         if (!code.own && typeof entry.type === 'string') {
           skip(outside(propName, code), propName);
         }

package/foundation/discovery/prop-drift.test.mjs

@@ -58,6 +58,37 @@ function withTypeScript() {
   );
 }
 
+/**
+ * TypeScript 7 (no JavaScript compiler API) with the TypeScript 6 API package
+ * beside it, which re-exports a real TypeScript.
+ */
+function withTypeScript7AndItsTypeScript6Api() {
+  const ts7 = path.join(pkg, 'node_modules', 'typescript');
+  fs.mkdirSync(ts7, {recursive: true});
+  fs.writeFileSync(
+    path.join(ts7, 'package.json'),
+    JSON.stringify({
+      name: 'typescript',
+      version: '7.0.2',
+      exports: {'./package.json': './package.json'},
+    }),
+  );
+  const ts6 = path.join(pkg, 'node_modules', '@typescript', 'typescript6');
+  fs.mkdirSync(ts6, {recursive: true});
+  fs.writeFileSync(
+    path.join(ts6, 'package.json'),
+    JSON.stringify({
+      name: '@typescript/typescript6',
+      version: '6.0.2',
+      main: 'index.js',
+    }),
+  );
+  fs.writeFileSync(
+    path.join(ts6, 'index.js'),
+    `module.exports = require(${JSON.stringify(TYPESCRIPT_DIR)});\n`,
+  );
+}
+
 /**
  * Write `components/<name>.tsx` and its doc; returns its prop table, which
  * also carries the component record (name, docPath, sourcePath).
@@ -176,7 +207,8 @@ describe('comparePropTables', () => {
     expect(await compare([component('Badge', source, doc)])).toMatchObject({
       findings: [],
       typesCompared: 0,
-      typesSkipped: `TypeScript 4.7.4 is older than 4.8, the oldest the type comparison reads`,
+      typesSkipped:
+        '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',
     });
   });
 
@@ -334,6 +366,71 @@ export function Badge(props: BadgeProps) { return null; }`,
     ).toMatchObject({docRequired: false, codeRequired: true});
   });
 
+  it('compares a documented default with a literal default in the props destructuring, quotes and whitespace aside, and skips any other default', async () => {
+    withTypeScript();
+    const widget = component(
+      'Widget',
+      `const SIZE = 'md';
+export interface WidgetProps { size?: 'sm' | 'md'; tone?: string; count?: number; open?: boolean; label?: string; gap?: number; mode?: string }
+export function Widget({size = 'md', tone = "info", count = -2, open = false, label = SIZE, gap = 4, mode}: WidgetProps) { return null; }`,
+      {
+        props: [
+          prop('size', "'sm' | 'md'", {default: "'sm'"}),
+          prop('tone', 'string', {default: ' "info" '}),
+          prop('count', 'number', {default: '-2'}),
+          prop('open', 'boolean', {default: 'true'}),
+          prop('label', 'string', {default: "'x'"}),
+          prop('gap', 'number', {default: 'the theme gap'}),
+          prop('mode', 'string', {default: "'a'"}),
+        ],
+      },
+    );
+    const forwarded = component(
+      'Forwarded',
+      `declare function forwardRef<T>(render: T): T;
+export const Forwarded = forwardRef(function Forwarded({variant = 'solid'}: {variant?: string}) { return null; });`,
+      {props: [prop('variant', 'string', {default: "'ghost'"})]},
+    );
+
+    const report = await compare([widget, forwarded]);
+
+    expect(kinds(report)).toEqual([
+      'Forwarded.variant default_mismatch',
+      'Widget.open default_mismatch',
+      'Widget.size default_mismatch',
+    ]);
+    // A default that is not a literal on either side is listed, not skipped.
+    expect(report.typesNotCompared).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          component: 'Widget',
+          reason: expect.stringContaining(
+            'default in the code is not a literal',
+          ),
+          props: ['label'],
+        }),
+        expect.objectContaining({
+          component: 'Widget',
+          reason: expect.stringContaining(
+            'documented default is not a literal',
+          ),
+          props: ['gap'],
+        }),
+      ]),
+    );
+    expect(report.typesNotCompared.flatMap(entry => entry.props)).not.toContain(
+      'mode',
+    );
+    expect(report.findings.find(f => f.prop === 'size')).toMatchObject({
+      severity: 'warning',
+      message:
+        "\"size\" is documented with default 'sm', but the code defaults it to 'md'.",
+      fix: 'In components/Widget.doc.mjs, set the "size" prop\'s default to the code\'s: default: "\'md\'".',
+      docDefault: "'sm'",
+      codeDefault: "'md'",
+    });
+  });
+
   it("judges a field, a name an index signature takes, and a prop declared in another file by the type's name where the prop is declared, not by the name the type was declared with", async () => {
     withTypeScript();
     const dir = path.join(pkg, 'components');
@@ -2179,6 +2276,23 @@ export const Hoc = withName((props: {label?: string}) => null);`;
     ]);
   });
 
+  it("compares with TypeScript 7's TypeScript 6 API package when the project has one", async () => {
+    const badge = component(
+      'Badge',
+      'export function Badge(props: {label: string}) { return null; }\n',
+      {props: [prop('label', 'number')]},
+    );
+    withTypeScript7AndItsTypeScript6Api();
+
+    const report = await compare([badge]);
+
+    expect(report.status).toBe('checked');
+    // The comparison ran: the documented `number` is judged against `string`.
+    expect(
+      report.findings.map(f => `${f.component}.${f.prop} ${f.kind}`),
+    ).toContain('Badge.label type_mismatch');
+  });
+
   it('skips with a reason, and compares nothing, without a TypeScript it can use', async () => {
     const badge = component(
       'Badge',
@@ -2196,6 +2310,7 @@ export const Hoc = withName((props: {label?: string}) => null);`;
     });
 
     expect(await compare([badge])).toEqual(skipped(TYPESCRIPT_MISSING_REASON));
+    expect(TYPESCRIPT_MISSING_REASON).toContain('npm install -D typescript@6');
     // TypeScript 7 has no JavaScript compiler API to load.
     const dir = path.join(pkg, 'node_modules', 'typescript');
     fs.mkdirSync(dir, {recursive: true});
@@ -2207,7 +2322,10 @@ export const Hoc = withName((props: {label?: string}) => null);`;
         exports: {'./package.json': './package.json'},
       }),
     );
-    expect(await compare([badge])).toEqual(
+    const report = await compare([badge]);
+    expect(report.reason).toContain('TypeScript 7.0.0');
+    expect(report.reason).toContain('npm install -D @typescript/typescript6');
+    expect(report).toEqual(
       skipped(
         unusableTypeScriptReason(
           '7.0.0',

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";
+    }>;
+}>;