@cosyte/script-utils 0.1.2 → 0.1.3

package/internal-refs.js

@@ -24,8 +24,16 @@
 // change what this gate looks for or what it concludes.
 
 import { execFileSync } from "node:child_process";
-import { closeSync, constants as fsConstants, fstatSync, openSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * The exit codes this gate assigns, as a caller may redeclare them.
@@ -332,7 +340,7 @@ export function compileCanonicalRules(resolved) {
       name: "phase or wave language",
       patterns: [
         new RegExp(
-          `\\b(?:roadmap phase\\b[ ]?[A-Za-z0-9]*|${PHASE_NOT_CLINICAL}phase[ -]${PHASE_NOT_FIELD}` +
+          `\\b(?:roadmap phases?\\b[ ]?[A-Za-z0-9]*|${PHASE_NOT_CLINICAL}phases?[ -]${PHASE_NOT_FIELD}` +
             `[A-Za-z0-9]+[a-z]?\\b|wave \\d+\\b|the \\w+ and final phase\\b|` +
             `documentation residual\\b|${ORDINAL} (?:slice|wave)\\b)`,
           "gi",
@@ -340,6 +348,8 @@ export function compileCanonicalRules(resolved) {
       ],
       positives: [
         "Phase 5b closes it (Phase W, Phase-L and the thirteenth slice landed earlier, in wave 2)",
+        // The plural, which ten of the eleven per-repository copies matched (`phases?[ -]`).
+        "Phases 1 to 6 shipped together",
       ],
       negatives: [
         "CSP-1 Study Phase Identifier, CSP-2 Study Phase Start Date/Time, CSP-3 Study Phase End " +
@@ -351,8 +361,12 @@ export function compileCanonicalRules(resolved) {
     {
       id: "adr-reference",
       name: "ADR reference",
-      patterns: [new RegExp("\\bADR[ -]?\\d{3,4}\\b", "gi")],
-      positives: ["Decided in ADR 0015 and restated in ADR-0021"],
+      // `[ /-]`: ten of the eleven per-repository copies also matched an ADR path segment.
+      patterns: [new RegExp("\\bADR[ /-]?\\d{3,4}\\b", "gi")],
+      positives: [
+        "Decided in ADR 0015 and restated in ADR-0021",
+        "Recorded in docs/adr/0001-scope.md",
+      ],
       negatives: ["ADR is not a segment, and 0015 alone is a value"],
     },
     {
@@ -646,13 +660,26 @@ function compileExtraRule(rule, index) {
       }
       continue;
     }
+    // `{ source, flags }`: the form a JSON configuration can carry, so a rule read from
+    // `scripts/internal-refs.json` can be case-insensitive (`"flags": "i"`). `g` is always added.
+    if (isPlainObject(entry) && typeof entry.source === "string") {
+      const flags = typeof entry.flags === "string" ? entry.flags : "";
+      try {
+        patterns.push(new RegExp(entry.source, flags.includes("g") ? flags : `${flags}g`));
+      } catch (cause) {
+        problems.push(`${where} carries a pattern that does not compile: ${String(cause)}`);
+      }
+      continue;
+    }
     if (entry instanceof RegExp) {
       patterns.push(
         new RegExp(entry.source, entry.flags.includes("g") ? entry.flags : `${entry.flags}g`),
       );
       continue;
     }
-    problems.push(`${where} carries a pattern that is neither a string nor a RegExp`);
+    problems.push(
+      `${where} carries a pattern that is neither a string, a RegExp nor a { source, flags } object`,
+    );
   }
   if (patterns.length === 0) problems.push(`${where} declares no pattern`);
   if (!isStringList(rule.positives) || rule.positives.length === 0) {
@@ -1361,3 +1388,101 @@ function report(hits) {
 
 /** Re-exported for a caller that wants to state, in its own docs, what it cannot turn off. */
 export { DEFAULT_EXIT_CODES, REFUSED_OPTIONS };
+
+// ---- The command-line form (ST34) --------------------------------------------
+//
+// `node node_modules/@cosyte/script-utils/internal-refs.js` runs this gate over the repository in
+// the working directory with no caller script: the axes a caller would pass are read from
+// `scripts/internal-refs.json`, the one file a repository keeps for this gate. Keys starting with
+// `$` are notes and are ignored. The exit codes are the house contract, 0 clean, 1 hits, 2 the gate
+// could not run, and the file may not set them, the repository root or the output sinks: the
+// command-line form owns those, and a file that names one is refused rather than half-honoured.
+
+/** Where the command-line form reads the repository's axes. */
+export const INTERNAL_REFS_CONFIG_PATH = "scripts/internal-refs.json";
+
+/** The exit codes of the command-line form. */
+const CLI_EXIT_CODES = Object.freeze({ clean: 0, hits: 1, refuse: 2 });
+
+/** Keys a configuration file may not set, because the command-line form sets them. */
+const CLI_OWNED_KEYS = ["exitCodes", "repoRoot", "write"];
+
+/**
+ * Run the gate from the command line over the repository in the working directory.
+ *
+ * @param {string[]} argv Only `--config <path>` is accepted (default `scripts/internal-refs.json`).
+ * @returns {number} 0 clean, 1 hits, 2 the gate could not run.
+ */
+export function runInternalRefsCli(argv) {
+  let path = INTERNAL_REFS_CONFIG_PATH;
+  const args = argv.filter((arg) => arg !== "--");
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--config" && typeof args[i + 1] === "string") {
+      path = args[i + 1];
+      i += 1;
+    } else {
+      process.stderr.write(
+        `internal-refs: ${JSON.stringify(args[i])} is not an argument this gate accepts (only ` +
+          `--config <path>). Nothing was checked.\n`,
+      );
+      return CLI_EXIT_CODES.refuse;
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(join(process.cwd(), path), "utf8"));
+  } catch (err) {
+    process.stderr.write(
+      `internal-refs: could not read ${path}: ${err.message} Nothing was checked.\n`,
+    );
+    return CLI_EXIT_CODES.refuse;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    process.stderr.write(`internal-refs: ${path} is not a JSON object. Nothing was checked.\n`);
+    return CLI_EXIT_CODES.refuse;
+  }
+  const owned = CLI_OWNED_KEYS.filter((key) => key in parsed);
+  if (owned.length > 0) {
+    process.stderr.write(
+      `internal-refs: ${path} sets ${owned.join(", ")}, which the command-line form sets ` +
+        `itself. Remove ${owned.length === 1 ? "it" : "them"}. Nothing was checked.\n`,
+    );
+    return CLI_EXIT_CODES.refuse;
+  }
+  const config = Object.fromEntries(Object.entries(parsed).filter(([key]) => !key.startsWith("$")));
+  return runInternalRefsScan({ ...config, exitCodes: CLI_EXIT_CODES, repoRoot: process.cwd() });
+}
+
+/**
+ * Whether node was pointed at this file, which is the command-line form.
+ *
+ * SELF-CONTAINED ON PURPOSE: this module is also vendored and copied as a single file, so it may not
+ * import a sibling at load. A file whose name differs from the one node was pointed at cannot be the
+ * entry point, and that is settled without loading anything; only a matching name asks `index.js`'s
+ * `isCliEntrypoint`, and a copy with no `index.js` beside it compares real paths instead. Unsure is
+ * yes, so a gate that cannot tell runs loudly rather than skipping.
+ *
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @returns {Promise<boolean>}
+ */
+async function invokedAsCommand(moduleUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== "string" || entry === "") return false;
+  const own = fileURLToPath(moduleUrl);
+  const stem = (path) => basename(path).replace(/\.[cm]?[jt]s$/, "");
+  if (stem(entry) !== stem(own)) return false;
+  try {
+    const { isCliEntrypoint } = await import("./index.js");
+    return isCliEntrypoint(moduleUrl);
+  } catch {
+    try {
+      return realpathSync(entry) === realpathSync(own);
+    } catch {
+      return true;
+    }
+  }
+}
+
+void invokedAsCommand(import.meta.url).then((command) => {
+  if (command) process.exitCode = runInternalRefsCli(process.argv.slice(2));
+});

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",
     "entrypoint",
     "import-meta",
     "phi",
+    "readme",
     "scripts",
     "cosyte"
   ],
@@ -37,6 +38,22 @@
     "./attw": {
       "types": "./attw.d.ts",
       "default": "./attw.js"
+    },
+    "./readme": {
+      "types": "./readme.d.ts",
+      "default": "./readme.js"
+    },
+    "./claude-card": {
+      "types": "./claude-card.d.ts",
+      "default": "./claude-card.js"
+    },
+    "./catalog": {
+      "types": "./catalog.d.ts",
+      "default": "./catalog.js"
+    },
+    "./agent-notes": {
+      "types": "./agent-notes.d.ts",
+      "default": "./agent-notes.js"
     }
   },
   "files": [
@@ -48,6 +65,15 @@
     "internal-refs.d.ts",
     "attw.js",
     "attw.d.ts",
+    "readme.js",
+    "readme.d.ts",
+    "claude-card.js",
+    "claude-card.d.ts",
+    "catalog.js",
+    "catalog.d.ts",
+    "catalog.json",
+    "agent-notes.js",
+    "agent-notes.d.ts",
     "check-no-emdash.sh",
     "README.md",
     "CHANGELOG.md"

package/phi-scan.d.ts

@@ -274,3 +274,25 @@ export declare function runPhiScan(config: PhiScanConfig): number;
  * is read by NEITHER sweeping route, while a `.md` named explicitly on argv IS scanned.
  */
 export declare function exemptsMarkdown(relPath: string): boolean;
+
+/** Where the command-line form reads what a repository leaves out: `scripts/phi-scan.exclude`. */
+export declare const PHI_EXCLUDE_PATH: "scripts/phi-scan.exclude";
+
+/**
+ * Read an exclusions file (one literal tracked path per line, `#` lines are comments) against the
+ * repository's tracked paths. A directory, a pattern, a repeat or a path git does not track is a
+ * problem, never a silent skip.
+ */
+export declare function readPhiExclusions(
+  text: string,
+  tracked: ReadonlySet<string>,
+): { paths: Set<string>; problems: string[] };
+
+/**
+ * The command-line form: the engine over the repository in the working directory, with exit codes
+ * 0 clean, 1 hits, 2 refuse, the whole repository as the scan root, the `--staged` route reading
+ * everything but Markdown, and `scripts/phi-scan.exclude`. The cross-cutting floor only: a
+ * repository that needs field-level detectors keeps a caller passing `detect`.
+ * `node node_modules/@cosyte/script-utils/phi-scan.js [--staged | <path>...]`.
+ */
+export declare function runPhiScanCli(argv: string[]): number;

package/phi-scan.js

@@ -39,10 +39,11 @@
 // repository reads its own `node_modules` copy of this file only if it is not gitignored, and a
 // diagnostic ABOUT a PHI leak is itself a PHI surface. Describe the shape; never write one down.
 
-import { readFileSync, statSync, lstatSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, statSync, lstatSync, existsSync, readdirSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { join, resolve, relative, sep, isAbsolute } from "node:path";
+import { basename, join, resolve, relative, sep, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * Every state in which the scan cannot account for something. Raised throughout, caught in `run`,
@@ -1135,10 +1136,15 @@ class PhiScan {
   buildTargetsForStaged() {
     let listBuf;
     try {
-      // SECURITY: array-form execFileSync, no shell.
+      // SECURITY: array-form execFileSync, no shell. `--ignore-submodules=none` because
+      // `diff.ignoreSubmodules` in a user's own git config would otherwise hide a staged gitlink
+      // from this list, and the route would never refuse it (x12, terminology and astm pass it;
+      // measured in x12's own suite).
       listBuf = execFileSync(
         "git",
-        ["diff", "--cached", "--raw", "-z", "--no-renames", "--diff-filter=d"],
+        ["diff", "--cached", "--raw", "-z", "--no-renames", "--diff-filter=d"].concat(
+          "--ignore-submodules=none",
+        ),
         {
           cwd: this.cfg.repoRoot,
           encoding: "buffer",
@@ -1942,3 +1948,145 @@ function gitModeKind(mode) {
   if (mode === "160000") return "a gitlink (a nested repository)";
   return `a git mode-${mode} entry`;
 }
+
+// ---- The command-line form (ST34) ---------------------------------------------------------------
+//
+// `node node_modules/@cosyte/script-utils/phi-scan.js [--staged | <path>...]` runs this engine over
+// the repository in the working directory with the house settings and no caller script: exit codes
+// 0 clean, 1 hits, 2 refuse; the whole repository as the one scan root; the `--staged` route reading
+// everything but Markdown (`exemptsMarkdown`); the allow-list at `scripts/phi-allow-list.txt` and the
+// override log at `phi-scan-overrides.md`, the engine's defaults; and what the repository leaves
+// out, in `scripts/phi-scan.exclude`.
+//
+// AN EXCLUSION IS ONE LITERAL TRACKED PATH, as `excludedPaths` requires: no pattern, no directory,
+// because a class quietly grows new members. One per line; a line whose first character is `#` is a
+// comment. An entry that names no tracked path is refused rather than ignored: an exclusion that has
+// outlived its file is a hole nobody is looking at.
+//
+// IT CARRIES THE CROSS-CUTTING FLOOR ONLY. A repository whose standard needs field-level detectors
+// keeps a caller passing `detect` until the per-standard detectors ship in this package.
+
+/** Where the command-line form reads what a repository leaves out. */
+export const PHI_EXCLUDE_PATH = "scripts/phi-scan.exclude";
+
+/** The exit codes of the command-line form. */
+const CLI_EXIT_CODES = Object.freeze({ clean: 0, hits: 1, refuse: 2 });
+
+/**
+ * Read an exclusions file against the repository's tracked paths.
+ *
+ * @param {string} text The file's contents.
+ * @param {ReadonlySet<string>} tracked Every tracked path, repo-relative and forward-slashed.
+ * @returns {{ paths: Set<string>, problems: string[] }}
+ */
+export function readPhiExclusions(text, tracked) {
+  const paths = new Set();
+  const problems = [];
+  text.split("\n").forEach((raw, index) => {
+    const entry = raw.trim();
+    if (entry === "" || entry.startsWith("#")) return;
+    const where = `line ${index + 1}: ${JSON.stringify(entry)}`;
+    if (entry.endsWith("/") || /[*?[\]]/.test(entry)) {
+      problems.push(`${where} is a directory or a pattern; an exclusion is one literal path.`);
+    } else if (paths.has(entry)) {
+      problems.push(`${where} is listed twice.`);
+    } else if (!tracked.has(entry)) {
+      problems.push(`${where} is not a tracked path, so it excludes nothing.`);
+    } else {
+      paths.add(entry);
+    }
+  });
+  return { paths, problems };
+}
+
+/**
+ * Run the engine from the command line over the repository in the working directory.
+ *
+ * @param {string[]} argv The engine's own arguments: `--staged`, paths, `--allow-fixture <path>`.
+ * @returns {number} 0 clean, 1 hits, 2 the scan could not account for something.
+ */
+export function runPhiScanCli(argv) {
+  const repoRoot = process.cwd();
+  let excludedPaths = new Set();
+  const file = join(repoRoot, ...PHI_EXCLUDE_PATH.split("/"));
+  if (existsSync(file)) {
+    let read;
+    try {
+      const tracked = new Set(
+        execFileSync("git", ["ls-files", "-z"], {
+          cwd: repoRoot,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          maxBuffer: 256 * 1024 * 1024,
+        })
+          .split("\0")
+          .filter((path) => path !== ""),
+      );
+      read = readPhiExclusions(readFileSync(file, "utf8"), tracked);
+    } catch (err) {
+      process.stderr.write(
+        `[phi-scan] could not read ${PHI_EXCLUDE_PATH}: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      return CLI_EXIT_CODES.refuse;
+    }
+    if (read.problems.length > 0) {
+      process.stderr.write(
+        `[phi-scan] ${PHI_EXCLUDE_PATH} is not usable, so nothing was scanned:\n` +
+          read.problems.map((problem) => `  ${problem}\n`).join(""),
+      );
+      return CLI_EXIT_CODES.refuse;
+    }
+    excludedPaths = read.paths;
+  }
+  try {
+    return runPhiScan({
+      exitCodes: CLI_EXIT_CODES,
+      scanRoots: ["."],
+      isStagedReadable: exemptsMarkdown,
+      excludedPaths,
+      repoRoot,
+      argv,
+    });
+  } catch (err) {
+    // The backstop: an error the engine did not raise as a refusal must still not take node's own
+    // exit 1, which this contract reserves for hits.
+    process.stderr.write(
+      `[phi-scan] the scan failed and did not complete: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return CLI_EXIT_CODES.refuse;
+  }
+}
+
+/**
+ * Whether node was pointed at this file, which is the command-line form.
+ *
+ * SELF-CONTAINED ON PURPOSE: this module is also vendored and copied as a single file, so it may not
+ * import a sibling at load. A file whose name differs from the one node was pointed at cannot be the
+ * entry point, and that is settled without loading anything; only a matching name asks `index.js`'s
+ * `isCliEntrypoint`, and a copy with no `index.js` beside it compares real paths instead. Unsure is
+ * yes, so a gate that cannot tell runs loudly rather than skipping.
+ *
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @returns {Promise<boolean>}
+ */
+async function invokedAsCommand(moduleUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== "string" || entry === "") return false;
+  const own = fileURLToPath(moduleUrl);
+  const stem = (path) => basename(path).replace(/\.[cm]?[jt]s$/, "");
+  if (stem(entry) !== stem(own)) return false;
+  try {
+    const { isCliEntrypoint } = await import("./index.js");
+    return isCliEntrypoint(moduleUrl);
+  } catch {
+    try {
+      return realpathSync(entry) === realpathSync(own);
+    } catch {
+      return true;
+    }
+  }
+}
+
+void invokedAsCommand(import.meta.url).then((command) => {
+  if (command) process.exitCode = runPhiScanCli(process.argv.slice(2));
+});

package/readme.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for `@cosyte/script-utils/readme`: the README gate for every `@cosyte/*` library, which
+ * checks the house skeleton and a size limit under npm's.
+ */
+
+/** The tile's alt text, as assets `alt-text.json` declares it for the light tile. */
+export declare const TILE_ALT: string;
+
+/** The shared lockup tile every library README opens with, byte for byte. */
+export declare const TILE: string;
+
+/** npm's own cut: the registry keeps this many characters of a README. */
+export declare const NPM_README_LIMIT: 65536;
+
+/** This gate's limit, in characters (UTF-16 code units). */
+export declare const README_CHARACTER_LIMIT: 60000;
+
+/** The longest tagline the gate accepts, in characters. */
+export declare const TAGLINE_LIMIT: 120;
+
+/** The `##` sections every library README carries, in order, with License last. */
+export declare const REQUIRED_SECTIONS: readonly string[];
+
+/** A rule id a finding can carry. */
+export type ReadmeRule =
+  | "tile"
+  | "tile-alt"
+  | "title"
+  | "tagline"
+  | "badges"
+  | "section-missing"
+  | "section-order"
+  | "section-empty"
+  | "docs-link"
+  | "license-last"
+  | "license-link"
+  | "size";
+
+/** Every rule id, with what it requires. */
+export declare const README_RULES: Readonly<Record<ReadmeRule, string>>;
+
+/** One place a README departs from the skeleton. */
+export interface ReadmeFinding {
+  rule: ReadmeRule;
+  /** 1-based line, or 0 when the finding is about the whole file. */
+  line: number;
+  message: string;
+}
+
+/**
+ * The badge row a library README carries (npm version, CI, license, Node), one badge per line,
+ * derived from its package.json.
+ *
+ * @throws {TypeError} When the manifest has no `@cosyte/*` name, no github.com/cosyte repository
+ *   URL, or no `engines.node`.
+ */
+export declare function badgeRow(manifest: Record<string, unknown>): string[];
+
+/**
+ * Check a library README against the house skeleton. Returns no findings when it follows it.
+ *
+ * @throws {TypeError} When the manifest cannot supply what the skeleton is derived from.
+ */
+export declare function checkReadme(
+  text: string,
+  manifest: Record<string, unknown>,
+): ReadmeFinding[];
+
+export interface ReadmeGateOptions {
+  /** The package directory holding README.md and package.json. Default: the working directory. */
+  dir?: string;
+  /** CLI arguments; only `--dir <path>` is accepted. */
+  argv?: string[];
+}
+
+/**
+ * Run the gate over one package directory and return the exit code: 0 the README follows the
+ * skeleton, 1 at least one finding, 2 the input could not be read. It reports on stdout or stderr
+ * and never exits the process.
+ */
+export declare function runReadmeGate(options?: ReadmeGateOptions): 0 | 1 | 2;