@geonosis/release 1.2.0 → 1.4.0

package/README.md

@@ -101,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
 
-`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.
+```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.
+
+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-BOTEFN3W.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 {
@@ -571,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");
@@ -578,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) => {

package/dist/index.js

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

package/dist/release-cli.js

@@ -10,10 +10,90 @@ import {
   runDeployed,
   runMigrations,
   runPlan
-} from "./chunk-BOTEFN3W.js";
+} from "./chunk-D5IC766I.js";
 
 // src/release-cli.ts
 import { resolve } from "path";
+
+// src/envelope.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var ENVELOPES_DIR = ".geonosis/envelopes";
+var envelopePath = (root, tool) => join(root, ENVELOPES_DIR, `${tool}.json`);
+var UnbalancedEnvelope = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnbalancedEnvelope";
+  }
+};
+var isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+var unbalancedMessage = (envelope, next) => `${envelope.tool}: considered ${envelope.considered} but accounts for ${envelope.read + envelope.refused.length + envelope.excused.length} \u2014 ${envelope.read} read + ${envelope.refused.length} refused + ${envelope.excused.length} excused. A run that has lost count of its own inputs cannot say what it measured, so no verdict was rendered and no envelope was written. Next: ${next}`;
+var writeEnvelope = ({
+  envelope,
+  next,
+  root
+}) => {
+  if (envelope.tool.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `an envelope with no tool name cannot be filed or reported against. Next: ${next}`
+    );
+  }
+  if (envelope.version.trim() === "") {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: an envelope that cannot name the build that wrote it dates nothing, and a stale one reads exactly like a fresh one. Next: ${next}`
+    );
+  }
+  if (!isCount(envelope.considered) || !isCount(envelope.read)) {
+    throw new UnbalancedEnvelope(
+      `${envelope.tool}: considered ${envelope.considered} and read ${envelope.read} \u2014 a census is a whole number of things, and arithmetic over anything else balances by accident. Next: ${next}`
+    );
+  }
+  if (envelope.considered !== envelope.read + envelope.refused.length + envelope.excused.length) {
+    throw new UnbalancedEnvelope(unbalancedMessage(envelope, next));
+  }
+  const at = envelopePath(root, envelope.tool);
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(envelope, void 0, 2)}
+`);
+  return at;
+};
+var UNKNOWN = "unknown";
+var versionIn = (dir) => {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var versionOf = (moduleUrl) => {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (; ; ) {
+    const found = versionIn(dir);
+    if (found !== void 0) return found;
+    const up = dirname(dir);
+    if (up === dir) return UNKNOWN;
+    dir = up;
+  }
+};
+var MIGRATIONS_TOOL = "release-migrations";
+var MIGRATIONS_NEXT = "geonosis-release migrations --since <ref> --json and compare `files` against `unreadable` \u2014 every added file leaves by exactly one door, and a file in one list and not the other is the accounting bug this refuses over";
+var migrationsEnvelope = (report, durationMs) => ({
+  considered: report.files.length,
+  durationMs,
+  excused: report.files.filter((one) => one.state === "excused").map((one) => ({
+    path: one.path,
+    reason: "a contract-migration marker this gate could believe"
+  })),
+  findings: [...report.refusals, ...report.markers, ...report.squawk],
+  read: report.files.filter((one) => one.state !== "excused" && one.state !== "unreadable").length,
+  refused: report.unreadable.map((one) => ({ path: one.path, reason: one.why })),
+  tool: MIGRATIONS_TOOL,
+  version: versionOf(import.meta.url)
+});
+
+// src/release-cli.ts
 var USAGE = `geonosis-release <command> [options]
 
   migrations --since <ref> [--dialect <name>] [--root <dir>] [--json]
@@ -84,15 +164,24 @@ var migrations = (parsed, cwd) => {
   if (dialect !== void 0 && !DIALECTS.has(dialect)) {
     throw new CannotRun(`--dialect must be one of ${[...DIALECTS].toSorted().join(", ")}`);
   }
+  const root = resolve(cwd, parsed.read["--root"] ?? cwd);
+  const startedAt = Date.now();
   const report = runMigrations({
     ...dialect === void 0 ? {} : { dialect },
-    root: resolve(cwd, parsed.read["--root"] ?? cwd),
+    root,
     since
   });
   process.stdout.write(
     parsed.json ? `${JSON.stringify(report, void 0, 2)}
 ` : formatMigrations(report)
   );
+  const at = writeEnvelope({
+    envelope: migrationsEnvelope(report, Date.now() - startedAt),
+    next: MIGRATIONS_NEXT,
+    root
+  });
+  if (!parsed.json) process.stdout.write(`envelope: ${at}
+`);
   if (report.unreadable.length > 0) return 2;
   return report.ok ? 0 : 1;
 };
@@ -134,8 +223,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.2.0",
+  "version": "1.4.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,9 +35,18 @@
     "bin",
     "dist"
   ],
-  "dependencies": {
+  "peerDependencies": {
     "squawk-cli": "2.63.0"
   },
+  "peerDependenciesMeta": {
+    "squawk-cli": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "squawk-cli": "2.63.0",
+    "@geonosis/ratchet": "1.4.0"
+  },
   "engines": {
     "node": ">=22"
   },