@geonosis/verify 1.0.0 → 1.1.0

package/bin/geonosis-verify.mjs

@@ -1,4 +1,27 @@
 #!/usr/bin/env node
 // Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
 // produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
-import '../dist/cli.js'
+//
+// In the repo, `src/` sits beside `dist/`, and a dist older than src answered for a fix it did not
+// carry once (#62). The published package ships no src, so there the check is skipped.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const newest = (dir) =>
+  existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true }).reduce((most, entry) => {
+        const at = join(dir, entry.name)
+        return Math.max(most, entry.isDirectory() ? newest(at) : statSync(at).mtimeMs)
+      }, 0)
+    : 0
+const src = join(here, '..', 'src')
+if (existsSync(src) && newest(src) > newest(join(here, '..', 'dist'))) {
+  process.stderr.write(
+    'geonosis-verify: dist is older than src — run pnpm build before trusting this bin.\n',
+  )
+  process.exit(2)
+}
+
+await import('../dist/cli.js')

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+declare const CONFIG_FILE = "geonosis.json";
+/** The tiers a repo declared, in the order it declared them. */
+type VerifyConfig = {
+    tiers: Record<string, string[]>;
+};
+/**
+ * There is no default tier and there never will be one. A default that happened to match one repo's
+ * script names would run the wrong commands everywhere else and still report green, so an
+ * unconfigured repo is refused by name instead of guessed at.
+ */
+declare const loadVerifyConfig: (cwd: string) => VerifyConfig;
+/**
+ * One command to run, and the tier that DECLARED it — which is not always the tier being run. A
+ * step inlined from `fast` into `full` is still a step of the fast tier, and it keeps saying so, so
+ * that `fast/2` names the same command whether the operator asked for `fast` or for `full`.
+ */
+type TierStep = {
+    command: string;
+    tier: string;
+};
+/**
+ * Flattens a tier into the steps it actually runs: a step whose text is another tier's name is that
+ * tier, inlined in place, however deep it goes.
+ *
+ * The visiting path is carried so a cycle is named rather than discovered as a stack overflow with
+ * nothing in it a reader could act on.
+ */
+declare const resolveTier: (config: VerifyConfig, tier: string, path?: string[]) => TierStep[];
+
+type Proof = {
+    ok: boolean;
+    message: string;
+};
+/**
+ * The gate proves itself before anyone trusts it.
+ *
+ * A runner that reports green is worth nothing until it has been watched going red on purpose: this
+ * plants a tier with one passing step and one that exits 3, runs the real binary over it in a
+ * throwaway directory, and checks that the failure reached the report, the right step was named and
+ * the process exited 1. Everything it touches is in a temp dir, so it can be run in any repo at any
+ * time without disturbing that repo's own report.
+ */
+declare const prove: ({ entry, execPath }: {
+    entry: string;
+    execPath: string;
+}) => Proof;
+
+/** Where the report lands unless `--report` says otherwise. Runner-owned; agents read, never write. */
+declare const DEFAULT_REPORT = ".geonosis/gate-report.json";
+/** How much of a step's output survives into the report — enough to act on, small enough to read. */
+declare const TAIL_LINES = 40;
+/** A step that never ran carries this code: it has no exit status of its own to report. */
+declare const NEVER_RAN = -1;
+type GateStep = {
+    id: string;
+    command: string;
+    ok: boolean;
+    exitCode: number;
+    ms: number;
+    tail: string;
+    skipped?: boolean;
+};
+type GateReport = {
+    tier: string;
+    startedAt: string;
+    finishedAt: string;
+    ok: boolean;
+    steps: GateStep[];
+};
+/**
+ * The end of a step's output, with the colour codes taken out — the report is read by a hook that
+ * pipes it into stderr and by a human reading JSON, and neither wants escape sequences.
+ */
+declare const lastLines: (output: string, limit?: number) => string;
+/**
+ * A gate that cannot record has not passed, so a failed write is thrown rather than warned about:
+ * the caller turns it into a refusal instead of handing back a green nobody can go back and read.
+ */
+declare const writeReport: (cwd: string, path: string, report: GateReport) => string;
+
+type StepResult = {
+    exitCode: number;
+    output: string;
+};
+type StepRun = (command: string) => StepResult;
+/**
+ * One step, through the shell, with stderr folded into stdout by the shell itself so the two stay
+ * interleaved in the order they were written — concatenating two captured buffers would not.
+ *
+ * The step runs inside a subshell because `<step> 2>&1` binds the redirect to the LAST command in
+ * the step only: `echo boom >&2; exit 3` would lose "boom" entirely, and a gate whose report is
+ * missing the error line is a gate nobody can act on. The newlines let a step end in a comment.
+ */
+declare const shellRun: (cwd: string) => StepRun;
+/**
+ * Serial, and it stops at the first red.
+ *
+ * Serial because the parts of a gate compete for the same cores, and a suite that lost a core reads
+ * as a flake. Stopping because the second failure of a broken build tells the operator nothing the
+ * first one did not — but the steps that never ran are still written down, as `skipped`, so the
+ * report cannot be mistaken for a shorter, greener tier.
+ */
+declare const runSteps: ({ run, steps: planned, tier, }: {
+    run: StepRun;
+    steps: TierStep[];
+    tier: string;
+}) => GateReport;
+
+/**
+ * The Stop hook's own record, one bucket per day.
+ *
+ * Per DAY rather than per session, and two integers rather than a log, because the question it
+ * answers is "did cutting the law change how often a turn ends green" — which needs a before window
+ * and an after window and nothing else. A per-session log would be a session log: bigger, more
+ * personal, and no better at the one question.
+ *
+ * The sibling `stop-blocks.json` cannot answer it. That file is the block CAP's working memory, and
+ * a green turn deletes its own row from it — so a session that never blocked and a session that
+ * blocked and recovered are both simply absent.
+ */
+declare const TURNS_FILE = ".geonosis/stop-turns.json";
+type DayRecord = {
+    blocked: number;
+    turns: number;
+};
+type Window = {
+    blocked: number;
+    passRate: number | undefined;
+    turns: number;
+};
+type Stats = Window & {
+    before?: Window;
+    since?: string;
+};
+/**
+ * The first-try pass rate: the share of turn-ends whose fast tier was green on the first run.
+ *
+ * With `since`, the reading is the window from that day on, and `before` is everything earlier —
+ * one command, two windows, one instrument, which is what makes a law diet measurable rather than
+ * a matter of opinion.
+ */
+declare const readStats: (root: string, since?: string) => Stats;
+declare const formatStats: (stats: Stats) => string;
+/**
+ * One turn ended. Appends to the day's bucket, creating the file if it is not there.
+ *
+ * Read-modify-write with no lock, deliberately: the writer is a Stop hook, one per turn per session,
+ * and the cost of a lost increment is a KPI one turn out. A lock here would be machinery guarding a
+ * number that is already an estimate.
+ */
+declare const recordTurn: ({ blocked, day, root, }: {
+    blocked: boolean;
+    day: string;
+    root: string;
+}) => void;
+
+export { CONFIG_FILE, DEFAULT_REPORT, type DayRecord, type GateReport, type GateStep, NEVER_RAN, type Proof, type Stats, type StepResult, type StepRun, TAIL_LINES, TURNS_FILE, type TierStep, type VerifyConfig, type Window, formatStats, lastLines, loadVerifyConfig, prove, readStats, recordTurn, resolveTier, runSteps, shellRun, writeReport };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@geonosis/verify",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "types": "./dist/index.d.ts",
   "description": "One gate runner — tiers of shell steps, run serially, recorded as a JSON gate report.",
   "keywords": [
     "gate",
@@ -23,14 +24,17 @@
     "geonosis-verify": "bin/geonosis-verify.mjs"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
     "bin",
     "dist"
   ],
   "dependencies": {
-    "@geonosis/ratchet": "1.0.0"
+    "@geonosis/ratchet": "1.1.0"
   },
   "engines": {
     "node": ">=22"