qmstrace thread¶

TL;DR

qmstrace thread <ID> walks one item backward to what it derives from, and forward to what hangs off it — for a requirement, its design elements, code and tests; for a clause, every item here that derives from it. Each item appears once, nearest first. It stops at this repo's edge.

Synopsis¶

Usage: qmstrace thread [OPTIONS] {ID}

  Walk one item backward to what it derives from, and forward to what hangs off
  it.

  Each item is shown once, nearest first, under the link that reaches it first.
  It stops at this repo's edge.

Arguments:
  ID  A requirement, design element, test or clause ID.  [required]

Options:
  -C PATH  Run as if qmstrace had been started in PATH, as with git -C. Before
           or after the command.
  --help   Show this message and exit.

Any ID the run can see works: a requirement or a design element, a module's path, a test's ID (file::function, as pytest names it), a clause the agreement declares, or an item of a sibling repo. -C goes on either side of the command, as with status.

Output¶

A requirement — backward to its clause, forward to its design, code and tests:

REQ-SVC-01 — A call carries a key
  requirement · docs/req/service-srs.md:12

backward — what it derives from:
  Origin  AGR-1 · origin clause, in the agreement

forward — what hangs off it, nearest first:
  Satisfies   DSN-SVC-01 — Key check · design element · docs/design/service-design.md:8
    Implements  src/service/keys.py · component
    verifies    tests/unit/test_keys.py::TestTheKeyCheck::test_it_runs_before_any_handler · automated test, unit
    Assumes     DSN-SVC-02 — Record store · design element · docs/design/service-design.md:13 · assumes it — counts toward no coverage
      Implements  src/service/store.py · component
      verifies    tests/integration/test_store.py::test_a_record_survives_a_restart · automated test, integration
  verifies    tests/unit/test_keys.py::test_a_call_without_a_valid_key_is_refused · automated test, unit

forward: 2 design elements, 2 components, 3 automated tests · backward: 1 origin clause — this repo only

An automated test, walked back to the clauses it serves:

tests/integration/test_store.py::test_a_record_survives_a_restart
  automated test, integration

backward — what it derives from:
  verifies  DSN-SVC-02 — Record store · design element · docs/design/service-design.md:13
    Assumes   DSN-SVC-01 — Key check · design element · docs/design/service-design.md:8 · assumed — what it derives from is not followed
  verifies  REQ-SVC-02 — Records survive a restart · requirement · docs/req/service-srs.md:21 · also Satisfies from DSN-SVC-02
    Origin    AGR-2 · origin clause, in the agreement
    Origin    AGR-3 · origin clause, in the agreement

forward — what hangs off it, nearest first:
  nothing here hangs off it

forward: nothing · backward: 1 requirement, 2 design elements, 2 origin clauses — this repo only

A clause, and everything here that derives from it:

AGR-3
  origin clause, in the agreement

backward — what it derives from:
  declared in the agreement, outside any product repo

forward — what hangs off it, nearest first:
  Origin      REQ-SVC-02 — Records survive a restart · requirement · docs/req/service-srs.md:21
    Satisfies   DSN-SVC-02 — Record store · design element · docs/design/service-design.md:13
      Implements  src/service/store.py · component
    verifies    tests/integration/test_store.py::test_a_record_survives_a_restart · automated test, integration · also verifies DSN-SVC-02
    verifies    tests/integration/test_store.py::test_a_restart_loses_no_accepted_record · automated test, integration
  Origin      REQ-SVC-03 — The record format is written down · requirement · docs/req/service-srs.md:28

forward: 2 requirements, 1 design element, 1 component, 2 automated tests · backward: nothing — this repo only

A sibling's item — this repo's side of it only:

REQ-SVC-01 — A call carries a key
  requirement, in sibling service — not pinned · ../service/docs/req/service-srs.md:12

backward — what it derives from:
  declared in sibling service — what it derives from there is not shown

forward — what hangs off it, nearest first:
  verifies  tests/unit/test_api.py::test_the_service_refuses_a_call_without_a_key · automated test, unit

forward: 1 automated test · backward: nothing — this repo only

The same item in a pipeline, where the sibling and the ledger are not checked out:

REQ-SVC-01
  not verified here — judged at the ledger's import
  external AGR-*: NOT VERIFIED — ../ledger/agreement.md is not reachable; each cited AGR-N is judged at the ledger's import
  sibling service: NOT REACHABLE at ../service

backward — what it derives from:
  not verified here — judged at the ledger's import

forward — what hangs off it, nearest first:
  verifies  tests/unit/test_api.py::test_the_service_refuses_a_call_without_a_key · automated test, unit

forward: 1 automated test · backward: nothing — this repo only

When an assumption and an ordinary ancestry path reach the same item backward, the ordinary path is used so its origins remain visible; the assumption is retained as also. To combine several starting items into a change-request candidate, use impact.

Reading a line¶

Part	Example	What it says
the marker	`Satisfies`	the link that reaches this item first; each step of indentation is one more link from the item you asked about
the item	`DSN-SVC-01 — Key check · design element · docs/design/…:8`	its ID, title, type and where it is written; a sibling's item carries the sibling's path, and not pinned
`also …`	`also Satisfies from DSN-SVC-02`	another link between this item and one already shown — the item is not repeated
`assumes it — counts toward no coverage`		an `Assumes` link, followed forward: what the assuming item relies on changing can break it
`assumed — what it derives from is not followed`		walking backward, an assumption ends the walk
the last line	`forward: 2 design elements, … — this repo only`	counts by type, in both directions

When the run could not read something — an external source, a sibling — or refused links as violations, the lines under the heading say so. An empty direction says nothing here hangs off it. Why each item appears once, and where the walk stops: The chain.

Exit code¶

0 — or 2 for an ID nothing here can see, with the closest IDs it can. In a pipeline, where a sibling could not be read, it says so instead of calling the ID missing. See Exit codes.