@ploaness/governance 1.0.0

package/dist/commit-message.js

@@ -0,0 +1,144 @@
+// Pure commit-message logic, kept out of the `commit-history` gate in packages/cli/src/checks/history.ts
+// so it can be unit- and coverage-tested without a fixture repository (that gate keeps all I/O). It enforces
+// Conventional Commits headers, subject quality, the shared AI-typography ban, the AI-agent
+// attribution ban (no co-author trailer, session id, or generated-by signature naming an agent), and a
+// mandatory body explaining WHY for non-trivial changes (>2 files or >50 changed lines).
+import { findAgentReferences } from './agent-references.js';
+import { findTypographyViolations } from './banned-typography.js';
+// The governing standard's own list, in its own order. `revert` is deliberately absent: git writes a
+// revert commit with a `Revert "..."` subject, and the standard requires that subject be replaced by a
+// conforming one by hand rather than given a type of its own.
+const TYPES = [
+    'build',
+    'chore',
+    'ci',
+    'docs',
+    'feat',
+    'fix',
+    'perf',
+    'refactor',
+    'test',
+];
+const TYPES_LABEL = TYPES.join(', ');
+// Built from TYPES rather than written out again. The two were separate literals, and they drifted:
+// the alternation is what actually decided a verdict, so a type removed from the list above stayed
+// accepted here. A pattern derived from the list cannot disagree with it.
+const HEADER_PATTERN = new RegExp(String.raw `^(?:${TYPES.join('|')})(?:\([a-z0-9-]+\))?: .+$`);
+// The standard says the subject "contains none of these words", so the match is unanchored. It was
+// anchored to the first word, which accepted `fix: clear the tmp directory` - a subject the standard
+// rejects. The list is the standard's own; `update` and `change` are not on it and are not added,
+// because unanchored they would reject a legitimate `chore(deps): update the pinned biome version`.
+const JUNK_DESCRIPTION = /\b(?:wip|tmp|temp|misc|stuff|asdf|fixup)\b/i;
+// What separates the type (and optional scope) from the subject.
+const HEADER_SEPARATOR = ': ';
+// A numstat row reports added and deleted counts before the path.
+const NUMSTAT_COLUMNS = 2;
+const MAX_HEADER_LENGTH = 72;
+const MIN_DESCRIPTION_LENGTH = 15;
+const MAX_TRIVIAL_FILES = 2;
+const MAX_TRIVIAL_LINES = 50;
+const SCISSORS = '# ------------------------ >8 ------------------------';
+/**
+ * Splits a raw commit message into header and body, dropping git comment lines and any verbose-diff
+ * section below the scissors marker.
+ * @param raw the full commit-message file contents.
+ * @returns the first non-blank line as `header` and the remaining prose as `body` (both may be empty).
+ */
+export const parseMessage = (raw) => {
+    // Line endings are normalised before anything reads a line. `HEADER_PATTERN` ends in `.+$` with no
+    // `m` flag, and `.` does not cross a `\r`, so on a machine with `core.autocrlf=true` every commit was
+    // rejected as an invalid header - naming the header pattern rather than the one character that
+    // actually differed. The trailing-period check was defeated by the same `\r`.
+    const lines = (raw.replaceAll('\r\n', '\n').split(SCISSORS)[0] ?? '')
+        .split('\n')
+        .filter((line) => !line.startsWith('#'));
+    const headerIndex = lines.findIndex((line) => line.trim().length > 0);
+    if (headerIndex === -1) {
+        return { header: '', body: '' };
+    }
+    return {
+        header: lines[headerIndex] ?? '',
+        body: lines
+            .slice(headerIndex + 1)
+            .join('\n')
+            .trim(),
+    };
+};
+const descriptionOf = (header) => {
+    const marker = header.indexOf(HEADER_SEPARATOR);
+    return marker === -1 ? header : header.slice(marker + HEADER_SEPARATOR.length);
+};
+const validateHeaderFormat = (header) => HEADER_PATTERN.test(header)
+    ? []
+    : [
+        `invalid header "${header}": expected "<type>(<scope>): <description>", type one of ${TYPES_LABEL}`,
+    ];
+const SUBJECT_RULES = [
+    (header) => header.length > MAX_HEADER_LENGTH
+        ? `header is ${String(header.length)} chars; keep it at most ${String(MAX_HEADER_LENGTH)}`
+        : undefined,
+    (header) => header.endsWith('.') ? 'header must not end with a period' : undefined,
+    (_header, description) => description.length < MIN_DESCRIPTION_LENGTH
+        ? `description "${description}" is too short; be specific (>= ${String(MIN_DESCRIPTION_LENGTH)} chars)`
+        : undefined,
+    (_header, description) => JUNK_DESCRIPTION.test(description)
+        ? `description "${description}" looks low-effort; describe the actual change`
+        : undefined,
+];
+const validateSubjectQuality = (header) => {
+    const description = descriptionOf(header);
+    return SUBJECT_RULES.flatMap((rule) => {
+        const problem = rule(header, description);
+        return problem === undefined ? [] : [problem];
+    });
+};
+const validateBody = (body, isBodyRequired) => isBodyRequired && body.length === 0
+    ? [
+        `change touches >${String(MAX_TRIVIAL_FILES)} files or >${String(MAX_TRIVIAL_LINES)} lines; ` +
+            'add a body (blank line then prose) explaining WHY',
+    ]
+    : [];
+const typographyProblems = (message) => findTypographyViolations(`${message.header}\n${message.body}`).map((found) => `banned ${found.label} (line ${String(found.line)}); use ${found.replacement}`);
+const agentReferenceProblems = (message) => findAgentReferences(`${message.header}\n${message.body}`).map((found) => `references an AI agent or its session (${found.label}, line ${String(found.line)}); a commit must ` +
+    'not attribute the change to an agent, so remove the trailer/signature');
+/**
+ * Validates a parsed commit message, returning a human-readable problem per rule violation. Every
+ * commit is held to every rule: there is no exemption list, so a git-generated merge, revert, or
+ * autosquash subject must be rewritten by hand to conform.
+ * @param message the header/body pair from {@link parseMessage}.
+ * @param isBodyRequired whether the change is non-trivial and therefore must carry an explanatory body.
+ * @returns an empty array when the message passes.
+ */
+export const validateMessage = (message, isBodyRequired) => [
+    ...validateHeaderFormat(message.header),
+    ...validateSubjectQuality(message.header),
+    ...validateBody(message.body, isBodyRequired),
+    ...typographyProblems(message),
+    ...agentReferenceProblems(message),
+];
+const toCount = (raw) => {
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Parses `git --numstat` output into a file count and a total changed-line count.
+ * @param numstat the raw stdout of a `--numstat` diff (tab-separated added/deleted/path rows).
+ * @returns the number of changed files and the sum of added plus deleted lines (binary rows count 0).
+ */
+export const parseNumstat = (numstat) => {
+    const rows = numstat
+        .split('\n')
+        .filter((row) => row.length > 0);
+    const lines = rows.reduce((total, row) => {
+        const [added, deleted] = row.split('\t', NUMSTAT_COLUMNS);
+        return total + toCount(added) + toCount(deleted);
+    }, 0);
+    return { files: rows.length, lines };
+};
+/**
+ * Decides whether a diff is large enough to require an explanatory commit body.
+ * @param stat the file and line counts from {@link parseNumstat}.
+ * @returns true when the change touches more than 2 files or more than 50 lines.
+ */
+export const isNonTrivial = (stat) => stat.files > MAX_TRIVIAL_FILES || stat.lines > MAX_TRIVIAL_LINES;
+//# sourceMappingURL=commit-message.js.map

package/dist/commit-message.js.map

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

package/dist/config-references.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extract the concrete, existence-checkable source paths a config file references. Returns each unique
+ * path (sorted for deterministic output) with any leading `!` negation stripped; glob/regex patterns
+ * and non-source tokens are excluded.
+ */
+export declare const extractLiteralSourcePaths: (content: string) => readonly string[];
+/** A config path reference that no longer resolves to a real file. */
+export interface ConfigReferenceViolation {
+    readonly path: string;
+    readonly reason: string;
+}
+/**
+ * Return every extracted path that does not exist, with `isExistingFile` injected so the core stays pure. An
+ * empty array means every source file the config carves out is still present.
+ */
+export declare const findMissingConfigReferences: (paths: readonly string[], isExistingFile: (relativePath: string) => boolean) => readonly ConfigReferenceViolation[];
+//# sourceMappingURL=config-references.d.ts.map

package/dist/config-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-references.d.ts","sourceRoot":"","sources":["../src/config-references.ts"],"names":[],"mappings":"AAsCA;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,MAAM,KAAG,SAAS,MAAM,EAU1E,CAAA;AAED,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GACtC,OAAO,SAAS,MAAM,EAAE,EACxB,gBAAgB,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,KAChD,SAAS,wBAAwB,EAQ/B,CAAA"}

package/dist/config-references.js

@@ -0,0 +1,54 @@
+// Config-reference integrity policy: the pure logic that finds LITERAL source-file paths carved out of
+// (or into) a tool config - a Biome `includes`, an ESLint `ignores`, a Vitest `coverageExclude` - that
+// no longer exist on disk. The `config-refs` gate in packages/cli/src/checks/references.ts reads the
+// config files and probes the filesystem.
+//
+// This is the sibling of the doc-rot gate (document-references.ts), applied to configs instead of docs,
+// and chosen to be HIGH-SIGNAL and false-positive-free. A quoted token is only checked when it is
+// unambiguously a concrete project file: it starts with a known source directory (`src/`, `tests/`,
+// `scripts/`, `public/`), carries a file extension, and contains NO glob or regex metacharacter. Globs
+// (`src/**/*.tsx`), path regexes (`^src/lib/`), and bare tokens are deliberately ignored, because a
+// config legitimately uses those and existence-checking them would make the gate lie. A leading `!`
+// (Biome negation) is stripped before the path is returned.
+// The directories a carve-out may name. `DEFAULT_SOURCE_ROOTS` is imported rather than restated - the
+// three names were written out here as a second alternation, so a change to either list left the other
+// describing a project that no longer exists. `public` is added on top because a config legitimately
+// carves out a static asset, and no source root claims that directory.
+const CARVE_OUT_DIRECTORIES = [...DEFAULT_SOURCE_ROOTS, 'public'];
+import { DEFAULT_SOURCE_ROOTS } from './settings.js';
+import { escapeForRegex } from './text-escapes.js';
+// A quoted string whose content, after an optional leading `!`, starts with one of those directories and
+// ends with a file extension. The three quote styles cover JSON (`"`) and JS/TS config literals
+// (`'`, `` ` ``).
+const CARVE_OUT_ALTERNATION = CARVE_OUT_DIRECTORIES.map((directory) => escapeForRegex(directory)).join('|');
+const LITERAL_SOURCE_PATH = new RegExp(String.raw `(['"\`])(!?(?:${CARVE_OUT_ALTERNATION})/[^'"\`\n]*?\.[A-Za-z0-9]+)\1`, 'g');
+// Glob and regex metacharacters. A token carrying any of these is a pattern, not a concrete path, so it
+// cannot be existence-checked and is dropped.
+const METACHARACTER = /[*?[\]{}()|^$\\+]/;
+/**
+ * Extract the concrete, existence-checkable source paths a config file references. Returns each unique
+ * path (sorted for deterministic output) with any leading `!` negation stripped; glob/regex patterns
+ * and non-source tokens are excluded.
+ */
+export const extractLiteralSourcePaths = (content) => {
+    const candidates = [...content.matchAll(LITERAL_SOURCE_PATH)]
+        // The second group is the quoted body, which the pattern always captures when it matches. The
+        // conversion is written out rather than guarded, because a guard here would describe a case that
+        // cannot occur and would report as an untested branch forever.
+        .map((match) => String(match[2]))
+        .map((token) => (token.startsWith('!') ? token.slice(1) : token))
+        .filter((candidate) => !METACHARACTER.test(candidate));
+    const paths = new Set(candidates);
+    return [...paths].sort((left, right) => left.localeCompare(right));
+};
+/**
+ * Return every extracted path that does not exist, with `isExistingFile` injected so the core stays pure. An
+ * empty array means every source file the config carves out is still present.
+ */
+export const findMissingConfigReferences = (paths, isExistingFile) => paths
+    .filter((path) => !isExistingFile(path))
+    .map((path) => ({
+    path,
+    reason: 'carved out of a tool config but the file does not exist',
+}));
+//# sourceMappingURL=config-references.js.map

package/dist/config-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-references.js","sourceRoot":"","sources":["../src/config-references.ts"],"names":[],"mappings":"AAAA,uGAAuG;AACvG,uGAAuG;AACvG,qGAAqG;AACrG,0CAA0C;AAC1C,EAAE;AACF,wGAAwG;AACxG,kGAAkG;AAClG,oGAAoG;AACpG,uGAAuG;AACvG,oGAAoG;AACpG,oGAAoG;AACpG,4DAA4D;AAE5D,sGAAsG;AACtG,uGAAuG;AACvG,qGAAqG;AACrG,uEAAuE;AACvE,MAAM,qBAAqB,GAAsB,CAAC,GAAG,oBAAoB,EAAE,QAAQ,CAAC,CAAA;AAEpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElD,yGAAyG;AACzG,gGAAgG;AAChG,kBAAkB;AAClB,MAAM,qBAAqB,GAAW,qBAAqB,CAAC,GAAG,CAAC,CAAC,SAAiB,EAAU,EAAE,CAC5F,cAAc,CAAC,SAAS,CAAC,CAC1B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAEX,MAAM,mBAAmB,GAAW,IAAI,MAAM,CAC5C,MAAM,CAAC,GAAG,CAAA,iBAAiB,qBAAqB,gCAAgC,EAChF,GAAG,CACJ,CAAA;AAED,wGAAwG;AACxG,8CAA8C;AAC9C,MAAM,aAAa,GAAW,mBAAmB,CAAA;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,OAAe,EAAqB,EAAE;IAC9E,MAAM,UAAU,GAAsB,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;QAC9E,8FAA8F;QAC9F,iGAAiG;QACjG,+DAA+D;SAC9D,GAAG,CAAC,CAAC,KAAsB,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;SACzD,GAAG,CAAC,CAAC,KAAa,EAAU,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SAChF,MAAM,CAAC,CAAC,SAAiB,EAAW,EAAE,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;IACzE,MAAM,KAAK,GAAwB,IAAI,GAAG,CAAS,UAAU,CAAC,CAAA;IAC9D,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;AAC5F,CAAC,CAAA;AAQD;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,KAAwB,EACxB,cAAiD,EACZ,EAAE,CACvC,KAAK;KACF,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;KACxD,GAAG,CACF,CAAC,IAAY,EAA4B,EAAE,CAAC,CAAC;IAC3C,IAAI;IACJ,MAAM,EAAE,yDAAyD;CAClE,CAAC,CACH,CAAA"}

package/dist/container-failure.d.ts

@@ -0,0 +1,40 @@
+/** One finished invocation, reduced to what a classifier reads. */
+export interface ContainerRun {
+    readonly code: number;
+    readonly output: string;
+}
+/** Which failure of the container toolchain a gate hit. */
+export type DockerFailureKind = 'absent' | 'daemonDown' | 'rateLimited' | 'unreachable' | 'manifestUnknown' | 'unstartable';
+/** A failure of Docker itself, worded for the gate that hit it. */
+export interface DockerFailure {
+    readonly kind: DockerFailureKind;
+    readonly summary: string;
+    readonly remedies: readonly string[];
+}
+/** The exit code a shell reports for a command it cannot find. */
+export declare const COMMAND_NOT_FOUND: number;
+/**
+ * Classify a failure of `docker image inspect` or `docker pull`.
+ *
+ * Safe to read the output here, and only here: the command is docker's own and every byte it wrote is
+ * docker's. Acquiring the image as a step of its own is what creates that guarantee - it moves "the
+ * analyzer could not run" onto a different command from "the analyzer found something", so the two stop
+ * being one exit code read two ways.
+ * @param gate the gate's name, opening the sentence the summary completes.
+ * @param invocation the finished `docker` invocation.
+ * @returns the failure, or undefined when the image was acquired.
+ */
+export declare const classifyImageFailure: (gate: string, invocation: ContainerRun) => DockerFailure | undefined;
+/**
+ * Classify a failure of a run whose output the project may have authored.
+ *
+ * Exit code only. gitleaks prints the commit it found a secret in, hadolint prints the Dockerfile line,
+ * actionlint prints the workflow step - so a marker matched against that output would let a commit
+ * message decide whether a real finding is reported, which is the same defect one level deeper. The codes
+ * `docker run` reserves for itself carry no such ambiguity.
+ * @param gate the gate's name, opening the sentence the summary completes.
+ * @param invocation the finished `docker run` or shell invocation.
+ * @returns the failure, or undefined when the exit code is the tool's own verdict.
+ */
+export declare const classifyContainerExit: (gate: string, invocation: ContainerRun) => DockerFailure | undefined;
+//# sourceMappingURL=container-failure.d.ts.map

package/dist/container-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-failure.d.ts","sourceRoot":"","sources":["../src/container-failure.ts"],"names":[],"mappings":"AAmBA,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,YAAY,GACZ,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,aAAa,CAAA;AAEjB,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,MAAY,CAAA;AAyG5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,YAAY,YAAY,KACvB,aAAa,GAAG,SAalB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,YAAY,YAAY,KACvB,aAAa,GAAG,SAOlB,CAAA"}

package/dist/container-failure.js

@@ -0,0 +1,154 @@
+// Why a containerised gate failed, told apart from what its analyzer reported.
+//
+// `docker run` passes the container's own exit code through, so a gate that reads every non-zero exit as
+// the tool's verdict reads a failure of Docker as a finding. The consequence was not cosmetic: a Docker
+// Hub pull-rate limit - 100 anonymous pulls per six hours per IP, which several teams behind one CI
+// egress reach - made the secret scan announce that it had found a secret in the git history. That is the
+// one verdict a project cannot dismiss on its own judgement, and the worst thing this harness can say. A
+// registry outage, an unreachable network, and a digest the registry no longer serves all landed the same
+// way.
+//
+// Two classifiers rather than one, and the split is the actual repair. `classifyImageFailure` reads
+// markers out of the output because it judges `docker image inspect` and `docker pull`, whose every byte
+// docker wrote. `classifyContainerExit` judges a run of the analyzer, whose output carries content the
+// PROJECT authored - a commit message, a Dockerfile, a workflow - so it reads the exit code and nothing
+// else. Matching `no such host` against a commit message would invert the same bug rather than fix it.
+//
+// The rules are pure so they are exercised against captured `docker` output rather than against a live
+// daemon: every branch below describes a failure that is expensive or impossible to stage on demand.
+/** The exit code a shell reports for a command it cannot find. */
+export const COMMAND_NOT_FOUND = 127;
+// `docker run` reserves these for a failure of docker itself, distinct from whatever the container exits
+// with: 125 when docker could not run the container at all, 126 when the entry point was not executable.
+// No analyzer this harness runs emits either - gitleaks, hadolint and actionlint all answer with 0 and 1 -
+// so they separate docker's failure from the tool's verdict before a byte of output is read.
+const DOCKER_ITSELF_FAILED = 125;
+const ENTRY_POINT_NOT_EXECUTABLE = 126;
+const WORDING = {
+    absent: {
+        suffix: 'needs Docker, which is not installed on this machine',
+        remedies: ['Docker is already required for the Payload test database; install it and retry'],
+    },
+    daemonDown: {
+        suffix: 'needs Docker, which is installed but not running',
+        remedies: ['start the Docker daemon and retry; nothing about the project has been judged yet'],
+    },
+    rateLimited: {
+        suffix: 'could not pull its analyzer image: the container registry is rate-limiting this network',
+        remedies: [
+            'Docker Hub caps anonymous pulls per IP, and a shared CI egress reaches that cap sooner than one machine does',
+            'run `docker login` and retry, or retry once the window resets',
+            'no analyzer ran, so this says nothing about the project',
+        ],
+    },
+    unreachable: {
+        suffix: 'could not reach the container registry to pull its analyzer image',
+        remedies: [
+            'this gate is fail-closed by design; retry with network access',
+            'an image already pulled is reused, so a machine that has run this gate before needs no network',
+        ],
+    },
+    manifestUnknown: {
+        suffix: 'names an analyzer image the registry does not serve',
+        remedies: [
+            'the image is pinned by digest in ploaness, not by the project',
+            'this is a ploaness packaging defect; report it',
+        ],
+    },
+    unstartable: {
+        suffix: 'could not start its analyzer container',
+        remedies: ['docker refused to run the image; no analyzer ran, so no finding has been made'],
+    },
+};
+const failureFor = (kind, gate) => ({
+    kind,
+    summary: `${gate} ${WORDING[kind].suffix}`,
+    remedies: WORDING[kind].remedies,
+});
+// Ordered, because the first match wins and the categories are not disjoint in principle: a rate-limited
+// pull and an unreachable registry both mention the registry host. The more specific cause is listed
+// first so it is the one reported.
+//
+// `manifestUnknown` sits BELOW `unreachable` for that same rule read the other way round. Docker frames
+// every registry failure the same way - `failed to resolve reference "<ref>": <cause>` - so a bad
+// digest, a refused connection and a host that does not resolve all carry that opening, and only the
+// clause after the colon says which one happened. The frame is therefore the LEAST specific marker here
+// rather than the most, and matching it above the transport markers would report a ploaness packaging
+// defect for a team's network outage: the same misattribution this classifier exists to prevent, moved
+// one category over.
+const MARKERS = [
+    ['absent', ['enoent', 'command not found', 'executable file not found']],
+    [
+        'daemonDown',
+        [
+            'cannot connect to the docker daemon',
+            'is the docker daemon running',
+            'error during connect',
+            'docker daemon is not running',
+        ],
+    ],
+    ['rateLimited', ['toomanyrequests', 'pull rate limit', 'too many requests']],
+    [
+        'unreachable',
+        [
+            'dial tcp',
+            'no such host',
+            'i/o timeout',
+            'tls handshake',
+            'connection refused',
+            'network is unreachable',
+            'temporary failure in name resolution',
+        ],
+    ],
+    [
+        'manifestUnknown',
+        [
+            'manifest unknown',
+            'not found: manifest',
+            'repository does not exist',
+            'failed to resolve reference',
+        ],
+    ],
+];
+/**
+ * Classify a failure of `docker image inspect` or `docker pull`.
+ *
+ * Safe to read the output here, and only here: the command is docker's own and every byte it wrote is
+ * docker's. Acquiring the image as a step of its own is what creates that guarantee - it moves "the
+ * analyzer could not run" onto a different command from "the analyzer found something", so the two stop
+ * being one exit code read two ways.
+ * @param gate the gate's name, opening the sentence the summary completes.
+ * @param invocation the finished `docker` invocation.
+ * @returns the failure, or undefined when the image was acquired.
+ */
+export const classifyImageFailure = (gate, invocation) => {
+    if (invocation.code === 0) {
+        return undefined;
+    }
+    if (invocation.code === COMMAND_NOT_FOUND) {
+        return failureFor('absent', gate);
+    }
+    const haystack = invocation.output.toLowerCase();
+    const matched = MARKERS.find(([, markers]) => markers.some((marker) => haystack.includes(marker)));
+    return failureFor(matched === undefined ? 'unstartable' : matched[0], gate);
+};
+/**
+ * Classify a failure of a run whose output the project may have authored.
+ *
+ * Exit code only. gitleaks prints the commit it found a secret in, hadolint prints the Dockerfile line,
+ * actionlint prints the workflow step - so a marker matched against that output would let a commit
+ * message decide whether a real finding is reported, which is the same defect one level deeper. The codes
+ * `docker run` reserves for itself carry no such ambiguity.
+ * @param gate the gate's name, opening the sentence the summary completes.
+ * @param invocation the finished `docker run` or shell invocation.
+ * @returns the failure, or undefined when the exit code is the tool's own verdict.
+ */
+export const classifyContainerExit = (gate, invocation) => {
+    if (invocation.code === COMMAND_NOT_FOUND) {
+        return failureFor('absent', gate);
+    }
+    return invocation.code === DOCKER_ITSELF_FAILED || invocation.code === ENTRY_POINT_NOT_EXECUTABLE
+        ? failureFor('unstartable', gate)
+        : undefined;
+};
+//# sourceMappingURL=container-failure.js.map

package/dist/container-failure.js.map

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

package/dist/container-files.d.ts

@@ -0,0 +1,36 @@
+/** A directory compose would treat as a project, and the file that identifies it. */
+export interface ComposeProject {
+    /** Repo-relative directory holding the project; empty at the repository root. */
+    readonly directory: string;
+    /** Repo-relative path of the file that identified it. */
+    readonly file: string;
+}
+/**
+ * Decide whether a path names a Dockerfile.
+ * @param file a repo-relative path.
+ * @returns true when the file is a Dockerfile under any of its conventional spellings.
+ */
+export declare const isDockerfile: (file: string) => boolean;
+/**
+ * Decide whether a path names a file compose would read on its own.
+ * @param file a repo-relative path.
+ * @returns true when the file identifies a compose project.
+ */
+export declare const isComposeFile: (file: string) => boolean;
+/**
+ * Every Dockerfile the repository tracks.
+ * @param tracked the repo-relative paths of the tracked files.
+ * @returns the Dockerfiles, ordered so a report reads the same on every machine.
+ */
+export declare const dockerfilesIn: (tracked: readonly string[]) => readonly string[];
+/**
+ * Every compose project the repository tracks, one per directory.
+ *
+ * Grouped by directory rather than listed per file, because that is the unit compose itself validates: it
+ * reads the base file and every override beside it as one project, and the directory is what a
+ * developer's own `docker compose config` would be run from.
+ * @param tracked the repo-relative paths of the tracked files.
+ * @returns one project per directory holding a compose file, in directory order.
+ */
+export declare const composeProjectsIn: (tracked: readonly string[]) => readonly ComposeProject[];
+//# sourceMappingURL=container-files.d.ts.map

package/dist/container-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-files.d.ts","sourceRoot":"","sources":["../src/container-files.ts"],"names":[],"mappings":"AASA,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAqBD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,OAG3C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,OAAuD,CAAA;AAMpG;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAGO,CAAA;AAEjF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,SAAS,MAAM,EAAE,KAAG,SAAS,cAAc,EAcrF,CAAA"}

package/dist/container-files.js

@@ -0,0 +1,74 @@
+// Which files in a tracked tree are container definitions, and which directories hold a compose project.
+//
+// Discovery is stated here for both kinds at once, because stating it for only one is how the two halves
+// drifted. The Dockerfile half already walked the tracked tree - a project may keep a Dockerfile in any
+// directory, and a hard-coded path would silently skip the ones it did not anticipate - while the compose
+// half looked at the repository root and nowhere else. A Payload project that keeps its application in a
+// member directory keeps its compose file beside it, so the gate linted that member's Dockerfile and
+// reported a pass having validated no compose project at all.
+// Sliced rather than split, so neither helper carries a case that cannot happen. `lastIndexOf`
+// returns -1 for a bare basename, which makes these the whole string and the empty string - the two
+// answers a repository-root file wants - without a fallback no input could reach.
+const basenameOf = (file) => file.slice(file.lastIndexOf('/') + 1);
+const directoryOf = (file) => file.slice(0, Math.max(file.lastIndexOf('/'), 0));
+// The names compose reads on its own, in the precedence it applies to them.
+//
+// An override file is deliberately absent: compose merges one into the project its base file defines, so
+// a directory is validated once, through that base. Discovering an override as a project of its own would
+// hand compose a fragment to validate alone and report a defect the project does not have.
+const COMPOSE_BASENAMES = [
+    'compose.yaml',
+    'compose.yml',
+    'docker-compose.yaml',
+    'docker-compose.yml',
+];
+/**
+ * Decide whether a path names a Dockerfile.
+ * @param file a repo-relative path.
+ * @returns true when the file is a Dockerfile under any of its conventional spellings.
+ */
+export const isDockerfile = (file) => {
+    const name = basenameOf(file);
+    return name === 'Dockerfile' || name.endsWith('.Dockerfile') || name.startsWith('Dockerfile.');
+};
+/**
+ * Decide whether a path names a file compose would read on its own.
+ * @param file a repo-relative path.
+ * @returns true when the file identifies a compose project.
+ */
+export const isComposeFile = (file) => COMPOSE_BASENAMES.includes(basenameOf(file));
+// Where a name sits in compose's own precedence. Only ever asked of a file `isComposeFile` accepted,
+// so the -1 `indexOf` returns for anything else is unreachable rather than meaningful.
+const precedenceOf = (file) => COMPOSE_BASENAMES.indexOf(basenameOf(file));
+/**
+ * Every Dockerfile the repository tracks.
+ * @param tracked the repo-relative paths of the tracked files.
+ * @returns the Dockerfiles, ordered so a report reads the same on every machine.
+ */
+export const dockerfilesIn = (tracked) => tracked
+    .filter((file) => isDockerfile(file))
+    .toSorted((left, right) => left.localeCompare(right));
+/**
+ * Every compose project the repository tracks, one per directory.
+ *
+ * Grouped by directory rather than listed per file, because that is the unit compose itself validates: it
+ * reads the base file and every override beside it as one project, and the directory is what a
+ * developer's own `docker compose config` would be run from.
+ * @param tracked the repo-relative paths of the tracked files.
+ * @returns one project per directory holding a compose file, in directory order.
+ */
+export const composeProjectsIn = (tracked) => {
+    const found = tracked.filter((file) => isComposeFile(file));
+    return [...new Set(found.map((file) => directoryOf(file)))]
+        .toSorted((left, right) => left.localeCompare(right))
+        .flatMap((directory) => 
+    // The directory's files are ranked and the first is taken, rather than the names being tried in
+    // order against the list. Both spell compose's precedence; only this one is total, so there is no
+    // "no file matched" case to answer for in a directory that is here because a file matched.
+    found
+        .filter((file) => directoryOf(file) === directory)
+        .toSorted((left, right) => precedenceOf(left) - precedenceOf(right))
+        .slice(0, 1)
+        .map((file) => ({ directory, file })));
+};
+//# sourceMappingURL=container-files.js.map

package/dist/container-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-files.js","sourceRoot":"","sources":["../src/container-files.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,EAAE;AACF,yGAAyG;AACzG,wGAAwG;AACxG,0GAA0G;AAC1G,yGAAyG;AACzG,qGAAqG;AACrG,8DAA8D;AAU9D,+FAA+F;AAC/F,oGAAoG;AACpG,kFAAkF;AAClF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;AAElF,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAE/F,4EAA4E;AAC5E,EAAE;AACF,yGAAyG;AACzG,0GAA0G;AAC1G,2FAA2F;AAC3F,MAAM,iBAAiB,GAAsB;IAC3C,cAAc;IACd,aAAa;IACb,qBAAqB;IACrB,oBAAoB;CACrB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAW,EAAE;IACpD,MAAM,IAAI,GAAW,UAAU,CAAC,IAAI,CAAC,CAAA;IACrC,OAAO,IAAI,KAAK,YAAY,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAA;AAChG,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAA;AAEpG,qGAAqG;AACrG,uFAAuF;AACvF,MAAM,YAAY,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAA;AAE1F;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA0B,EAAqB,EAAE,CAC7E,OAAO;KACJ,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;KACrD,QAAQ,CAAC,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;AAEjF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAA0B,EAA6B,EAAE;IACzF,MAAM,KAAK,GAAsB,OAAO,CAAC,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/F,OAAO,CAAC,GAAG,IAAI,GAAG,CAAS,KAAK,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;SAChF,QAAQ,CAAC,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SAC5E,OAAO,CAAC,CAAC,SAAiB,EAA6B,EAAE;IACxD,gGAAgG;IAChG,kGAAkG;IAClG,2FAA2F;IAC3F,KAAK;SACF,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;SAClE,QAAQ,CAAC,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;SAC3F,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,IAAY,EAAkB,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAChE,CAAA;AACL,CAAC,CAAA"}