IF Commons GitHub

ci/findings

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-libraries-ci-findings FR-002

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-"); // true

Source: commons/libraries/src/ci/findings.ts

9 of 19 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

SEVERITIESconstno test imports it
const SEVERITIES: readonly ["error", "warning", "note"]

The severities of a finding.

Severitytypeno test imports it
type Severity = (typeof SEVERITIES)[number];

A severity.

Evidencetypeno test imports it
type Evidence = { readonly run: string; readonly commit: string; readonly step: string; readonly logSha256: string };

Where a finding was read from.

Findingtypeno test imports it
type 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 it
const OUTCOMES: readonly ["ok", "findings", "tool-error", "timeout", "no-output"]

How a step ended.

Outcometypeno test imports it
type Outcome = (typeof OUTCOMES)[number];

An outcome.

StepRecordtypeno test imports it
type 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 it
type RunInfo = { readonly id: string; readonly workflow: string; readonly commit: string; readonly at: string; readonly url?: string };

The run a file is of.

FindingsFiletype
type 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).

Imported by 13 tests of the run (13 passed, 0 failed): the library's results

findingIdfunction
function findingId(p: { readonly tool: string; readonly code: string; readonly module: string; readonly file?: string | undefined; readonly key: string; }): string

The identity of a finding: from the tool, the code, the module, the file and the key, and from nothing that changes between runs.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

sha256Ofconst
const sha256Of: (text: string) => string

The SHA-256 of a text, as the evidence of a log.

Imported by 1 test of the run (1 passed, 0 failed): the library's results

makeFindingfunction
function 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; }): Finding

A finding made from what a parser read, with its id and its evidence.

Imported by 2 tests of the run (2 passed, 0 failed): the library's results

decodeFindingsFilefunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Acceptancetype
type 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).

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

acceptanceProblemsfunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Statustypeno test imports it
type Status = "open" | "fixed" | "accepted";

The status of a finding, derived (0038-build-policy FR-007).

Rowtypeno test imports it
type 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.

deriveRowsfunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

countsOffunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.