IF Commons GitHub

governance/issue

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0044-issues FR-001, 0044-issues FR-002, 0044-issues FR-003, 0044-issues FR-004, 0044-issues FR-005

Issues as typed code (commons data 0044-issues): a known weakness of a library or a module is a value of the type Issue, not a line in a document, so that it is checked, cannot be silently dropped and cannot be called fixed without a proof. A status is a sum: one that is fixed carries its proof, one that is a duplicate names the issue it duplicates, one that will not be fixed carries its reason; a status that lacks what it needs does not compile. A set of issues is checked as a whole (numbers, references, which engines an issue is about), and two versions of a set are checked against each other, so that an issue does not move along a path the state machine does not allow.

Pure: it names no file and no database. appliesTo says which engines a weakness is about, so that an engine that cannot do what is missing is not charged with it (0043-sql-invariants FR-006).

Source: commons/data/governance/issue.ts

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

AppliesTotypeno test imports it
type AppliesTo = { readonly engines: "all" } | { readonly engines: readonly [string, ...string[]] };

Which engines an issue is about: all of them, or only those that could do better (an engine that cannot is not charged).

canMoveconst
const canMove: (from: "deferred" | "duplicate" | "fixed" | "in-progress" | "not-a-defect" | "open" | "wont-fix", to: "deferred" | "duplicate" | "fixed" | "in-progress" | "not-a-defect" | "open" | "wont-fix") => boolean

Whether an issue may go from one status to another.

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

checkIssueMovesfunction
function checkIssueMoves(before: IssueSet, after: IssueSet): readonly IssueFinding[]

The findings of a set against the version before it: an issue is never taken out (close it instead), its number and slug never change, and its status moves only along MOVES. It is what keeps an issue from being lost.

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

checkIssueSetfunction
function checkIssueSet(set: IssueSet): readonly IssueFinding[]

The findings of one set: numbers from 1 with no gap, a slug in words, a date, a priority that fits the severity (a critical issue is P1, a low one is never P1), engines that are named, a fixed issue with a proof, a reason where one is owed, a duplicate that names an issue that exists and is not itself a duplicate, and links and citations that resolve.

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

Evidencetypeno test imports it
type Evidence =
  | { readonly kind: "commit"; readonly sha: string }
  | { readonly kind: "test"; readonly file: string; readonly name: string }
  | { readonly kind: "spec"; readonly id: string }
  | { readonly kind: "file"; readonly path: string; readonly line?: number }
  | { readonly kind: "review"; readonly source: string };

Something that shows what an issue says: a commit, a test, a specification, a place in a file, a review.

IssueGoaltypeno test imports it
type IssueGoal = "G1" | "G2" | "G3" | "G4" | "G5" | "G6" | "G7" | "G8";

What the library is meant to be: the goals the issues are held against.

isLiveconstno test imports it
const isLive: (s: Status) => boolean

Whether an issue is still to be done.

Issuetype
type Issue = Readonly<IssueSpec>;

An issue: frozen, made by issue.

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

issuefunction
function issue(spec: IssueSpec): Readonly<IssueSpec>

Makes an issue; it is frozen, as are its parts.

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

IssueFindinginterfaceno test imports it
interface IssueFinding

A finding of the checks of issues.

MemberTypeWhat it is
ruleIssueRule
scopestring
idnumber
messagestring
IssueRuletypeno test imports it
type IssueRule =
  | "issue/number"
  | "issue/slug"
  | "issue/date"
  | "issue/priority"
  | "issue/engines"
  | "issue/goals"
  | "issue/proof"
  | "issue/reason"
  | "issue/duplicate"
  | "issue/link"
  | "issue/cite"
  | "issue/lost"
  | "issue/move"
  | "issue/reused";

The rules of the checks of issues.

IssueSetinterface
interface IssueSet

The issues of one library or module: its scope (its path) and its issues in order of number.

MemberTypeWhat it is
scopestring
issuesreadonly Readonly<IssueSpec>[]

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

issueSetfunction
function issueSet(scope: string, issues: readonly Readonly<IssueSpec>[]): IssueSet

Makes the set of a scope.

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

IssueSpecinterface
interface IssueSpec

What an issue is made from.

MemberTypeWhat it is
idnumber
slugstring
titlestring
summarystring
severityIssueSeverity
priorityIssuePriority
goalsreadonly IssueGoal[]
appliesToAppliesTo
statusStatus
sizeIssueSize
cites?readonly string[]The requirements of a specification it is about, as 0043-sql-invariants FR-002.
evidence?readonly Evidence[]
links?readonly Link[]
raisedstringWhen it was raised, as 2026-11-19.

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

Linktypeno test imports it
type Link = { readonly kind: "blocks" | "relates" | "caused-by"; readonly to: number };

How two issues of a set are related.

liveIssuesfunction
function liveIssues(set: IssueSet): readonly Readonly<IssueSpec>[]

The issues of a set that are still to be done, most pressing first (priority, then severity, then number).

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

MOVESconst
const MOVES: Readonly<Record<"deferred" | "duplicate" | "fixed" | "in-progress" | "not-a-defect" | "open" | "wont-fix", readonly ("deferred" | "duplicate" | "fixed" | "in-progress" | "not-a-defect" | "open" | "wont-fix")[]>>

Where each status may go. A finished issue can only be reopened; nothing is deleted, so an issue is never lost.

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

IssuePrioritytypeno test imports it
type IssuePriority = "P1" | "P2" | "P3";

When it is to be done: P1 before the next release, P2 the one after, P3 when it is convenient.

IssueSeveritytypeno test imports it
type IssueSeverity = "critical" | "high" | "medium" | "low";

How bad an issue is, for what the library promises.

IssueSizetypeno test imports it
type IssueSize = "xs" | "s" | "m" | "l" | "xl";

How much work the fix is.

STATUS_KINDSconst
const STATUS_KINDS: readonly ("deferred" | "duplicate" | "fixed" | "in-progress" | "not-a-defect" | "open" | "wont-fix")[]

Every kind of status, for tests and for the database's code list.

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

Statustypeno test imports it
type Status = | { readonly kind: "open" } | { readonly kind: "in-progress"; readonly by?: string } | { readonly ki… (448 characters)
type Status =
  | { readonly kind: "open" }
  | { readonly kind: "in-progress"; readonly by?: string }
  | { readonly kind: "fixed"; readonly proof: readonly [Evidence, ...Evidence[]] }
  | { readonly kind: "wont-fix"; readonly reason: string }
  | { readonly kind: "not-a-defect"; readonly reason: string }
  | { readonly kind: "duplicate"; readonly of: number }
  | { readonly kind: "deferred"; readonly reason: string; readonly until?: string };

Where an issue is: a sum, each case carrying what it needs.

StatusKindtypeno test imports it
type StatusKind = Status["kind"];

The kind of a status.

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