changes.capabilityTracefunctionno test imports itfunction capabilityTrace(input: CapabilityTraceInput): CapabilityTraceResultThe trace of the capabilities a range of commits serves (0020-ifccm FR-035).
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"); // truechanges.capabilityTracefunctionno test imports itfunction capabilityTrace(input: CapabilityTraceInput): CapabilityTraceResultThe trace of the capabilities a range of commits serves (0020-ifccm FR-035).
changes.NO_RUNGconstno test imports itconst NO_RUNG: "-"The id of the rung of an artefact no rung's home matches.
changes.parseIssuesfunctionno test imports itfunction 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 itfunction traceJson(t: CapabilityTraceResult): stringThe 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 itfunction traceOutput(t: CapabilityTraceResult, format: TraceFormat): stringThe trace in a format.
changes.traceTablefunctionno test imports itfunction traceTable(t: CapabilityTraceResult): stringThe 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 ittype Basis = "commit" | "spec" | "issue" | "code" | "test";Why a requirement concerns a capability.
changes.CapabilityCommittypeno test imports ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype TraceFormat = "text" | "json";The kinds of output the command gives.
changes.TraceRungtypeno test imports ittype 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).
capabilityTracefunctionfunction capabilityTrace(input: CapabilityTraceInput): CapabilityTraceResultThe trace of the capabilities a range of commits serves (0020-ifccm FR-035).
NO_RUNGconstno test imports itconst NO_RUNG: "-"The id of the rung of an artefact no rung's home matches.
parseIssuesfunctionfunction 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.
traceJsonfunctionfunction traceJson(t: CapabilityTraceResult): stringThe 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.
traceOutputfunctionno test imports itfunction traceOutput(t: CapabilityTraceResult, format: TraceFormat): stringThe trace in a format.
traceTablefunctionfunction traceTable(t: CapabilityTraceResult): stringThe 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).
Basistypeno test imports ittype Basis = "commit" | "spec" | "issue" | "code" | "test";Why a requirement concerns a capability.
CapabilityCommittypeno test imports ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype TraceFormat = "text" | "json";The kinds of output the command gives.
TraceRungtypeno test imports ittype 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).