IF Commons GitHub

Findings of the build, in the libraries library

0002Draft

0002-libraries-ci-findings · owner if · domain commons

The policy as code

FR-001checkpassing

src/ci/policy.ts MUST hold, as values with no import, the closed list of red causes and the sentence that justifies each, the closed table of tools, the gates, the union StepPolicy (a red cause, a step of findings with its tool, time limit, module and errexit, a gate, or plumbing), the list of approvers, the longest an acceptance lasts, and the release policy with its function releaseDecision, which publishes regardless until the day of the policy and after it does not proceed and carries the finding owner-review-due (commons 0038-build-policy FR-002, FR-008, FR-010).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-findings.test.ts: the red causes are a closed list with their reasons and the release decision is a day's

Written in: libraries/src/ci/policy.ts

Tests: passed: suite/ci-findings.test.ts the release publishes regardless until 2027-01-31 and, after it, does not proceed and carr; passed: suite/ci-findings.test.ts the red causes are a closed list of four, each with its justification, and the tools of th

FR-002checkpassing

src/ci/findings.ts MUST hold the finding with its identity made from the tool, the code, the module, the file and the key and from nothing that changes between runs, the file of a run (build-findings/1) and its decoder, the rules of an acceptance, and the derivation of the status of each finding from a history of runs and the acceptances: open, fixed or accepted, a module that did not run keeping the status of the last run in which it did, and an acceptance that has ended leaving the finding open with the note (commons 0038-build-policy FR-006, FR-007, FR-008).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-findings.test.ts: the id is stable, the status is derived from the runs and the acceptances

Written in: libraries/src/ci/findings.ts

Tests: passed: suite/ci-findings.test.ts a finding is open where the latest run of its module has it, fixed where that run does not; passed: suite/ci-findings.test.ts an acceptance makes a finding accepted until its day, an acceptance that ended leaves it o; passed: suite/ci-findings.test.ts the id of a finding is the same when the line, the run, the time or the message changes, a

FR-003checkpassing

src/ci/parsers.ts MUST read the output of each tool of the table into findings, purely, with the file, the line, the code and a key that is not a line; it MUST read the output the tools print (kept as fixtures of the tests), make nothing up, give a finding no more than once, and give a step that failed with nothing a parser reads the finding no-output, one that could not be started tool-error and one stopped by its limit timeout (commons 0038-build-policy FR-013).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-findings.test.ts: each parser reads the real output of its tool

Written in: libraries/src/ci/parsers.ts

Tests: passed: suite/ci-findings.test.ts each parser reads the real output of its tool into findings with the file, the line, the c

FR-004checkpassing

src/ci/step.ts MUST run one command with a time limit that stops its whole process group, print what the command printed as it was printed, write the file of the step, give the later steps of the job the outputs outcome, detail and findings, and exit 0 whatever the command's status was; the one status that is not 0 is 2, for a call with no command, an unknown tool, a bad id or a limit that is not a number (commons 0038-build-policy FR-002, FR-004, FR-013).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-findings.test.ts: the wrapper runs real processes and exits 0, and a wrong call is the one exit that is not

Written in: libraries/src/ci/step.ts

Tests: passed: suite/ci-findings.test.ts the wrapper called wrongly is the one thing that is not green: no command, an unknown tool; passed: suite/ci-findings.test.ts the wrapper runs a failing test command and exits as a green step with the failure as a fi

Cited by: Steps of a pipeline under the build policy

FR-005checkpassing

src/ci/inventory.ts and src/ci/wrap.ts MUST give every step of every workflow of the model its policy by an ordered list of rules with their reasons, make the table of steps with the count of each policy, put the wrapper on the steps of findings (the script moves into the environment of the step), end each job that makes findings by keeping them, make the job that gathers a workflow's findings, and find in a workflow a step with no policy, a step of findings that is not wrapped or whose limit is not below its job's, a matrix that fails fast, plumbing that is not continueOnError and a job after a matrix that does not run with always(); the generator MUST write nothing while there is one (commons 0038-build-policy FR-003, FR-004, FR-005).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-policy.test.ts: every workflow keeps the policy, no step can end a job red but a red cause or a gate, and the validation finds what it is for

Written in: libraries/src/ci/inventory.ts, libraries/src/ci/wrap.ts

Tests: passed: suite/ci-policy.test.ts every red cause a step names is one of the closed list, and the only steps that can end a ; passed: suite/ci-policy.test.ts every workflow of the repository keeps the policy: every step has one, the steps of findin; passed: suite/ci-policy.test.ts no step of any job of any workflow can end its job red unless it is a step of a red cause ; passed: suite/ci-policy.test.ts the inventory counts every step by its policy and the counts add up to the steps of the wo; passed: suite/ci-policy.test.ts the validation finds a step with no policy, a step of findings that is not wrapped or has

Cited by: Generated workflows

FR-006checkpassing

src/ci/collect.ts MUST merge the files the steps wrote into one file of the run, make sure that every cell that ran left its file and end 2 (the red cause reports-not-produced) where one did not and in no other case, write the merged file and a summary, give the commit the check findings with the conclusion neutral or success and never failure, and add the finding owner-review-due where the release policy has ended; it MUST NOT write the history (commons 0038-build-policy FR-005, FR-011, FR-012).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-collect.test.ts: the merge, the sound-pipeline check, the summary

Written in: libraries/src/ci/collect.ts

Tests: passed: suite/ci-collect.test.ts the files of the steps are merged with each finding once, and the pipeline is not sound on; passed: suite/ci-collect.test.ts the real program ends 0 where cells have failing tests and findings, 2 where a cell that r

FR-007checkpassing

src/ci/history.ts MUST keep a run as one new file of the orphan branch findings-history at runs/YYYY/MM/DD/<workflow>-<run id>.json by a commit that adds a file and changes none, never replace a file that is there, push as a fast-forward and, where the branch moved, retry from its new tip and never force; and MUST read the files of the branch, oldest first; as a program (history.ts --file FILE --remote URL) it is what the job keep-findings runs, says where the file is not a findings file and is never a failure (commons 0038-build-policy FR-012).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-history.test.ts: a real repository, a file added and never replaced, a moved branch retried

Written in: libraries/src/ci/history.ts

Tests: passed: suite/ci-history.test.ts a run is added to the orphan branch as one new file by a commit that changes none, a file ; passed: suite/ci-history.test.ts two runs that push at once both land: the one that finds the branch moved retries from the

FR-008checkpassing

src/ci/release-gate.ts MUST say what the release policy lets the run do on a day, list the open findings of each module of the history, and end 1, as the release's own decision, where the policy does not let it proceed (commons 0038-build-policy FR-010).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-findings.test.ts: the release policy of a day

Written in: libraries/src/ci/release-gate.ts

Tests: passed: suite/ci-findings.test.ts the release publishes regardless until 2027-01-31 and, after it, does not proceed and carr

FR-009checkno test run

src/ci/accepted.ts MUST read the accepted risks of commons/spec-kit/accepted-findings/ (typed files with an export acceptance) and find an acceptance with no reason, an end that is not a day or is more than 366 days ahead, an approver who is not on the list, a file not named for its finding's id and two acceptances of one finding, and end 1 for any; the check MUST be one of repoctl check (commons 0038-build-policy FR-008).

Enforced (check): .github: cd commons/libraries && bun test suite/ — ci-accepted.test.ts: each rule of an acceptance is found in real files and a good one passes

Written in: libraries/src/ci/accepted.ts

Acceptance scenarios

  1. Given the output of tsc, bun test, the linter, the formatter, repoctl check, the checks of Mizan and Kanon and the generator's check as the tools printed it, When the parsers read it, Then each gives its findings with the file, the line and the code, per FR-003.
  2. Given a command that fails, prints nothing, does not exist or does not end, When the wrapper runs it, Then it exits 0 and the file says findings, no-output, tool-error or timeout, per FR-004.
  3. Given a step added to a workflow with no rule that matches it, When the generator runs, Then it writes nothing and names the step, per FR-005.
  4. Given a cell of the matrix that ran and left no file, When the gathering job runs, Then it ends 2 and no other case ends it red, per FR-006.
  5. Given two runs that push at once, When the second finds the branch moved, Then it retries from the new tip and both files are on the branch, per FR-007.

Out of scope

  • The verb repoctl ci step and the page of findings: the specifications of repoctl and of the documentation generator.

Edge cases

  • A findings file that is not one: named by the gathering job and left out of the merge, per FR-006.
  • A history branch that is not there: made orphan by the first run, per FR-007.

Assumptions

  • Real git and gh are on the runner.

Open questions

  • None.

Key entities

  • Policy - src/ci/policy.ts.
  • Finding - src/ci/findings.ts.
  • Wrapper - src/ci/step.ts.

Success criteria

SC-001success criterion

A failing module's words are findings and never a red run, shown by a test over the typed workflows and by a run.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Steps of a pipeline under the build policy, Generated workflows

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