IF Commons GitHub

trace

Trace: 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: [] }

Source: commons/mizan/src/trace.ts

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

tracenamespace
namespace trace
trace.TraceRuletypeno test imports it
type 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 it
type 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 it
type Rule = TraceRule | LayerRule;

Every rule a finding may be of.

trace.Findingtypeno test imports it
type 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 it
type 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 it
function finding(rule: Rule, file: string, line: number, message: string, about?: string | undefined): Finding

A finding, its key made from its rule, its file and what it is about.

trace.SourceFiletypeno test imports it
type 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 it
function isGenerated(path: string): boolean

Whether a file is generated, so exempt from the trace's rules: its name holds .auto. (FR-007).

trace.parseBaselinefunctionno test imports it
function 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 it
function formatBaseline(findings: readonly Keyed[], comments?: readonly string[]): string

A baseline file from findings: the comment lines given (each prefixed # ), then the keys sorted by code point, each once.

trace.Judgementtypeno test imports it
type 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 it
function 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 it
function passes(j: Judgement<Keyed>): boolean

Whether a judgement passes: nothing new and nothing stale.

trace.reportfunctionno test imports it
function 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 it
type 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 it
type 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 it
function parseSpec(slug: string, specText: string, reviewedText?: string): Spec

A specification read from its spec.md and, where it has one, its reviewed.tsv (FR-004).

trace.inForcefunctionno test imports it
function inForce(spec: Spec): boolean

Whether a spec is held to proofs: its status is neither Draft nor Retired (FR-007).

trace.Citedtypeno test imports it
type 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 it
type 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 it
function 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 it
function 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 it
function 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 it
type 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 it
function 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 it
type 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 it
type 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 it
function 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 it
type 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 it
function traceFindings(input: TraceInput): readonly Finding[]

Every finding of the trace (FR-007), in the order: sources, specifications, ontology.

TraceRuletypeno test imports it
type 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 it
type LayerRule = "layers/unclassified" | "layers/ambiguous" | "layers/above" | "layers/around";

The rules of the layers check (layers.ts, FR-009, FR-010).

Ruletypeno test imports it
type Rule = TraceRule | LayerRule;

Every rule a finding may be of.

Findingtypeno test imports it
type 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 it
type 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.

findingfunction
function finding(rule: Rule, file: string, line: number, message: string, about?: string | undefined): Finding

A finding, its key made from its rule, its file and what it is about.

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

SourceFiletype
type SourceFile = { readonly path: string; readonly text: string };

A file a harness passes in: its path relative to the repository, with /, and its text.

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

isGeneratedfunctionno test imports it
function isGenerated(path: string): boolean

Whether a file is generated, so exempt from the trace's rules: its name holds .auto. (FR-007).

parseBaselinefunction
function parseBaseline(text: string): readonly string[]

The keys of a baseline file: every line that is not blank and not a # comment, trimmed, each once.

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

formatBaselinefunction
function formatBaseline(findings: readonly Keyed[], comments?: readonly string[]): string

A baseline file from findings: the comment lines given (each prefixed # ), then the keys sorted by code point, each once.

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

Judgementtypeno test imports it
type 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.

judgefunction
function judge<F extends Keyed>(findings: readonly F[], baseline: readonly string[]): Judgement<F>

Findings judged against a baseline's keys (FR-002).

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

passesfunction
function passes(j: Judgement<Keyed>): boolean

Whether a judgement passes: nothing new and nothing stale.

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

reportfunction
function 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.

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

SpecRequirementtypeno test imports it
type SpecRequirement = { readonly id: string; readonly line: number };

A requirement of a specification and the line of spec.md it is on.

Spectypeno test imports it
type 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).

parseSpecfunction
function parseSpec(slug: string, specText: string, reviewedText?: string): Spec

A specification read from its spec.md and, where it has one, its reviewed.tsv (FR-004).

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

inForcefunctionno test imports it
function inForce(spec: Spec): boolean

Whether a spec is held to proofs: its status is neither Draft nor Retired (FR-007).

Citedtypeno test imports it
type 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 it
type 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).

parseCitationfunction
function 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.

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

commentLinesfunctionno test imports it
function 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.

specLinesfunction
function 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.

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

Prooftypeno test imports it
type Proof = { readonly line: number; readonly spec: string; readonly requirement: Cited };

A requirement, or a range of them, a test names, and its line.

proofsOffunction
function 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.

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

OntologyCitationtypeno test imports it
type 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 it
type CitingSchema = { readonly class: { readonly iri: string }; readonly fields: Fields };

What citationsOf reads of a class schema: its class and its fields.

citationsOffunction
function 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).

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

traceFindingsfunction
function traceFindings(input: TraceInput): readonly Finding[]

Every finding of the trace (FR-007), in the order: sources, specifications, ontology.

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

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