import {
    BOUNDARY_SECTION_ICON,
    FILESYSTEM_SECTION_ICON,
    HOME_SECTION_ICON,
} from "#configuration/icons/invariant.icons";
import { BOUNDARY_SECTION_ID, FILESYSTEM_SECTION_ID, HOME_SECTION_ID } from "#core/ids/invariant.ids";
import { JAVASCRIPT_LANGUAGE, TYPESCRIPT_LANGUAGE, YAML_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";

const LOCATION_SHAPE =
    "app:\n    root: <application-root>\n    member: <application-member>          # → <application-root>/<application-member>\n    builds: <build-output>                # → <application-root>/<build-output>\ntesting:\n    root: <test-root>\n    app: <application-suite>              # → <test-root>/<application-suite>\ngovernance:\n    root: <governance-host>\n    rules: <rule-host>                    # → <governance-host>/<rule-host>\n    reports: <report-root>                # → <governance-host>/<report-root>";

const LOOKUP_SHAPE =
    'type LocationKey = "app.root" | "app.member" | "app.builds" | "testing.app" | "governance.rules";\n\nexport declare function relativePath(key: LocationKey): string;\nexport declare function absolutePath(key: LocationKey): string;\n\nconst ruleHost = absolutePath("governance.rules");\nconst suite = relativePath("testing.app");';

const REGISTRY_SHAPE =
    'export interface Variant<Kind extends string> {\n    readonly kind: Kind;\n    readonly applies: (subject: Subject) => boolean;\n    readonly run: (subject: Subject) => Finding[];\n}\n\nexport interface Registry<Kind extends string> {\n    readonly register: (variant: Variant<Kind>) => void;\n    readonly all: () => readonly Variant<Kind>[];\n    readonly get: (kind: Kind) => Variant<Kind>;\n}\n\nexport const checks = createRegistry<CheckKind>();\n\nchecks.register({ kind: "unreachable-export", applies: isModule, run: findUnreachableExports });';

const HOME_DIAGRAM =
    'flowchart TB\n    subgraph copies["Three homes"]\n        s1["settings · lines-per-file: 200"]\n        c1["checker · MAX_LINES = 150"]\n        r1["readme · files never exceed 150 lines"]\n    end\n    subgraph home["One home"]\n        s2["settings · lines-per-file: 200"]\n        c2["checker · reads lines-per-file from the settings"]\n        r2["readme · states the shape, never the number"]\n        s2 -- derived --> c2\n        s2 -. no number to copy .-> r2\n    end\n    s1 -. drift .- c1\n    c1 -. drift .- r1';

const TRUTH_DIAGRAM =
    'flowchart TB\n    subgraph truths["One truth per concern"]\n        quality["Quality config · one file, every tool\'s config built in memory from it"]\n        paths["Locations · one declaration, every location resolved by key"]\n        vocabulary["Naming · one closed vocabulary"]\n    end\n    tools["Every tool"]\n    scripts["Every script"]\n    checks["Every check"]\n    quality -- in memory --> tools\n    paths -- by key --> scripts\n    vocabulary -- parsed --> checks\n    drift["A per-tool config on disk · a spelled path · an undeclared word"]\n    drift -. refused .-> truths';

const REGISTRY_DIAGRAM =
    'flowchart TB\n    subgraph before["Before · the router learns every name"]\n        router1["router · switch on the page name"]\n        router1 --> home1["home page"]\n        router1 --> terms1["terms page"]\n        router1 --> faq1["faq page"]\n    end\n    subgraph after["After · the directory is the registry"]\n        pages["pages folder · collected by pattern"]\n        home2["home page · registers itself"] --> pages\n        terms2["terms page · registers itself"] --> pages\n        faq2["faq page · registers itself"] --> pages\n        pages --> router2["router · never learns a name"]\n    end';

const BOUNDARY_SAMPLE =
    'const masked = env.HOST ?? "localhost";\n\nconst surfaced = env.HOST ?? fail("HOST is not set; the deploy needs a droplet");';

const DEBT_DIAGRAM =
    'flowchart TB\n    subgraph never["Never · debt"]\n        shortcut["a shortcut"]\n        fallback["a fallback"]\n        dual["a dual path"]\n        deprecation["a deprecation marker"]\n        fornow["a for-now"]\n        optional["an optional feature the system depends on"]\n    end\n    subgraph always["Always · leverage"]\n        constraint["a constraint"]\n        failfast["fail-fast"]\n        single["a single path"]\n        removal["explicit removal"]\n        now["now"]\n        mandatory["mandatory"]\n    end\n    shortcut --> constraint\n    fallback --> failfast\n    dual --> single\n    deprecation --> removal\n    fornow --> now\n    optional --> mandatory';

const HOME_SECTION: Section = {
    icon: HOME_SECTION_ICON,
    id: HOME_SECTION_ID,
    intro: "Every fact has one home, as <cite>one limit</cite> draws. Everything else that repeats the fact is a derivation from that home, as <cite>one truth per concern</cite> draws, or it is drift waiting for a day to happen. Single source of truth is the principle, DRY is its everyday name, and the rule applies to a number in a config, a location in a script, a word in a filename and a sentence in a document alike, each with one mechanism that holds it. For a location the mechanism is <cite>a location declaration</cite> and <cite>the lookup</cite>. The architecture page states the same split as definitions own what, code owns how, and derived state is the verification side of it.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Pick the home for each fact. Derive every other appearance from it by a generator or a lookup. Delete every copy you cannot derive.",
                    boundary:
                        "A declaration file is the one exempt place, because there the string is the declaration rather than a copy of one. Every consumer reads that file by key, and the exemption never widens to a second file.",
                    cause: "A copy is cheaper to make than a derivation, and the two agree on the day of copying, so the drift is invisible until it costs something.",
                    decision: "Make the second appearance a lookup rather than a copy, even where the copy is shorter.",
                    failureMode:
                        "A limit lives in the tool's config, in a checker, in a script and in three documents. Someone changes one. The others keep enforcing the old value.",
                    kind: "lesson",
                    principle: "One home per fact. A second appearance is a derivation, or it is a defect.",
                    problem: "The same fact gets stated in several places, and the places stop agreeing.",
                    validation:
                        "Change the fact at its home. Every other appearance must follow without a second edit. An appearance that stayed behind was a copy.",
                },
                {
                    kind: "text",
                    text: "Three truths carry most of the tree. One quality truth: every tool's configuration is built in memory from one declaration, a validator refuses a second one on disk, and a catalogued default means the declaration carries deviations only. One location declaration holds where every member lives, branches compose so a directory is spelled once, and every script resolves a location by key, so a rename is one edit; that is configuration externalization, and a spelled path is hardcoded configuration. One closed vocabulary holds every word a filename may carry, and an undeclared word is an approved edit to the vocabulary rather than a naming choice.",
                },
                {
                    kind: "text",
                    text: "A location is never spelled in a string, and the check for that has four shapes. A declared location spelled as a literal anywhere. The same location assembled from parts, with local constants, arrays and concatenation folded first. A literal tail appended to a lookup when a key already covers the whole path. And any path-shaped string with no anchor at all. Position is not a defence; a path in an array entry or a template is the same defect as a path in a value.",
                },
                {
                    kind: "text",
                    text: "The location declaration has a shape that makes composition free. A branch declares its own place under a root key and every key beneath it resolves relative to that, so a directory is spelled once and a rename is one edit, and a branch that declares a root also resolves as a leaf, so a key keeps working after it gains children. The keys are agnostic and the values are yours: the governance stack reads the application by a fixed key whatever the directory is called, and renaming the directory is editing the value. The lookup is typed over the declared keys, so a key that does not exist fails to compile rather than resolving to nothing at run time. The declaration answers one question only, where a member lives and which governed roots sit inside it. What lives below a root belongs to the naming vocabulary and is never re-listed here.",
                },
                { code: LOCATION_SHAPE, kind: "code", language: YAML_LANGUAGE, title: "a location declaration" },
                { code: LOOKUP_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "the lookup" },
                { caption: "one limit", kind: "mermaid", text: HOME_DIAGRAM },
                { caption: "one truth per concern", kind: "mermaid", text: TRUTH_DIAGRAM },
            ],
            title: "One home per fact",
        },
    ],
    title: "One home",
};

const FILESYSTEM_SECTION: Section = {
    icon: FILESYSTEM_SECTION_ICON,
    id: FILESYSTEM_SECTION_ID,
    intro: "Every extension point is a file in a directory. Adding a capability is adding a file. Removing one is deleting a file. A hand-maintained list of what exists is a registry in disguise, and a registry in disguise is where the next inconsistency lives, as <cite>wired then collected</cite> draws. The same shape governs pages, rules, checks, templates and documents, the shape <cite>the registry</cite> types: the registry pattern, filled by auto-discovery, is the open/closed principle made physical, and a plugin architecture is what it grows into.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Give each variant its own file that registers itself at module scope. Collect the files by pattern, never by name. Delete the switch, the lookup table and the list of imports that had to learn each new name. Where a barrel collects the files, let it be generated from the directory rather than written, and check it in both directions: an entry with no file, and a file with no entry.",
                    boundary:
                        "A shape-discovered surface is the highest-risk artifact in any rename, because a suffix change silently changes what it collects. The collection is compared before and after every move, as moves and renames describes, and a count that dropped to zero is a broken move rather than a clean one.",
                    cause: "A list is complete on the day it is written, and nothing compares it against the directory afterwards.",
                    decision: "Make the directory the registry.",
                    failureMode:
                        "A new variant renders through the fallback branch because the switch that dispatches it never learned its name, and nothing reported that.",
                    kind: "lesson",
                    principle:
                        "The filesystem is the architecture. A core file that must learn a name is the wrong design.",
                    problem:
                        "Every switch over a kind, every record literal of variants and every import list in a composer is a list someone has to remember to update.",
                    validation:
                        "Add a variant by adding one file and touching nothing else. If it needed a second edit, the registry is still in disguise.",
                },
                {
                    kind: "text",
                    text: "A barrel that hand-writes its side-effect imports is the disguise reappearing one level down, and the same move governs the rules, as a check matches a shape shows.",
                },
                {
                    kind: "text",
                    text: "A generated index over authored data is regenerated from its source and drift-checked in the gate, never hand-edited. Every scan is depth-agnostic, because a scan anchored to a fixed depth reports pass over what sits one level below it. The index is checked both ways because one direction is decorative: the failure that occurs is a scan resolving a smaller set than it claims and the difference reading as coverage.",
                },
                {
                    kind: "text",
                    text: "The registry has one shape wherever it appears, and the kind is a closed union, so a variant of an undeclared kind fails to compile and a lookup for one cannot be written. The same three parts appear whether the variants are pages, checks, codemods or document forms, which is why one primitive serves all of them and a second registry implementation is a duplicate rather than a convenience.",
                },
                { code: REGISTRY_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "the registry" },
                { caption: "wired then collected", kind: "mermaid", text: REGISTRY_DIAGRAM },
            ],
            title: "Adding is adding a file",
        },
    ],
    title: "The filesystem is the architecture",
};

const BOUNDARY_SECTION: Section = {
    icon: BOUNDARY_SECTION_ICON,
    id: BOUNDARY_SECTION_ID,
    intro: "A failure surfaces at the boundary where it happens, as <cite>masked and surfaced</cite> shows. Fail fast is the principle: no default, no fallback and no second path carries on as if nothing went wrong, and <cite>the debt shapes</cite> draws what replaces each. Execution joins the halves on the architecture page gives errors their place in the language; this chapter is the practice at the boundary, and never and always derives the pairs below.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Fail at the first point a precondition does not hold. Say what you expected and what you found. Refuse a default value for anything the configuration should have supplied, and refuse a second path that carries on when the first one cannot. Delete replaced code in the same edit rather than marking it, because a marker is a second path with a label.",
                    boundary:
                        "Fail-fast is for the boundaries of your own system. A surface a person meets still gets graceful degradation, a real page rather than a bare error, and the failure it hides is logged where you will see it.",
                    cause: "A fallback turns a loud failure into a quiet wrong answer, and a quiet wrong answer costs more than any crash.",
                    decision: "Refuse fallbacks, dual paths and silent defaults.",
                    failureMode:
                        "A missing secret falls back to a placeholder. The deploy succeeds. The service starts talking to nothing, and the first sign is a customer.",
                    kind: "lesson",
                    principle: "Errors are language. A failure surfaces where it occurs, and no default masks it.",
                    problem:
                        "Code that handles every edge case by carrying on hides the one case that should have stopped it.",
                    validation:
                        "Remove one required input and run. The run must stop at the boundary that needed it, naming it. A run that continued has a fallback somewhere.",
                },
                {
                    kind: "text",
                    text: "The debt shapes are named as pairs, never as a list of don'ts, because each pair states what to do instead. A deprecation marker, a tombstone or a compatibility shim is how lava flow and zombie code begin, and its pair is explicit removal in the same edit. Every write is checked for those markers before it lands, and only living code on one forward path survives; the accounting behind the pairs is debt and leverage.",
                },
                {
                    kind: "text",
                    text: "An environment variable never carries a fallback value, and a missing one fails at boot with its name; a placeholder there is a hidden side effect waiting for production. A guard that fails open is itself a defect, because a guard exists to stop a state and a guard that lets the state through on error has stopped nothing, which is why secure by default is the same rule seen from the security core. A boolean flag reads as an explicit positive test rather than a negated default, so an absent flag hides the feature rather than enabling it by accident.",
                },
                { code: BOUNDARY_SAMPLE, kind: "code", language: JAVASCRIPT_LANGUAGE, title: "masked and surfaced" },
                { caption: "the debt shapes", kind: "mermaid", text: DEBT_DIAGRAM },
            ],
            title: "Loud at the boundary",
        },
    ],
    title: "Fail at the boundary",
};

export const INVARIANT_SECTIONS: readonly Section[] = [HOME_SECTION, FILESYSTEM_SECTION, BOUNDARY_SECTION];