IF Commons GitHub

changes/capability-trace

The capability view and the trace, offline (commons 0020-ifccm FR-035 to FR-038): for each capability a range of commits serves, the requirements it concerns, and for each requirement the terms, the code and the tests that link it, placed on the rungs of the ladder, with the stage where its chain ends. No Git host is asked: a capability is a change request a commit's Refs #N or Closes #N line names, and everything else is read from files.

Pure: the commits (their messages, the files they changed and the requirements their changes to a spec.md added or edited), the specifications, the ontology's citations (mz:definedBy), the source and test files (Spec: and Proves: lines, proves calls) and the cases of a quality run are arguments, and so are the bodies and titles of the change requests, where a harness has kept them as a JSON file (parseIssues). A requirement concerns a capability when a commit of it names the requirement in its message, a commit changed the requirement's line in its specification, the change request's Done when names it, or a source or test file a commit changed cites it. The chain of each requirement is traceOf's, so that the stages are the ones of ifccm:TraceStage; each artefact is then placed on the rung whose home matches it most specifically (kernel/layers.ts), and an artefact no home matches is on the rung -. Output is data (traceJson, deterministic: sorted, no clock, LF) and a table of text (traceTable).

import { capabilityTrace, traceTable } from "./capability-trace.ts";
const t = capabilityTrace({
  commits: [{ sha: "a".repeat(40), subject: "Add it", message: "Add it\n\nRefs #3\n", files: ["src/a.ts"], requirements: ["0001-x FR-001"] }],
  issues: [], specs: [{ slug: "0001-x", spec: "- **FR-001**: It MUST work.\n" }], terms: [], sources: [], tests: [], cases: [], rungs: [],
});
traceTable(t).split("\n")[2]?.startsWith("#3"); // true

Source: commons/mizan/src/changes/capability-trace.ts

4 of 32 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

changes.capabilityTracefunctionno test imports it
function capabilityTrace(input: CapabilityTraceInput): CapabilityTraceResult

The trace of the capabilities a range of commits serves (0020-ifccm FR-035).

changes.NO_RUNGconstno test imports it
const NO_RUNG: "-"

The id of the rung of an artefact no rung's home matches.

changes.parseIssuesfunctionno test imports it
function parseIssues(text: string): Result<readonly IssueFact[], string>

The change requests of a JSON file a harness keeps offline: an array of { number, title?, body? }, or an object with that array as issues.

changes.traceJsonfunctionno test imports it
function traceJson(t: CapabilityTraceResult): string

The trace as deterministic JSON (2-space indent, LF, one newline at the end): the same text for the same input, so that it can be kept and compared.

changes.traceOutputfunctionno test imports it
function traceOutput(t: CapabilityTraceResult, format: TraceFormat): string

The trace in a format.

changes.traceTablefunctionno test imports it
function traceTable(t: CapabilityTraceResult): string

The trace as a table of text, one line for each requirement on each rung, with the stage where its chain ends (whole where it does not).

changes.Basistypeno test imports it
type Basis = "commit" | "spec" | "issue" | "code" | "test";

Why a requirement concerns a capability.

changes.CapabilityCommittypeno test imports it
type CapabilityCommit = {
  readonly sha: string;
  readonly subject: string;
  readonly message: string;
  readonly files: readonly string[];
  readonly requirements: readonly string[];
};

A commit as the trace reads it: its object name, subject, whole message, the files it changed and the requirements (NNNN-slug FR-nnn) whose lines in a spec.md it added or edited.

changes.CapabilityTracetypeno test imports it
type CapabilityTrace = { readonly number: number; readonly title: string | undefined; /** The commits that name it… (414 characters)
type CapabilityTrace = {
  readonly number: number;
  readonly title: string | undefined;
  /** The commits that name it, oldest first, by their object names. */
  readonly commits: readonly string[];
  /** Whether a commit of it says `Closes`. */
  readonly closed: boolean;
  /** The rungs its changed files are on. */
  readonly rungs: readonly string[];
  readonly requirements: readonly RequirementTrace[];
};

One capability: a change request the commits name.

changes.CapabilityTraceInputtypeno test imports it
type CapabilityTraceInput = { readonly commits: readonly CapabilityCommit[]; readonly issues: readonly IssueFact[]; … (705 characters)
type CapabilityTraceInput = {
  readonly commits: readonly CapabilityCommit[];
  readonly issues: readonly IssueFact[];
  readonly specs: readonly SpecSource[];
  /** The ontology's citations: each term, the requirements it cites (`mz:definedBy`) and, where known, the file that states it. */
  readonly terms: readonly OntologyCitation[];
  readonly sources: readonly SourceFile[];
  readonly tests: readonly SourceFile[];
  readonly cases: readonly RunCase[];
  readonly rungs: readonly TraceRung[];
  /** Where a specification's `spec.md` is, from the root of the repository (`specs/<slug>/spec.md` where not given), so that it is placed on a rung. */
  readonly specPath?: (slug: string) => string;
};

What the trace reads.

changes.CapabilityTraceResulttypeno test imports it
type CapabilityTraceResult = {
  readonly rungs: readonly { readonly id: string; readonly label: string }[];
  readonly capabilities: readonly CapabilityTrace[];
  /** The commits that name no change request of this repository. */
  readonly unreferenced: readonly string[];
};

The trace of a range.

changes.IssueFacttypeno test imports it
type IssueFact = { readonly number: number; readonly title?: string; readonly body?: string };

A change request as a harness keeps it offline: its number and, where it has them, its title and body.

changes.RequirementTracetypeno test imports it
type RequirementTrace = { readonly requirement: string; readonly basis: readonly Basis[]; /** The stages of the ch… (518 characters)
type RequirementTrace = {
  readonly requirement: string;
  readonly basis: readonly Basis[];
  /** The stages of the chain, each linked or not (`ifccm:TraceStage`). */
  readonly stages: readonly StageResult[];
  /** The first stage with no link, or `undefined` where the chain is whole. */
  readonly endsAt: Stage | undefined;
  /** Terms, code and tests on each rung that has any, in the order of the rungs; one row on the rung `-` where nothing links the requirement. */
  readonly rungs: readonly RungLinks[];
};

One requirement of one capability.

changes.RungLinkstypeno test imports it
type RungLinks = {
  readonly rung: string;
  readonly spec: readonly string[];
  readonly terms: readonly string[];
  readonly code: readonly string[];
  readonly tests: readonly string[];
};

What links a requirement, on one rung.

changes.TraceFormattypeno test imports it
type TraceFormat = "text" | "json";

The kinds of output the command gives.

changes.TraceRungtypeno test imports it
type TraceRung = { readonly id: string; readonly label: string; readonly homes: readonly string[] };

A rung as the trace places files on it: its identifier, its label and its homes (globs; a trailing / is everything under a folder).

capabilityTracefunction
function capabilityTrace(input: CapabilityTraceInput): CapabilityTraceResult

The trace of the capabilities a range of commits serves (0020-ifccm FR-035).

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

NO_RUNGconstno test imports it
const NO_RUNG: "-"

The id of the rung of an artefact no rung's home matches.

parseIssuesfunction
function parseIssues(text: string): Result<readonly IssueFact[], string>

The change requests of a JSON file a harness keeps offline: an array of { number, title?, body? }, or an object with that array as issues.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

traceJsonfunction
function traceJson(t: CapabilityTraceResult): string

The trace as deterministic JSON (2-space indent, LF, one newline at the end): the same text for the same input, so that it can be kept and compared.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

traceOutputfunctionno test imports it
function traceOutput(t: CapabilityTraceResult, format: TraceFormat): string

The trace in a format.

traceTablefunction
function traceTable(t: CapabilityTraceResult): string

The trace as a table of text, one line for each requirement on each rung, with the stage where its chain ends (whole where it does not).

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

Basistypeno test imports it
type Basis = "commit" | "spec" | "issue" | "code" | "test";

Why a requirement concerns a capability.

CapabilityCommittypeno test imports it
type CapabilityCommit = {
  readonly sha: string;
  readonly subject: string;
  readonly message: string;
  readonly files: readonly string[];
  readonly requirements: readonly string[];
};

A commit as the trace reads it: its object name, subject, whole message, the files it changed and the requirements (NNNN-slug FR-nnn) whose lines in a spec.md it added or edited.

CapabilityTracetypeno test imports it
type CapabilityTrace = { readonly number: number; readonly title: string | undefined; /** The commits that name it… (414 characters)
type CapabilityTrace = {
  readonly number: number;
  readonly title: string | undefined;
  /** The commits that name it, oldest first, by their object names. */
  readonly commits: readonly string[];
  /** Whether a commit of it says `Closes`. */
  readonly closed: boolean;
  /** The rungs its changed files are on. */
  readonly rungs: readonly string[];
  readonly requirements: readonly RequirementTrace[];
};

One capability: a change request the commits name.

CapabilityTraceInputtypeno test imports it
type CapabilityTraceInput = { readonly commits: readonly CapabilityCommit[]; readonly issues: readonly IssueFact[]; … (705 characters)
type CapabilityTraceInput = {
  readonly commits: readonly CapabilityCommit[];
  readonly issues: readonly IssueFact[];
  readonly specs: readonly SpecSource[];
  /** The ontology's citations: each term, the requirements it cites (`mz:definedBy`) and, where known, the file that states it. */
  readonly terms: readonly OntologyCitation[];
  readonly sources: readonly SourceFile[];
  readonly tests: readonly SourceFile[];
  readonly cases: readonly RunCase[];
  readonly rungs: readonly TraceRung[];
  /** Where a specification's `spec.md` is, from the root of the repository (`specs/<slug>/spec.md` where not given), so that it is placed on a rung. */
  readonly specPath?: (slug: string) => string;
};

What the trace reads.

CapabilityTraceResulttypeno test imports it
type CapabilityTraceResult = {
  readonly rungs: readonly { readonly id: string; readonly label: string }[];
  readonly capabilities: readonly CapabilityTrace[];
  /** The commits that name no change request of this repository. */
  readonly unreferenced: readonly string[];
};

The trace of a range.

IssueFacttypeno test imports it
type IssueFact = { readonly number: number; readonly title?: string; readonly body?: string };

A change request as a harness keeps it offline: its number and, where it has them, its title and body.

RequirementTracetypeno test imports it
type RequirementTrace = { readonly requirement: string; readonly basis: readonly Basis[]; /** The stages of the ch… (518 characters)
type RequirementTrace = {
  readonly requirement: string;
  readonly basis: readonly Basis[];
  /** The stages of the chain, each linked or not (`ifccm:TraceStage`). */
  readonly stages: readonly StageResult[];
  /** The first stage with no link, or `undefined` where the chain is whole. */
  readonly endsAt: Stage | undefined;
  /** Terms, code and tests on each rung that has any, in the order of the rungs; one row on the rung `-` where nothing links the requirement. */
  readonly rungs: readonly RungLinks[];
};

One requirement of one capability.

RungLinkstypeno test imports it
type RungLinks = {
  readonly rung: string;
  readonly spec: readonly string[];
  readonly terms: readonly string[];
  readonly code: readonly string[];
  readonly tests: readonly string[];
};

What links a requirement, on one rung.

TraceFormattypeno test imports it
type TraceFormat = "text" | "json";

The kinds of output the command gives.

TraceRungtypeno test imports it
type TraceRung = { readonly id: string; readonly label: string; readonly homes: readonly string[] };

A rung as the trace places files on it: its identifier, its label and its homes (globs; a trailing / is everything under a folder).

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