tracenamespacenamespace traceTrace: every source file tied to a requirement, every requirement proved, every ontology term citing its specification (commons 0015-trace FR-001 to FR-008). Pure functions over the contents of files a harness passes in: the specifications (specs/NNN-slug/spec.md and reviewed.tsv), the source files and their // Spec: lines, the tests and their proves([...]) calls and // Proves: lines, and the ontology's citations. The findings are data, held against a baseline that may only shrink; the layers check (layers.ts) gives its findings in the same shape and is judged the same way.
A citation is // Spec: 097-controller FR-001, FR-003 to FR-005; 098-pair (a spec with no requirement cites all of it). A baseline is a plain text file of finding keys, one a line, sorted: the tool writes it, a person only deletes lines from it, and nothing in it runs when it is read (FR-002).
import { judge, parseSpec, traceFindings } from "./trace.ts";
const spec = parseSpec("001-demo", "**Status:** Active\n\n- **FR-001**: It MUST work.\n");
const found = traceFindings({ specs: [spec], sources: [{ path: "src/a.ts", text: "// Spec: 001-demo FR-001\n" }], tests: [], ontology: [] });
judge(found, []); // { fresh: [the unproved FR-001], stale: [], kept: [] }tracenamespacenamespace tracetrace.TraceRuletypeno test imports ittype TraceRule =
| "trace/no-spec-line"
| "trace/unknown-spec"
| "trace/unknown-requirement"
| "trace/unproved"
| "trace/term-uncited"
| "trace/term-unknown-spec";The rules of the trace check (FR-007).
trace.LayerRuletypeno test imports ittype LayerRule = "layers/unclassified" | "layers/ambiguous" | "layers/above" | "layers/around";The rules of the layers check (layers.ts, FR-009, FR-010).
trace.Ruletypeno test imports ittype Rule = TraceRule | LayerRule;Every rule a finding may be of.
trace.Findingtypeno test imports ittype Finding = {
/** The file, relative to the repository, with `/`. */
readonly file: string;
/** The line, from 1 (1 for a whole file). */
readonly line: number;
/** The rule's id. */
readonly rule: Rule;
/** One plain sentence. */
readonly message: string;
/** `<rule> <file>`, and what the finding is about where a file holds several of one rule. */
readonly key: string;
};A finding (FR-001): where, by which rule, one sentence, and a key that names it without its line.
trace.Keyedtypeno test imports ittype Keyed = {
readonly file: string;
readonly line: number;
readonly rule: string;
readonly message: string;
readonly key: string;
};What a baseline and its judgement need of a finding, whatever its rule: a harness's own rules (commons 0003-mizan FR-015) use the same baseline as the trace and layers checks.
trace.findingfunctionno test imports itfunction finding(rule: Rule, file: string, line: number, message: string, about?: string | undefined): FindingA finding, its key made from its rule, its file and what it is about.
trace.SourceFiletypeno test imports ittype SourceFile = { readonly path: string; readonly text: string };A file a harness passes in: its path relative to the repository, with /, and its text.
trace.isGeneratedfunctionno test imports itfunction isGenerated(path: string): booleanWhether a file is generated, so exempt from the trace's rules: its name holds .auto. (FR-007).
trace.parseBaselinefunctionno test imports itfunction parseBaseline(text: string): readonly string[]The keys of a baseline file: every line that is not blank and not a # comment, trimmed, each once.
trace.formatBaselinefunctionno test imports itfunction formatBaseline(findings: readonly Keyed[], comments?: readonly string[]): stringA baseline file from findings: the comment lines given (each prefixed # ), then the keys sorted by code point, each once.
trace.Judgementtypeno test imports ittype Judgement<F extends Keyed = Finding> = {
/** Findings whose key the baseline does not hold: they fail the check. */
readonly fresh: readonly F[];
/** Baseline keys no finding has: they fail the check until they are deleted. */
readonly stale: readonly string[];
/** Findings the baseline holds. */
readonly kept: readonly F[];
};A judgement of findings against a baseline: the new findings, the stale keys, and the findings the baseline keeps.
trace.judgefunctionno test imports itfunction judge<F extends Keyed>(findings: readonly F[], baseline: readonly string[]): Judgement<F>Findings judged against a baseline's keys (FR-002).
trace.passesfunctionno test imports itfunction passes(j: Judgement<Keyed>): booleanWhether a judgement passes: nothing new and nothing stale.
trace.reportfunctionno test imports itfunction report(j: Judgement<Keyed>, name: string, baselineFile: string): readonly string[]The lines a judgement is told with (FR-003): each new finding, each stale key, then a summary. name names the check and its baseline.
trace.SpecRequirementtypeno test imports ittype SpecRequirement = { readonly id: string; readonly line: number };A requirement of a specification and the line of spec.md it is on.
trace.Spectypeno test imports ittype Spec = {
/** Its folder's name, `NNN-slug`. */
readonly slug: string;
/** The first word of its status, where its head states one. */
readonly status: string | undefined;
/** Its requirements, in order. */
readonly requirements: readonly SpecRequirement[];
/** The requirements its `reviewed.tsv` reviews (`FR-NNN`). */
readonly reviewed: readonly string[];
};A specification as the trace reads it (FR-004).
trace.parseSpecfunctionno test imports itfunction parseSpec(slug: string, specText: string, reviewedText?: string): SpecA specification read from its spec.md and, where it has one, its reviewed.tsv (FR-004).
trace.inForcefunctionno test imports itfunction inForce(spec: Spec): booleanWhether a spec is held to proofs: its status is neither Draft nor Retired (FR-007).
trace.Citedtypeno test imports ittype Cited = { readonly kind: "one"; readonly id: string } | { readonly kind: "range"; readonly from: string; readonly to: string };A requirement or a range of them, as a citation writes it.
trace.Citationtypeno test imports ittype Citation = { readonly line: number; readonly spec: string; readonly requirements: readonly Cited[] };One group of a citation: a spec, and the requirements it names (none: the whole spec).
trace.parseCitationfunctionno test imports itfunction parseCitation(text: string, line: number): readonly Citation[]The groups of a citation's text (097-controller FR-001, FR-003 to FR-005; 098-pair), at a line.
trace.commentLinesfunctionno test imports itfunction commentLines(text: string): readonly { readonly line: number; readonly body: string; }[]The text of each line of a file that is a comment line (FR-005, FR-012), with its line number: a line that begins with two slashes and a space gives what follows; a line inside a block comment (from a line that begins with a slash and an asterisk to the asterisk and slash that close it) gives what follows its leading asterisk, without the closing pair. A line of code that holds a comment after the code is not a comment line.
trace.specLinesfunctionno test imports itfunction specLines(text: string): readonly Citation[]Every citation of a file's Spec: lines (FR-005, FR-012): // Spec: ..., and Spec: ... as a line of a block comment.
trace.Prooftypeno test imports ittype Proof = { readonly line: number; readonly spec: string; readonly requirement: Cited };A requirement, or a range of them, a test names, and its line.
trace.proofsOffunctionno test imports itfunction proofsOf(text: string): readonly Proof[]Every requirement a test file proves (FR-006, FR-012): in the array a proves( call opens, and on its // Proves: lines and the Proves: lines of its block comments.
trace.OntologyCitationtypeno test imports ittype OntologyCitation = { readonly term: string; readonly cites: readonly string[]; readonly file: string; readonly line?: number };An ontology term and what it cites: specs (NNN-slug) or requirements (NNN-slug FR-NNN), and where it is stated.
trace.CitingSchematypeno test imports ittype CitingSchema = { readonly class: { readonly iri: string }; readonly fields: Fields };What citationsOf reads of a class schema: its class and its fields.
trace.citationsOffunctionno test imports itfunction citationsOf(schemas: readonly CitingSchema[], individuals: readonly AnyIndividual[], file: string, field?: string, termOf?: (iri: string) => string): readonly OntologyCitation[]The citations of the individuals made by schemas that have a field field (spec by default): its values, or none (FR-008).
trace.TraceInputtypeno test imports ittype TraceInput = {
/** The specifications. */
readonly specs: readonly Spec[];
/** The source files, each to carr… (493 characters)type TraceInput = {
/** The specifications. */
readonly specs: readonly Spec[];
/** The source files, each to carry a `// Spec:` line. */
readonly sources: readonly SourceFile[];
/** The test files, whose proofs are read. */
readonly tests: readonly SourceFile[];
/** The ontology's terms and their citations. */
readonly ontology: readonly OntologyCitation[];
/** Where the specifications are, from the repository (`specs` by default). */
readonly specsFolder?: string;
};What the trace check reads (FR-007).
trace.traceFindingsfunctionno test imports itfunction traceFindings(input: TraceInput): readonly Finding[]Every finding of the trace (FR-007), in the order: sources, specifications, ontology.
TraceRuletypeno test imports ittype TraceRule =
| "trace/no-spec-line"
| "trace/unknown-spec"
| "trace/unknown-requirement"
| "trace/unproved"
| "trace/term-uncited"
| "trace/term-unknown-spec";The rules of the trace check (FR-007).
LayerRuletypeno test imports ittype LayerRule = "layers/unclassified" | "layers/ambiguous" | "layers/above" | "layers/around";The rules of the layers check (layers.ts, FR-009, FR-010).
Ruletypeno test imports ittype Rule = TraceRule | LayerRule;Every rule a finding may be of.
Findingtypeno test imports ittype Finding = {
/** The file, relative to the repository, with `/`. */
readonly file: string;
/** The line, from 1 (1 for a whole file). */
readonly line: number;
/** The rule's id. */
readonly rule: Rule;
/** One plain sentence. */
readonly message: string;
/** `<rule> <file>`, and what the finding is about where a file holds several of one rule. */
readonly key: string;
};A finding (FR-001): where, by which rule, one sentence, and a key that names it without its line.
Keyedtypeno test imports ittype Keyed = {
readonly file: string;
readonly line: number;
readonly rule: string;
readonly message: string;
readonly key: string;
};What a baseline and its judgement need of a finding, whatever its rule: a harness's own rules (commons 0003-mizan FR-015) use the same baseline as the trace and layers checks.
findingfunctionfunction finding(rule: Rule, file: string, line: number, message: string, about?: string | undefined): FindingA finding, its key made from its rule, its file and what it is about.
SourceFiletypetype SourceFile = { readonly path: string; readonly text: string };A file a harness passes in: its path relative to the repository, with /, and its text.
isGeneratedfunctionno test imports itfunction isGenerated(path: string): booleanWhether a file is generated, so exempt from the trace's rules: its name holds .auto. (FR-007).
parseBaselinefunctionfunction parseBaseline(text: string): readonly string[]The keys of a baseline file: every line that is not blank and not a # comment, trimmed, each once.
formatBaselinefunctionfunction formatBaseline(findings: readonly Keyed[], comments?: readonly string[]): stringA baseline file from findings: the comment lines given (each prefixed # ), then the keys sorted by code point, each once.
Judgementtypeno test imports ittype Judgement<F extends Keyed = Finding> = {
/** Findings whose key the baseline does not hold: they fail the check. */
readonly fresh: readonly F[];
/** Baseline keys no finding has: they fail the check until they are deleted. */
readonly stale: readonly string[];
/** Findings the baseline holds. */
readonly kept: readonly F[];
};A judgement of findings against a baseline: the new findings, the stale keys, and the findings the baseline keeps.
judgefunctionfunction judge<F extends Keyed>(findings: readonly F[], baseline: readonly string[]): Judgement<F>Findings judged against a baseline's keys (FR-002).
passesfunctionfunction passes(j: Judgement<Keyed>): booleanWhether a judgement passes: nothing new and nothing stale.
reportfunctionfunction report(j: Judgement<Keyed>, name: string, baselineFile: string): readonly string[]The lines a judgement is told with (FR-003): each new finding, each stale key, then a summary. name names the check and its baseline.
SpecRequirementtypeno test imports ittype SpecRequirement = { readonly id: string; readonly line: number };A requirement of a specification and the line of spec.md it is on.
Spectypeno test imports ittype Spec = {
/** Its folder's name, `NNN-slug`. */
readonly slug: string;
/** The first word of its status, where its head states one. */
readonly status: string | undefined;
/** Its requirements, in order. */
readonly requirements: readonly SpecRequirement[];
/** The requirements its `reviewed.tsv` reviews (`FR-NNN`). */
readonly reviewed: readonly string[];
};A specification as the trace reads it (FR-004).
parseSpecfunctionfunction parseSpec(slug: string, specText: string, reviewedText?: string): SpecA specification read from its spec.md and, where it has one, its reviewed.tsv (FR-004).
inForcefunctionno test imports itfunction inForce(spec: Spec): booleanWhether a spec is held to proofs: its status is neither Draft nor Retired (FR-007).
Citedtypeno test imports ittype Cited = { readonly kind: "one"; readonly id: string } | { readonly kind: "range"; readonly from: string; readonly to: string };A requirement or a range of them, as a citation writes it.
Citationtypeno test imports ittype Citation = { readonly line: number; readonly spec: string; readonly requirements: readonly Cited[] };One group of a citation: a spec, and the requirements it names (none: the whole spec).
parseCitationfunctionfunction parseCitation(text: string, line: number): readonly Citation[]The groups of a citation's text (097-controller FR-001, FR-003 to FR-005; 098-pair), at a line.
commentLinesfunctionno test imports itfunction commentLines(text: string): readonly { readonly line: number; readonly body: string; }[]The text of each line of a file that is a comment line (FR-005, FR-012), with its line number: a line that begins with two slashes and a space gives what follows; a line inside a block comment (from a line that begins with a slash and an asterisk to the asterisk and slash that close it) gives what follows its leading asterisk, without the closing pair. A line of code that holds a comment after the code is not a comment line.
specLinesfunctionfunction specLines(text: string): readonly Citation[]Every citation of a file's Spec: lines (FR-005, FR-012): // Spec: ..., and Spec: ... as a line of a block comment.
Prooftypeno test imports ittype Proof = { readonly line: number; readonly spec: string; readonly requirement: Cited };A requirement, or a range of them, a test names, and its line.
proofsOffunctionfunction proofsOf(text: string): readonly Proof[]Every requirement a test file proves (FR-006, FR-012): in the array a proves( call opens, and on its // Proves: lines and the Proves: lines of its block comments.
OntologyCitationtypeno test imports ittype OntologyCitation = { readonly term: string; readonly cites: readonly string[]; readonly file: string; readonly line?: number };An ontology term and what it cites: specs (NNN-slug) or requirements (NNN-slug FR-NNN), and where it is stated.
CitingSchematypeno test imports ittype CitingSchema = { readonly class: { readonly iri: string }; readonly fields: Fields };What citationsOf reads of a class schema: its class and its fields.
citationsOffunctionfunction citationsOf(schemas: readonly CitingSchema[], individuals: readonly AnyIndividual[], file: string, field?: string, termOf?: (iri: string) => string): readonly OntologyCitation[]The citations of the individuals made by schemas that have a field field (spec by default): its values, or none (FR-008).
traceFindingsfunctionfunction traceFindings(input: TraceInput): readonly Finding[]Every finding of the trace (FR-007), in the order: sources, specifications, ontology.