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 -. nobody walked it .-> 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: "Documentation is code, and <cite>every run</cite> draws what a document passes through. It is typed, the same grammar that placement is a grammar describes places it, a check resolves its references so traceability runs both ways, the reference <cite>a resolved reference</cite> shows, a count in it is derived rather than typed, and a document that drifts fails the same gate the code does. 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 surface <cite>a manifest</cite> types and <cite>compiled from four</cite> draws. Prose that cannot be parsed cannot be governed, so it is authored in a form that can be.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Give every document a type, and let the type select its schema, its rules and its one computed location. Point every reference at an identifier and a path with a declared verb, and let a check resolve both halves and fail an undeclared verb rather than skipping it. Generate each module's overview from a manifest the module owns plus its derived public surface. State no count in prose. Keep a scaling guide beside every system that has seams, and update it in the same change that adds a seam.",
                    boundary:
                        "A generated document is exempt from the content scan and drift-checked instead, because the governed surface is the manifest it was generated from. The one place a generated document differs from generated source is its marker: the source carries its marker in its name, and a document opens with a banner the gate keys on.",
                    cause: "Prose about code has no compiler, so nothing tells you when it stops being true.",
                    decision:
                        "Author the parseable form and generate the prose, rather than write the prose and hope it stays true.",
                    failureMode:
                        "The readme names a script someone renamed a month ago. A new contributor runs it, gets nothing, and assumes the tooling is broken.",
                    kind: "lesson",
                    principle:
                        "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:
                        "Rename one file the documents mention. The document gate must fail before anything else does. 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: a guide, a reference, a contract, a template, a taxonomy. Its owner says which part of the tree it belongs to. Its name says the subject, prefixed by the activity verb where the form is directive. A document's location is a function of its declared type and its owner and never a choice, so 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 decompose fails.",
                },
                {
                    kind: "text",
                    text: "Every document has one audience, one purpose and one abstraction level: a behaviour policy, a codebase contract, a guide to extending one system, a reference to what is enforced, a taxonomy that is a standard and its vocabulary. Content that belongs to a different level moves there and is never duplicated. The test is to strip the words belonging to the wrong level and ask whether the entry still communicates 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, and the gate resolves both: the path must exist, and the identifier must be exported from, declared in or referenced in that file. An undeclared verb fails rather than being skipped, which is what keeps a typo from making a reference invisible. Every claim a document makes about what it validates is backed by a real construct. Documents 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 derivable is computed: the public surface from the declarations, the dependencies from the descriptor, the governing principles resolved by identity against the canon, the diagrams from the module's own graph. A thin manifest is a bug. The content rules run on each field rendered to its fragment and report against the field, and the generated document is drift-checked 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 self-expands: any further key renders as its own section with no generator change, so the type admits arbitrary lowercase keys beside the required ones. A 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: done by hand, one container at a time, with the gate green between each, and it opens with impact analysis over every reference, as <cite>a surviving move</cite> draws. The references that matter most are the ones a pattern collects rather than a path names, because the filesystem is the architecture and a glob-resolvable tree is what a rename tool never sees.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Enumerate every reference before the move, the pattern-resolved ones included. Move and rename by hand, one container at a time. Update every importer as a literal edit a search can verify. Land a structural rewrite as a draft beside the live file with a published migration map, and delete the original only after approval.",
                    boundary:
                        "A throwaway script can move whatever it likes. The discipline is for code that something else depends on, and a rename is a create at its destination, so the destination is read before the write because the attention sits on the source.",
                    cause: "A pattern-resolved surface holds no literal path a rewrite could touch.",
                    decision: "Trade the rename tool's speed for a literal edit a search can verify.",
                    failureMode:
                        "A suffix changes. The collector that gathered files by that suffix now gathers nothing. Everything downstream passes because there is nothing left to check.",
                    kind: "lesson",
                    principle:
                        "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 silently go empty.",
                    validation:
                        "Compare what each pattern-based surface collects before and after the move. Any set that shrank without explanation is a broken move the tool would have called clean.",
                },
                {
                    kind: "text",
                    text: "Nothing is silently dropped. A restructure produces a migration map: every displaced block and its destination, or an explicit deletion with its reason. Content removed from one place appears in another or is listed as deleted. Relocation is a rewrite, so it takes the same approval as rewriting the contents, and a move plus a delete in one step is the most destructive form because the original is gone and there is nothing 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 derived set over the grid the architecture page builds in what can drift, seen through how it drifts: 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")}, read through 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 a cell that resists an invariant. What this chapter adds is the rule side, <cite>one cell per rule</cite>: every rule declares the gate that observes it or declares conduct with the evidence a check would need, as <cite>gate or conduct</cite> draws. The conduct roster, the vocabulary <cite>the conduct roster</cite> types, shrinks by whatever a mechanism now observes in an artifact instead of a party holding it in mind. That sentence is this method's own definition of progress.`,
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Declare for every rule the check that observes it or that none can, and for every conduct rule name the half that is decidable and whether that half is built. Work the unbuilt halves to zero, and gate a gap found while gating in the same run.",
                    boundary: "A cell is watched only by a predicate that can fail, as the check comes first requires.",
                    cause: "A rule stated without its cell has no address, so nobody can tell which drift it watches and which drift is unwatched.",
                    decision: "Count the empty cells 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:
                        "Coverage is a derived set over the grid of drift dimensions and lenses, and every rule declares its gate or its conduct.",
                    problem:
                        "Coverage claimed from a count of rules says nothing about which drift classes the rules reach.",
                    validation:
                        "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 acquire a check. Many such rules have a half that is decidable: whether a surface conforms to its template, whether a reader set resolves, whether a report states the boundary of its own negative result. That half is named in a cell with a closed vocabulary: observed, naming its gates; unbuilt, which is debt rather than a paragraph; none, with the reason from a closed set; and null, which is unassessed, and that too is a declared state. The reasons a half can be none are three: the subject is an act, no declared surface holds it, or the property is not evaluable 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. Nobody writes a count. Every number a reader wants is the length of one of those arrays on the run that produced it.",
                },
                {
                    kind: "text",
                    text: "The cell is filled by walking questions, never by reading the entry. Does the half name a declared surface, or is it imagined. Is its subject an artifact or an act. Is the population non-empty, because a check over an empty set is a green that measures nothing. Is the property evaluable on a member. Three of those are one search each and only the fourth is judgement, which inverts how the roster reads: every entry presents as a judgement and most of them turn on a fact. And the cell 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 assert more than it can.",
                },
                {
                    kind: "text",
                    text: "Projected onto correctness, the same grid is the test-surface catalogue what can drift, seen through how it drifts describes, and the verdict unknown is not pass gives an unmeasured surface rests on it. A re-walk of the roster compares against the kinds a check emits rather than against the list of checks, because a half acquires an observer as a new kind far more often 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];