@geonosis/release 1.1.0 → 1.3.0

package/README.md

@@ -17,6 +17,10 @@ geonosis-release migrations --since <ref> [--dialect <name>] [--root <dir>] [--j
 
 Exit **0** clean · **1** refusals · **2** the run could not be made.
 
+## What it reads
+
+The files added since `--since <ref>` — committed, **staged, and untracked** — under every configured `release.migrations[].dir`. A migration that exists and narrows is a refusal whatever git thinks of it: the local gate a person runs before committing is the one window in which it is still free to fix, and a gate that only speaks after the commit speaks after the cheap moment has passed. A run that finds no migration file anywhere says `NONE … nothing was read`, never `OK`.
+
 ## `migrations` — expand-only, enforced
 
 For every file the diff ADDED under a directory `geonosis.json` names, in the dialect it names it
@@ -97,11 +101,25 @@ An **identifier** argument (`this.addSql(dropOperationChecks)`) and a **template
 are refused BY NAME with exit 2. Resolving either is name resolution — a TypeScript parser — and
 this package will not grow one. A migration nobody could read is not a migration that passed.
 
-### squawk
+### squawk — an OPTIONAL peer
+
+```bash
+pnpm add -D squawk-cli@2.63.0   # only if release.migrations names postgres or mikro-orm-ts
+```
+
+`squawk-cli` ships platform binaries, and as a hard dependency of this package it grew one
+consumer's lockfile by **395 lines** for a Postgres linter that repo never configured. It is a peer
+marked optional: nothing installs it for you.
+
+- a `release.migrations` naming only the **`sqlite`** dialect never calls it, and needs none of it;
+- a `postgres` or `mikro-orm-ts` dialect with squawk absent is **exit 2**, with the install line
+  above — the dialect cannot be measured, and a gate that cannot measure has not passed.
 
-`squawk-cli` is a pinned dependency of this package, spawned from its own `node_modules/.bin`. Its
-bin is called `squawk`, and `squawk` on a public registry is an unrelated package that exits 0 on
-anything — a gate that passes because it linted nothing. Nothing here asks a resolver.
+It is pinned exactly, because a squawk that renamed a rule would change what a release argues from,
+and that is a decision rather than an install. It is spawned from the `node_modules/.bin` beside
+this package: its bin is called `squawk`, and `squawk` on a public registry is an unrelated package
+that exits 0 on anything — a gate that passes because it linted nothing. Nothing here asks a
+resolver.
 
 Exit 0 is clean and exit 1 is findings. **Anything else is exit 2**, one line naming it: a linter
 that could not start has not measured, and a gate that cannot measure has not passed.

package/dist/{chunk-2JLVQK7Y.js → chunk-D5IC766I.js}

@@ -12,26 +12,33 @@ var strings = (value2, where) => {
   }
   return value2;
 };
+var ENTRY_KEYS = "expected { dir, dialect, phases?, squawk? }";
 var oneDir = (value2, index) => {
-  if (!isRecord(value2)) throw new CannotRun(`release.migrations[${index}] must be an object`);
+  const at = `release.migrations[${index}]`;
+  if (!isRecord(value2)) throw new CannotRun(`${at} must be an object \u2014 ${ENTRY_KEYS}`);
+  const known = /* @__PURE__ */ new Set(["dialect", "dir", "phases", "squawk"]);
+  const unknown = Object.keys(value2).find((key) => !known.has(key));
+  if (unknown !== void 0) {
+    throw new CannotRun(`${at}.${unknown} is not a key it takes \u2014 ${ENTRY_KEYS}`);
+  }
   const dir = value2["dir"];
   const dialect = value2["dialect"];
   if (typeof dir !== "string" || dir === "") {
-    throw new CannotRun(`release.migrations[${index}].dir must name a directory`);
+    throw new CannotRun(`${at}.dir must name a directory \u2014 ${ENTRY_KEYS}`);
   }
   if (typeof dialect !== "string" || !DIALECTS.has(dialect)) {
     throw new CannotRun(
-      `release.migrations[${index}].dialect must be one of ${[...DIALECTS].toSorted().join(", ")}`
+      `${at}.dialect must be one of ${[...DIALECTS].toSorted().join(", ")} \u2014 ${ENTRY_KEYS}`
     );
   }
-  const phases = strings(value2["phases"], `release.migrations[${index}].phases`);
+  const phases = strings(value2["phases"], `${at}.phases`);
   for (const phase of phases) {
     if (phase !== "up" && phase !== "down") {
-      throw new CannotRun(`release.migrations[${index}].phases may only hold "up" and "down"`);
+      throw new CannotRun(`${at}.phases may only hold "up" and "down"`);
     }
   }
   const squawk = value2["squawk"];
-  const exclude = isRecord(squawk) ? strings(squawk["exclude"], `release.migrations[${index}].squawk.exclude`) : [];
+  const exclude = isRecord(squawk) ? strings(squawk["exclude"], `${at}.squawk.exclude`) : [];
   return {
     dialect,
     dir,
@@ -49,13 +56,27 @@ var EMPTY = {
   workers: [],
   wrangler: []
 };
+var BLOCK_KEYS = "expected { migrations?, proof?, secrets?, steps?, workers?, wrangler?, wranglerEnv? }";
 var parseReleaseConfig = (raw) => {
   if (!isRecord(raw)) return EMPTY;
   const release = raw["release"];
   if (!isRecord(release)) return EMPTY;
+  const known = /* @__PURE__ */ new Set([
+    "migrations",
+    "proof",
+    "secrets",
+    "steps",
+    "workers",
+    "wrangler",
+    "wranglerEnv"
+  ]);
+  const unknown = Object.keys(release).find((key) => !known.has(key));
+  if (unknown !== void 0) {
+    throw new CannotRun(`release.${unknown} is not a key it reads \u2014 ${BLOCK_KEYS}`);
+  }
   const migrations = release["migrations"];
   if (migrations !== void 0 && !Array.isArray(migrations)) {
-    throw new CannotRun("release.migrations must be a list");
+    throw new CannotRun(`release.migrations must be a list \u2014 ${ENTRY_KEYS}, per entry`);
   }
   const proof = release["proof"];
   return {
@@ -191,9 +212,9 @@ var arrayTable = (into, path) => {
 var parseToml = (source) => {
   const out = {};
   let here = out;
-  const lines = source.split("\n");
-  for (let index = 0; index < lines.length; index += 1) {
-    const line = (lines[index] ?? "").split("#")[0]?.trim() ?? "";
+  const lines2 = source.split("\n");
+  for (let index = 0; index < lines2.length; index += 1) {
+    const line = (lines2[index] ?? "").split("#")[0]?.trim() ?? "";
     if (line === "") continue;
     if (line.startsWith("[[") && line.endsWith("]]")) {
       here = arrayTable(out, line.slice(2, -2).trim().split("."));
@@ -208,9 +229,9 @@ var parseToml = (source) => {
     let text = line.slice(at + 1);
     while ([...text].filter((one) => one === "[").length > [...text].filter((one) => one === "]").length) {
       index += 1;
-      if (index >= lines.length) throw new CannotRun("an unterminated array in the TOML config");
+      if (index >= lines2.length) throw new CannotRun("an unterminated array in the TOML config");
       text += `
-${(lines[index] ?? "").split("#")[0] ?? ""}`;
+${(lines2[index] ?? "").split("#")[0] ?? ""}`;
     }
     put(here, line.slice(0, at).trim().split("."), value(text));
   }
@@ -353,7 +374,13 @@ var git = (root, args) => {
     throw new CannotRun(`git ${args.join(" ")} failed: ${(error.message ?? "").trim()}`);
   }
 };
-var addedSince = (root, since) => git(root, ["diff", "--name-only", "--diff-filter=A", `${since}..HEAD`]).split("\n").filter((line) => line !== "");
+var lines = (out) => out.split("\n").filter((line) => line !== "");
+var addedSince = (root, since) => {
+  const committed = lines(git(root, ["diff", "--name-only", "--diff-filter=A", `${since}..HEAD`]));
+  const staged = lines(git(root, ["diff", "--name-only", "--diff-filter=A", "--cached"]));
+  const untracked = lines(git(root, ["ls-files", "--others", "--exclude-standard"]));
+  return [.../* @__PURE__ */ new Set([...committed, ...staged, ...untracked])].toSorted();
+};
 var gitOk = (root, args) => {
   const run = spawnSync("git", [...args], { cwd: root, encoding: "utf8" });
   return run.error === void 0 && run.status === 0;
@@ -565,6 +592,7 @@ import { existsSync as existsSync3 } from "fs";
 import { dirname, resolve as resolve4 } from "path";
 import { fileURLToPath } from "url";
 var HERE = dirname(fileURLToPath(import.meta.url));
+var PINNED = "2.63.0";
 var findSquawk = (from = HERE) => {
   for (let dir = from; ; dir = dirname(dir)) {
     const candidate = resolve4(dir, "node_modules/.bin/squawk");
@@ -572,7 +600,11 @@ var findSquawk = (from = HERE) => {
     if (dirname(dir) === dir) break;
   }
   throw new CannotRun(
-    "squawk-cli is not installed beside this package \u2014 the Postgres dialect cannot be measured, and a gate that cannot measure has not passed"
+    `squawk-cli is not installed beside this package, and the postgres and mikro-orm-ts dialects cannot be measured without it \u2014 a gate that cannot measure has not passed. Install it:
+
+    pnpm add -D squawk-cli@${PINNED}
+
+It is an optional peer: a repo whose release.migrations names only the sqlite dialect needs none of this.`
   );
 };
 var squawkOn = (input) => {
@@ -604,12 +636,17 @@ var EXTENSION = {
 var under = (dir, file) => file === dir || file.startsWith(dir.endsWith("/") ? dir : `${dir}/`);
 var fromTypeScript = (path, source, entry) => {
   try {
-    return addSqlIn(source, entry.phases ?? ["up"]).flatMap(
-      (one) => refusalsIn(path, one.sql, one.line)
-    );
+    return {
+      refusals: addSqlIn(source, entry.phases ?? ["up"]).flatMap(
+        (one) => refusalsIn(path, one.sql, one.line)
+      )
+    };
   } catch (error) {
     if (error instanceof Unreadable) {
-      throw new CannotRun(`${path} holds ${error.message} \u2014 this reader cannot read it`);
+      return {
+        refusals: [],
+        unreadable: `${path} holds ${error.message} \u2014 this reader cannot read it`
+      };
     }
     throw error;
   }
@@ -636,7 +673,9 @@ var runMigrations = (input) => {
   const refusals = [];
   const markers = [];
   const squawk = [];
+  const unreadable = [];
   const forSquawk = [];
+  const states = /* @__PURE__ */ new Map();
   for (const { entry, file } of matched) {
     const source = readFileSync4(resolve5(input.root, file), "utf8");
     const found = markersIn(source);
@@ -646,11 +685,18 @@ var runMigrations = (input) => {
     });
     markers.push(...bad);
     const excused = found.length > 0 && bad.length === 0;
+    states.set(file, excused ? "excused" : "clean");
     if (!excused) {
-      refusals.push(
-        ...entry.dialect === "mikro-orm-ts" ? fromTypeScript(file, source, entry) : refusalsIn(file, source)
-      );
+      const mine = entry.dialect === "mikro-orm-ts" ? fromTypeScript(file, source, entry) : { refusals: refusalsIn(file, source) };
+      if (mine.unreadable !== void 0) {
+        unreadable.push({ path: file, why: mine.unreadable });
+        states.set(file, "unreadable");
+        continue;
+      }
+      refusals.push(...mine.refusals);
+      if (mine.refusals.length > 0) states.set(file, "refused");
     }
+    if (bad.length > 0) states.set(file, "refused");
     if (entry.dialect !== "sqlite")
       forSquawk.push({ entry, file, sql: sqlFor(file, source, entry) });
   }
@@ -670,6 +716,7 @@ var runMigrations = (input) => {
         if (!found.ok) {
           clean = false;
           squawk.push({ findings: found.findings, path: one.file });
+          if (states.get(one.file) === "clean") states.set(one.file, "findings");
         }
       }
     } finally {
@@ -677,14 +724,18 @@ var runMigrations = (input) => {
     }
   }
   return {
+    dirs: entries.map((one) => one.dir),
+    files: matched.map(({ file }) => ({ path: file, state: states.get(file) ?? "clean" })),
     linted: forSquawk.length,
     markers: markers.toSorted((a, b) => a.path.localeCompare(b.path) || a.line - b.line),
-    ok: refusals.length === 0 && markers.length === 0 && clean,
-    read: matched.length,
+    ok: refusals.length === 0 && markers.length === 0 && clean && unreadable.length === 0,
+    read: matched.length - unreadable.length,
+    since: input.since,
     refusals: refusals.toSorted(
       (a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.verb.localeCompare(b.verb)
     ),
-    squawk
+    squawk,
+    unreadable
   };
 };
 var WHY = `
@@ -695,21 +746,35 @@ is safe now:
   -- contract-migration: <what expanded it, and why nothing reads it any more> since:<ref>
 `;
 var formatMigrations = (report) => {
+  if (report.files.length === 0) {
+    return `NONE  migrations: no migration file was added since ${report.since} \u2014 committed, staged or untracked \u2014 under ${report.dirs.join(", ")}; nothing was read
+`;
+  }
   if (report.ok) {
     return `OK    migrations: expand-only (${String(report.read)} read, ${String(report.linted)} linted by squawk)
 `;
   }
   const said = report.markers.map((one) => `  ${one.path}: ${one.why} (line ${String(one.line)})
 `);
-  const lines = report.refusals.map(
+  const lines2 = report.refusals.map(
     (one) => `  ${one.path}: ${one.verb} (line ${String(one.line)})
 `
   );
   const found = report.squawk.map((one) => `  ${one.path}:
 ${one.findings}
+`);
+  const cannot = report.unreadable.map((one) => `  ${one.why}
 `);
   const why = report.markers.length + report.refusals.length === 0 ? "" : WHY;
-  return `${said.join("")}${lines.join("")}${why}${found.join("")}`;
+  return `${said.join("")}${lines2.join("")}${cannot.join("")}${why}${found.join("")}${accounting(report)}`;
+};
+var accounting = (report) => {
+  const total = report.files.length;
+  const by = (state) => report.files.filter((one) => one.state === state).length;
+  const rows = report.files.map((one) => `  ${one.state.padEnd(10)} ${one.path}
+`);
+  return `${rows.join("")}migrations: ${String(report.read)} of ${String(total)} files read \u2014 ${String(by("refused"))} refused, ${String(by("findings"))} with squawk findings, ${String(by("excused"))} excused, ${String(by("clean"))} clean${report.unreadable.length === 0 ? "" : `, ${String(report.unreadable.length)} unreadable`}
+`;
 };
 
 // src/plan.ts
@@ -871,7 +936,7 @@ var stubPath = () => {
   return path;
 };
 var prove = async (cwd, stub = stubPath()) => {
-  const lines = [];
+  const lines2 = [];
   let ok = true;
   for (const plant of PLANTS) {
     const verdict = await proveOver({
@@ -881,10 +946,10 @@ var prove = async (cwd, stub = stubPath()) => {
       timeoutMs: 3e4
     });
     if (verdict.ok) ok = false;
-    lines.push(`  ${verdict.ok ? "MISSED" : "PROVEN"} ${plant.says}`);
+    lines2.push(`  ${verdict.ok ? "MISSED" : "PROVEN"} ${plant.says}`);
     if (plant.name !== "promoted" && verdict.steps.includes("promote")) {
       ok = false;
-      lines.push("  MISSED a refused smoke was followed by a promote request");
+      lines2.push("  MISSED a refused smoke was followed by a promote request");
     }
   }
   const honest = await proveOver({
@@ -894,10 +959,10 @@ var prove = async (cwd, stub = stubPath()) => {
     timeoutMs: 3e4
   });
   if (!honest.ok) ok = false;
-  lines.push(
+  lines2.push(
     `  ${honest.ok ? "PROVEN" : "MISSED"} a smoke that answered the version it overrode to is not refused`
   );
-  return { lines, ok };
+  return { lines: lines2, ok };
 };
 var formatProve = (outcome) => `${outcome.lines.join("\n")}
 

package/dist/index.d.ts

@@ -37,16 +37,30 @@ type MarkerRefusal = {
     path: string;
     why: string;
 };
+type FileState = 'clean' | 'excused' | 'findings' | 'refused' | 'unreadable';
 type MigrationsReport = {
+    /** The configured directories the run looked under. */
+    dirs: string[];
+    /** Every file the diff added under a configured dir, by name and state — a clean file included. */
+    files: {
+        path: string;
+        state: FileState;
+    }[];
     linted: number;
     markers: MarkerRefusal[];
     ok: boolean;
     read: number;
     refusals: Refusal[];
+    since: string;
     squawk: {
         findings: string;
         path: string;
     }[];
+    /** Files this reader could not read: named, never a stop for the others. */
+    unreadable: {
+        path: string;
+        why: string;
+    }[];
 };
 
 declare const parseReleaseConfig: (raw: unknown) => ReleaseConfig;

package/dist/index.js

@@ -28,7 +28,7 @@ import {
   runMigrations,
   runPlan,
   statementsOf
-} from "./chunk-2JLVQK7Y.js";
+} from "./chunk-D5IC766I.js";
 export {
   DEPLOYED_FILE,
   NARROWING,

package/dist/release-cli.js

@@ -10,7 +10,7 @@ import {
   runDeployed,
   runMigrations,
   runPlan
-} from "./chunk-2JLVQK7Y.js";
+} from "./chunk-D5IC766I.js";
 
 // src/release-cli.ts
 import { resolve } from "path";
@@ -93,6 +93,7 @@ var migrations = (parsed, cwd) => {
     parsed.json ? `${JSON.stringify(report, void 0, 2)}
 ` : formatMigrations(report)
   );
+  if (report.unreadable.length > 0) return 2;
   return report.ok ? 0 : 1;
 };
 var plan = (parsed, cwd) => {
@@ -133,8 +134,30 @@ var deployed = (parsed, cwd) => {
   );
   return report.ok ? 0 : 1;
 };
+var CONFIG_SHAPE = `geonosis-release reads geonosis.json
+
+geonosis.json \u2192 "release"      every key optional; a repo that configured nothing gets nothing
+  migrations    Entry[]?        the directories whose migrations a release examines
+      dir       string          required \u2014 the directory, relative to the root
+      dialect   string          required \u2014 one of mikro-orm-ts, postgres, sqlite
+      phases    string[]?       "up" and/or "down" (default ["up"])
+      squawk    object?         { exclude: string[] } \u2014 the rule ids to leave out
+  proof         object?         { mustAssertVersion: boolean }
+  secrets       string[]?       the secret names a deployment carries
+  steps         string[]?       the release steps
+  workers       string[]?       the workers it deploys
+  wrangler      string[]?       the wrangler configs it carries
+  wranglerEnv   string?         the named environment block to read out of them
+
+A key outside either list is refused BY NAME, with the accepted set. This shape had to be read out
+of a bundled chunk file by a consumer once (#75).`;
 var main = async () => {
   const argv = process.argv.slice(2);
+  if (argv.includes("--print-config-shape")) {
+    process.stdout.write(`${CONFIG_SHAPE}
+`);
+    return 0;
+  }
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
     process.stdout.write(USAGE);
     return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/release",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "types": "./dist/index.d.ts",
   "description": "The release contract with its proofs: an expand-only migration gate over three dialects, a smoke that must name the version that answered it, and declared ≠ deployed.",
   "keywords": [
@@ -35,7 +35,15 @@
     "bin",
     "dist"
   ],
-  "dependencies": {
+  "peerDependencies": {
+    "squawk-cli": "2.63.0"
+  },
+  "peerDependenciesMeta": {
+    "squawk-cli": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
     "squawk-cli": "2.63.0"
   },
   "engines": {