SEVERITIESconstno test imports itconst SEVERITIES: readonly ["error", "warning", "note"]The severities of a finding.
The finding (commons 0038-build-policy FR-006 to FR-008): what a tool said about a module, as a typed record with an identity that is the same in the next run, the file a run keeps (build-findings/1), the status derived from the runs of a history and from the acceptances, and the rules of an acceptance. Pure and dependency free, like policy.ts: the wrapper that writes the file runs in a cell before any package is installed.
The id of a finding is made from the tool, the code, the module, the file and the key, and never from the line, the run, the time or the message, so that a finding that moves is the same finding. A status is never written: it is read from the runs. A finding of a module that did not run in the latest run keeps the status of the last run in which the module ran (a cell that did not run is not a cell that is clean).
import { findingId } from "./findings.ts";
findingId({ tool: "tsc", code: "TS2322", module: "core", file: "src/a.ts", key: "x" }).startsWith("f-"); // trueSEVERITIESconstno test imports itconst SEVERITIES: readonly ["error", "warning", "note"]The severities of a finding.
Severitytypeno test imports ittype Severity = (typeof SEVERITIES)[number];A severity.
Evidencetypeno test imports ittype Evidence = { readonly run: string; readonly commit: string; readonly step: string; readonly logSha256: string };Where a finding was read from.
Findingtypeno test imports ittype Finding = {
readonly id: string;
readonly tool: Tool;
readonly code: string;
readonly module: string;
readonly file?: string;
readonly line?: number;
readonly severity: Severity;
readonly message: string;
readonly key: string;
readonly evidence: Evidence;
readonly at: string;
};One finding.
OUTCOMESconstno test imports itconst OUTCOMES: readonly ["ok", "findings", "tool-error", "timeout", "no-output"]How a step ended.
Outcometypeno test imports ittype Outcome = (typeof OUTCOMES)[number];An outcome.
StepRecordtypeno test imports ittype StepRecord = { readonly id: string; readonly job: string; readonly module: string; readonly tool: Tool; readonly outcome: Outcome; readonly findings: number; readonly durationMs: number; readonly exitStatus?: number };What the file of a run says of one step: that it ran, for which module, and how it ended.
RunInfotypeno test imports ittype RunInfo = { readonly id: string; readonly workflow: string; readonly commit: string; readonly at: string; readonly url?: string };The run a file is of.
FindingsFiletypetype FindingsFile = { readonly schema: "build-findings/1"; readonly run: RunInfo; readonly steps: readonly StepRecord[]; readonly findings: readonly Finding[] };The file a run keeps (0038-build-policy FR-006, FR-012).
findingIdfunctionfunction findingId(p: { readonly tool: string; readonly code: string; readonly module: string; readonly file?: string | undefined; readonly key: string; }): stringThe identity of a finding: from the tool, the code, the module, the file and the key, and from nothing that changes between runs.
sha256Ofconstconst sha256Of: (text: string) => stringThe SHA-256 of a text, as the evidence of a log.
makeFindingfunctionfunction makeFinding(p: { readonly tool: "bun-test" | "checks" | "exit-status" | "format" | "generated-files" | "install… (490 characters)function makeFinding(p: { readonly tool: "bun-test" | "checks" | "exit-status" | "format" | "generated-files" | "install" | "kanon-check" | "lint" | "mizan-check" | "policy" | "repoctl-check" | "tsc" | "verify"; readonly code: string; readonly module: string; readonly file?: string | undefined; readonly line?: number | undefined; readonly severity: "error" | "note" | "warning"; readonly message: string; readonly key: string; readonly evidence: Evidence; readonly at: string; }): FindingA finding made from what a parser read, with its id and its evidence.
decodeFindingsFilefunctionfunction decodeFindingsFile(input: unknown): { readonly kind: "ok"; readonly value: FindingsFile; } | { readonly kind: "err"; readonly error: string; }A file read as a FindingsFile, or the sentence that says what is wrong with it.
Acceptancetypetype Acceptance = { readonly id: string; readonly owner: string; readonly reason: string; readonly from: string; readonly until: string; readonly by: string };A person's word that a risk has been seen, until a day (0038-build-policy FR-008).
acceptanceProblemsfunctionfunction acceptanceProblems(a: Acceptance, approvers?: readonly string[]): readonly string[]What is wrong with an acceptance (none where it keeps the rules): a reason, an owner, days that are days, an end within the longest, an approver who is one of the list.
Statustypeno test imports ittype Status = "open" | "fixed" | "accepted";The status of a finding, derived (0038-build-policy FR-007).
Rowtypeno test imports ittype Row = {
readonly finding: Finding;
readonly status: Status;
readonly firstSeen: string;
readonly lastSeen: string;
readonly runsSeen: number;
/** A note the status carries: an acceptance that ended, or the run the finding was last seen in. */
readonly note?: string;
readonly acceptance?: Acceptance;
};One finding with what the history says of it.
deriveRowsfunctionfunction deriveRows(history: readonly FindingsFile[], acceptances: readonly Acceptance[], today: string): readonly Row[]The rows of a history (oldest run first) on a day: every finding any run had, once, as it was in the run that last had it. A finding is open where the last run in which its module ran has it, fixed where that run does not, and accepted where it is open and a live acceptance names it; an acceptance that has ended leaves it open with the note.
countsOffunctionfunction countsOf(rows: readonly Row[], history: readonly FindingsFile[]): { readonly open: number; readonly fresh: number; readonly fixed: number; readonly accepted: number; }The counts a page and a status say: open, new since the run before, fixed in the latest run, accepted.