@avi2dg/checks 0.52.1 → 0.53.0

package/docs/gates/checks-secrets.md

@@ -5,6 +5,7 @@ audience: consumers
 # checks-secrets
 
 `checks-secrets` is the gate that fails a range whose commits add a secret, such as an API token, a private key, a VPN key or a proxy link that carries its credential.
+A private pack adds terms no public file may carry, such as a person's name, an employer's domain, host names and IP ranges.
 
 ## What it checks
 
@@ -39,12 +40,90 @@ 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.
+
+## 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.
+
+Each key is optional, and each holds a list of strings:
+
+| Key | Rule | What it matches |
+| --- | --- | --- |
+| `names` | `private-name` | a person's name form, such as a full name, a handle or a login |
+| `domains` | `private-domain` | an employer's or any other domain, also inside an email address or a subdomain |
+| `hosts` | `private-host` | a host name |
+| `runners` | `private-runner` | a CI runner's name |
+| `ipRanges` | `private-ip-range` | an IPv4 address inside a CIDR range, such as `192.0.2.0/24`, or a single IPv4 address |
+
+A pack with obviously fake terms reads like this:
+
+```json
+{
+  "names": ["Pat Example", "pexample"],
+  "domains": ["employer.example"],
+  "hosts": ["build-01.corp.example"],
+  "runners": ["runner-blue-7"],
+  "ipRanges": ["192.0.2.0/24", "198.51.100.7"]
+}
+```
+
+A term matches in any case, and the spaces inside it match any run of ASCII whitespace or Unicode space separators.
+A term's end that is an ASCII letter, digit or underscore matches only at a word boundary, so `pexample` does not match inside `pexamples`.
+An address matches only as a whole, so `192.0.2.0/24` does not match `1192.0.2.5`.
+An IPv6 range has no key, so a pack lists its prefix under `hosts` as its addresses are written, such as `2001:db8:`.
+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 gate exits 2, and scans nothing, when `CHECKS_SECRETS_PACK` is set but the pack cannot serve:
+
+- the variable is set to an empty value, as a CI secret that is missing expands
+- the file is missing, unreadable or a directory
+- the file is not JSON or holds a key the table does not name
+- a term is blank or holds a control character, or a range is not IPv4
+- the pack lists no term at all
+
+No report or error prints a matched term text or the pack path, because a public CI log would publish either.
+A finding names its file, its line and its rule, and the description of each pack rule says only which kind of term matched.
+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.
+
+The pack lives where only its owner reads it.
+On a laptop it is a file outside every checkout, and the shell profile exports its path:
+
+```sh
+export CHECKS_SECRETS_PACK="$HOME/.config/checks/secrets-pack.json"
+```
+
+In GitHub Actions a repository or organisation secret holds the JSON, and the job writes it to a file before the gate runs:
+
+```yaml
+- name: write the private pack
+  env:
+    PACK: ${{ secrets.CHECKS_SECRETS_PACK }}
+  run: |
+    printf '%s' "$PACK" > "$RUNNER_TEMP/secrets-pack.json"
+    echo "CHECKS_SECRETS_PACK=$RUNNER_TEMP/secrets-pack.json" >> "$GITHUB_ENV"
+- run: bun run lint
+```
+
+A fork's `pull_request` run gets no secret, so the file is empty and the gate exits 2 rather than pass without the pack.
+Unlike [checks-pr-text](checks-pr-text.md), this gate has no skip: a job that writes the pack from an unset secret exits 2.
+[checks-pr-text](checks-pr-text.md) scans a pull request's title, body and comments with the same pack.
 
 ## What it reads
 
 It reads the commits of the range 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 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>/`.
@@ -69,7 +148,7 @@ With one it scans that commit alone.
 | --- | --- |
 | 0 | no commit in the range adds a secret |
 | 1 | a commit in the range adds a secret |
-| 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 |
+| 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
 
@@ -78,6 +157,15 @@ secrets: the range adds 3 secret(s); put a placeholder such as <private-key> in
   vpn/links.txt:1 proxy-userinfo-link in e19e45c2: A proxy share link that carries its credential before the @, such as vless://, trojan://, socks5:// or wireguard://
   vpn/wg0.conf:2 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
   vpn/wg0.conf:7 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
+secrets: CHECKS_SECRETS_PACK is unset, so the kit's rules ran without a private pack
+```
+
+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:
+  docs/setup.md:12 private-domain in 4f1c09ab: A domain the private pack lists
+secrets: the kit's rules and the private pack CHECKS_SECRETS_PACK names ran
 ```
 
 The report never prints a secret.
@@ -90,4 +178,5 @@ A local `bun run lint` runs it over the commits the branch adds, so it fails bef
 ## Related topics
 
 - [checks-lint](checks-lint.md)
+- [checks-pr-text](checks-pr-text.md)
 - [Why it is shaped this way](../design.md)

package/docs/gates/checks-setup.md

@@ -0,0 +1,76 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-setup
+
+`checks-setup` writes the kit config, the CI workflow and the doc templates into a repository that does not hold them yet.
+
+## What it checks
+
+A run writes each missing file and brings the files it finds up to what the checks need.
+It adds the `node_modules/` line to `.gitignore` when the file lacks it.
+It adds the kit entry and any missing script to a `package.json` it finds.
+It replaces the kit version pin with its own version, and a `--private` run sets `private` to `true`.
+It stops when a `lint` script it finds does not run oxlint and the layout check, and names the script to fix.
+It stops when a `typecheck` script it finds does not run the Effect diagnostics, and names the script to fix.
+It stops when a `test` script it finds is not the kit suite, and names the script to fix.
+It copies the fleet pin into `.bun-version` and the preset into `bunfig.toml`.
+It writes `oxlint.config.ts`, `tsconfig.json` and `knip.config.ts` from the kit builders, with Effect rules on.
+It writes the Effect paths of the `oxlint.config.ts` it finds or writes into the language service entry of `tsconfig.json`.
+The pair passes `checks-effect-scope --check` from the first write.
+It writes `package.json` with the kit in `devDependencies` and with `lint`, `typecheck` and `test` scripts.
+It writes `.github/workflows/ci.yml`, which installs with `bun install --frozen-lockfile` and then runs the `build` script when the manifest holds one.
+The workflow always runs `bun run lint`, `bun run typecheck` and `bun run test`.
+A `build` script there also brings a `git diff --exit-code` step.
+Other scripts a `package.json` it finds already holds stay, but the workflow never schedules them.
+The workflow always ends with a `bunx checks-commit-title` step for the pull request title.
+A `--private` run pins each job to `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
+Setting the `CI_RUNS_ON` variable to a self-hosted runner label then lands the jobs there.
+A public run pins each job to `ubuntu-latest`.
+It copies each kit template under `dist/templates/` into `templates/`, so a new doc file starts from a copy there.
+It names every file it wrote and every file it kept.
+It tells the owner to declare the repository owners in `package.json` `author` or `contributors` before the first commit.
+
+## What it reads
+
+It reads the working tree, which is the repository it sets up.
+It reads a `package.json` it finds for the fields and scripts it keeps, replaces or refuses.
+It reads the kit install for `.bun-version`, `bunfig.toml`, its version and each template.
+
+## Arguments
+
+```sh
+checks-setup [--private]
+```
+
+With no arguments the repository is public, and its jobs run on `ubuntu-latest`.
+With `--private` the jobs read the `CI_RUNS_ON` variable, and the run names the value to set.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every file is written or already there |
+| 2 | an argument is unknown, a file it needs cannot be read, or a `lint`, `typecheck` or `test` script it finds does not run the checks |
+
+## Sample output
+
+```
+checks-setup: wrote .bun-version
+checks-setup: kept oxlint.config.ts, already there
+checks-setup: declare the repository owners in package.json author or contributors before the first commit
+checks-setup: set the CI_RUNS_ON variable to a self-hosted runner label so the new jobs land there
+```
+
+## When it runs
+
+A repository owner runs it once in a new repository, before the first install.
+Declare the repository owners in `package.json` `author` or `contributors` before the first commit.
+Running it again with the same kit version changes nothing.
+A later kit release arrives through [Upgrade the kit](../how-to/upgrade-the-kit.md).
+
+## Related topics
+
+- [Set up a repository](../how-to/set-up-a-repository.md)
+- [Upgrade the kit](../how-to/upgrade-the-kit.md)

package/docs/gates/checks-vendor.md

@@ -60,19 +60,19 @@ With no arguments it pins nothing.
 ## Sample output
 
 ```
-checks-vendor: cloned effect@4.0.0 from https://github.com/Effect-TS/effect.git and linked repos/effect
+checks-vendor: cloned effect@<version> from https://github.com/Effect-TS/effect.git and linked repos/effect
 ```
 
 A fresh fetch reports the tag it cloned and the link it made.
 
 ```
-checks-vendor: repos/effect still holds effect@4.0.0, verified against its recorded commit
+checks-vendor: repos/effect still holds effect@<version>, verified against its recorded commit
 ```
 
 A later run reports the link it kept.
 
 ```
-checks-vendor: found 1 path writable by its owner, starting with /home/runner/.cache/avi2dg-checks/repos/github.com/Effect-TS/effect/effect@4.0.0, and froze the tree again, so repos/effect still holds effect@4.0.0, verified against its recorded commit
+checks-vendor: found 1 path writable by its owner, starting with /home/runner/.cache/avi2dg-checks/repos/github.com/Effect-TS/effect/effect@<version>, and froze the tree again, so repos/effect still holds effect@<version>, verified against its recorded commit
 ```
 
 A run that found an owner write bit reports how many paths carried one and the first of them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -39,8 +39,12 @@
     "src/delivery/release-notes.ts",
     "src/delivery/release-report.ts",
     "src/delivery/release.ts",
+    "src/delivery/release-commit.ts",
     "src/delivery/release-pr.ts",
+    "src/delivery/release-publish.ts",
+    "src/delivery/release-push.ts",
     "src/delivery/release-tag.ts",
+    "src/delivery/release-tagging.ts",
     "src/delivery/github.ts",
     "src/testing/test-layout.ts",
     "src/testing/test.ts",
@@ -70,6 +74,9 @@
     "src/delivery/mutation-job.ts",
     "src/delivery/runner-policy.ts",
     "src/delivery/secrets.ts",
+    "src/delivery/secrets-pack.ts",
+    "src/delivery/pr-text.ts",
+    "src/delivery/setup.ts",
     "src/delivery/gitleaks.ts",
     "src/delivery/gitleaks.toml",
     "src/quality/comment-matchers.ts",
@@ -157,6 +164,8 @@
     "checks-release-notes": "src/delivery/release-notes.ts",
     "checks-release-report": "src/delivery/release-report.ts",
     "checks-release-pr": "src/delivery/release-pr.ts",
+    "checks-release-publish": "src/delivery/release-publish.ts",
+    "checks-release-push": "src/delivery/release-push.ts",
     "checks-release-tag": "src/delivery/release-tag.ts",
     "checks-lint-coverage": "src/quality/lint-coverage.sh",
     "checks-test-layout": "src/testing/test-layout.ts",
@@ -184,6 +193,8 @@
     "checks-vendor": "src/dependencies/vendor.ts",
     "checks-advisories": "src/dependencies/advisories.ts",
     "checks-secrets": "src/delivery/secrets.ts",
+    "checks-pr-text": "src/delivery/pr-text.ts",
+    "checks-setup": "src/delivery/setup.ts",
     "checks-frontend-syntax": "src/quality/frontend-syntax.ts",
     "checks-no-plain-js": "src/quality/no-plain-js.ts",
     "checks-browser": "src/quality/browser/browser.ts",

package/src/delivery/commit-title.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
-import { collect } from "../core/git.ts";
+import { collect, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 
 const NAME = "commit-title";
@@ -41,22 +41,29 @@ const dispatchedTitle = Effect.fn("dispatchedTitle")(function* () {
     "api",
     `repos/${repository}/pulls?head=${owner}:${ref}&state=open`,
     "--jq",
-    `if length == 1 then .[0].title else error("no one open pull request heads the branch") end`,
+    `if length == 1 then .[0].title elif length == 0 then empty else error("more than one open pull request heads the branch") end`,
   ]);
   const title = found.stdout.trim();
-  if (found.exitCode !== 0 || title === "" || title === "null") {
+  if (found.exitCode !== 0 || title === "null") {
     const report = found.stderr.trim() === "" ? found.stdout.trim() : found.stderr.trim();
     if (report !== "") yield* Console.error(report);
     return undefined;
   }
-  return title;
+  if (title !== "") return landedTitle(title);
+  // With no pull request the head commit lands as it is, so its own subject is the one to lint.
+  return (yield* git(["log", "-1", "--format=%s", "HEAD"])).trim();
 });
 
-const lintTitle = Effect.fn("lintTitle")(function* (title: string) {
+// GitHub appends the pull request number to the squashed subject.
+function landedTitle(title: string): string {
+  return `${title} (#0000)`;
+}
+
+const lintTitle = Effect.fn("lintTitle")(function* (subject: string) {
   const system = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const file = path.join(yield* system.makeTempDirectoryScoped({ prefix: "checks-commit-title-" }), "pr-title");
-  yield* system.writeFileString(file, `${title} (#0000)`);
+  yield* system.writeFileString(file, subject);
   // A title opening with the git comment character lints as empty without this: commentChar moves off the hash.
   const linted = yield* collect(process.execPath, [yield* cliOf(), "--config", yield* configOf(), "--edit", file], undefined, {
     env: { GIT_CONFIG_COUNT: "1", GIT_CONFIG_KEY_0: "core.commentChar", GIT_CONFIG_VALUE_0: "\x01" },
@@ -68,7 +75,7 @@ const lintTitle = Effect.fn("lintTitle")(function* (title: string) {
 
 const check = Effect.scoped(Effect.gen(function* () {
   const direct = yield* Config.String("PR_TITLE").pipe(Config.withDefault(""));
-  if (direct !== "") return yield* lintTitle(direct);
+  if (direct !== "") return yield* lintTitle(landedTitle(direct));
   const event = yield* Config.String("GITHUB_EVENT_NAME").pipe(Config.withDefault(""));
   if (event === "workflow_dispatch") {
     const title = yield* dispatchedTitle();

package/src/delivery/gitleaks.ts

@@ -65,23 +65,27 @@ export type Leak = typeof Leak.Type;
 
 const decodeGitleaksReport = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Leak)));
 
-export type Scan = {
+type Scanner = {
   readonly binary: string;
-  readonly gitDir: string;
-  readonly logOptions: string;
   readonly config: string;
   readonly ignoreDir: string;
 };
 
+export type Scan = Scanner & {
+  readonly gitDir: string;
+  readonly logOptions: string;
+};
+
+export type DirectoryScan = Scanner & {
+  readonly dir: string;
+};
+
 // gitleaks exits 1 both on a leak and on a fatal error, so it exits 0 on a leak here and the report alone tells them apart.
 // It exits 0 with an empty report when git log fails, and logs only errors here, so any line it logs fails the scan.
-// It reads a .gitleaksignore at its source whatever --gitleaks-ignore-path says, so the source is the git directory, where no tracked file lands.
-export const scanCommits = Effect.fn("scanCommits")(function* ({ binary, gitDir, logOptions, config, ignoreDir }: Scan) {
+// It reads a .gitleaksignore at its source whatever --gitleaks-ignore-path says, so a source holds no file a repository or an author can name.
+const scanned = Effect.fn("scanned")(function* (source: readonly string[], { binary, config, ignoreDir }: Scanner) {
   const args = [
-    "git",
-    gitDir,
-    "--log-opts",
-    logOptions,
+    ...source,
     "--config",
     config,
     "--gitleaks-ignore-path",
@@ -109,3 +113,14 @@ export const scanCommits = Effect.fn("scanCommits")(function* ({ binary, gitDir,
     Effect.mapError((cause) => new GitleaksError({ message: `cannot read the report gitleaks wrote: ${cause.message}` })),
   );
 });
+
+type Scanned = ReturnType<typeof scanned>;
+
+// The source is the git directory, where no tracked file lands.
+export function scanCommits({ gitDir, logOptions, ...scanner }: Scan): Scanned {
+  return scanned(["git", gitDir, "--log-opts", logOptions], scanner);
+}
+
+export function scanDirectory({ dir, ...scanner }: DirectoryScan): Scanned {
+  return scanned(["dir", dir], scanner);
+}

package/src/delivery/pr-text.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { runMain, Usage } from "../core/main.ts";
+import { cacheRoot } from "../dependencies/cache-root.ts";
+import { pinnedGitleaks, scanDirectory, type Leak } from "./gitleaks.ts";
+import { gh, gitHubJson, GitHubFailure, REPOSITORY } from "./github.ts";
+import { scanConfig } from "./secrets-pack.ts";
+
+const NAME = "pr-text";
+const USAGE = "usage: pr-text.ts <pull-request-number>";
+
+const PullRequest = Schema.Struct({ title: Schema.String, body: Schema.NullOr(Schema.String) });
+
+const Comment = Schema.Struct({ id: Schema.Int, html_url: Schema.String, body: Schema.NullOr(Schema.String) });
+
+const decodePullRequest = Schema.decodeUnknownEffect(Schema.fromJsonString(PullRequest));
+
+const decodeCommentPages = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.Array(Comment))));
+
+export type Text = { readonly file: string; readonly place: string; readonly body: string };
+
+const COMMENT_KINDS = [
+  { file: "issue-comment", parent: "issues", list: "comments" },
+  { file: "review", parent: "pulls", list: "reviews" },
+  { file: "review-comment", parent: "pulls", list: "comments" },
+] as const;
+
+const numberOf = Effect.fn("numberOf")(function* (args: readonly string[]) {
+  const [number, ...rest] = args;
+  if (number === undefined || rest.length > 0 || !/^[1-9]\d*$/.test(number)) return yield* new Usage({ message: USAGE });
+  return number;
+});
+
+const commentsOf = Effect.fn("commentsOf")(function* (path: string) {
+  const pages = yield* gh(["api", "--paginate", "--slurp", path], `gh api --paginate ${path}`);
+  return (yield* decodeCommentPages(pages).pipe(Effect.mapError((cause) => new GitHubFailure({ message: `gh api ${path} answered ${cause.message}` })))).flat();
+});
+
+// The title and the body come from the API rather than the event, which carries them as they stood when the event fired.
+const textsOf = Effect.fn("textsOf")(function* (number: string) {
+  const { title, body } = yield* gitHubJson(decodePullRequest, "GET", `${REPOSITORY}/pulls/${number}`);
+  const comments = yield* Effect.forEach(COMMENT_KINDS, (kind) =>
+    commentsOf(`${REPOSITORY}/${kind.parent}/${number}/${kind.list}`).pipe(
+      Effect.map((found) => found.map(({ id, html_url, body: text }) => ({ file: `${kind.file}-${id}`, place: html_url, body: text ?? "" }))),
+    ),
+  );
+  return [{ file: "title", place: "the title", body: title }, { file: "body", place: "the body", body: body ?? "" }, ...comments.flat()] satisfies readonly Text[];
+});
+
+export function report(number: string, texts: readonly Text[], leaks: readonly Leak[]): string {
+  if (leaks.length === 0) return `${NAME}: pull request ${number} carries no secret and no private term`;
+  const order = new Map(texts.map(({ file }, index) => [file, index]));
+  const placeOf = new Map(texts.map(({ file, place }) => [file, place]));
+  const fileOf = (leak: Leak) => leak.File.slice(leak.File.lastIndexOf("/") + 1);
+  const sorted = leaks.toSorted((left, right) => (order.get(fileOf(left)) ?? 0) - (order.get(fileOf(right)) ?? 0) || left.StartLine - right.StartLine || left.RuleID.localeCompare(right.RuleID));
+  return [
+    `${NAME}: pull request ${number} carries ${leaks.length} secret(s) or private term(s); delete each from the text it names, and delete the revision GitHub keeps in that text's edit history:`,
+    ...sorted.map((leak) => `  ${placeOf.get(fileOf(leak)) ?? fileOf(leak)}:${leak.StartLine} ${leak.RuleID}: ${leak.Description}`),
+  ].join("\n");
+}
+
+const prText = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const number = yield* numberOf(process.argv.slice(2));
+  const { config, notice } = yield* scanConfig(NAME, yield* fs.makeTempDirectoryScoped({ prefix: "checks-pr-text-pack-" }));
+  const texts = yield* textsOf(number);
+  const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-pr-text-" });
+  yield* Effect.forEach(texts, ({ file, body }) => fs.writeFileString(path.join(dir, file), body));
+  const ignoreDir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-pr-text-ignore-" });
+  const leaks = yield* scanDirectory({ binary: yield* pinnedGitleaks(yield* cacheRoot()), dir, config, ignoreDir });
+  yield* Console.log(report(number, texts, leaks));
+  yield* Console.log(notice);
+  return leaks.length === 0;
+}).pipe(Effect.scoped);
+
+if (import.meta.main) runMain(NAME, prText);

package/src/delivery/release-commit.ts

@@ -0,0 +1,152 @@
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import * as Base64 from "effect/encoding/Base64";
+import { gitHubJson, REPOSITORY } from "./github.ts";
+import { nextVersion, type Pending, readPending, releaseTitle, runBuild, withVersion } from "./release.ts";
+import { git } from "../core/git.ts";
+
+export class ReleaseRefused extends Schema.TaggedError<ReleaseRefused>()("ReleaseRefused", {
+  message: Schema.String,
+}) {}
+
+type Staged =
+  | { readonly kind: "written"; readonly path: string; readonly mode: string }
+  | { readonly kind: "deleted"; readonly path: string; readonly mode: string };
+
+type Read =
+  | { readonly kind: "written"; readonly path: string; readonly mode: string; readonly content: string }
+  | { readonly kind: "deleted"; readonly path: string; readonly mode: string };
+
+type Built = {
+  readonly tree: string;
+  readonly files: readonly Read[];
+};
+
+export const MANIFEST = "package.json";
+const REGULAR_FILE_MODES = new Set(["100644", "100755"]);
+const RAW_ENTRY = /^:(\d{6}) (\d{6}) [0-9a-f]+ [0-9a-f]+ ([A-Z])/;
+
+const decodeVersion = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.String })));
+const decodeSha = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ sha: Schema.String })));
+export const decodeRef = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ ref: Schema.String })));
+
+export function releaseBranchOf(base: string): string {
+  return `release/${base}`;
+}
+
+export function stagedOf(raw: string): readonly Staged[] {
+  const fields = raw.split("\0");
+  const staged: Staged[] = [];
+  for (let index = 0; index + 1 < fields.length; index += 2) {
+    const [, from = "", to = "", status] = RAW_ENTRY.exec(fields[index] ?? "") ?? [];
+    const path = fields[index + 1] ?? "";
+    staged.push(status === "D" ? { kind: "deleted", path, mode: from } : { kind: "written", path, mode: to });
+  }
+  return staged;
+}
+
+export function refused(message: string): ReleaseRefused {
+  return new ReleaseRefused({ message });
+}
+
+export const versionIn = (manifest: string): Effect.Effect<string | undefined> =>
+  decodeVersion(manifest).pipe(
+    Effect.map(({ version }) => version),
+    Effect.orElseSucceed(() => undefined),
+  );
+
+const releaseVersion = Effect.fn("releaseVersion")(function* (manifest: string, { since, unreleased }: Pending, untagged: string) {
+  const { version } = yield* decodeVersion(manifest).pipe(Effect.mapError((cause) => refused(`${MANIFEST}: ${cause.message}`)));
+  if (since !== undefined && since !== `v${version}`) {
+    return yield* refused(
+      `${MANIFEST} holds ${version}, but the last release tag is ${since}, so v${version} is untagged; ${untagged}, or return its version to ${since.slice(1)}`,
+    );
+  }
+  const next = nextVersion(version, unreleased);
+  if (next === undefined) return yield* refused(`${MANIFEST} holds ${version}, which is no plain major.minor.patch version`);
+  const bumped = withVersion(manifest, version, next);
+  if (bumped === undefined || (yield* versionIn(bumped)) !== next) {
+    return yield* refused(`cannot rewrite the version ${version} in ${MANIFEST} as ${next}`);
+  }
+  return { next, bumped };
+});
+
+const currentBranch = Effect.fn("currentBranch")(function* (root: string) {
+  const branch = yield* git(["symbolic-ref", "--quiet", "--short", "HEAD"], root).pipe(
+    Effect.map((name) => name.trim()),
+    Effect.catchTag("GitFailure", () => Effect.succeed("")),
+  );
+  if (branch === "") return yield* refused("HEAD is detached; check out the branch the release goes to");
+  return branch;
+});
+
+export const hasBranch = Effect.fn("hasBranch")(function* (root: string, branch: string) {
+  return (yield* git(["ls-remote", "origin", `refs/heads/${branch}`], root)).trim() !== "";
+});
+
+type Plan = {
+  readonly base: string;
+  readonly branch: string;
+  readonly head: string;
+  readonly next: string;
+  readonly bumped: string;
+};
+
+// Undefined means nothing is unreleased, which it has already said.
+export const planRelease = Effect.fn("planRelease")(function* (label: string, root: string, untagged: string) {
+  const pending = yield* readPending(root);
+  if (pending.unreleased.length === 0) {
+    yield* Console.log(`${label}: no unreleased changes ${pending.since === undefined ? "with no tag yet" : `since ${pending.since}`}`);
+    return undefined;
+  }
+  const base = yield* currentBranch(root);
+  const head = (yield* git(["rev-parse", "HEAD"], root)).trim();
+  const manifest = yield* (yield* FileSystem.FileSystem).readFileString((yield* Path.Path).join(root, MANIFEST));
+  const { next, bumped } = yield* releaseVersion(manifest, pending, untagged);
+  return { base, branch: releaseBranchOf(base), head, next, bumped } satisfies Plan;
+});
+
+const readStaged = Effect.fn("readStaged")(function* (root: string, staged: Staged) {
+  if (staged.kind === "deleted") return staged;
+  if (!REGULAR_FILE_MODES.has(staged.mode)) return yield* refused(`the build wrote ${staged.path} with mode ${staged.mode}, which is no regular file`);
+  const bytes = yield* (yield* FileSystem.FileSystem).readFile((yield* Path.Path).join(root, staged.path));
+  return { ...staged, content: Base64.encode(bytes) };
+});
+
+// The build writes into the working tree, so the tree it starts from has to hold nothing a release would sweep in.
+export const buildRelease = Effect.fn("buildRelease")(function* (name: string, root: string, bumped: string) {
+  if ((yield* git(["status", "--porcelain", "--untracked-files=no"], root)).trim() !== "") {
+    return yield* refused("the working tree has changes to tracked files; the release commits only what the build writes");
+  }
+  const restore = git(["reset", "--quiet", "--hard", "HEAD"], root).pipe(
+    Effect.catchTag("GitFailure", (failure) => Console.error(`${name}: cannot restore the working tree: ${failure.message}`)),
+  );
+  return yield* Effect.gen(function* () {
+    yield* (yield* FileSystem.FileSystem).writeFileString((yield* Path.Path).join(root, MANIFEST), bumped);
+    yield* runBuild(root);
+    yield* git(["add", "--update"], root);
+    const tree = (yield* git(["write-tree"], root)).trim();
+    const staged = stagedOf(yield* git(["diff", "--cached", "--raw", "-z", "--no-renames", "HEAD"], root));
+    return { tree, files: yield* Effect.forEach(staged, (one) => readStaged(root, one)) } satisfies Built;
+  }).pipe(Effect.ensuring(restore));
+});
+
+const treeEntry = Effect.fn("treeEntry")(function* (file: Read) {
+  if (file.kind === "deleted") return { path: file.path, mode: file.mode, type: "blob", sha: null };
+  const { sha } = yield* gitHubJson(decodeSha, "POST", `${REPOSITORY}/git/blobs`, { content: file.content, encoding: "base64" });
+  return { path: file.path, mode: file.mode, type: "blob", sha };
+});
+
+export const commitRelease = Effect.fn("commitRelease")(function* (root: string, head: string, built: Built, version: string) {
+  const tree = yield* Effect.forEach(built.files, treeEntry);
+  const baseTree = (yield* git(["rev-parse", `${head}^{tree}`], root)).trim();
+  const made = yield* gitHubJson(decodeSha, "POST", `${REPOSITORY}/git/trees`, { base_tree: baseTree, tree });
+  if (made.sha !== built.tree) return yield* refused(`GitHub built the tree ${made.sha}, but the build wrote ${built.tree}`);
+  const commit = { message: releaseTitle(version), tree: made.sha, parents: [head] };
+  return (yield* gitHubJson(decodeSha, "POST", `${REPOSITORY}/git/commits`, commit)).sha;
+});
+
+export const pointBranch = Effect.fn("pointBranch")(function* (branch: string, sha: string, exists: boolean) {
+  yield* exists
+    ? gitHubJson(decodeRef, "PATCH", `${REPOSITORY}/git/refs/heads/${branch}`, { sha, force: true })
+    : gitHubJson(decodeRef, "POST", `${REPOSITORY}/git/refs`, { ref: `refs/heads/${branch}`, sha });
+});