@avi2dg/checks 0.57.0 → 0.58.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.58.0
+
+Released 2026-10-29.
+
+### Features
+
+- **delivery:** scan commit messages for secrets and pack terms [#17](https://github.com/avi2d/checks/pull/17)
+
+## 0.57.1
+
+Released 2026-10-29.
+
+### Fixes
+
+- **complexity:** time out graphwalk and its dependency cruiser child [#18](https://github.com/avi2d/checks/pull/18)
+
 ## 0.57.0
 
 Released 2026-10-27.

package/commitlint.config.ts

@@ -1,21 +1,3 @@
-import configConventional from "@commitlint/config-conventional";
-
-const houseTypes: ReadonlyArray<string> = [
-  "theme",
-  "renamer",
-  "shell",
-  "pi",
-  "home",
-  "audit",
-  "comments",
-  "unslop",
-];
-
-const conventionalEnum = configConventional.rules["type-enum"];
-
 export default {
   extends: ["@commitlint/config-conventional"],
-  rules: {
-    "type-enum": [conventionalEnum[0], conventionalEnum[1], [...conventionalEnum[2], ...houseTypes]],
-  },
 };

package/docs/configs/commit-messages.md

@@ -8,7 +8,7 @@ The shared commitlint config holds each pull request title to the conventional c
 
 ## Config
 
-Commits follow `@commitlint/config-conventional` plus the house prefixes `commitlint.config.ts` lists, shared from `node_modules/@avi2dg/checks/commitlint.config.ts`.
+Commits follow `@commitlint/config-conventional`, shared from `node_modules/@avi2dg/checks/commitlint.config.ts`.
 It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-conventional` are dependencies, not peers.
 
 ## Workflow

package/docs/configs/effect-rules.md

@@ -28,8 +28,8 @@ import { defineConfig } from "@avi2dg/checks/oxlint";
 export default defineConfig({
   effect: {
     excludeFiles: [
-      // Launchd runs the renamer, and it cannot import Effect v4.
-      "home/.config/renamer/**",
+      // The host loads this entry outside the Effect runtime.
+      "src/host/**",
     ],
   },
 });

package/docs/design.md

@@ -323,6 +323,8 @@ A finding location prints as it stands, such as a file name or a link.
 So a term inside a file name or a repository name shows there.
 That location is already public in the scanned commit or the scanned pull request.
 
+A pushed branch has already sent each commit message to the forge.
+So `checks-secrets` scans each message in the range with the same rules and the same pack.
 A pull request's title, body and comments reach the forge without a commit, so [checks-pr-text](gates/checks-pr-text.md) scans them with the same rules and the same pack.
 
 ## The frontend checks are opt-in

package/docs/gates/checks-docs-only.md

@@ -9,7 +9,7 @@ audience: consumers
 ## What it checks
 
 A change is docs-only when every file it touches is a `.md` file at the top level or under `docs/`, and it touches at least one file.
-Markdown anywhere else, such as a test fixture under `tests/` or a template under `dist/`, keeps the full run.
+Markdown anywhere else, such as a test fixture under `tests/` or a template under `dist/`, keeps the typecheck and unit test steps running.
 A rename counts both sides.
 An empty change and a change with no range keep the full run.
 
@@ -41,10 +41,11 @@ docs-only=true
 
 ## When it runs
 
-Each of the `static`, `unit` and `e2e` jobs of the `ci` workflow appends the verdict to `GITHUB_OUTPUT` in a filter step.
+The `static` and `unit` jobs of the `ci` workflow append the verdict to `GITHUB_OUTPUT` in a filter step.
 Their typecheck and test steps skip when the verdict reads `true`.
+The `e2e` job does not read this verdict: `scripts/e2e-skip.ts` skips it for a change of only Markdown and the root `copy.json`, a wider set than this bin's.
 The build, its `git diff --exit-code` and `bun run lint` still run, so `checks-docs` and the generated blocks hold on a docs-only change.
-Every job still runs and reports, so every required check stays green on a docs-only change.
+The `checks` job still runs and reports, so its required check stays green on a docs-only change.
 
 ## Related topics
 

package/docs/gates/checks-graphwalk.md

@@ -55,6 +55,14 @@ It cruises against the first config it finds there:
 It runs dependency-cruiser from the installed kit under Bun, which loads a TypeScript config wherever it sits.
 It leaves out a tracked file the working tree no longer holds.
 
+## Time limits
+
+A run that lasts past 300 seconds stops, prints `graphwalk: timed out after 300s; set CHECKS_GRAPHWALK_TIMEOUT_SECONDS to allow longer` and exits 2.
+A dependency-cruiser run that lasts past 120 seconds stops, and the imports section prints `imports: dependency-cruiser timed out after 120s; set CHECKS_DEPCRUISE_TIMEOUT_SECONDS to allow longer` and cannot decide.
+`CHECKS_GRAPHWALK_TIMEOUT_SECONDS` and `CHECKS_DEPCRUISE_TIMEOUT_SECONDS` each take a whole number of seconds above 0, and any other value leaves the run or the section undecided.
+When a limit passes, the gate sends SIGTERM to the process group of each process it started.
+It sends SIGKILL 2 seconds later to any process still in that group, so nothing it started outlives the gate.
+
 ## Arguments
 
 ```sh
@@ -81,9 +89,10 @@ A seed written after the range adds a dead export, or after it removes the last
 | --- | --- |
 | 0 | no file is unreferenced, no symbol is unlisted, added or stale, and no import breaks an `error` rule, or `--write` recorded the baseline |
 | 1 | a file is unreferenced, a symbol is unlisted, added or stale, an import breaks an `error` rule, or the repository holds no Knip configuration |
-| 2 | a ref does not resolve, a scanner cannot run, or a Knip report, a cruise report or the baseline does not parse |
+| 2 | a ref does not resolve, a scanner cannot run, the run or dependency-cruiser passes its time limit, or a Knip report, a cruise report or the baseline does not parse |
 
 The gate exits 1 when any section reports a violation, and exits 2 only when no section reports one and at least one section cannot decide.
+When the run passes its time limit the gate exits 2 even when a section already reported a violation.
 
 It also exits 2 when the repository tracks no `.ts`, `.tsx`, `.astro`, `.mts` or `.cts` file, or, with `--write`, when it tracks no TypeScript file.
 A repository that tracks `.astro` files but no `.ts`, `.tsx`, `.mts` or `.cts` file prints only the unreferenced-files section.

package/docs/gates/checks-secrets.md

@@ -12,7 +12,10 @@ A private pack adds terms no public file may carry, such as a person's name, an
 It scans the lines each commit in the range adds, in every file the commit adds or modifies, with gitleaks.
 In a merge commit it scans the lines the merge's own resolution adds, such as a key written while resolving a conflict, and not what the merge brings in from the other parent.
 It exits 2 when a commit it scans is an octopus merge, one with three or more parents, because git gives no resolution diff for one.
+It scans the message of each commit in the range with the rules and the private pack [checks-pr-text](checks-pr-text.md) runs on a pull request's text.
+A merge commit's own message is scanned too, though the file scan skips what the merge brings in from the other parent.
 It fails on each secret the scan finds, and names its file, its line, the rule that matched and the commit that added it.
+A finding in a message names `the message` and its line in place of a file, where the subject is line 1.
 A secret one commit adds and a later commit in the range removes still fails, because the first commit still holds it.
 It guards new changes only, and never scans a commit before the range, so a secret already in the history takes no part.
 
@@ -40,14 +43,15 @@ These rules do not catch:
 No setting accepts a finding.
 It ignores a repository's `.gitleaks.toml`, its `.gitleaksignore` and every `gitleaks:allow` comment.
 It skips the paths gitleaks' default config skips, such as lockfiles, images and `node_modules/`.
-It scans what a commit adds to its files, and not its message or its author, which [checks-commit-identity](checks-commit-identity.md) judges.
+It scans what a commit adds to its files and its message, and not its author, which [checks-commit-identity](checks-commit-identity.md) judges.
 
 ## The private pack
 
 The private pack is a JSON file of terms that lives outside every public repository, and `CHECKS_SECRETS_PACK` names its path.
 The kit ships no pack and no term, so a public repository can run the pack without carrying what it hides.
 With `CHECKS_SECRETS_PACK` unset the gate runs the kit's rules alone, exactly as it does without a pack, and its last line says so.
-With it set the gate adds a rule for each kind of term the pack lists, and fails a range that adds any of them.
+With it set the gate adds a rule for each kind of term the pack lists.
+It fails a range that adds any of them to a file or a commit message.
 
 Each key is optional, and each holds a list of strings:
 
@@ -78,7 +82,7 @@ An IPv6 range has no key, so a pack lists its prefix under `hosts` as its addres
 The gitleaks default allowlist skips paths such as lockfiles, go.mod and go.sum, images and documents such as PDFs.
 It also skips node_modules and some Go and Ruby vendor paths, so the pack terms are not searched there.
 A lockfile's resolved URLs can carry a private registry host, so keep such a host out of lockfiles, go.mod and go.sum by other means.
-Commit messages are not scanned by the pack, and checks-commit-identity covers only the author, the committer and Co-authored-by trailers.
+The pack scans each commit message, trailers included, and checks-commit-identity also judges the author, the committer and Co-authored-by trailers.
 
 The gate exits 2, and scans nothing, when `CHECKS_SECRETS_PACK` is set but the pack cannot serve:
 
@@ -119,11 +123,12 @@ Unlike [checks-pr-text](checks-pr-text.md), this gate has no skip: a job that wr
 
 ## What it reads
 
-It reads the commits of the range from git, not the working tree.
+It reads the commits of the range and their messages from git, not the working tree.
 It needs git 2.36 or newer, which diffs a merge against the merge git would make on its own, and it exits 2 on an older git.
 It reads its rules from `src/delivery/gitleaks.toml` in the installed package.
 It reads the path of the private pack from `CHECKS_SECRETS_PACK`.
-It writes the kit's rules and the pack's into one config in a temporary directory it deletes when the scan ends.
+It writes the kit's rules and the pack's into one config, and each commit message into a file of its own.
+Each goes in a temporary directory it deletes when the scan ends.
 
 It runs the gitleaks release `src/delivery/gitleaks.ts` pins, by the SHA-256 of each platform's archive and of the binary inside it.
 On first use it downloads the archive from the scanner's GitHub release and unpacks the binary into `~/.cache/avi2dg-checks/gitleaks/<version>/`.
@@ -146,8 +151,8 @@ With one it scans that commit alone.
 
 | Code | When |
 | --- | --- |
-| 0 | no commit in the range adds a secret |
-| 1 | a commit in the range adds a secret |
+| 0 | no commit in the range adds a secret, in its files or its message |
+| 1 | a commit in the range adds a secret, in its files or its message |
 | 2 | a ref does not resolve, or a commit it scans is an octopus merge, or no verified scanner is at hand, or git is older than 2.36, or gitleaks fails, or `CHECKS_SECRETS_PACK` is set and the pack cannot serve |
 
 ## Sample output
@@ -163,8 +168,9 @@ secrets: CHECKS_SECRETS_PACK is unset, so the kit's rules ran without a private
 With a pack set, a finding of the pack names the kind of term and never the term:
 
 ```
-secrets: the range adds 1 secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:
+secrets: the range adds 2 secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:
   docs/setup.md:12 private-domain in 4f1c09ab: A domain the private pack lists
+  the message:3 private-name in 4f1c09ab: A name form the private pack lists
 secrets: the kit's rules and the private pack CHECKS_SECRETS_PACK names ran
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",

package/src/complexity/graphwalk.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { BunServices } from "@effect/platform-bun";
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Config, Console, Duration, Effect, FileSystem, Path, Schema } from "effect";
 import { LINTED_SOURCE, TYPESCRIPT_SOURCE, type TrackedContent } from "../core/gates.ts";
 import { checkoutFiles, collect, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { PASSED, runExitMain, UNDECIDED, Usage, VIOLATED } from "../core/main.ts";
@@ -34,6 +34,10 @@ export const CRUISED = ["*.ts", "*.tsx", "*.mts", "*.cts"] as const;
 
 const KIT_DEFAULTS = "kit-defaults.ts";
 
+type TimeLimit = { readonly variable: string; readonly seconds: number };
+const RUN_LIMIT = { variable: "CHECKS_GRAPHWALK_TIMEOUT_SECONDS", seconds: 300 } satisfies TimeLimit;
+const CRUISE_LIMIT = { variable: "CHECKS_DEPCRUISE_TIMEOUT_SECONDS", seconds: 120 } satisfies TimeLimit;
+
 export type Status = "passed" | "violated" | "undecided";
 
 class GraphwalkError extends Schema.TaggedError<GraphwalkError>()("GraphwalkError", {
@@ -75,6 +79,15 @@ function outside(symbols: readonly UnusedSymbol[], others: readonly UnusedSymbol
   return symbols.filter((symbol) => !known.has(keyOf(symbol))).toSorted(byPosition);
 }
 
+const withinLimit = Effect.fn("withinLimit")(function* <A, E, R>(prefix: string, { variable, seconds: fallback }: TimeLimit, body: Effect.Effect<A, E, R>) {
+  const seconds = yield* Config.schema(Schema.Int.check(Schema.isGreaterThan(0)), variable).pipe(
+    Config.withDefault(fallback),
+    Effect.mapError(() => new GraphwalkError({ message: `${variable} must be a whole number of seconds above 0` })),
+  );
+  const message = `${prefix}timed out after ${seconds}s; set ${variable} to allow longer`;
+  return yield* body.pipe(Effect.timeoutOrElse({ duration: Duration.seconds(seconds), orElse: () => Effect.fail(new GraphwalkError({ message })) }));
+});
+
 const describe = (symbol: UnusedSymbol): string => `  ${symbol.file}: ${symbol.name} (${symbol.kind})`;
 
 export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
@@ -267,9 +280,10 @@ const importsSection = (root: string) =>
       const files = yield* trackedInTree(root);
       if (files.length === 0) return yield* new GraphwalkError({ message: "no tracked TypeScript to cruise" });
       const config = yield* configOf(root);
-      const run = yield* collect(process.execPath, [yield* depcruise(), "--config", config.file, "--output-type", "json", ...files], root).pipe(
+      const cruise = collect(process.execPath, [yield* depcruise(), "--config", config.file, "--output-type", "json", ...files], root).pipe(
         Effect.mapError((cause) => new GraphwalkError({ message: `cannot run dependency-cruiser: ${cause.message}` })),
       );
+      const run = yield* withinLimit("dependency-cruiser ", CRUISE_LIMIT, cruise);
       const { summary } = yield* decodeCruise(run.stdout).pipe(
         Effect.mapError(
           () => new GraphwalkError({ message: `dependency-cruiser exits ${run.exitCode} with no report: ${(run.stdout + run.stderr).trim()}` }),
@@ -369,6 +383,10 @@ const gate = Effect.gen(function* () {
   ),
 );
 
+const timedGate = withinLimit("", RUN_LIMIT, gate).pipe(
+  Effect.catch((cause) => Console.error(`${NAME}: ${cause.message}`).pipe(Effect.as(UNDECIDED))),
+);
+
 if (import.meta.main) {
-  runExitMain(gate);
+  runExitMain(timedGate);
 }

package/src/core/git.ts

@@ -15,12 +15,15 @@ export type Feed = {
   readonly input?: string;
 };
 
+// Without a SIGKILL deadline, an interrupted child that ignores SIGTERM holds its scope open forever.
+const KILL_GRACE = "2 seconds";
+
 // Both pipes drain while the program runs: one left unread fills its buffer and stalls it.
 export const collect = Effect.fn("collect")(
   function* (program: string, args: readonly string[], cwd?: string, { env, input }: Feed = {}) {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const stdin = input === undefined ? undefined : Stream.make(new TextEncoder().encode(input));
-    const handle = yield* spawner.spawn(ChildProcess.make(program, args, { cwd, env, extendEnv: true, stdin }));
+    const handle = yield* spawner.spawn(ChildProcess.make(program, args, { cwd, env, extendEnv: true, stdin, forceKillAfter: KILL_GRACE }));
     const [stdout, stderr, exitCode] = yield* Effect.all([text(handle.stdout), text(handle.stderr), handle.exitCode], {
       concurrency: "unbounded",
     });

package/src/delivery/release-push.ts

@@ -101,7 +101,7 @@ const land = Effect.fn("land")(function* (root: string, base: string, head: stri
           Effect.gen(function* () {
             const now = listed.split("\t")[0];
             if (now === release) return "landed";
-            if (now === head) return yield* Effect.fail(failure);
+            if (now === head) return yield* failure;
             yield* git(["fetch", "--quiet", "--no-tags", "origin", `refs/heads/${base}`], root);
             const ancestor = yield* git(["merge-base", "--is-ancestor", release, "FETCH_HEAD"], root).pipe(
               Effect.as(true),

package/src/delivery/secrets.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Schema } from "effect";
-import { commitOf, git, refArgs } from "../core/git.ts";
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { GitFailure, commitOf, git, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { cacheRoot } from "../dependencies/cache-root.ts";
-import { pinnedGitleaks, scanCommits, type Leak } from "./gitleaks.ts";
+import { pinnedGitleaks, scanCommits, scanDirectory, type DirectoryScan, type Leak } from "./gitleaks.ts";
 import { scanConfig } from "./secrets-pack.ts";
 
 const NAME = "secrets";
@@ -27,8 +27,7 @@ const revisionsOf = Effect.fn("revisionsOf")(function* (args: readonly string[],
 
 // Without --remerge-diff git log prints no diff for a merge, and a first-parent diff would rescan what the merge brings in.
 // git skips --remerge-diff for an octopus merge with only a warning, so the scan would pass a commit it never read.
-const logOptionsOf = Effect.fn("logOptionsOf")(function* (args: readonly string[], root: string) {
-  const revisions = yield* revisionsOf(args, root);
+const logOptionsOf = Effect.fn("logOptionsOf")(function* (revisions: readonly string[], root: string) {
   const [octopus] = (yield* git(["rev-list", `--min-parents=${OCTOPUS_PARENTS}`, ...revisions], root)).split("\n");
   if (octopus !== undefined && octopus !== "") {
     return yield* new OctopusMerge({
@@ -48,10 +47,42 @@ const atRepositoryPath = Effect.fn("atRepositoryPath")(function* (leak: Leak, ro
   return held ? leak : { ...leak, File: leak.File.slice(NEW_SIDE_PREFIX.length) };
 });
 
+type Message = { readonly commit: string; readonly text: string };
+
+// git refuses a NUL in a commit message, so the NUL -z writes after each record ends it.
+const messagesOf = Effect.fn("messagesOf")(function* (revisions: readonly string[], root: string) {
+  const records = (yield* git(["log", "--no-show-signature", "-z", "--format=%H%n%B", ...revisions], root)).split("\0").filter((record) => record !== "");
+  return yield* Effect.forEach(records, (record) => {
+    const newline = record.indexOf("\n");
+    const commit = newline === -1 ? "" : record.slice(0, newline);
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(commit)) {
+      return Effect.fail(new GitFailure({ message: "git log: a record does not start with a commit id" }));
+    }
+    return Effect.succeed({ commit, text: record.slice(newline + 1) } satisfies Message);
+  });
+});
+
+const messageLeaksOf = Effect.fn("messageLeaksOf")(function* (messages: readonly Message[], scanner: Omit<DirectoryScan, "dir">) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-secrets-messages-" });
+  yield* Effect.forEach(messages, ({ commit, text }) => fs.writeFileString(path.join(dir, commit), text));
+  const leaks = yield* scanDirectory({ ...scanner, dir });
+  return leaks.map((leak) => ({ ...leak, Commit: path.basename(leak.File) }));
+});
+
 function leakLine({ File, StartLine, RuleID, Commit, Description }: Leak): string {
   return `  ${File}:${StartLine} ${RuleID} in ${Commit.slice(0, SHORT_SHA)}: ${Description}`;
 }
 
+function messageLine({ StartLine, RuleID, Commit, Description }: Leak): string {
+  return `  the message:${StartLine} ${RuleID} in ${Commit.slice(0, SHORT_SHA)}: ${Description}`;
+}
+
+function byMessage(left: Leak, right: Leak): number {
+  return left.Commit.localeCompare(right.Commit) || left.StartLine - right.StartLine || left.RuleID.localeCompare(right.RuleID);
+}
+
 function byPlace(left: Leak, right: Leak): number {
   return (
     left.File.localeCompare(right.File) ||
@@ -61,27 +92,31 @@ function byPlace(left: Leak, right: Leak): number {
   );
 }
 
-export function report(leaks: readonly Leak[]): string {
-  if (leaks.length === 0) return `${NAME}: the range adds no secret`;
+export function report(fileLeaks: readonly Leak[], messageLeaks: readonly Leak[]): string {
+  const count = fileLeaks.length + messageLeaks.length;
+  if (count === 0) return `${NAME}: the range adds no secret`;
   return [
-    `${NAME}: the range adds ${leaks.length} secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:`,
-    ...leaks.toSorted(byPlace).map(leakLine),
+    `${NAME}: the range adds ${count} secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:`,
+    ...fileLeaks.toSorted(byPlace).map(leakLine),
+    ...messageLeaks.toSorted(byMessage).map(messageLine),
   ].join("\n");
 }
 
 const secrets = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem;
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const logOptions = yield* logOptionsOf(process.argv.slice(2), root);
+  const revisions = yield* revisionsOf(process.argv.slice(2), root);
+  const logOptions = yield* logOptionsOf(revisions, root);
   const ignoreDir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-secrets-" });
   const { config, notice } = yield* scanConfig(NAME, yield* fs.makeTempDirectoryScoped({ prefix: "checks-secrets-pack-" }));
   const binary = yield* pinnedGitleaks(yield* cacheRoot());
   const gitDir = (yield* git(["rev-parse", "--absolute-git-dir"], root)).trim();
   const reported = yield* scanCommits({ binary, gitDir, logOptions, config, ignoreDir });
-  const leaks = yield* Effect.forEach(reported, (leak) => atRepositoryPath(leak, root));
-  yield* Console.log(report(leaks));
+  const fileLeaks = yield* Effect.forEach(reported, (leak) => atRepositoryPath(leak, root));
+  const messageLeaks = yield* messageLeaksOf(yield* messagesOf(revisions, root), { binary, config, ignoreDir });
+  yield* Console.log(report(fileLeaks, messageLeaks));
   yield* Console.log(notice);
-  return leaks.length === 0;
+  return fileLeaks.length + messageLeaks.length === 0;
 }).pipe(Effect.scoped);
 
 if (import.meta.main) runMain(NAME, secrets);