# configuration/strings/coverage.strings.ts
> 175 lines of code and 12 definitions.
Tree: Site tree
Language: typescript
Layer: product
Canonical: https://banes-lab.com/anatomy/tree#file-configuration-strings-coverage-strings-ts
Source text: https://banes-lab.com/assets/sources/source.793bebce4ee9905e08af586c54ec5422c50678457aff5725b449d5267186dd0e.generated.txt
## Definitions
- `MANIFEST_SHAPE` (lexical_declaration, line 11)
- `ROSTER_SHAPE` (lexical_declaration, line 14)
- `REFERENCE_SAMPLE` (lexical_declaration, line 17)
- `DOCUMENT_DIAGRAM` (lexical_declaration, line 20)
- `MANIFEST_DIAGRAM` (lexical_declaration, line 23)
- `RENAME_DIAGRAM` (lexical_declaration, line 26)
- `GRID_DIAGRAM` (lexical_declaration, line 29)
- `ROSTER_DIAGRAM` (lexical_declaration, line 32)
- `DOCUMENTATION_SECTION` (lexical_declaration, line 35)
- `RENAME_SECTION` (lexical_declaration, line 105)
- `COVERAGE_SECTION` (lexical_declaration, line 141)
- `COVERAGE_SECTIONS` (lexical_declaration, line 187, exported)
## Source
```typescript
import {
COVERAGE_SECTION_ICON,
DOCUMENTATION_SECTION_ICON,
RENAME_SECTION_ICON,
} from "#configuration/icons/coverage.icons";
import { COVERAGE_SECTION_ID, DOCUMENTATION_SECTION_ID, RENAME_SECTION_ID } from "#core/ids/coverage.ids";
import { MARKDOWN_LANGUAGE, TYPESCRIPT_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";
import { nodeLink as node } from "#domain/converters/link.converter";
const MANIFEST_SHAPE =
'export interface Manifest {\n readonly label: string;\n readonly summary: string;\n readonly maturity: "experimental" | "stable";\n readonly domains: readonly { readonly meta: Domain; readonly sub: SubDomain }[];\n readonly governedBy: readonly ConceptId[];\n readonly entries: readonly string[];\n readonly docs: {\n readonly overview: string;\n readonly whenToUse: readonly string[];\n readonly whenNotToUse: readonly string[];\n readonly quickStart: readonly { readonly intent: string; readonly lang: string; readonly code: string }[];\n readonly configuration: string;\n readonly disposal: readonly string[];\n readonly aiContext: readonly string[];\n readonly apiNotes?: readonly { readonly name: string; readonly note: string }[];\n readonly [section: string]: unknown;\n };\n}';
const ROSTER_SHAPE =
'export type CheckableHalf =\n | { readonly kind: "observed"; readonly by: readonly GateId[] }\n | { readonly kind: "unbuilt" }\n | { readonly kind: "none"; readonly because: "subject-is-an-act" | "no-declared-surface" | "not-evaluable" };\n\nexport interface ConductEntry {\n readonly slug: RuleSlug;\n readonly whatACheckWouldNeed: string;\n readonly half: CheckableHalf | null;\n}\n\nexport interface Coverage {\n readonly gated: readonly { readonly slug: RuleSlug; readonly gate: GateId }[];\n readonly conduct: readonly ConductEntry[];\n readonly unassessed: readonly RuleSlug[];\n readonly debt: readonly RuleSlug[];\n}';
const REFERENCE_SAMPLE =
'The placement check parses every path, see: `parsePath` "engine/matchers/path.matcher.ts"\n\nThe validator resolves both halves:\n the path must exist\n the identifier must be declared in that file\n\nA verb it does not know fails the document rather than being skipped,\nso a typo cannot make a reference invisible.';
const DOCUMENT_DIAGRAM =
'flowchart TB\n typed["Typed · the form selects the schema, the rules and the legal place"]\n placed["Placed · one computed location from form, owner and name"]\n parsed["Parsed · references are constructs with a verb, an identifier and a path"]\n validated["Validated · every reference resolves, no count, no past tense"]\n repaired["Repaired · bare paths healed, generated documents regenerated"]\n typed --> placed --> parsed --> validated --> repaired\n repaired -. on every run .-> typed';
const MANIFEST_DIAGRAM =
'flowchart TB\n manifest["The manifest · the authored surface"]\n surface["The public surface · derived from the code"]\n deps["The dependencies · derived from the descriptor"]\n principles["The principles · resolved by identity against the canon"]\n readme["The module document · generated, drift-checked, never edited"]\n manifest --> readme\n surface --> readme\n deps --> readme\n principles --> readme\n readme -. a hand edit is reverted on the next run .-> manifest';
const RENAME_DIAGRAM =
'flowchart TB\n enumerate["Enumerate every reference, the pattern-resolved ones included"]\n before["Record what each collector gathers"]\n move["Move and rename by hand, one container at a time"]\n update["Update every importer as a literal edit"]\n verify["Verify every reference with a search"]\n after["Record what each collector gathers now"]\n same{"Same sets?"}\n clean["The gate is green · next container"]\n broken["A collector went empty · the move is broken"]\n enumerate --> before --> move --> update --> verify --> after --> same\n same -- yes --> clean\n same -- no --> broken';
const GRID_DIAGRAM =
'flowchart TB\n dimensions["What can drift · identity, structure, relation, state, behaviour, and the rest"]\n lenses["How it drifts · structural, causal, temporal, invariant, and the rest"]\n cell["One cell · an invariant that must hold"]\n watched["A predicate enforces it"]\n unwatched["Declared unwatched, with the reason"]\n empty["An empty cell · a drift class nothing watches"]\n dimensions --> cell\n lenses --> cell\n cell --> watched\n cell --> unwatched\n cell -. never walked .-> empty';
const ROSTER_DIAGRAM =
'flowchart TB\n rule["A rule"]\n gate{"Does an artifact observe it?"}\n check["Names its check"]\n conduct["Declared conduct · with the evidence a check would need"]\n half{"Is a half of it decidable?"}\n built["The half is gated, and the entry names its range"]\n debt["The half is unbuilt · counted as debt"]\n none["No checkable half · an act, not an artifact"]\n rule --> gate\n gate -- yes --> check\n gate -- no --> conduct --> half\n half -- built --> built\n half -- unbuilt --> debt\n half -- no --> none\n debt -. worked to zero .-> built';
const DOCUMENTATION_SECTION: Section = {
icon: DOCUMENTATION_SECTION_ICON,
id: DOCUMENTATION_SECTION_ID,
intro: "This method treats documentation as code, and every run shows what a document passes through. A document is typed, and it is placed by the same grammar described in placement is a grammar. A check resolves its references, as shown in a resolved reference, so traceability runs in both directions. A count in a document is derived rather than typed, and a document that drifts fails the same gate as the code. A module's overview is generated from the manifest the module owns and never written by hand, which is manifest-based design taken literally; the manifest is typed in a manifest, and compiled from four shows how the overview is assembled. Prose that cannot be parsed cannot be governed, so documentation is written in a form that can be.",
subsections: [
{
blocks: [
{
application:
"In practice, every document has a type, and the type selects its schema, its rules and its one computed location. Every reference points at an identifier and a path with a declared verb, and a check resolves both halves and fails on an undeclared verb rather than skipping it. Each module's overview is generated from a manifest the module owns, together with its derived public surface. No count is stated in prose. A scaling guide sits beside every system that has seams, and it is updated in the same change that adds a seam.",
boundary:
"A generated document is exempt from the content scan and checked for drift instead, because the governed surface is the manifest it was generated from. The one way a generated document differs from generated source is its marker: generated source carries its marker in its name, while a generated document opens with a banner that the gate looks for.",
cause: "Prose about code has no compiler, so nothing tells you when it stops being true.",
decision:
"The parseable form is written and the prose generated from it, rather than the prose written in the hope that it stays true.",
failureMode:
"The readme names a script that was renamed a month ago, and a new contributor runs it, gets nothing, and assumes the tooling is broken.",
kind: "lesson",
principle:
"For this reason documentation goes through the same typing, placement, parsing, validation and repair as any other code.",
problem: "Hand-written documentation is right on the day of writing and drifts every day after.",
validation:
"To check this, rename one file that the documents mention. The document gate should fail before anything else does, and a rename the documents survived is a rename they never mentioned.",
},
{ caption: "every run", kind: "mermaid", text: DOCUMENT_DIAGRAM },
],
title: "Typed, placed, parsed",
},
{
blocks: [
{
kind: "text",
text: "A document's path is computed from three axes and never chosen. Its form says what it is, such as a guide, a reference, a contract, a template or a taxonomy. Its owner says which part of the tree it belongs to. Its name states the subject, prefixed by the activity verb where the form is directive. Because a document's location is a function of its declared type and its owner, one search finds every document of a type and every document an owner holds. A document is created through a tool that computes that location, and a filename that does not break down into these parts fails.",
},
{
kind: "text",
text: "Every document has one audience, one purpose and one abstraction level, as with a behaviour policy, a codebase contract, a guide to extending one system, a reference to what is enforced, or a taxonomy that holds a standard and its vocabulary. Content that belongs to a different level moves to that level and is never duplicated. The test is to strip out the words that belong to the wrong level and ask whether the entry still says something at this one. A document that reads at two levels is two documents.",
},
],
title: "A path computed from three axes",
},
{
blocks: [
{
kind: "text",
text: "A document points at code with a construct rather than a phrase: a declared verb, an identifier and a path. The gate resolves both halves, so the path has to exist, and the identifier has to be exported from, declared in or referenced in that file. An undeclared verb fails rather than being skipped, which is what stops a typo from making a reference invisible. Every claim a document makes about what it validates is backed by a real construct. Documents also form a dependency graph: a document's name is its export, its edge fields are imports resolved through a registry, a superseded edge sets the target's status, and a duplicate name or a dead edge is a finding.",
},
{ code: REFERENCE_SAMPLE, kind: "code", language: MARKDOWN_LANGUAGE, title: "a resolved reference" },
],
title: "References are constructs",
},
{
blocks: [
{
kind: "text",
text: "A module's overview is generated, and the manifest is its whole editorial surface. Everything that can be derived is computed: the public surface from the declarations, the dependencies from the descriptor, the governing principles resolved by identity against the canon, and the diagrams from the module's own graph. A thin manifest is a bug. The content rules run on each field as rendered into its fragment and report against that field, and the generated document is checked for drift in both directions, so a hand edit is reverted on the next run.",
},
{
kind: "text",
text: "The manifest is a typed record, and its type is what separates a stub from a document. The documentation block has a required core and expands itself: any further key renders as its own section without a change to the generator, so the type admits arbitrary lowercase keys beside the required ones. A quick start is runnable code with its intent and its language, never a sketch, and a validator holds every required field to its shape before anything is generated.",
},
{ code: MANIFEST_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "a manifest" },
{ caption: "compiled from four", kind: "mermaid", text: MANIFEST_DIAGRAM },
],
title: "The manifest is the editorial surface",
},
],
title: "Documentation is code",
};
const RENAME_SECTION: Section = {
icon: RENAME_SECTION_ICON,
id: RENAME_SECTION_ID,
intro: "A move is a manual identity migration: it is done by hand, one container at a time, with the gate green between each, and it opens with impact analysis over every reference, as shown in a surviving move. The references that matter most are the ones a pattern collects rather than the ones a path names. As described in the filesystem is the architecture, much of the tree is collected by pattern, and a glob-resolvable tree is exactly what a rename tool never sees.",
subsections: [
{
blocks: [
{
application:
"In practice, every reference is enumerated before the move, including the ones resolved by pattern. Files are moved and renamed by hand, one container at a time, and every importer is updated by hand as well. A structural rewrite lands as a draft beside the live file, with a published migration map, and the original is deleted only after approval.",
boundary:
"A throwaway script can move whatever it likes. The discipline applies to code that something else depends on. A rename is also a create at its destination, so the destination is read before the write, because attention tends to stay on the source.",
cause: "A surface resolved by pattern holds no literal path that a rewrite could touch.",
decision: "The rename tool's speed is traded for literal edits that a search can verify.",
failureMode:
"A suffix changes, the collector that gathered files by that suffix now gathers nothing, and everything downstream passes because nothing is left to check.",
kind: "lesson",
principle:
"For this reason a move starts with an enumeration and ends with a verification, and a count checks every surface that resolves by pattern.",
problem:
"A rename tool reports a clean rename while the surfaces that resolve by pattern quietly go empty.",
validation:
"To check this, compare what each pattern-based surface collects before and after the move. Any set that shrank without explanation is a broken move that the tool would have called clean.",
},
{
kind: "text",
text: "Nothing is dropped without a record. A restructure produces a migration map listing every displaced block with its destination, or an explicit deletion with its reason, so content removed from one place either appears in another or is listed as deleted. Relocation is a rewrite, so it needs the same approval as rewriting the contents. A move and a delete in one step is the most destructive form, because the original is gone and nothing is left to compare the replacement against.",
},
{ caption: "a surviving move", kind: "mermaid", text: RENAME_DIAGRAM },
],
title: "Enumerate, move, verify",
},
],
title: "Moves and renames",
};
const COVERAGE_SECTION: Section = {
icon: COVERAGE_SECTION_ICON,
id: COVERAGE_SECTION_ID,
intro: `Rule coverage is a set derived over the grid the architecture page builds in what can drift, seen through how it drifts. Each cell pairs a dimension of the ontology axis, such as ${node("ont-identity", "identity")}, ${node("ont-structure", "structure")}, ${node("ont-relation", "relation")}, ${node("ont-state", "state")} or ${node("ont-behaviour", "behaviour")}, with a lens of the analysis axis, such as ${node("ana-structural", "structural")}, ${node("ana-causal", "causal")} or ${node("ana-temporal", "temporal")}. The walk that finds an empty cell is described in a cell that resists an invariant. What this section adds is the rule side, shown in one cell per rule: every rule declares the gate that observes it, or declares conduct together with the evidence a check would need, as shown in gate or conduct. The conduct roster, whose vocabulary is typed in the conduct roster, shrinks whenever a mechanism starts observing in an artifact what the developer or the model previously had to keep in mind. That shrinking is how this method defines progress.`,
subsections: [
{
blocks: [
{
application:
"In practice, every rule declares the check that observes it, or that no check can, and every conduct rule names the half of it that is decidable and whether that half has been built. The unbuilt halves are worked down to zero, and a gap found while building a gate is gated in the same run.",
boundary:
"A cell is watched only by a predicate that can fail, as described in the check comes first.",
cause: "A rule stated without its cell has no address, so neither you nor the model can tell which drift it watches and which drift nothing watches.",
decision: "The empty cells are counted, rather than the rules.",
failureMode:
"A team believes its architecture is covered because it has many rules, and the failure that ships lives in a dimension no rule ever named.",
kind: "lesson",
principle:
"For this reason coverage is a set derived over the grid of drift dimensions and lenses, and every rule declares either its gate or its conduct.",
problem:
"Coverage claimed from a count of rules says nothing about which drift classes the rules reach.",
validation:
"To check this, take any rule and name its dimension and its lens; a rule that fits no cell watches nothing in particular. Then find an empty cell and ask what would drift there unseen.",
},
{
kind: "text",
text: "Conduct is a closed question, not a softer state. A rule declares conduct when no construct in any artifact observes it, and the declaration stays falsifiable because each entry names what would have to become observable for the rule to gain a check. Many such rules have a half that is decidable, such as whether a surface conforms to its template, whether a set of readers resolves, or whether a report states the boundary of its own negative result. That half is recorded in a cell with a closed vocabulary of four values: observed, naming its gates; unbuilt, which counts as debt rather than a paragraph of explanation; none, with a reason taken from a closed set; and null, which means unassessed and is also a declared state. There are three reasons a half can be none: the subject is an act, no declared surface holds it, or the property cannot be evaluated on a member. The coverage report is then derived over the whole set: the gated rules with their gates, the conduct entries, the unassessed rows, which are exactly the entries whose cell is null, and the debt, which is exactly the unbuilt halves. No count is written by hand. Every number a reader wants is the length of one of those lists on the run that produced it.",
},
{
kind: "text",
text: "The cell is filled by walking through questions, never by reading the entry. Does the half name a declared surface, or an imagined one? Is its subject an artifact or an act? Is the population non-empty, given that a check over an empty set is a green result that measures nothing? Can the property be evaluated on a member? Three of these questions take one search each, and only the fourth needs judgement. That changes how the roster reads: every entry looks like a judgement, yet most of them turn on a fact. The cell also holds the value while the entry holds the range, because an observing check is often narrower than the rule whose half it answers, and a bare id would claim more than the check covers.",
},
{
kind: "text",
text: "Projected onto correctness, the same grid becomes the catalogue of test surfaces described in what can drift, seen through how it drifts, and the unknown verdict that an unmeasured surface receives, described in unknown is not pass, rests on it. A fresh walk of the roster compares against the kinds of finding the checks emit rather than against the list of checks, because a half gains an observer far more often as a new kind than as a new rule.",
},
{ code: ROSTER_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "the conduct roster" },
{ caption: "one cell per rule", kind: "mermaid", text: GRID_DIAGRAM },
{ caption: "gate or conduct", kind: "mermaid", text: ROSTER_DIAGRAM },
],
title: "The grid and the roster",
},
],
title: "Coverage is derived",
};
export const COVERAGE_SECTIONS: readonly Section[] = [DOCUMENTATION_SECTION, RENAME_SECTION, COVERAGE_SECTION];
```