IF Commons GitHub

rules

The rules Mizan adds to the format of a specification (commons 0003-mizan FR-013 to FR-015, 0018-standards-first FR-009, FR-016), as plugins: each reads the specifications of a folder and gives its findings as data, held against a baseline that only shrinks (kernel/trace.ts). A harness adds its own rules by passing more plugins.

Pure functions over text. A requirement is a bullet - **FR-nnn**: ... (and the indented lines under it); its wording is read for RFC 2119 keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) and the EARS patterns: event-driven (WHEN <event>, ...), state-driven (WHILE <state>, ...), unwanted behaviour (IF <condition>, THEN ...), optional feature (WHERE <feature>, ...), a combination of them, and ubiquitous (none of these leads the sentence). An acceptance scenario is a line with Given, When and Then in that order that cites a requirement. A plan.md has a ## Standards considered section. A requirement that names a citation of the Code of Federal Regulations or the United States Code carries Authority: and the identifiers of the mz:Authority individuals that cover it (0018-standards-first FR-015, FR-016).

import { earsPatternOf, mizanFindings } from "./rules.ts";
earsPatternOf("WHEN a file has no citation, the check MUST report it."); // "event"
mizanFindings([{ slug: "0001-x", spec: "- **FR-001**: It works.\n" }]).map((f) => f.rule); // ["mizan/requirement-keyword"]

Source: commons/mizan/src/rules.ts

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

authorityCitationfunction
function authorityCitation(known: readonly AuthorityRecord[]): RulePlugin

The rule that a requirement that comes from law cites its authority (0018-standards-first FR-015, FR-016), for the authorities given: a requirement that names a citation of law and has no Authority: followed by identifiers is found, so is one that names an identifier of none of the authorities, and so is a citation of law that no authority it names covers.

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

AuthorityRecordtypeno test imports it
type AuthorityRecord = { readonly id: string; readonly citation: string };

An authority a requirement may name: the CURIE of its mz:Authority individual (mzid:authority-21-cfr-820) and the citation of the law (21 CFR Part 820).

commonsAudienceProfilesconst
const commonsAudienceProfiles: readonly ProfileRecord[]

The profiles of the audience models in commons' ontology.

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

commonsAuthoritiesconst
const commonsAuthorities: readonly AuthorityRecord[]

The authorities of commons' own ontology, as the rule reads them.

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

commonsSubjectProfilesconst
const commonsSubjectProfiles: readonly ProfileRecord[]

The profiles of the kinds of subject in commons' ontology.

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

declaredInfunction
function declaredIn(spec: string, field: "Audience" | "Subject"): { readonly value: string; readonly line: number; } | undefined

The key a specification declares in its head with **Subject:** or **Audience:**, in lower case, and the line it is on; the first such line counts (0029-subject-profiles FR-002, FR-008).

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

earsPatternOffunction
function earsPatternOf(sentence: string): EarsPattern | undefined

The EARS pattern of a requirement's sentence, or undefined where a trigger leads it in a form EARS does not have (an IF with no THEN, a trigger with no comma).

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

EarsPatterntypeno test imports it
type EarsPattern = "ubiquitous" | "event" | "state" | "unwanted" | "optional" | "complex";

The patterns of EARS (Easy Approach to Requirements Syntax).

MizanFindingtypeno test imports it
type MizanFinding = Keyed & { readonly rule: MizanRule; readonly severity?: Phase };

A finding of one of Mizan's rules: the same shape as the trace's, with a rule that is Mizan's. A finding of the changes check (commons 0020-ifccm) also carries its phase: a gate finding fails whatever the baseline holds, a warn finding is held by it.

MizanRuletypeno test imports it
type MizanRule = (typeof MIZAN_RULES)[number] | ChangesRule | VersionsRule;

The id of a rule Mizan adds, or of the change-control and release checks.

MIZAN_RULESconst
const MIZAN_RULES: readonly ["mizan/requirement-keyword", "mizan/requirement-ears", "mizan/scenario-form", "mizan/standa… (503 characters)
const MIZAN_RULES: readonly ["mizan/requirement-keyword", "mizan/requirement-ears", "mizan/scenario-form", "mizan/standards-considered", "mizan/term-standard", "mizan/unaligned-justification", "mizan/decision-missing", "mizan/decision-overdue", "mizan/term-basis-missing", "mizan/spec-term-unknown", "mizan/spec-term-deprecated", "mizan/term-not-defined-by", "mizan/deprecated-no-replacement", "mizan/authority-citation", "mizan/standard-newer", "mizan/profile-unknown", "mizan/profile-section-missing"]

The ids of the rules Mizan adds (0003-mizan FR-013 to FR-015, 0018-standards-first FR-009), in the order a report lists them.

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

mizanFindingsfunction
function mizanFindings(specs: readonly SpecText[], plugins?: readonly RulePlugin[]): readonly MizanFinding[]

The findings of every plugin over every specification, in the order of the specifications and of the plugins.

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

ProfileRecordtypeno test imports it
type ProfileRecord = { readonly key: string; readonly sections: readonly string[] };

A profile as the check reads it (0029-subject-profiles FR-001, FR-008): the key a specification declares it by and the sections it asks for.

profileKindfunction
function profileKind(subjects: readonly ProfileRecord[], audiences: readonly ProfileRecord[]): RulePlugin

A specification that declares a kind of subject or an audience that is none of the ontology's is found (0029-subject-profiles FR-002, FR-008).

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

profileSectionsfunction
function profileSections(subjects: readonly ProfileRecord[], audiences: readonly ProfileRecord[]): RulePlugin

A specification lacks a section that the profile of its kind of subject or its audience asks for (0029-subject-profiles FR-011): none where it declares nothing, because a library asks for none.

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

requirementEarsconstno test imports it
const requirementEars: RulePlugin

A requirement whose sentence a trigger leads must be in the form of its EARS pattern (0003-mizan FR-013).

requirementKeywordconstno test imports it
const requirementKeyword: RulePlugin

Every requirement of a specification must carry an RFC 2119 keyword (0003-mizan FR-013).

RulePlugintype
type RulePlugin = { readonly id: MizanRule; readonly check: (s: SpecText) => readonly MizanFinding[] };

A rule as a plugin: its id and what it finds in one specification.

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

rulePluginsconst
const rulePlugins: readonly RulePlugin[]

Mizan's own rules, as plugins, in the order they run: a harness with authorities of its own passes authorityCitation with them in place of the last.

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

scenarioFormconstno test imports it
const scenarioForm: RulePlugin

A line that holds Given must hold When and Then after it, and cite a requirement (0003-mizan FR-014).

SpecTexttype
type SpecText = { readonly slug: string; readonly spec: string; readonly plan?: string };

One specification of a folder as the rules read it: its slug, the text of spec.md and, where it has one, of plan.md.

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

standardsConsideredconstno test imports it
const standardsConsidered: RulePlugin

A feature's plan.md names the standards considered (0018-standards-first FR-009).

sentenceOffunctionno test imports it
function sentenceOf(lines: readonly string[], index: number): string

The sentence of a requirement: what follows **FR-nnn**:, with the indented lines under it joined.

LawCitationtypeno test imports it
type LawCitation = { readonly written: string; readonly normal: string };

A citation of law as the rule compares it: 21 CFR 820.30 for a section, 42 USC 1320d for the United States Code, however the text spaced or punctuated it.

lawCitationsInfunction
function lawCitationsIn(text: string): readonly LawCitation[]

The citations of the Code of Federal Regulations and the United States Code that a text names, in the order it names them (0018-standards-first FR-015).

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

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