From aa4ca0f897b7ea20d90745aa4b7d7a215df123a8 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Wed, 14 Oct 2026 13:43:15 +0800 Subject: [PATCH] MIL-010 task 2: ADR-0010, the contract of the code metrics badges (RC-072) Refs #156 --- .../adr-0010-code-metrics-badges-contract.md | 203 ++++++++++++++++++ docs/artifact-registry.md | 4 +- docs/sqa/reviews/rc-072-adr-0010.md | 54 +++++ docs/sqa/traceability-matrix.md | 9 +- 4 files changed, 265 insertions(+), 5 deletions(-) create mode 100644 docs/adr/adr-0010-code-metrics-badges-contract.md create mode 100644 docs/sqa/reviews/rc-072-adr-0010.md diff --git a/docs/adr/adr-0010-code-metrics-badges-contract.md b/docs/adr/adr-0010-code-metrics-badges-contract.md new file mode 100644 index 0000000..59a0c86 --- /dev/null +++ b/docs/adr/adr-0010-code-metrics-badges-contract.md @@ -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 `` 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 diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 1d51d75..1239ca2 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.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 | diff --git a/docs/sqa/reviews/rc-072-adr-0010.md b/docs/sqa/reviews/rc-072-adr-0010.md new file mode 100644 index 0000000..70c7f1f --- /dev/null +++ b/docs/sqa/reviews/rc-072-adr-0010.md @@ -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 diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 20cbbbf..b6f58e1 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.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