IF Commons GitHub

ci/policy

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

The build policy of this repository (commons 0038-build-policy): a run is red only for a cause of the closed list RED_CAUSES, everything a module says is a finding, and the decisions that depend on findings (the release) are explicit values and never the exit status of a step. This file is the one place the policy is written; the workflows, the step wrapper, the checks and the documentation read it.

Pure and dependency free (no package, only values and functions of this file), so that the step wrapper that imports it runs in a cell of the matrix before any package is installed: a wrapper that needs a package of the cell it is to observe could itself be the thing that fails.

import { RED_CAUSES, releaseDecision } from "./policy.ts";
RED_CAUSES.length; // 4
releaseDecision("2027-02-01").proceed; // false

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

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

RED_CAUSESconst
const RED_CAUSES: readonly ["workflow-invalid", "wrapper-misused", "plan-unavailable", "reports-not-produced"]

What may turn a run red (0038-build-policy FR-002): the pipeline's own scripting and configuration, and nothing that a module says.

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

RedCausetypeno test imports it
type RedCause = (typeof RED_CAUSES)[number];

A red cause.

RED_CAUSE_WHYconstno test imports it
const RED_CAUSE_WHY: Readonly<Record<"plan-unavailable" | "reports-not-produced" | "workflow-invalid" | "wrapper-misused", string>>

Why each red cause is one: the sentence that justifies it.

TOOLSconst
const TOOLS: readonly ["tsc", "bun-test", "lint", "format", "repoctl-check", "mizan-check", "kanon-check", "generated-files", "verify", "checks", "exit-status", "install", "policy"]

The tools whose output becomes findings (0038-build-policy FR-013): a closed table. verify is a library's verify script (the parsers of tsc, bun-test and kanon-check over its output) and checks a script of the repository's checks (generated-files, repoctl-check, kanon-check and mizan-check); policy is the policy's own (the review of the release); install and exit-status read a step that has no parser of its own.

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

Tooltypeno test imports it
type Tool = (typeof TOOLS)[number];

A tool.

GATESconstno test imports it
const GATES: readonly ["release", "branch-protection", "pages"]

The gates there are: the decisions that depend on findings, each written as data of this file.

Gatetypeno test imports it
type Gate = (typeof GATES)[number];

A gate.

StepPolicytypeno test imports it
type StepPolicy =
  | { readonly kind: "red-cause"; readonly cause: RedCause }
  | { readonly kind: "finding"; readonly tool: Tool; readonly timeoutMinutes: number; readonly module: string; readonly errexit: boolean }
  | { readonly kind: "gate"; readonly gate: Gate }
  | { readonly kind: "plumbing" };

The policy of one step of a workflow (0038-build-policy FR-003): a red cause the step may be, a step whose output is read into findings by the parser of a tool, a gate, or plumbing (a step that moves or keeps what the other steps made and says nothing about a module).

redCauseconstno test imports it
const redCause: (cause: "plan-unavailable" | "reports-not-produced" | "workflow-invalid" | "wrapper-misused") => StepPolicy

The policy of a step that is a red cause.

findingconstno test imports it
const finding: (tool: "bun-test" | "checks" | "exit-status" | "format" | "generated-files" | "install" | "kanon-check" | "lint" | "mizan-check" | "policy" | "repoctl-check" | "tsc" | "verify", timeoutMinutes: number, o?: { readonly module?: string | undefined; readonly errexit?: boolean | undefined; }) => StepPolicy

The policy of a step whose output is read into findings: the tool, the minutes after which the wrapper stops its command, the module its findings are of (the text of a matrix expression such as ${{ matrix.name }} where the step is in a library's cell, repository otherwise) and whether the script stops at its first failing command (errexit; a script of several independent checks does not, so that each one runs and says its findings).

gateconstno test imports it
const gate: (g: "branch-protection" | "pages" | "release") => StepPolicy

The policy of a step that is a gate.

plumbingconstno test imports it
const plumbing: StepPolicy

The policy of a step that is plumbing.

APPROVERSconst
const APPROVERS: readonly string[]

The people who may approve an accepted risk (0038-build-policy FR-008): by their login. An agent is never one.

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

ACCEPTANCE_MAX_DAYSconstno test imports it
const ACCEPTANCE_MAX_DAYS: 366

The longest an acceptance may last, in days (0038-build-policy FR-008).

ReleasePolicytypeno test imports it
type ReleasePolicy = { readonly mode: "publish-regardless"; readonly until: string };

The decision the release is under (0038-build-policy FR-010).

RELEASE_POLICYconst
const RELEASE_POLICY: ReleasePolicy

The release policy: until the day, a library is released whatever its open findings are; after it the owner decides again (January 2027).

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

ReleaseDecisiontypeno test imports it
type ReleaseDecision =
  | { readonly proceed: true; readonly reportOpenFindings: true; readonly until: string }
  | { readonly proceed: false; readonly finding: { readonly tool: "policy"; readonly code: "owner-review-due"; readonly severity: "error"; readonly module: "repository"; readonly message: string } };

What the release may do on a day, with the finding the owner must see where it may not.

releaseDecisionfunction
function releaseDecision(day: string, policy?: ReleasePolicy): ReleaseDecision

The decision of the release on a day (YYYY-MM-DD): publish regardless until the day of the policy, and after it nothing proceeds silently (0038-build-policy FR-010).

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

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