@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/foundation/discovery/module-exports.mjs

@@ -309,6 +309,259 @@ export function moduleExportSource(file, exportName, seen = new Set()) {
   return found;
 }
 
+/**
+ * The module's own top-level statements of one type: an `export` inside a
+ * TypeScript namespace names a member of that namespace, not of the module.
+ * @param {any} program
+ * @param {string} type
+ * @returns {any[]}
+ */
+function topLevel(program, type) {
+  return program.body.filter((/** @type {any} */ node) => node.type === type);
+}
+
+/**
+ * Every runtime name a module exports that this read can see (`default` for
+ * a default export), or null when it cannot see them all: an `export *`, `export =`, CommonJS exports, or a
+ * file that does not parse.
+ * @param {string} file
+ * @returns {string[] | null}
+ */
+export function moduleExportNames(file) {
+  let text;
+  let ast;
+  try {
+    if (!fs.statSync(file).isFile()) return null;
+    text = moduleText(file);
+    ast = parseModule(file);
+  } catch {
+    return null;
+  }
+  if (/\bmodule\.exports\b|\bexports\.[$\w]/u.test(text)) return null;
+  if (
+    topLevel(ast.program, 'TSExportAssignment').length > 0 ||
+    topLevel(ast.program, 'ExportAllDeclaration').length > 0
+  ) {
+    return null;
+  }
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const node of topLevel(ast.program, 'TSImportEqualsDeclaration')) {
+    if (!node.isExport) continue;
+    // A type-only alias has no runtime value; any other might.
+    if (node.importKind === 'type') continue;
+    if (typeof node.id?.name !== 'string') return null;
+    names.add(node.id.name);
+  }
+  for (const node of topLevel(ast.program, 'ExportNamedDeclaration')) {
+    if (node.exportKind === 'type') continue;
+    const declaration = node.declaration;
+    if (declaration?.type === 'VariableDeclaration') {
+      for (const item of declaration.declarations) {
+        if (item.id?.type !== 'Identifier') return null;
+        names.add(item.id.name);
+      }
+    } else if (declaration != null) {
+      if (!runtimeDefault(declaration)) continue;
+      if (typeof declaration.id?.name !== 'string') return null;
+      names.add(declaration.id.name);
+    }
+    for (const specifier of node.specifiers ?? []) {
+      if (specifier.exportKind === 'type') continue;
+      const exported = specifier.exported?.name ?? specifier.exported?.value;
+      if (typeof exported === 'string') names.add(exported);
+    }
+  }
+  if (
+    topLevel(ast.program, 'ExportDefaultDeclaration').some(
+      (/** @type {any} */ node) => runtimeDefault(node.declaration),
+    )
+  ) {
+    names.add('default');
+  }
+  return [...names].sort();
+}
+
+/**
+ * @typedef {{verdict: 'exports'} | {verdict: 'lacks'} | {verdict: 'unknown', reason: string}} ExportVerdict
+ */
+
+/**
+ * Whether a module exports `exportName` at runtime, read without executing
+ * it: `exports` when a declaration or a followed re-export binds it, `lacks`
+ * only when every export the module writes was read and none binds it, and
+ * `unknown`, with the first reason, when some export could not be read: a
+ * re-export from another package or from a specifier that resolves to no
+ * file, a destructured binding, a namespace, an ambient or const enum
+ * declaration, `export =`, CommonJS exports, or a file that does not parse.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {ExportVerdict}
+ */
+export function moduleExportVerdict(file, exportName, seen = new Set()) {
+  const identity = `${file}\0${exportName}`;
+  // A cycle adds nothing a module's own exports have not already said.
+  if (seen.has(identity)) return {verdict: 'lacks'};
+  seen.add(identity);
+  const shown = path.basename(file);
+  let text;
+  let ast;
+  try {
+    if (!fs.statSync(file).isFile()) {
+      return {verdict: 'unknown', reason: `${shown} is not a file.`};
+    }
+    text = moduleText(file);
+    ast = parseModule(file);
+  } catch {
+    return {
+      verdict: 'unknown',
+      reason: `${shown} could not be read or parsed.`,
+    };
+  }
+  /** @type {string[]} */
+  const unknown = [];
+  if (/\bmodule\.exports\b|\bexports\.[$\w]/u.test(text)) {
+    unknown.push(
+      `${shown} uses CommonJS exports, whose names this check does not read.`,
+    );
+  }
+  if (topLevel(ast.program, 'TSExportAssignment').length > 0) {
+    unknown.push(`${shown} uses \`export =\`, whose names this check does not read.`);
+  }
+  /**
+   * Follow a re-export of `imported` from `specifier`.
+   * @param {string} specifier
+   * @param {string} imported
+   * @param {string} what how the reason names what is re-exported
+   * @returns {boolean} true when it proves the export
+   */
+  const follow = (specifier, imported, what) => {
+    if (!specifier.startsWith('.')) {
+      unknown.push(
+        `${shown} re-exports ${what} from "${specifier}", another package this check does not read.`,
+      );
+      return false;
+    }
+    const target = resolveLocalModule(specifier, file);
+    if (!target) {
+      unknown.push(
+        `${shown} re-exports ${what} from "${specifier}", which resolves to no file this check can read.`,
+      );
+      return false;
+    }
+    const inner = moduleExportVerdict(target, imported, seen);
+    if (inner.verdict === 'exports') return true;
+    if (inner.verdict === 'unknown') unknown.push(inner.reason);
+    return false;
+  };
+  // `export import Name = Some.Path;` binds a runtime value unless it is
+  // type-only.
+  for (const node of topLevel(ast.program, 'TSImportEqualsDeclaration')) {
+    if (!node.isExport || node.id?.name !== exportName) continue;
+    if (node.importKind === 'type') {
+      unknown.push(
+        `${shown} exports ${exportName} with \`export import type\`, which has no runtime value this check can see.`,
+      );
+    } else {
+      return {verdict: 'exports'};
+    }
+  }
+  for (const node of topLevel(ast.program, 'ExportNamedDeclaration')) {
+    if (node.exportKind === 'type') continue;
+    const declaration = node.declaration;
+    if (declaration?.type === 'VariableDeclaration') {
+      for (const item of declaration.declarations) {
+        if (item.id?.type !== 'Identifier') {
+          unknown.push(
+            `${shown} exports a destructured binding, whose names this check does not read.`,
+          );
+        } else if (item.id.name === exportName) {
+          if (declaration.declare === true) {
+            unknown.push(
+              `${shown} declares ${exportName} with \`declare\`, which has no runtime value this check can see.`,
+            );
+          } else {
+            return {verdict: 'exports'};
+          }
+        }
+      }
+    } else if (declaration != null && declaration.id?.name === exportName) {
+      if (
+        ['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'].includes(
+          declaration.type,
+        )
+      ) {
+        // A type only: no runtime export.
+      } else if (declaration.type === 'TSModuleDeclaration') {
+        unknown.push(
+          `${shown} exports ${exportName} as a TypeScript namespace, which has a runtime value only when it holds one.`,
+        );
+      } else if (declaration.declare === true || declaration.const === true) {
+        unknown.push(
+          `${shown} declares ${exportName} as an ambient or const declaration, which has no runtime value this check can see.`,
+        );
+      } else if (runtimeDefault(declaration)) {
+        return {verdict: 'exports'};
+      }
+    }
+    for (const specifier of node.specifiers ?? []) {
+      if (specifier.exportKind === 'type') continue;
+      const exported = specifier.exported?.name ?? specifier.exported?.value;
+      if (exported !== exportName) continue;
+      if (!node.source || specifier.type === 'ExportNamespaceSpecifier') {
+        return {verdict: 'exports'};
+      }
+      if (specifier.type !== 'ExportSpecifier') {
+        unknown.push(`${shown} re-exports ${exportName} in a form this check does not read.`);
+        continue;
+      }
+      const imported =
+        specifier.local?.name ?? specifier.local?.value ?? exportName;
+      if (follow(String(node.source.value), imported, exportName)) {
+        return {verdict: 'exports'};
+      }
+    }
+  }
+  if (exportName === 'default') {
+    const defaults = topLevel(ast.program, 'ExportDefaultDeclaration');
+    if (
+      defaults.some((/** @type {any} */ node) =>
+        runtimeDefault(node.declaration),
+      )
+    ) {
+      return {verdict: 'exports'};
+    }
+  }
+  for (const node of topLevel(ast.program, 'ExportAllDeclaration')) {
+    if (node.exportKind === 'type') continue;
+    const exported = node.exported?.name ?? node.exported?.value;
+    if (exported != null) {
+      if (exported === exportName) return {verdict: 'exports'};
+      continue;
+    }
+    // `export *` never re-exports a default.
+    if (exportName === 'default') continue;
+    if (follow(String(node.source?.value ?? ''), exportName, 'everything')) {
+      return {verdict: 'exports'};
+    }
+  }
+  return unknown.length > 0
+    ? {verdict: 'unknown', reason: unknown[0]}
+    : {verdict: 'lacks'};
+}
+
+/**
+ * Whether a module provably does not export `exportName` at runtime: see
+ * {@link moduleExportVerdict}.
+ * @param {string} file
+ * @param {string} exportName
+ * @returns {boolean}
+ */
+export function moduleLacksExport(file, exportName) {
+  return moduleExportVerdict(file, exportName).verdict === 'lacks';
+}
+
 /**
  * Marks an object {@link staticExportObject} returns (or one inside it) whose
  * source also has properties or spreads it could not read as literals. Not

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

@@ -14,10 +14,8 @@
  *   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.
+ * The matcher is runnerCommandsIn (foundation/discovery/runner-commands.mjs),
+ * the rule `doctor integration validate` holds integrations to.
  *
  * @input  nothing
  * @output the allowlist

package/foundation/discovery/runner-allowlist.mjs

@@ -13,10 +13,8 @@
  *   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.
+ * The matcher is runnerCommandsIn (foundation/discovery/runner-commands.mjs),
+ * the rule `doctor integration validate` holds integrations to.
  *
  * @input  nothing
  * @output the allowlist

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

@@ -0,0 +1,77 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Each runner command in a text, as written, with the bare command to write
+ * instead, in order.
+ *
+ * @param {string} text
+ * @returns {{written: string, bare: string, download: boolean}[]}
+ */
+export function runnerCommandsIn(text: string): {
+    written: string;
+    bare: string;
+    download: boolean;
+}[];
+/**
+ * An Astryx command a topic writes with a package runner in front.
+ *
+ * @typedef {object} RunnerCommand
+ * @property {string} topic
+ * @property {string | null} section the title of the section it is in
+ * @property {string} file the doc file
+ * @property {number | null} line the file line that holds it, when found
+ * @property {string} command the command as written
+ * @property {string} message the bare command to write instead
+ */
+/**
+ * Runner commands in a package's topics.
+ *
+ * @param {{records: {name: string, path: string}[], guides?: {name: string, ref?: {topicFile?: string}}[]}} discovered
+ *   the package's docs, as discoverIntegrationDocs returns them
+ * @returns {Promise<RunnerCommand[]>}
+ */
+export function findRunnerCommands(discovered: {
+    records: {
+        name: string;
+        path: string;
+    }[];
+    guides?: {
+        name: string;
+        ref?: {
+            topicFile?: string;
+        };
+    }[];
+}): Promise<RunnerCommand[]>;
+/**
+ * The CLI's top-level commands, the words that make a project runner's
+ * `astryx <word>` a command; runner-commands.test.mjs keeps the list equal to
+ * the command docs.
+ */
+export const CLI_COMMANDS: readonly string[];
+/**
+ * An Astryx command a topic writes with a package runner in front.
+ */
+export type RunnerCommand = {
+    topic: string;
+    /**
+     * the title of the section it is in
+     */
+    section: string | null;
+    /**
+     * the doc file
+     */
+    file: string;
+    /**
+     * the file line that holds it, when found
+     */
+    line: number | null;
+    /**
+     * the command as written
+     */
+    command: string;
+    /**
+     * the bare command to write instead
+     */
+    message: string;
+};

package/foundation/discovery/runner-commands.mjs

@@ -0,0 +1,294 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Runner commands in docs: an Astryx command written with a package runner in
+ * front. Docs write the bare `astryx <command>` and the CLI shows it with the
+ * reader's runner, so a written runner is wrong for every reader on another
+ * package manager.
+ *
+ * - A download runner (`npx`, `pnpm dlx`, `yarn dlx`, `bunx`, `bun x`,
+ *   `npm exec`) with the unscoped name `astryx`, with or without an
+ *   `@<version>` after it, always counts, even with nothing after it: it
+ *   fetches an unrelated package of that name.
+ * - A project runner (`pnpm exec`, `pnpm`, `yarn`) counts when one of the
+ *   CLI's commands follows on the same line (`pnpm exec astryx docs`). Named
+ *   alone, or before a word that is not a command (`yarn astryx runs the
+ *   copy…`), it is left alone.
+ * - A runner and what follows it are read within one line; flags between a
+ *   download runner and the name are read past.
+ * - The scoped package (`npx @astryxdesign/cli init`) never counts: it is the
+ *   one form that runs before the CLI is installed, for install steps.
+ * - Other tools' commands (`npx prettier`) never count.
+ */
+
+import fs from 'node:fs';
+
+import {loadTopicModule} from './docs-discovery.mjs';
+
+/**
+ * @param {string} file
+ * @returns {Promise<any>} the doc, or null for one that does not load (the
+ *   load problem is reported elsewhere)
+ */
+async function loadQuietly(file) {
+  try {
+    return await loadTopicModule(file);
+  } catch {
+    return null;
+  }
+}
+
+const DOWNLOAD_RUNNERS = [
+  'pnpm dlx',
+  'yarn dlx',
+  'npm exec --',
+  'npm exec',
+  'npx',
+  'bunx',
+  'bun x',
+];
+const PROJECT_RUNNERS = ['pnpm exec', 'pnpm', 'yarn'];
+
+/**
+ * The CLI's top-level commands, the words that make a project runner's
+ * `astryx <word>` a command; runner-commands.test.mjs keeps the list equal to
+ * the command docs.
+ */
+export const CLI_COMMANDS = Object.freeze([
+  'blog',
+  'build',
+  'component',
+  'discover',
+  'docs',
+  'doctor',
+  'gap-report',
+  'help',
+  'hook',
+  'init',
+  'integration',
+  'manifest',
+  'postinstall',
+  'search',
+  'swizzle',
+  'template',
+  'theme',
+  'upgrade',
+]);
+
+/** Blanks within one line. */
+const BLANK = '[ \\t]+';
+
+/** @param {readonly string[]} words */
+const alternatives = words =>
+  words.map(each => each.replace(/ /g, BLANK)).join('|');
+
+/** After `astryx`: the name ends here (a sentence's period may follow). */
+const NAME_END = '(?![\\w@/-]|\\.\\w)';
+
+const DOWNLOAD_COMMAND = new RegExp(
+  `(?<![\\w@/.-])(?:${alternatives(DOWNLOAD_RUNNERS)})(?:${BLANK}--?[a-z][\\w-]*)*${BLANK}astryx(?:@[\\w^~-]+(?:\\.[\\w^~-]+)*)?${NAME_END}(?:${BLANK}(${alternatives(CLI_COMMANDS)})(?![\\w-]))?`,
+  'g',
+);
+const PROJECT_COMMAND = new RegExp(
+  `(?<![\\w@/.-])(?:${alternatives(PROJECT_RUNNERS)})${BLANK}astryx${BLANK}(${alternatives(CLI_COMMANDS)})(?![\\w-])`,
+  'g',
+);
+
+/**
+ * Each runner command in a text, as written, with the bare command to write
+ * instead, in order.
+ *
+ * @param {string} text
+ * @returns {{written: string, bare: string, download: boolean}[]}
+ */
+export function runnerCommandsIn(text) {
+  const found = [
+    ...[...String(text).matchAll(DOWNLOAD_COMMAND)].map(match => ({
+      match,
+      download: true,
+    })),
+    ...[...String(text).matchAll(PROJECT_COMMAND)].map(match => ({
+      match,
+      download: false,
+    })),
+  ];
+  /** @type {{at: number, written: string, bare: string, download: boolean}[]} */
+  const unique = [];
+  for (const {match, download} of found) {
+    if (unique.some(each => each.at === match.index)) continue;
+    unique.push({
+      at: match.index,
+      written: match[0],
+      bare: match[1] ? `astryx ${match[1]}` : 'astryx',
+      download,
+    });
+  }
+  return unique
+    .sort((a, b) => a.at - b.at)
+    .map(({written, bare, download}) => ({written, bare, download}));
+}
+
+/**
+ * Every string in a doc, with the title of the section it is in. Code counts:
+ * most commands sit in code blocks.
+ *
+ * @param {unknown} doc
+ * @returns {{text: string, section: string | null}[]}
+ */
+function allStrings(doc) {
+  /** @type {{text: string, section: string | null}[]} */
+  const strings = [];
+  // A doc that refers back to itself is walked once.
+  const visited = new WeakSet();
+  /**
+   * @param {unknown} value
+   * @param {string | null} section
+   */
+  const walk = (value, section) => {
+    if (typeof value === 'string') {
+      strings.push({text: value, section});
+    } else if (value != null && typeof value === 'object') {
+      if (visited.has(value)) return;
+      visited.add(value);
+      if (Array.isArray(value)) {
+        for (const item of value) walk(item, section);
+        return;
+      }
+      const record = /** @type {Record<string, unknown>} */ (value);
+      for (const [key, field] of Object.entries(record)) {
+        if (key === 'sections' && Array.isArray(field)) {
+          for (const each of field) {
+            walk(each, typeof each?.title === 'string' ? each.title : section);
+          }
+        } else {
+          walk(field, section);
+        }
+      }
+    }
+  };
+  walk(doc, null);
+  return strings;
+}
+
+/**
+ * Where a file next holds the text, at or after a cursor (a 0-based line and
+ * column), else the first place it holds it, else null. A doc's strings are
+ * read in file order, so moving the cursor past each match puts a command the
+ * topic writes twice on its own line.
+ *
+ * @param {string[]} lines
+ * @param {string} written
+ * @param {{line: number, column: number}} cursor
+ * @returns {{line: number, column: number} | null}
+ */
+function locate(lines, written, cursor) {
+  for (let at = cursor.line; at < lines.length; at++) {
+    const column = lines[at].indexOf(
+      written,
+      at === cursor.line ? cursor.column : 0,
+    );
+    if (column >= 0) return {line: at, column};
+  }
+  const first = lines.findIndex(line => line.includes(written));
+  return first < 0
+    ? null
+    : {line: first, column: lines[first].indexOf(written)};
+}
+
+/**
+ * An Astryx command a topic writes with a package runner in front.
+ *
+ * @typedef {object} RunnerCommand
+ * @property {string} topic
+ * @property {string | null} section the title of the section it is in
+ * @property {string} file the doc file
+ * @property {number | null} line the file line that holds it, when found
+ * @property {string} command the command as written
+ * @property {string} message the bare command to write instead
+ */
+
+/**
+ * Runner commands in a package's topics.
+ *
+ * @param {{records: {name: string, path: string}[], guides?: {name: string, ref?: {topicFile?: string}}[]}} discovered
+ *   the package's docs, as discoverIntegrationDocs returns them
+ * @returns {Promise<RunnerCommand[]>}
+ */
+export async function findRunnerCommands(discovered) {
+  const topics = [
+    ...discovered.records.map(record => ({
+      name: record.name,
+      file: record.path,
+    })),
+    ...(discovered.guides ?? []).map(guide => ({
+      name: guide.name,
+      file: guide.ref?.topicFile,
+    })),
+  ];
+  /** @type {RunnerCommand[]} */
+  const found = [];
+  for (const {name, file} of topics) {
+    const doc = file ? await loadQuietly(file) : null;
+    if (!doc || !file) continue;
+    /** @type {string[]} */
+    let lines = [];
+    try {
+      lines = fs.readFileSync(file, 'utf8').split('\n');
+    } catch {
+      // The doc loaded, so only the line number is lost.
+    }
+    let cursor = {line: 0, column: 0};
+    for (const {text, section} of allStrings(doc)) {
+      const commands = runnerCommandsIn(text);
+      if (commands.length === 0) continue;
+      // A one-line string's own literal places it, wherever the walk reached
+      // it (a section in a constant above the doc object, say); else the
+      // cursor search, in file order.
+      const forms = [`'${text}'`, `"${text}"`, JSON.stringify(text)];
+      const holds = (/** @type {string} */ line) =>
+        forms.some(form => line.includes(form));
+      // On the cursor's own line, only a copy at or after the cursor counts:
+      // the copy just matched still sits before it.
+      const after = text.includes('\n')
+        ? -1
+        : lines.findIndex((line, at) =>
+            at > cursor.line
+              ? holds(line)
+              : at === cursor.line &&
+                forms.some(form => line.indexOf(form, cursor.column) >= 0),
+          );
+      const literal =
+        after >= 0 || text.includes('\n') ? after : lines.findIndex(holds);
+      const column = after >= 0 && after === cursor.line ? cursor.column : 0;
+      let from = literal >= 0 ? {line: literal, column} : cursor;
+      for (const {written, bare, download} of commands) {
+        const place = locate(lines, written, from);
+        if (place) {
+          from = {line: place.line, column: place.column + written.length};
+          if (
+            place.line > cursor.line ||
+            (place.line === cursor.line && place.column >= cursor.column)
+          ) {
+            cursor = from;
+          }
+        }
+        const line = place ? place.line + 1 : null;
+        const where = section ? ` (section "${section}")` : '';
+        found.push({
+          topic: name,
+          section,
+          file,
+          line,
+          command: written,
+          message:
+            `"${name}"${where} writes \`${written}\`${line == null ? '' : ` (line ${line})`}. ` +
+            `Write \`${bare}\`; the CLI shows it with your project's runner` +
+            (download
+              ? ', and a download runner with the bare name fetches an unrelated package called astryx.'
+              : '.'),
+        });
+      }
+    }
+  }
+  return found;
+}