Findings¶
TL;DR
A finding is one thing wrong or unfinished in a repo, on one line: a code, where it is, what
is wrong, and what to do next. A code's first letter is its kind. This version reports
violations — the V codes below, which are qmstrace's own — and gaps, whose G codes are
the project's, printed by qmstrace rules. S01 lists a downstream item needing review.
The shape of a finding¶
Every finding carries the same four parts, and the last one is never left out:
| Part | Example | What it is |
|---|---|---|
| code | V09 |
stable, classed by its first letter |
| where | docs/req/service-srs.md:14 |
the file and line to open |
| what is wrong | the agreement declares no AGR-9 |
the fact, with the IDs involved |
| next move | Fix: cite a real one, or tell the developer that nothing covers this — never invent one. |
what to do, and, where a wrong move is tempting, which one not to make |
Kinds¶
| Letter | Kind | What it fails | In this version |
|---|---|---|---|
V |
violation | always — the trace data is wrong at any stage | reported |
G |
gap | only the gate — a coverage rule not met yet; its codes come from the project's trace schema | reported |
S |
suspect | never — downstream of changed or deleted frozen text | reported |
The catalogue¶
| Code | Kind | What is wrong |
|---|---|---|
| S01 | suspect | an existing local item downstream of changed or removed frozen content needs review |
| V01 | violation | an ID declared twice — in this repo, or already in a sibling |
| V02 | violation | an ID of this repo's kind that does not match its pattern |
| V03 | violation | a link to an ID that exists nowhere this run could read |
| V04 | violation | a link whose source or target is a kind of item the link type does not allow |
| V05 | violation | a required field missing, or a value outside its list |
| V06 | violation | a test with no level — not under a level folder |
| V07 | violation | an item declared in a file that is not scanned for its type |
| V08 | violation | a file that cannot be read or parsed |
| V09 | violation | an external ID its source does not declare |
| V10 | violation | a controlled item changed or added without a fresh change-request citation |
| V11 | violation | a cited change request does not exist, is malformed, or is not accepted |
| V12 | violation | a cited change request does not list the item under Impacts |
| V13 | violation | a frozen item's heading was removed |
| V14 | violation | a link field that holds something other than IDs |
| V15 | violation | a verifies marker in a form this tool does not read |
| V16 | violation | an ID of this repo's kind, declared nowhere, written where it declares nothing |
V10 to V13 are emitted by the baseline guard.
V16 is the one violation found in a baseline tag's tree that does not stop the tag being
read: it declares nothing. How to avoid it: write traced docs.
S01 is a suspect; its next move starts with Review: and does not claim
that review or approval has happened.
qmstrace status counts violations and gaps by code on its last line;
qmstrace check lists each one, with its place and next move. A gap's code
and words come from the project's rule — see qmstrace rules — and its next
move from qmstrace: the form of the marker to write, or the violation to fix first.