@cosyte/script-utils 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",
@@ -10,7 +10,9 @@
     "phi",
     "readme",
     "scripts",
-    "cosyte"
+    "cosyte",
+    "coverage",
+    "mutation-testing"
   ],
   "homepage": "https://github.com/cosyte/config/tree/main/packages/script-utils#readme",
   "repository": {
@@ -31,7 +33,9 @@
     "cosyte-readme": "bin/cosyte-readme.js",
     "cosyte-claude-card": "bin/cosyte-claude-card.js",
     "cosyte-agent-notes": "bin/cosyte-agent-notes.js",
-    "cosyte-catalog": "bin/cosyte-catalog.js"
+    "cosyte-catalog": "bin/cosyte-catalog.js",
+    "cosyte-ratchet": "bin/cosyte-ratchet.js",
+    "cosyte-docs-content": "bin/cosyte-docs-content.js"
   },
   "types": "index.d.ts",
   "exports": {
@@ -66,6 +70,18 @@
     "./agent-notes": {
       "types": "./agent-notes.d.ts",
       "default": "./agent-notes.js"
+    },
+    "./ratchet": {
+      "types": "./ratchet.d.ts",
+      "default": "./ratchet.js"
+    },
+    "./changes": {
+      "types": "./changes.d.ts",
+      "default": "./changes.js"
+    },
+    "./docs-content": {
+      "types": "./docs-content.d.ts",
+      "default": "./docs-content.js"
     }
   },
   "files": [
@@ -86,6 +102,12 @@
     "catalog.json",
     "agent-notes.js",
     "agent-notes.d.ts",
+    "ratchet.js",
+    "ratchet.d.ts",
+    "changes.js",
+    "changes.d.ts",
+    "docs-content.js",
+    "docs-content.d.ts",
     "check-no-emdash.sh",
     "bin",
     "README.md",
@@ -98,10 +120,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "vitest": "4.1.12"
+    "vitest": "5.1.0",
+    "@vitest/coverage-v8": "5.1.0"
   },
   "scripts": {
     "build": "node ../../scripts/pack-emdash-gate.mjs",
-    "test": "vitest run"
+    "test": "vitest run --coverage"
   }
 }

package/phi-scan.d.ts

@@ -293,7 +293,10 @@ export declare function readPhiExclusions(
  * 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>...]`.
+ * `--allow-list <path>` names the allow list to use instead of `scripts/phi-allow-list.txt`
+ * (resolved against the working directory, replacing the repository's list); a path that does not
+ * exist or cannot be read refuses at 2.
+ * `node node_modules/@cosyte/script-utils/phi-scan.js [--allow-list <path>] [--staged | <path>...]`.
  */
 export declare function runPhiScanCli(argv: string[]): number;
 

package/phi-scan.js

@@ -2102,12 +2102,13 @@ function gitModeKind(mode) {
 
 // ---- 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`.
+// `node node_modules/@cosyte/script-utils/phi-scan.js [--allow-list <path>] [--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`. `--allow-list
+// <path>` names another allow list in place of the repository's (see `runPhiScanCli`).
 //
 // 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
@@ -2150,14 +2151,90 @@ export function readPhiExclusions(text, tracked) {
   return { paths, problems };
 }
 
+/**
+ * Take `--allow-list <path>` out of the command line, leaving every other argument in its place.
+ *
+ * IT READS THE ENGINE'S OWN GRAMMAR, NOT A SIMPLER ONE, so it cannot take an argument the engine
+ * would have read as something else: everything after `--` is a path, and the word after
+ * `--allow-fixture` is that bypass's path, even when it reads `--allow-list`.
+ *
+ * @param {string[]} argv
+ * @returns {{ argv: string[], allowList: string | undefined, problem: string | undefined }}
+ */
+function takeAllowListOption(argv) {
+  /** @type {string[]} */
+  const rest = [];
+  /** @type {string | undefined} */
+  let allowList;
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === "--") {
+      rest.push(...argv.slice(i));
+      break;
+    }
+    if (a === "--allow-fixture") {
+      rest.push(...argv.slice(i, i + 2));
+      i += 2;
+      continue;
+    }
+    if (a === "--allow-list") {
+      const value = argv[i + 1];
+      if (value === undefined || value === "") {
+        return { argv, allowList: undefined, problem: "--allow-list requires a path argument" };
+      }
+      if (allowList !== undefined) {
+        return { argv, allowList: undefined, problem: "--allow-list was given more than once" };
+      }
+      allowList = value;
+      i += 2;
+      continue;
+    }
+    if (a !== undefined) rest.push(a);
+    i += 1;
+  }
+  return { argv: rest, allowList, problem: undefined };
+}
+
 /**
  * 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>`.
+ * `--allow-list <path>` NAMES THE ALLOW LIST INSTEAD OF `scripts/phi-allow-list.txt`, resolved
+ * against the working directory. It is what a tool scanning a repository that keeps no list of its
+ * own passes, usually an empty file: the run is then a scan with no exceptions, where without the
+ * option it refuses for the missing list. The named file REPLACES the repository's list rather than
+ * adding to it. A path that does not exist, or that exists and cannot be read (a directory, no read
+ * permission), refuses at exit 2 before anything is scanned and says which: the engine itself would
+ * let an unreadable list escape to node's own exit 1, the code reserved for hits. Without the option
+ * nothing here changes.
+ *
+ * @param {string[]} argv The engine's own arguments: `--staged`, paths, `--allow-fixture <path>`,
+ *   and this form's `--allow-list <path>`.
  * @returns {number} 0 clean, 1 hits, 2 the scan could not account for something.
  */
 export function runPhiScanCli(argv) {
   const repoRoot = process.cwd();
+  const option = takeAllowListOption(argv);
+  if (option.problem !== undefined) {
+    process.stderr.write(`[phi-scan] ${option.problem}\n`);
+    return CLI_EXIT_CODES.refuse;
+  }
+  /** @type {string | undefined} */
+  let allowListPath;
+  if (option.allowList !== undefined) {
+    allowListPath = resolve(repoRoot, option.allowList);
+    try {
+      readFileSync(allowListPath, "utf8");
+    } catch (err) {
+      const code = err instanceof Error && "code" in err ? String(err.code) : "";
+      process.stderr.write(
+        code === "ENOENT"
+          ? `[phi-scan] the allow list --allow-list names does not exist: ${allowListPath}\n`
+          : `[phi-scan] the allow list --allow-list names could not be read (${code || "unknown error"}): ${allowListPath}\n`,
+      );
+      return CLI_EXIT_CODES.refuse;
+    }
+  }
   let excludedPaths = new Set();
   const file = join(repoRoot, ...PHI_EXCLUDE_PATH.split("/"));
   if (existsSync(file)) {
@@ -2196,7 +2273,8 @@ export function runPhiScanCli(argv) {
       isStagedReadable: exemptsMarkdown,
       excludedPaths,
       repoRoot,
-      argv,
+      argv: option.argv,
+      ...(allowListPath === undefined ? {} : { allowListPath }),
     });
   } catch (err) {
     // The backstop: an error the engine did not raise as a refusal must still not take node's own

package/ratchet.d.ts

@@ -0,0 +1,127 @@
+import type { GitRunner } from "./changes.js";
+
+/** The floor file's name, at a repository's root. */
+export declare const FLOOR_FILE: "quality-floor.json";
+
+/** The four coverage metrics, in the order they print. */
+export declare const COVERAGE_METRICS: readonly ["lines", "branches", "functions", "statements"];
+
+/** Where each report is read from, relative to a package's directory. */
+export declare const REPORTS: Readonly<{
+  summary: "coverage/coverage-summary.json";
+  lcov: "coverage/lcov.info";
+  mutation: "reports/mutation/mutation.json";
+  changed: "reports/mutation/changed.json";
+}>;
+
+/** One package's floors. */
+export interface FloorEntry {
+  coverage?: Partial<Record<"lines" | "branches" | "functions" | "statements", number>>;
+  mutation?: number;
+}
+
+/** A floor file: each package directory, relative to the file, with its floors. */
+export interface Floor {
+  $comment?: string;
+  packages: Record<string, FloorEntry>;
+}
+
+/** An inline exception found in a source file. */
+export interface ExceptionComment {
+  line: number;
+  tool: "coverage" | "mutation";
+  directive: string;
+  reason: string | null;
+}
+
+/** What {@link judgeChangedCode} found in a change's own code. */
+export interface ChangedCodeVerdict {
+  uncovered: { file: string; line: number }[];
+  survived: { file: string; line: number; mutator: string; status: string }[];
+  exceptions: { file: string; line: number; tool: string; what: string; reason: string | null }[];
+  unmutated: string[];
+}
+
+/** Thrown when an input cannot be read or is not what it must be. */
+export declare class RatchetUnreadable extends Error {
+  constructor(message: string);
+}
+
+/** Check a parsed floor file's shape; every key must be known. */
+export declare function parseFloor(value: unknown): Floor;
+
+/**
+ * Compare a floor file with the one it replaces: each floor the earlier one held that is now lower
+ * (`after` the lower value) or gone (`after` null). Raised and new floors are not listed.
+ */
+export declare function compareFloors(
+  before: Floor,
+  after: Floor,
+): { dir: string; metric: string; before: number; after: number | null }[];
+
+/** Cut a percentage to two decimals, toward zero. */
+export declare function toFloor(value: number): number;
+
+/** Read the four coverage percentages from Istanbul's `json-summary` report. */
+export declare function readCoverageSummary(path: string): Record<string, number>;
+
+/** Count a Stryker JSON report's mutants by status and work out its mutation score. */
+export declare function mutationScore(
+  report: unknown,
+  path: string,
+): { score: number; counts: Record<string, number> };
+
+/** Read lcov's line records: absolute file path to line to hits. */
+export declare function parseLcov(text: string, baseDir: string): Map<string, Map<number, number>>;
+
+/** Find the inline coverage hints and Stryker directives in a source file. */
+export declare function findExceptionComments(text: string): ExceptionComment[];
+
+/** The first and last line a coverage hint takes out of the count. */
+export declare function hintRange(
+  hint: { line: number; directive: string },
+  lines: string[],
+  counted: Map<number, number> | undefined,
+): [number, number];
+
+/** Judge a change's own code: its changed lines coverage counts, and the mutants in them. */
+export declare function judgeChangedCode(input: {
+  changed: Map<string, Set<number>>;
+  lines: Map<string, Map<number, number>>;
+  mutants: Map<string, unknown[]> | null;
+  read: (file: string) => string;
+}): ChangedCodeVerdict;
+
+/** Read a changed-files mutation report into absolute file path to mutants. */
+export declare function readMutants(path: string, packageDir: string): Map<string, unknown[]>;
+
+/** Parse the ratchet's command line. */
+export declare function parseArgs(argv: string[]): {
+  command: "check" | "raise";
+  floor: string;
+  base: string | null;
+  skip: Set<"coverage" | "mutation">;
+};
+
+/**
+ * Run the ratchet and return its exit code: 0 nothing dropped and changed code is reached, 1 a
+ * drop or unreached changed code, 2 an input could not be read.
+ *
+ * @example
+ * ```js
+ * import { runRatchet } from "@cosyte/script-utils/ratchet";
+ * process.exitCode = runRatchet({
+ *   argv: ["check", "--base", "origin/main"],
+ *   cwd: process.cwd(),
+ *   out: (text) => process.stdout.write(text),
+ *   err: (text) => process.stderr.write(text),
+ * });
+ * ```
+ */
+export declare function runRatchet(opts: {
+  argv: string[];
+  cwd: string;
+  out: (text: string) => void;
+  err: (text: string) => void;
+  git?: GitRunner;
+}): number;