@geonosis/ratchet 0.4.0 → 1.0.0

package/dist/cli.js

@@ -5,9 +5,13 @@ import {
   formatReport,
   runProve,
   runRatchet
-} from "./chunk-QVORWCUD.js";
+} from "./chunk-LSYVFUP4.js";
 
 // src/cli.ts
+var numberAfter = (flag) => {
+  const at = process.argv.indexOf(flag);
+  return at === -1 ? void 0 : Number(process.argv[at + 1] ?? Number.NaN);
+};
 var cwdFlag = process.argv.indexOf("--cwd");
 var cwd = cwdFlag === -1 ? process.cwd() : process.argv[cwdFlag + 1] ?? process.cwd();
 var tierFlag = process.argv.indexOf("--tier");
@@ -16,9 +20,24 @@ var proving = process.argv.includes("--prove");
 var exclusive = process.argv.includes("--exclusive");
 var timeoutFlag = process.argv.indexOf("--exclusive-timeout");
 var timeoutSeconds = timeoutFlag === -1 ? void 0 : Number(process.argv[timeoutFlag + 1] ?? Number.NaN);
+var holdMs = numberAfter("--hold");
+var holdTheLock = async (ms) => {
+  process.stdout.write(`exclusive-hold start ${Date.now()}
+`);
+  await new Promise((done) => setTimeout(done, ms));
+  process.stdout.write(`exclusive-hold end ${Date.now()}
+`);
+  return 0;
+};
 var measure = async () => {
+  if (holdMs !== void 0) return holdTheLock(holdMs);
   if (proving) {
-    const proof = await runProve({ counters: COUNTERS, cwd, tier });
+    const proof = await runProve({
+      counters: COUNTERS,
+      cwd,
+      exclusiveVia: process.argv[1],
+      tier
+    });
     process.stdout.write(formatProve(proof));
     return proof.proven ? 0 : 2;
   }
@@ -33,6 +52,9 @@ try {
   if (timeoutSeconds !== void 0 && !(timeoutSeconds > 0)) {
     throw new Error("--exclusive-timeout needs a number of seconds");
   }
+  if (holdMs !== void 0 && !(holdMs > 0)) {
+    throw new Error("--hold needs a number of milliseconds");
+  }
   const release = exclusive ? await acquireExclusive({ timeoutSeconds }) : () => void 0;
   const giveBack = () => {
     release();

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+/** What a command did. `code` is the exit status; `output` is stdout and stderr, merged. */
+type CommandResult = {
+    code: number;
+    output: string;
+};
+/**
+ * A tool that reports findings exits non-zero — that is the tool working, not failing. A tool that
+ * could not be spawned at all, or whose output no longer parses, is a gate that cannot measure, and
+ * a gate that cannot measure has not passed. Counters throw this rather than returning zero.
+ */
+declare class CounterError extends Error {
+    readonly counter: string;
+    constructor(counter: string, message: string);
+}
+type CounterContext = {
+    /** The repo root every command runs in and every relative path resolves against. */
+    cwd: string;
+    /** The baseline key this instance writes — several instances of one counter can coexist. */
+    key: string;
+    /** Whatever the config gave this instance. Each counter validates its own. */
+    params: Record<string, unknown>;
+    run: (command: string) => CommandResult;
+};
+/**
+ * A counter's falsification probe: the known-bad input it must be able to read.
+ *
+ * `input` plants it in a scratch directory, `command` is the command shape to run THERE (absent for
+ * a counter that reads a file instead), `params` is whatever else that counter needs, and `expect`
+ * is the reading the planted input is worth — at least 1, because a probe that plants nothing
+ * proves nothing.
+ */
+type CounterProbe = {
+    command?: (dir: string) => string;
+    expect: number;
+    input: (dir: string) => void;
+    /**
+     * What this probe proves, when the counter has more than one way of reading. It is printed beside
+     * the key, so a report says WHICH mode was seen red rather than that the counter was.
+     */
+    name?: string;
+    params?: Record<string, unknown>;
+};
+type Counter = {
+    id: string;
+    /**
+     * Whether this counter's number is a measured QUANTITY — bytes, milliseconds — rather than a
+     * count of findings, and may therefore carry a `tolerance`.
+     *
+     * Opt-in, and declared by the counter rather than by the config, because the config is the wrong
+     * place to decide it: `"tolerance": 100` on a findings counter switches that gate off and the run
+     * still prints PASS. One more lint error is always one too many; forty more bytes is a dependency
+     * patch nobody chose. Only the counter knows which of those its number is.
+     */
+    tolerates?: true;
+    /**
+     * Absent only for a counter written outside this package. A gate that has never been seen red has
+     * not been shown to measure, so `--prove` refuses a configured counter that ships no probe.
+     *
+     * A counter that reads its tool in more than one way ships one probe per way: proving the mode
+     * nobody configured says nothing about the mode they did.
+     */
+    probe?: CounterProbe | CounterProbe[];
+    run: (context: CounterContext) => Promise<number>;
+};
+/** One line of `geonosis.ratchet.json`'s `counters` array. */
+type CounterConfig = {
+    counter: string;
+    /** The baseline key. Defaults to `counter`; required when a counter is used more than once. */
+    key?: string;
+    /**
+     * The tiers this counter belongs to — free-form names a repo chooses, `fast` and `full` by
+     * convention. Absent means every tier, so a repo that never asks for one is unaffected.
+     */
+    tiers?: string[];
+} & Record<string, unknown>;
+type RatchetConfig = {
+    baseline: string;
+    counters: CounterConfig[];
+};
+type Verdict = 'grew' | 'held' | 'shrank' | 'skipped';
+/**
+ * A counter that ran carries its number; a counter the tier left out carries none — deliberately,
+ * so nothing downstream can mistake a census nobody took for one that came back equal.
+ */
+type Measurement = {
+    baseline: number;
+    /**
+     * The tail of what this counter's command printed, kept only when the number GREW. A report
+     * that says a number went up and nothing else sends the reader back to re-run the tool; the
+     * lines that made it go up are the answer they were going to look for.
+     */
+    evidence: string[];
+    key: string;
+    now: number;
+    verdict: 'grew' | 'held' | 'shrank';
+} | {
+    key: string;
+    tier: string;
+    verdict: 'skipped';
+};
+/**
+ * What one counter's probe did. A reading of 0 is the finding this exists to catch: the counter ran,
+ * the input was planted, and the number came back the same as it does on a clean tree.
+ */
+type Proof = {
+    counter: string;
+    expected: number;
+    key: string;
+    reading: number;
+    verdict: 'misread';
+} | {
+    counter: string;
+    key: string;
+    reading: number;
+    verdict: 'cannot-fail' | 'proven';
+} | {
+    counter: string;
+    key: string;
+    reason: string;
+    verdict: 'cannot-measure';
+}
+/**
+ * Not a counter: `--exclusive` itself, measured by running two of it. A lock is a claim about the
+ * machine, and the only place that claim can be checked is the machine.
+ */
+ | {
+    key: string;
+    reason: string;
+    verdict: 'interleaved';
+} | {
+    key: string;
+    reason: string;
+    verdict: 'serialised';
+} | {
+    key: string;
+    tier: string;
+    verdict: 'skipped';
+};
+type ProveResult = {
+    proofs: Proof[];
+    /** False as soon as one counter could not be shown to read its own planted finding. */
+    proven: boolean;
+};
+type RatchetResult = {
+    measurements: Measurement[];
+    /** True when the baseline file was rewritten because something shrank. */
+    rewritten: boolean;
+};
+
+declare const CONFIG_FILE = "geonosis.ratchet.json";
+/** The baseline key an entry writes. Defaults to the counter's own id. */
+declare const keyOf: (entry: CounterConfig) => string;
+declare const loadConfig: (cwd: string) => RatchetConfig;
+
+declare const COUNTERS: Counter[];
+declare const counterById: (id: string) => Counter;
+
+/** Who is running the heavy thing, since when, and where from. */
+type Holder = {
+    cwd: string;
+    pid: number;
+    startedAt: string;
+};
+/**
+ * One path for the whole machine, because the contention is for the machine: three sessions on one
+ * laptop, each starting a verify, each slowing the other two down until a 25-minute run took two
+ * hours and produced failures that were about the load and not the code.
+ */
+declare const heavyLockPath: () => string;
+/**
+ * Takes the machine-wide lock, waiting for whoever has it, and gives back the release.
+ *
+ * A holder whose process is gone — killed, crashed, a laptop closed mid-run — is stale and is taken
+ * over with a printed note; so is a lock file nobody can parse, because a lock that can never be
+ * cleared is worse than no lock. The wait is bounded and says who it is waiting for: a run that
+ * hangs silently for half an hour is indistinguishable from a run that is broken.
+ */
+declare const acquireExclusive: ({ noticeMs, path, pollMs, say, timeoutSeconds, }?: {
+    noticeMs?: number;
+    path?: string;
+    pollMs?: number;
+    say?: (line: string) => void;
+    timeoutSeconds?: number;
+}) => Promise<() => void>;
+
+/**
+ * D-029: every gate ships its own falsification probe. The ratchet compares a number against a
+ * number and cannot tell a counter that found nothing from a counter that CAN find nothing — the
+ * kit's own `oxlintErrors` read 0 under the format its config asked for, from inception, and every
+ * baseline it wrote was a census nobody took.
+ *
+ * So each counter plants a known-bad input and must read it. The run stops at the first counter that
+ * reads 0 or throws: the rest of the report would be about a gate whose first gate is not a gate.
+ */
+declare const runProve: ({ counters, cwd, exclusiveVia, tier, }: {
+    counters: Counter[];
+    cwd: string;
+    /**
+     * The CLI to run two of, to see whether `--exclusive` serialises on this machine. Absent means
+     * the caller is a library and there is no process to run twice, so the lock is not proved.
+     */
+    exclusiveVia?: string;
+    tier?: string;
+}) => Promise<ProveResult>;
+
+/**
+ * A binary gate has two bad modes: ignore the debt, or block every commit until it is zero. Neither
+ * works mid-migration. This measures the debt, compares it against the baseline, and fails ONLY on
+ * regression — so a repo that predates a rule can adopt it the same day, and no NEW debt can land
+ * behind it.
+ *
+ * A `tier` runs only the counters that declare it; the rest are reported as skipped and take no
+ * part in the verdict, the exit code or a baseline rewrite. An iteration gate that took eleven
+ * seconds gets run less often than one that takes four, and a gate nobody runs enforces nothing —
+ * but a skipped counter that printed OK would be worse than not running at all.
+ */
+declare const runRatchet: ({ counters, cwd, tier, }: {
+    counters: Counter[];
+    cwd: string;
+    tier?: string;
+}) => Promise<RatchetResult>;
+
+/**
+ * One line per counter, then the verdict. Reads the same in a terminal and in a CI log. A counter
+ * the tier left out says so by name — printing a number for it would be the stale OK this exists
+ * to prevent.
+ */
+declare const formatReport: ({ measurements, rewritten }: RatchetResult) => string;
+declare const formatProve: ({ proofs, proven }: ProveResult) => string;
+
+/**
+ * Runs a command and merges stderr into stdout — most of these tools write their summary line to
+ * stderr, and on a zero exit `execSync` would otherwise hand back only stdout and the parse would
+ * fail. A non-zero exit is NOT an error here: a linter that found something exits non-zero, and
+ * that is the whole reason we are asking. Counters decide what an unparseable answer means.
+ *
+ * The command runs inside a SUBSHELL, because `<command> 2>&1` binds the redirect to the last
+ * command of the string only. `echo boom >&2; echo fine` merged nothing, and on a zero exit
+ * execSync hands back stdout alone — so a tool that prints its findings to stderr and exits 0 read
+ * as a tool that found nothing. That is the exact shape of a gate that has quietly stopped gating.
+ * On a non-zero exit the two buffers were concatenated instead, which put every stderr line after
+ * every stdout line and moved each diagnostic away from the line it was about. The shell keeps
+ * them in the order they were written. The newlines let a command end in a comment.
+ */
+declare const runCommand: (cwd: string, counterId: string, env?: NodeJS.ProcessEnv) => (command: string) => CommandResult;
+
+export { CONFIG_FILE, COUNTERS, type CommandResult, type Counter, type CounterConfig, type CounterContext, CounterError, type CounterProbe, type Holder, type Measurement, type Proof, type ProveResult, type RatchetConfig, type RatchetResult, type Verdict, acquireExclusive, counterById, formatProve, formatReport, heavyLockPath, keyOf, loadConfig, runCommand, runProve, runRatchet };

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   runCommand,
   runProve,
   runRatchet
-} from "./chunk-QVORWCUD.js";
+} from "./chunk-LSYVFUP4.js";
 export {
   CONFIG_FILE,
   COUNTERS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/ratchet",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "Debt as a number that may only shrink — one ratchet, pluggable counters.",
   "keywords": [
     "ratchet",