@avi2dg/checks 0.57.1 → 0.58.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.

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-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.1",
+  "version": "0.58.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",

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);