@trofimyukdev/repo-truth 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladimir Trofimyuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,274 @@
-# Temporary Holding Version
+# repo-truth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+repo-truth reads a range of git commits - `base..candidate`, the change a branch or a
+pull request makes - and reports the moves that make a repository look healthier than
+it is: a test skipped, focused or deleted, a coverage minimum lowered, a timeout
+raised, a workflow or a compiler setting loosened, a lint rule turned off, a
+credential or a secret file committed, a dependency from outside the registry, an
+action that is not pinned, a figure in the documentation with no command behind it.
+It is one command, `repo-truth check`, and a GitHub Action that runs it over a pull
+request.
+
+Each check answers with a record: its name, a status - `pass`, `fail` or `skip` - and
+evidence lines that name the file, the line or the commit. Each check reads the range
+through git and fails closed: a git call that fails is a `fail` record, never a `pass`.
+A revision that names no commit stops the command before any check runs, with exit 2.
+The exit code says whether any check failed.
+
+## Install
+
+Node.js 20 or newer, and git on the `PATH`.
+
+```sh
+npm install --save-dev @trofimyukdev/repo-truth
+```
+
+The package installs one command, `repo-truth`. In a project that installs it,
+`npx repo-truth` runs it. Outside one, name the package: the unscoped name
+`repo-truth` on npm is another project, so a bare `npx repo-truth` would fetch and
+run that one.
+
+```sh
+npm exec --package=@trofimyukdev/repo-truth -- repo-truth check --base origin/main --candidate HEAD
+```
+
+## Usage
+
+```sh
+repo-truth check --base <rev> --candidate <rev>
+repo-truth check --target <rev> --candidate <rev>
+repo-truth list
+repo-truth --help
+```
+
+`check` runs every registered check over `base..candidate` and prints one record per
+check, in the order `repo-truth list` prints the names.
+
+- `--base <rev>`: the range starts after this commit.
+- `--target <rev>`, in place of `--base`: the branch a pull request merges into. The
+  range then starts at the merge base of the target and the candidate, so commits that
+  reached the target after the branch forked are not charged to it. A missing merge
+  base is a refusal; in a shallow clone the message asks for `fetch-depth: 0`. When
+  `GITHUB_EVENT_NAME` is set, it must be `pull_request` or `pull_request_target`.
+- `--candidate <rev>`: the last commit of the range.
+- `--check <name>`, repeatable: run only the named checks.
+- `--except <name>`, repeatable: run every check but the named ones. It cannot be given
+  with `--check`, and it cannot name every check.
+- `--format text|json`: `json` prints one document instead of the text:
+  `"schema": "repo-truth.check/v1"`, the resolved `base` and `candidate`, `config`,
+  `ok`, `exitCode` and the `records`.
+- `--config <path>`: read the settings from this file instead of `repo-truth.json` at
+  the base commit (see Configuration).
+- `--no-fetch`: skip the `git fetch --all --quiet` the command otherwise runs before it
+  resolves either revision.
+
+The text form is one line per record, its status and its name, then its evidence lines
+indented, and a last line, `repo-truth: all checks passed` or
+`repo-truth: at least one check failed`. Text outside printable ASCII is printed as
+`\u{hex}`.
+
+The exit code is the contract. The header of `src/cli.ts` is the one place it is
+stated; in short:
+
+```text
+0  every check that ran passed or skipped
+1  at least one check failed
+2  bad invocation or unrunnable environment - an unknown option or check,
+   --except with --check or naming every check, a revision that names no
+   commit, a failed fetch, a configuration the command refuses; never a
+   check's finding
+```
+
+On exit 2 nothing is written to standard output and no check has run. `repo-truth list`
+answers 0 after printing the names, and 2 for any argument but `--help`.
+
+## GitHub Action
+
+The Action runs `repo-truth check` over the pull request that triggered it: `--target`
+is the pull request's base branch on `origin`, `--candidate` its head commit. It needs
+the whole history, so check out with `fetch-depth: 0`. It builds repo-truth from its
+own source with `npm ci && npm run build`, and it writes the records to the job
+summary.
+
+```yaml
+on: pull_request
+
+jobs:
+  repo-truth:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: trofimyukdev/repo-truth@v0.1.0
+        with:
+          except: RT-03
+```
+
+RT-03 fails a pull request whose head commit names no task in a `Task-Id` trailer.
+The example leaves it out; a repository that writes that trailer drops the `with:`
+block.
+
+Its inputs, all optional:
+
+- `checks`: names separated by white space or commas, each passed as `--check`.
+- `except`: names, each passed as `--except`. Not allowed together with `checks`.
+- `format`: `text` (the default) or `json`.
+- `config`: a path passed as `--config`. It is read from the checked-out tree, which in
+  a pull request is the pull request's own copy; the default, empty, reads
+  `repo-truth.json` at the merge base instead.
+- `base`: a revision passed as `--base`. The range is then from that revision to the
+  commit the run is for, on any event: a push, a merge queue, a scheduled or a manual
+  run. Empty keeps the pull request's range.
+
+A tag can be moved after you adopt it, and RT-88 below reports exactly that kind of
+reference. To hold the Action to one commit, write the full commit id the tag names
+in place of `v0.1.0`.
+
+## Configuration
+
+Options for the checks that take them live in `repo-truth.json` at the top of the
+repository. It is read from the base commit through git, not from the working tree or
+the candidate, so a range is judged by the settings it started from; RT-66 fails a
+range that changes the file. `--config <path>` reads another file instead.
+
+```json
+{
+  "schema": "repo-truth.config/v1",
+  "checks": {
+    "RT-57": { "forbidden": ["migrations/**", ".github/CODEOWNERS"] },
+    "RT-88": { "allowedOwners": ["actions"] }
+  }
+}
+```
+
+A missing or wrong `schema`, a key other than `schema` and `checks`, a check the
+registry does not hold, an option the check does not declare or a value of the wrong
+kind is a refusal, exit 2, naming each issue. The options:
+
+- `RT-12` `maxBytes` (integer): the largest blob the range may bring in.
+- `RT-18` `registries` (strings): the registries a dependency may come from.
+- `RT-19` `timeoutMs` (integer): how long one replayed command may run.
+- `RT-55` `allowedSuffixes` (strings): binary files whose names end so are not reported.
+- `RT-57` `forbidden` and `allowed` (strings): path patterns. `?` is one character but
+  `/`, `*` is any run but `/`, and a segment that is exactly `**` is any number of
+  whole segments.
+- `RT-88` `allowedOwners` (strings): action owners whose references need no pin.
+
+Many findings are for a human to accept rather than to fix. Eighteen checks accept a
+sanction: RT-04, RT-14, RT-16, RT-24, RT-31, RT-33, RT-34, RT-55, RT-56, RT-57, RT-66,
+RT-87, RT-88, RT-89, RT-91, RT-92, RT-93 and RT-94. A line
+`Sanctioned-Weakening: <id> <reason>` in a commit message of the range accepts the
+finding with that id, and the record then shows the reason. The header comment of
+each check's module states the form of its ids: `<category>:<file>` for some,
+`<category>:<file>:<line>` for others such as RT-04, RT-24 and RT-31. RT-04's id opens
+its evidence line, as in `skip:test/math.test.js:4`; other checks print the same parts
+in another order, as `<file>: <category>`, so the id is not always the evidence line's
+first word. The other thirteen checks have no sanction: the fix is to change the range.
+
+## Checks
+
+There are 31 checks in version 0.1.0: `repo-truth list | wc -l` printed 31 on
+2026-11-02, run from the package as it was packed for this release. In the order
+they run:
+
+- `RT-01` commit hygiene: the message and both identities of every commit hold only
+  printable ASCII and tab.
+- `RT-02` measurement rule: a figure with a unit, in a commit body or in a line the
+  range adds to a `.md` file, has a command (a code span or a fenced block) and an ISO
+  date in the same paragraph or commit body.
+- `RT-03` trailer: the candidate commit names the task it closes in a `Task-Id` or a
+  `Millwright-Task-ID` trailer.
+- `RT-04` weakened tests: no skip or focus marker added, no test file, test or
+  assertion removed.
+- `RT-05` stray files: no added path is a log, an editor backup, a set-aside copy, a
+  scratch script, coverage or build output, OS metadata, or a path the repository's
+  own ignore rules exclude.
+- `RT-06` lockfile drift: the dependency fields of `package.json` and the root
+  lockfile change together.
+- `RT-09` conflict markers: no added line is a leftover merge conflict marker.
+- `RT-10` portable paths: no new name differs from another only in letter case, is a
+  Windows device name, ends in a dot or a space, or holds a character Windows forbids.
+- `RT-11` symlinks: no added or changed link points at an absolute path, outside the
+  repository, or into `.git`.
+- `RT-12` large blobs: no blob the range brings into the history is larger than
+  `maxBytes`, counting blobs the candidate's tree no longer holds.
+- `RT-14` lowered thresholds: no coverage minimum goes down or goes away.
+- `RT-16` snapshot refreshes: every snapshot the range rewrites or deletes, and whether
+  the commit that did it also changed a file that is neither a snapshot nor a test.
+- `RT-18` dependency sources: every added dependency comes from a registry, not a git
+  URL, a tarball URL, a path or an alias.
+- `RT-19` replayed figures: a figure written as a git command in a code span, the word
+  `printed` and the output in a code span is run again when it is a read-only git
+  command the check knows how to replay, and a different output fails; any other
+  command is counted as not replayable.
+- `RT-88` unpinned actions: every `uses:` the range adds to a workflow or an
+  `action.yml` names a full commit id, a digest or a local path.
+- `RT-29` autosquash leftovers: no commit subject begins `fixup! `, `squash! ` or
+  `amend! `.
+- `RT-93` bidirectional controls: no file the range touches gains one of the nine
+  Unicode controls that reorder how a line is shown ("Trojan Source").
+- `RT-55` binary files: no file the range adds or changes is binary by git's own test.
+- `RT-66` configuration changed: the range does not add, change, delete or rename the
+  file the run's settings were read from.
+- `RT-26` credentials: no added line holds a credential in a form only a real one has;
+  the finding names the file, the line and the kind, never the text.
+- `RT-94` install scripts: no package the range adds to an npm lockfile runs an install
+  script.
+- `RT-92` lint rules: no rule is set to `off` or `0` in an ESLint, Biome or oxlint
+  configuration file. A rule set to `warn` or deleted, and a rule turned off through
+  `extends`, are not seen.
+- `RT-57` path policy: no changed path is one the repository's `forbidden` patterns
+  name, or outside its `allowed` ones.
+- `RT-24` raised timeouts: no timeout in a test file or the runner's configuration goes
+  up, and none is added to a file the base already holds.
+- `RT-33` ladder commands: every entry of `scripts` in a `package.json` that the range
+  adds, removes or changes is reported for a human to sanction.
+- `RT-89` secret files: no added or changed file is named like one that holds secrets
+  by what it is - `.env`, `.netrc`, a private key, a Terraform state.
+- `RT-34` compiler strictness: no strict option of a tsconfig loses its strict value,
+  and `extends` does not change.
+- `RT-87` submodules: no submodule is added or moved, and `.gitmodules` gains no `url`.
+- `RT-31` suppression directives: every suppression comment the range adds without
+  removing one like it from the same file.
+- `RT-91` workflow permissions: no workflow line gives the job's token write access or
+  runs the workflow on `pull_request_target`.
+- `RT-56` weakened workflows: no workflow is removed, and no workflow gains a line of a
+  weakening shape.
+
+Each check is also an async function in the package's `dist/` directory: it takes
+`{ cwd, base, candidate }` and resolves to a record of the same shape.
+
+## Known limitations
+
+- RT-04 reads a test renamed in its file - `test("adds")` becoming
+  `test("adds two numbers")` - as a test removed, a `test-removed` finding to
+  sanction. A test file renamed with its content unchanged is no finding.
+- RT-06 reads any change to the root lockfile with no change to a dependency field of
+  `package.json` as an unrequested change, even one that only renames the package or
+  changes its version at the top of the lockfile.
+- There is no `--version`: `repo-truth --version` is an unknown command, exit 2. The
+  installed version is in the package's `package.json`.
+- The package declares no main entry, so `import "@trofimyukdev/repo-truth"` fails; a
+  module is imported by its path, `@trofimyukdev/repo-truth/dist/<module>.js`.
+- The workflow checks (RT-56, RT-88, RT-91) read workflow files as lines of text; the
+  YAML is not parsed.
+
+## How it is built
+
+repo-truth's checks are built by Millwright, an autonomous coding factory, each from
+a task in `factory/tasks/` (https://github.com/trofimyukdev/autonomous-coding-factory).
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npx vitest run
+npm run build
+node --test test/e2e/cli.e2e.mjs
+```
+
+The last line runs the end-to-end suite against the built command.
+
+License: MIT

package/dist/action.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Range resolution for a pull request.
+ *
+ * A pull request's range is `merge-base(target, candidate)..candidate`, never
+ * `target..candidate`: commits that landed on the target after the branch
+ * forked are not the pull request's, and a rebased branch must not be charged
+ * for them. The merge base is also what a default shallow checkout lacks, so
+ * its absence is a stated failure, never an empty range that passes.
+ */
+import type { CliIo } from "./cli.js";
+/** The range cannot be resolved; the command maps this to its bad-invocation code. */
+export declare class RangeResolutionError extends Error {
+}
+/** Events whose range is a pull request's. Every other event has no `--target` rule. */
+export declare const PULL_REQUEST_EVENTS: readonly string[];
+/**
+ * Refuse `--target` for an event that is not a pull request. An unset event
+ * name (a local run) is allowed.
+ */
+export declare function assertPullRequestEvent(eventName: string | undefined): void;
+/**
+ * The merge base of two commits, as `git merge-base <target> <candidate>`
+ * prints it. Throws `RangeResolutionError` naming the missing history and the
+ * fetch depth needed when there is none.
+ */
+export declare function resolveMergeBase(cwd: string, target: string, candidate: string): Promise<string>;
+/**
+ * The command's arguments for the Action: `argv` as given, then one
+ * `--check <name>` per name in `env.REPO_TRUTH_CHECKS` (split at white space and
+ * commas), then one `--except <name>` per name in `env.REPO_TRUTH_EXCEPT` (split
+ * the same way), then `--format <format>` when `env.REPO_TRUTH_FORMAT` is set, then
+ * `--config <path>` when `env.REPO_TRUTH_CONFIG` is set and not empty. The range
+ * comes right after `argv`: `--base <env.REPO_TRUTH_BASE>` and `--candidate
+ * <env.GITHUB_SHA>` (`HEAD` when unset or empty) when `env.REPO_TRUTH_BASE` is set
+ * and not empty; else `--target <env.REPO_TRUTH_TARGET>` and `--candidate
+ * <env.REPO_TRUTH_CANDIDATE>` when `env.REPO_TRUTH_TARGET` is set; else none. Nothing
+ * is run, expanded or matched: every name, and the path, is one argument, as
+ * written.
+ */
+export declare function actionArguments(argv: readonly string[], env: Readonly<Record<string, string | undefined>>): string[];
+/**
+ * The job summary of a run: a heading, the outcome in one sentence, and the
+ * output whole in one fenced block whose fence is longer than any run of
+ * backticks the output holds, so no text of it closes or opens a block.
+ */
+export declare function jobSummary(exitCode: number, output: string): string;
+/**
+ * What the Action's program does: run the command with the Action's
+ * arguments, pass its output on, and append the job summary to the file
+ * `env.GITHUB_STEP_SUMMARY` names, if any. Resolves to the command's exit code.
+ */
+export declare function runAction(argv: readonly string[], env: Readonly<Record<string, string | undefined>>, io?: CliIo): Promise<number>;

package/dist/action.js

@@ -0,0 +1,182 @@
+/**
+ * Range resolution for a pull request.
+ *
+ * A pull request's range is `merge-base(target, candidate)..candidate`, never
+ * `target..candidate`: commits that landed on the target after the branch
+ * forked are not the pull request's, and a rebased branch must not be charged
+ * for them. The merge base is also what a default shallow checkout lacks, so
+ * its absence is a stated failure, never an empty range that passes.
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The range cannot be resolved; the command maps this to its bad-invocation code. */
+export class RangeResolutionError extends Error {
+}
+/** Events whose range is a pull request's. Every other event has no `--target` rule. */
+export const PULL_REQUEST_EVENTS = ["pull_request", "pull_request_target"];
+/**
+ * Refuse `--target` for an event that is not a pull request. An unset event
+ * name (a local run) is allowed.
+ */
+export function assertPullRequestEvent(eventName) {
+    if (eventName === undefined || eventName === "")
+        return;
+    if (!PULL_REQUEST_EVENTS.includes(eventName)) {
+        throw new RangeResolutionError(`--target resolves a pull request's range, but this run is a ${JSON.stringify(eventName)} event; ` +
+            `name the range with --base instead`);
+    }
+}
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+            const code = error ? (typeof error.code === "number" ? error.code : 128) : 0;
+            resolve({ code, stdout, stderr: stderr.trim() || (error ? error.message : "") });
+        });
+    });
+}
+/**
+ * The merge base of two commits, as `git merge-base <target> <candidate>`
+ * prints it. Throws `RangeResolutionError` naming the missing history and the
+ * fetch depth needed when there is none.
+ */
+export async function resolveMergeBase(cwd, target, candidate) {
+    const result = await git(cwd, ["merge-base", target, candidate]);
+    const base = result.stdout.trim().split("\n")[0] ?? "";
+    if (result.code === 0 && base.length > 0)
+        return base;
+    const shallow = (await git(cwd, ["rev-parse", "--is-shallow-repository"])).stdout.trim() === "true";
+    if (shallow) {
+        throw new RangeResolutionError(`the merge base of ${target} and ${candidate} is missing: this checkout is shallow and does not contain ` +
+            `the history that joins them. Check out with \`fetch-depth: 0\` (the actions/checkout input) so the full history is fetched`);
+    }
+    if (result.code === 1) {
+        throw new RangeResolutionError(`the merge base of ${target} and ${candidate} is missing: the two share no history. ` +
+            `If the checkout is partial, check out with \`fetch-depth: 0\` (the actions/checkout input)`);
+    }
+    throw new RangeResolutionError(`could not compute the merge base of ${target} and ${candidate}: ${result.stderr}`);
+}
+/**
+ * The command's arguments for the Action: `argv` as given, then one
+ * `--check <name>` per name in `env.REPO_TRUTH_CHECKS` (split at white space and
+ * commas), then one `--except <name>` per name in `env.REPO_TRUTH_EXCEPT` (split
+ * the same way), then `--format <format>` when `env.REPO_TRUTH_FORMAT` is set, then
+ * `--config <path>` when `env.REPO_TRUTH_CONFIG` is set and not empty. The range
+ * comes right after `argv`: `--base <env.REPO_TRUTH_BASE>` and `--candidate
+ * <env.GITHUB_SHA>` (`HEAD` when unset or empty) when `env.REPO_TRUTH_BASE` is set
+ * and not empty; else `--target <env.REPO_TRUTH_TARGET>` and `--candidate
+ * <env.REPO_TRUTH_CANDIDATE>` when `env.REPO_TRUTH_TARGET` is set; else none. Nothing
+ * is run, expanded or matched: every name, and the path, is one argument, as
+ * written.
+ */
+export function actionArguments(argv, env) {
+    const out = [...argv];
+    const base = env.REPO_TRUTH_BASE;
+    const sha = env.GITHUB_SHA;
+    if (base !== undefined && base !== "") {
+        out.push("--base", base, "--candidate", sha !== undefined && sha !== "" ? sha : "HEAD");
+    }
+    else if (env.REPO_TRUTH_TARGET !== undefined) {
+        out.push("--target", env.REPO_TRUTH_TARGET, "--candidate", env.REPO_TRUTH_CANDIDATE ?? "");
+    }
+    for (const name of (env.REPO_TRUTH_CHECKS ?? "").split(/[\s,]+/)) {
+        if (name !== "")
+            out.push("--check", name);
+    }
+    for (const name of (env.REPO_TRUTH_EXCEPT ?? "").split(/[\s,]+/)) {
+        if (name !== "")
+            out.push("--except", name);
+    }
+    const format = env.REPO_TRUTH_FORMAT;
+    if (format !== undefined && format !== "")
+        out.push("--format", format);
+    const config = env.REPO_TRUTH_CONFIG;
+    if (config !== undefined && config !== "")
+        out.push("--config", config);
+    return out;
+}
+function isActionEntryPoint() {
+    const script = process.argv[1];
+    if (!script)
+        return false;
+    try {
+        return realpathSync(script) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+const OUTCOMES = {
+    0: "All checks passed (exit code 0).",
+    1: "At least one check failed (exit code 1).",
+    2: "The checks did not run (exit code 2).",
+};
+/**
+ * The job summary of a run: a heading, the outcome in one sentence, and the
+ * output whole in one fenced block whose fence is longer than any run of
+ * backticks the output holds, so no text of it closes or opens a block.
+ */
+export function jobSummary(exitCode, output) {
+    const sentence = OUTCOMES[exitCode] ?? `The run ended with exit code ${exitCode}.`;
+    const body = output.endsWith("\n") ? output.slice(0, -1) : output;
+    const longest = Math.max(0, ...(output.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(Math.max(3, longest + 1));
+    return `## repo-truth\n\n${sentence}\n\n${fence}\n${body === "" ? "" : body + "\n"}${fence}\n`;
+}
+/**
+ * What the Action's program does: run the command with the Action's
+ * arguments, pass its output on, and append the job summary to the file
+ * `env.GITHUB_STEP_SUMMARY` names, if any. Resolves to the command's exit code.
+ */
+export async function runAction(argv, env, io = {}) {
+    const { main } = await import("./cli.js");
+    let stdout = "";
+    let stderr = "";
+    const toStderr = (text) => {
+        if (io.stderr)
+            io.stderr(text);
+        else
+            process.stderr.write(text);
+    };
+    const code = await main(actionArguments(argv, env), {
+        ...io,
+        stdout: (text) => {
+            stdout += text;
+            if (io.stdout)
+                io.stdout(text);
+            else
+                process.stdout.write(text);
+        },
+        stderr: (text) => {
+            stderr += text;
+            toStderr(text);
+        },
+    });
+    const file = env.GITHUB_STEP_SUMMARY;
+    if (file !== undefined && file !== "") {
+        try {
+            const held = existsSync(file) ? readFileSync(file, "utf8") : "";
+            const lead = held !== "" && !held.endsWith("\n") ? "\n" : "";
+            appendFileSync(file, lead + jobSummary(code, code === 2 ? stderr : stdout));
+        }
+        catch (error) {
+            const reason = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ");
+            toStderr(`repo-truth: could not write the job summary: ${reason}\n`);
+        }
+    }
+    return code;
+}
+// cli.ts imports this module, so `main` is reached only by a dynamic import
+// made after this module has finished loading.
+if (isActionEntryPoint()) {
+    void (async () => {
+        try {
+            process.exitCode = await runAction(process.argv.slice(2), process.env);
+        }
+        catch (error) {
+            process.stderr.write(`repo-truth: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 2;
+        }
+    })();
+}
+//# sourceMappingURL=action.js.map

package/dist/action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"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"}

package/dist/checks/action-pins.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Unpinned actions.
+ *
+ * A `uses: owner/repo@v4` runs whatever commit the tag names on the day the job
+ * runs, with the job's token and secrets. This check reads, whole and through
+ * git at the merge base of `base` and `candidate` and at `candidate` (never the
+ * working tree), every workflow file the range adds, changes or renames onto -
+ * `.github/workflows/<name>.yml` or `.yaml` directly in that directory - and
+ * every file named `action.yml` or `action.yaml` at any depth.
+ *
+ * The YAML is not parsed. A `uses:` line is a line whose text, white space at
+ * both ends removed, opens `uses:` or `- uses:`; its value is the rest of the
+ * line with a trailing comment (a `#` after white space) removed, then white
+ * space at both ends, then one pair of matching surrounding quotes. A line is
+ * added when the candidate's file holds its text more often than its source
+ * file (the file at the merge base, the one a rename came from, or none) did;
+ * a line moved or re-indented is not, and a text added more than once is one
+ * finding.
+ *
+ * Pinned: a local reference (opening `./`), a `docker://` image by digest
+ * (`@sha256:` and sixty-four hexadecimal digits), and a repository reference
+ * `<owner>/<repo>[/<path>]@<commit>` whose commit is exactly forty hexadecimal
+ * digits. Every other value - a tag, a branch, no `@`, a short commit id, a
+ * `docker://` image by tag - is unpinned and is a finding `unpinned-action`.
+ *
+ * The option `allowedOwners` (strings): a repository reference whose owner, the
+ * text before its first `/`, is one of them, compared exactly, yields no
+ * finding. `docker://` and local references are judged as above regardless.
+ *
+ * A finding's id is `unpinned-action:<file>`; it is sanctioned by a
+ * `Sanctioned-Weakening: <id> <reason>` line in a commit message of the range
+ * or by the caller's `sanctions`.
+ */
+import type { CheckRecord } from "../index.js";
+export declare const name = "RT-88";
+export declare const optionKinds: {
+    allowedOwners: string;
+};
+export interface ActionPinsOptions {
+    readonly cwd: string;
+    readonly base: string;
+    readonly candidate: string;
+    readonly allowedOwners?: readonly string[] | undefined;
+    /** Ids (`unpinned-action:<file>`) mapped to reasons. */
+    readonly sanctions?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Report each unpinned `uses:` reference `base..candidate` adds. Fails while any
+ * finding is unsanctioned, and fails closed: a revision that names no commit,
+ * or any git invocation that fails, is a `fail` record naming the cause.
+ */
+export declare function check(options: ActionPinsOptions): Promise<CheckRecord>;