MIL-010 task 2: ADR-0010, the contract of the code metrics badges (RC-072)

Refs #156
2026-10-14 13:43:15 +08:00
parent 9ca9673b00
commit aa4ca0f897
4 changed files with 265 additions and 5 deletions
@@ -0,0 +1,203 @@
 # ADR-0010: Contract of the code metrics and coverage badges workflow
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | ADR-0010 |
 | CrossReference | [MIL-010], [UC-008], [US-001], [ADR-0005], [ADR-0006] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; reviewed (RC-072) | pending |
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 ---
 ## Context
 MIL-010 adds a reusable workflow that shows the size of a repository's code
 and its test coverage as badges (UC-008, US-001.18 to US-001.20). ADR-0005
 defines the contract of the quality-check workflow: inputs with working
 defaults, a pinned version per tool, a failure that names the cause, and a
 script file of this repository, fetched at `tools-ref`, that the workflow runs.
 Decisions the user took in chat on 2026-10-14 bound this one: the counter is a
 Python script of this repository with no dependency outside the standard
 library, the delivery is a reusable workflow, the badges are committed to a
 `badges` branch, there are three badges (code files, lines of code, coverage),
 and the coverage report is read in the Cobertura XML format.
 Options for the counter:
 1. **Wrap `cloc`, `tokei` or `scc`.** Many languages, mature rules, but a tool
   to install and pin on every run and a download from outside the instance.
 2. **A Python script of this repository.** No install, fully tested offline,
   and the rules are ours; fewer languages and simple scanning rules.
 Options for the delivery of the badges: a run artifact (disappears and has no
 stable URL), a file on the default branch (a commit per change on the branch
 that protects the code), or a dedicated branch (stable raw URL, no effect on
 the default branch).
 Facts: the job of a reusable workflow runs on `ubuntu-latest` with `python3`
 3.12; a push made with the token of a run does not start another run; a
 workflow checks the shared scripts out into the workspace (`shared-scripts`),
 so the counter must not count them.
 ## Decision
 A reusable workflow `code-metrics.yml` runs three script files of this
 repository, fetched at its input `tools-ref` (default `v1`): `tools/count_loc.py`
 counts the code, `tools/badges.py` reads the coverage report and writes the
 badges, and `tools/code-metrics.sh` validates the inputs, calls both and
 publishes the badge files to the `badges` branch of the calling repository
 with the token of the run (`contents: write`, no other permission).
 The rules that follow from it:
 - **Code file.** A file under `working-directory` whose extension is in the
  language table below, that is not excluded, and that contains no NUL byte
  (it is text; it is read as UTF-8 and invalid bytes are replaced). Its
  language comes from the extension. A file with a code extension but no
  line is still a code file.
 - **Languages and comments (first version).**
  | Language | Extensions | Line comment | Block comment |
  | --- | --- | --- | --- |
  | Python | `.py` | `#` | none |
  | Shell | `.sh`, `.bash` | `#` at the start of a word | none |
  | PowerShell | `.ps1`, `.psm1` | `#` | `<#` ... `#>` |
  | C | `.c`, `.h` | `//` | `/*` ... `*/` |
  | C++ | `.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp` | `//` | `/*` ... `*/` |
  | C# | `.cs` | `//` | `/*` ... `*/` |
  | Java | `.java` | `//` | `/*` ... `*/` |
  | JavaScript | `.js`, `.mjs`, `.jsx` | `//` | `/*` ... `*/` |
  | TypeScript | `.ts`, `.tsx` | `//` | `/*` ... `*/` |
  | Go | `.go` | `//` | `/*` ... `*/` |
  | Rust | `.rs` | `//` | `/*` ... `*/` |
  | SQL | `.sql` | `--` | `/*` ... `*/` |
  Markup, data and configuration files (Markdown, YAML, JSON, XML, HTML,
  CSS) are not code files. A language is added by a minor release.
 - **Line classes.** Every physical line is exactly one of: *blank* (only
  white space, also inside a block comment), *comment* (not blank, and only
  comment text and white space), or *code* (anything else, including a line
  with code and a trailing comment). A comment marker inside a string literal
  is not a comment. String literals are the quoted forms of the language that
  end on the same line, plus the Python triple-quoted string and the backtick
  string of JavaScript, TypeScript and Go, which may span lines; a Python
  docstring is a string and so counts as code.
  Raw-string and verbatim forms that differ from these (Rust `r#"..."#`, C#
  `@"..."` with doubled quotes, C++ raw strings) are scanned as ordinary
  strings and can be mis-counted; this is a stated limit.
 - **Excluded by default.** Every directory whose name starts with `.`, and the
  directories `node_modules`, `vendor`, `third_party`, `dist`, `build`, `out`,
  `bin`, `obj`, `target`, `venv`, `__pycache__` and `shared-scripts`
  (the checkout of the shared scripts); symbolic links are not followed. The
  input `exclude` is a comma list of patterns that add to this: a pattern
  without `/` matches a directory or file name anywhere, a pattern with `/`
  matches the path relative to `working-directory` (`*` does not cross `/`).
  The counter does not read `.gitignore` or generated-file markers; a caller
  excludes generated code with `exclude`.
 - **Totals.** `files` is the number of code files and `lines` is the sum of
  their code lines (comment and blank lines are not in it); the result also
  holds `comment` and `blank` totals and the same four numbers per language,
  sorted by language name, in `code-metrics.json`.
 - **Coverage report.** The input `coverage-report` is the path, relative to
  the repository root, of a Cobertura XML file. The percentage is
  `lines-covered / lines-valid` of the root `coverage` element, shown rounded
  half up to a whole number; when a count is absent, `line-rate` is used.
  A path that does not exist, a file that is not well-formed Cobertura XML,
  and a report with no valid lines are failures with the category
  `[configuration]` that names the file; no coverage badge is written. An
  empty `coverage-report` means no coverage badge and a notice. The workflow
  does not run tests; the caller runs them before the call and the report
  must be in the workspace (the same job, or an artifact the caller fetched).
 - **Badges.** Three flat SVG files with a label and a value, written to the
  root of the `badges` branch with fixed names: `code-files.svg` (label
  `code files`), `code-lines.svg` (label `lines of code`) and `coverage.svg`
  (label `coverage`); the values are the whole number with `,` between groups
  of three digits and, for coverage, `%`. The value colour of the first two is
  blue `#007ec6`; coverage is red `#e05d44` below the input `coverage-warn`
  (default `60`), yellow `#dfb317` from there to below `coverage-good`
  (default `80`) and green `#44cc11` from `coverage-good`. Each file has
  `role="img"`, a `<title>` and an `aria-label` with the same text, a width
  computed from the number of characters (no font is measured) and no
  timestamp, script or external reference, so the same numbers give the same
  bytes.
 - **Publishing.** The `badges` branch holds only the three SVG files and
  `code-metrics.json`; the script creates it as an orphan branch when it does
  not exist. It writes the files, and when none differs from the branch it
  commits nothing and says so; otherwise one commit, message
  `Update code metrics badges [skip ci]`, changes only those files. The
  commit is made with the token of the run, which does not start another run;
  the guide tells a caller to start the workflow on pushes to its default
  branch only.
 - **Inputs.** `working-directory` (default `.`), `exclude` (default empty),
  `coverage-report` (default empty), `coverage-warn` (default `60`),
  `coverage-good` (default `80`), `badges-branch` (default `badges`) and
  `tools-ref` (default `v1`; pin it to the same exact tag as the workflow).
  There is no tool version input: the tools are files of this repository and
  Python 3 of the runner.
 - **Pass, fail, empty.** The run passes when the badges were written or were
  already current. It fails with a `[configuration]` message that names the
  input and the value for an input that is invalid (a threshold that is not a
  number from 0 to 100, `coverage-warn` above `coverage-good`, a
  `working-directory` that is not a directory, a branch name that is not a
  valid branch name) and for a coverage report as above. A repository with no
  code file passes with a notice and badges that show `0`.
 - **Not in the first version:** a badge per language (the JSON holds the
  numbers), lcov and other report formats, branch or function coverage, and
  counting only tracked files.
 ## Consequences
 **Positive:**
 - No tool is installed and nothing is downloaded: a run needs only the
  checkout, Python 3 and the instance, so the counter and the renderer are
  fully testable offline with fixtures.
 - The same input gives the same bytes, so an unchanged repository produces no
  commit and the `badges` branch history is the history of the numbers.
 - The badges have stable URLs on the instance and on the mirror, and nothing
  on the default branch changes.
 - A broken or missing report is a failure that names the file, never a
  misleading `0%`.
 **Negative:**
 - The counter knows only the listed languages and simple scanning rules; some
  string forms are mis-counted (stated above), and results will differ a
  little from `cloc` or `tokei`.
 - The workflow needs `contents: write`, which is more than the
  `contents: read` of the quality checks; a caller that grants less cannot use
  it. The write is limited to the `badges` branch by the script, not by the
  host.
 - A caller must run its tests and produce a Cobertura XML report before the
  call; other formats need a conversion until a later release adds them.
 - A fixed set of thresholds and colours; a caller can move the two thresholds
  only.
 - Security: the script runs with a token that can write to the repository.
  The files are ours and no code is downloaded, but a caller that pins
  `tools-ref` to a moving ref takes later changes of the script; the guide
  says to pin the exact tag. The script writes only the four named files, and
  the branch name input is validated so that it cannot name the default branch
  (`main`, `master`) or a branch of the caller's code.
 ## Affected Artifacts
 - [MIL-010] — decides its criterion 2 and unlocks tasks 4 to 6.
 - [UC-008] — the use case this workflow serves.
 - [US-001] — US-001.18 to US-001.20 state their acceptance criteria.
 - [ADR-0005] — the contract style that this decision follows, unchanged.
 - [ADR-0006] — adding a language, or changing a colour or a default, is a
  release under its rules; raising a default threshold is breaking.
 ---
 [MIL-010]: ../milestones/mil-010-code-metrics-badges.md
 [UC-008]: ../uc-008/uc.md
 [US-001]: ../user-stories.md
 [ADR-0005]: ./adr-0005-quality-check-contract.md
 [ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
@@ -11,9 +11,9 @@ each document lives in *this* project and the next version to use.
 | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
 | PP | Project Plan | docs/project-plan.md | 002 |
 | MIL | Milestone / Gateway | docs/milestones/*.md | 011 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 072 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 073 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0010 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0011 |
 | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
 | US | User Story | docs/user-stories.md | 002 |
 | UC | Use Case | docs/uc-NNN/uc.md | 009 |
@@ -0,0 +1,54 @@
 # Review Record: ADR-0010 (contract of the code metrics and coverage badges workflow)
 ## Metadata
 | Key | Value |
 | --- | --- |
 | ID | RC-072 |
 | CrossReference | [ADR-0010], [QC-ADR-001] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | pending |
 ---
 ## Artifact Under Review
 - Instance reviewed: [ADR-0010]
 - Checklist used: [QC-ADR-001]
 - Scope: full review (MIL-010 task 2)
 - Language and domain: n/a (technical type)
 - Language reviewer: none
 - Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
 ## Checklist Results
 | # | Criterion | Status | Evidence/Notes |
 | --- | --- | --- | --- |
 | 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0010 in `adr-0010-code-metrics-badges-contract.md`; the previous ADR is ADR-0009. |
 | 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Problem, the decisions of the user, facts about the runner and the checkout directory, two counter options and three delivery options. |
 | 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Wrap an existing counter or write one; run artifact, default branch or a branch. |
 | 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | A reusable workflow with three script files and a `badges` branch; the rules follow as a list. |
 | 5 | Consequences list both Positive and Negative outcomes | Pass | Four positive, five negative. |
 | 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security (a write token, a moving `tools-ref`, branch name validation), compatibility (report formats), maintainability (language table). |
 | 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-010, UC-008, US-001, ADR-0005, ADR-0006 in both. |
 | 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | One row, Accepted, commit `pending` until the commit exists. |
 | 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Neither superseded nor deprecated. |
 | 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | SVG, XML and NUL are standard; Cobertura is named as a format. |
 | 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Accepted. |
 ## Overall Verdict
 Go - all applicable criteria pass; the decisions of the user of 2026-10-14 are recorded and not reopened. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
 ## Action Items
 | Action | Owner | Due |
 | --- | --- | --- |
 | None | - | - |
 ---
 [ADR-0010]: ../../adr/adr-0010-code-metrics-badges-contract.md
 [QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
@@ -4,13 +4,13 @@
 | Key | Value |
 | --- | --- |
 | ID | TM-001 |
-| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [UC-008], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [RC-069], [RC-070], [RC-071], [ADR-0007], [ADR-0008], [ADR-0009], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
+| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [UC-008], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [RC-069], [RC-070], [RC-071], [RC-072], [ADR-0007], [ADR-0008], [ADR-0009], [ADR-0010], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
 | 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-010, RC-067 and RC-068 (code metrics and coverage badges) | [5002450] |
 | 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added UC-008, RC-069 to RC-071 (code metrics badges, MIL-010 task 1) | pending |
 | 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Added ADR-0010, RC-072 (contract of the code metrics badges, MIL-010 task 2) | pending |
 ---
@@ -31,6 +31,7 @@ updated whenever an artifact instance is created or reviewed.
 | [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | [MIL-003], [MIL-005] | [RC-005], [RC-027] |
 | [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-004] | [RC-006], [RC-028], [RC-033], [RC-039] |
 | [MIL-004] | MIL | [BC-001], [PP-001], [MIL-003] | - | [RC-007], [RC-029], [RC-034], [RC-048] |
 | [ADR-0010] | ADR | [MIL-010], [UC-008], [US-001], [ADR-0005], [ADR-0006] | - | [RC-072] |
 | [RC-001] | RC | [BC-001] | - | - |
 | [RC-002] | RC | [PP-001] | - | - |
 | [RC-003] | RC | [MIL-001] | - | - |
@@ -127,6 +128,7 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-069] | RC | [UC-008] | - | - |
 | [RC-070] | RC | [US-001] | - | - |
 | [RC-071] | RC | [UCD-001] | - | - |
 | [RC-072] | RC | [ADR-0010] | - | - |
 ## Coverage Notes
@@ -150,6 +152,7 @@ updated whenever an artifact instance is created or reviewed.
 [MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
 [MIL-010]: ../milestones/mil-010-code-metrics-badges.md
 [MIL-009]: ../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
 [ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md
 [RC-001]: ./reviews/rc-001-business-case.md
 [RC-002]: ./reviews/rc-002-project-plan.md
 [RC-003]: ./reviews/rc-003-mil-001.md
@@ -231,6 +234,7 @@ updated whenever an artifact instance is created or reviewed.
 [RC-069]: ./reviews/rc-069-uc-008.md
 [RC-070]: ./reviews/rc-070-us-001-metrics.md
 [RC-071]: ./reviews/rc-071-ucd-001-metrics.md
 [RC-072]: ./reviews/rc-072-adr-0010.md
 [ADR-0008]: ../adr/adr-0008-cpp-csharp-quality-check-contract.md
 [ADR-0009]: ../adr/adr-0009-wiki-publishing-reusable-workflow.md
 [ADR-0007]: ../adr/adr-0007-release-publish-destination.md
@@ -240,4 +244,3 @@ updated whenever an artifact instance is created or reviewed.
 [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
 [UC-005]: ../uc-005/uc.md
 [ADR-0005]: ../adr/adr-0005-quality-check-contract.md
 [5002450]: https://git.tirsystem.com/TirSystem/github-action/commit/50024505fe788b1c5e3021c0d1fc3d079590070e