import { DETECT_SECTION_ICON, GATE_SECTION_ICON, ORDER_SECTION_ICON } from "#configuration/icons/build.icons";
import { DETECT_SECTION_ID, GATE_SECTION_ID, ORDER_SECTION_ID } from "#core/ids/build.ids";
import type { Section } from "#types/document.types";
import { TEXT_LANGUAGE } from "#configuration/constants/code.constants";

const LOOP_DIAGRAM =
    'flowchart TB\n    detect["Detect · the one command, fixers on"]\n    heal["Heal · every finding with one correct answer, in the same run"]\n    report["Report · the findings the fixers left, as data on disk"]\n    fix["Fix · the AI, one finding at a time, from the report"]\n    detect --> heal --> report --> fix\n    fix -- until the report is empty --> detect';

const FINDING_SAMPLE =
    'engine/registries/route.registry.ts:41\n  rule      literal-in-lookup\n  locus     the first argument of the lookup call\n  trail     resolved the callee verb, matched the lookup form, read the argument\n  expected  an imported constant as the lookup key\n  found     the string literal "home"\n  fix       replace the argument with the id from the ids module: HOME_PAGE\n  healed    no';

const GATE_DIAGRAM =
    'flowchart TB\n    pattern["A new pattern enters the tree"]\n    ships["The check ships in the same change, with a planted violation"]\n    slips["A violation slips past the check"]\n    appended["The check is extended first, then the content is repaired"]\n    inconvenient["A finding is inconvenient"]\n    stays["It stays a finding · no warn tier, no exclusion"]\n    disagree["Two checks disagree on one line"]\n    derived["Both stay on · the form that satisfies both is derived"]\n    uncheckable["A pattern no static check can catch"]\n    surfaced["Surfaced as a question, never used as licence"]\n    pattern --> ships\n    slips --> appended\n    inconvenient --> stays\n    disagree --> derived\n    uncheckable --> surfaced\n    ships ~~~ slips\n    appended ~~~ inconvenient\n    stays ~~~ disagree\n    derived ~~~ uncheckable';

const ORDER_DIAGRAM =
    'flowchart TB\n    write["Write the check"]\n    plant["Plant a violation"]\n    fires{"Does it report the expected message?"}\n    real["Run it over the real population"]\n    passes{"Does at least one real member pass for the right reason?"}\n    restore["Restore the planted file"]\n    code["Write the code the check holds"]\n    write --> plant --> fires\n    fires -- no --> write\n    fires -- yes --> real --> passes\n    passes -- no, everything fails --> write\n    passes -- yes --> restore --> code';

const DETECT_SECTION: Section = {
    icon: DETECT_SECTION_ICON,
    id: DETECT_SECTION_ID,
    intro: "From the outside the work is one loop: detect with the fixers on, report what they left, fix what the report names, repeat until the tools are quiet, as <cite>the loop from outside</cite> draws. The loop closes because the tools speak to the AI in a typed vocabulary, the finding <cite>an actionable finding</cite> shows, and the report on disk is the state of the work rather than a rendering of one run. The architecture page reaches the same contract from the author's side: because the author is probabilistic, a finding is the contract between the check and the model.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Feed the AI the finding, not the rule. Say which file, which line, what the tool expected, what it found, and the one action that would close it. Let it repair that and nothing else. Run the tools again once the tree has changed.",
                    boundary:
                        "A finding whose only repair the toolchain refuses to perform is withdrawn or exempted with that refusal as the stated reason. A report nobody can drain trains every reader to discount the colour, and the cost lands on the findings beside it.",
                    cause: "A principle has to be re-derived into an action at every line, and the model re-derives it differently each time.",
                    decision:
                        "Spend the effort on the check that produces findings rather than on the explanation that produces agreement.",
                    failureMode:
                        "You explain the architecture at length, the AI agrees, and the next file it writes breaks it in a way the explanation did not anticipate.",
                    kind: "lesson",
                    principle:
                        "An AI refactoring against a specific finding tends to do better than an AI generating from an abstract principle.",
                    problem:
                        "Telling the AI about your principles and hoping for compliance does not hold across a session.",
                    validation:
                        "Compare a session driven by findings with one driven by explanation. Count the fixes that stuck. The findings session wins, and if it does not, the findings are not specific enough.",
                },
                {
                    kind: "text",
                    text: "Healing comes before reporting, and it is auto-remediation in the ontology's sense. A violation whose remediation has exactly one correct answer is repaired in the same run that caught it, without being asked: a missing type the grammar computes, a form the registry records, a name whose only legal spelling is derivable. The flag disables healing and never enables it, because an opt-in fix flag inverts the rule and turns a computed repair into a queue. A fix is applied, re-validated and converges, so applying it twice changes nothing, which is idempotency, and one that fails its own check is not a fix. What reaches the AI is the residue: the findings that need judgement, which concern a file is, whether two roles split, what a duplicated fact's source should be.",
                },
                {
                    kind: "text",
                    text: "The error log is the communication channel, so it is typed. A finding carries the id of the check that fired, the path, the locus inside the file, the trail of what the check resolved on the way, the observed value, the derived expected value where one exists, a remediation as an action with real operands, and whether it healed. Prose in a finding is a defect, because the consumer is a reasoning agent that must not re-derive the analysis the check already performed. A sentence describing a rename is a description; the action and its two operands are a contract the agent can execute.",
                },
                {
                    kind: "text",
                    text: "The report on disk is the state of the work and the run is the measurement, as a report, not a checkbox spells out; it is audit logging, and it is what gives the run auditability.",
                },
                { caption: "the loop from outside", kind: "mermaid", text: LOOP_DIAGRAM },
                { code: FINDING_SAMPLE, kind: "code", language: TEXT_LANGUAGE, title: "an actionable finding" },
            ],
            title: "Detect, heal, report, fix",
        },
    ],
    title: "Detect, log, fix",
};

const GATE_SECTION: Section = {
    icon: GATE_SECTION_ICON,
    id: GATE_SECTION_ID,
    intro: "A rule without a check is a wish. The check ships with the rule, in the same change, or the rule does not exist, and what happens to it afterwards is what <cite>a check's events</cite> draws. This is the one rule every other rule depends on, and its intent is not strictness for its own sake: it is that a rule held by a check costs the same to hold on the thousandth change as on the first, while a rule held by attention costs more every time. The checks are fitness functions, policy enforcement is what they do, and the architecture page turns the same idea into a theory of decay: an anti-pattern is a decay path, and seven controls, seven classes places each by the check that was missing.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Write the check the moment you introduce the pattern, and make it catch the pattern's bypasses too. When a violation slips past it, extend the check before you touch the content that slipped, so the gate strengthens before the cleanup. Never weaken a check, never exclude a case to go green, and never add a tier softer than failure. Where a pattern cannot be gated statically, raise that as a question rather than treating it as permission.",
                    boundary:
                        "A pattern no static check can catch is a question for the person who owns the work, not a licence to skip the check. The honest answer to that question is a rule declared unobservable, with the evidence a check would need written beside it.",
                    cause: "Convention re-decides a rule at every use, and the model has no reason to decide it the same way twice.",
                    decision:
                        "Ship the check in the same change as the rule, rather than the rule now and the check when it bites.",
                    failureMode:
                        "The team agrees on a rule, someone tells the AI about it, and a month later half the tree follows it because nothing ever refused the other half.",
                    kind: "lesson",
                    principle: "The gate holds the line, not discipline. A rule holds only when a check enforces it.",
                    problem: "Convention does not survive contact with a model or with a tired person.",
                    validation:
                        "Introduce the pattern's nearest bypass and confirm the same check reports it; a check that catches the pattern and not its bypass holds the line on one side only.",
                },
                {
                    kind: "text",
                    text: "The check is the fix and the content edit is the cleanup. That order matters because a repaired instance with an unrepaired check is the same defect waiting for its next instance, and the party who found it has already spent the attention that would find it again. A caught duplicate, a caught escape hatch and a better approach discovered mid-task are all the same trigger: the affected rule absorbs the shape.",
                },
                {
                    kind: "text",
                    text: "Every check returns pass or fail, which is fail fast applied to the gate. There is no warning tier and no advisory level, because a middle tier lets a run terminate as successful while a failure is still open, which is the outcome a binary verdict exists to prevent; a tolerated red is flaky test normalization by another name. Severity survives as repair ordering among failures, never as a softer verdict. A check that would warn is promoted or deleted. The same refusal covers exclusions: a caught finding is resolved by fixing the code or by proving the finding tests a false premise, which deletes it, and never by widening an exemption or disabling the rule for one file.",
                },
                { caption: "a check's events", kind: "mermaid", text: GATE_DIAGRAM },
            ],
            title: "The check is the rule",
        },
    ],
    title: "The gate holds the line",
};

const ORDER_SECTION: Section = {
    icon: ORDER_SECTION_ICON,
    id: ORDER_SECTION_ID,
    intro: "The check is proven before it is trusted, and the order is check, proof, then code, as <cite>the order</cite> draws; each half of the proof catches a failure the other cannot. Verify the verifier is the same discipline applied to the checks that already exist.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Write the check first. Break it on purpose and watch it fire with the message you expected. Then run it over the real population and confirm at least one real member passes for the right reason. Restore the planted file, and only then write the code the check will hold. After narrowing a check for precision, run the case that motivated it again.",
                    boundary:
                        "A check every member satisfies for free is a field that always says the same thing, and its own greenness becomes the evidence that what it measures is working. Where nothing can disagree with a check, it is held with the forgone property written down rather than shipped weaker.",
                    cause: "A check has only the code in front of it to be shaped by, so it learns the code's accidents as the rule; testability is designed in or it is absent.",
                    decision: "Order every change as check, proof of firing, positive control, then code.",
                    failureMode:
                        "The check comes last, passes on the first run, and nobody ever learns that it would have passed anything.",
                    kind: "lesson",
                    principle:
                        "The check precedes the code, and nobody trusts a check until it has caught something on purpose and let something through on purpose.",
                    problem: "A check written after the code describes the code rather than the rule.",
                    validation:
                        "Find the change where each check first fired and the member it first cleared. A check with no such moments has never shown that it works.",
                },
                {
                    kind: "text",
                    text: "The two halves of the proof answer two different questions. A planted violation shows the check can reject, and a check nobody has seen fail is indistinguishable from one that cannot. A real member passing shows the check can discriminate, and a check whose every member fails has only been shown to reject: its first green is indistinguishable from a scope that stopped reaching, the mock mirage of a test that exercises nothing real. Where no member can pass yet because the correct shape does not exist in the tree, the first conformant member is written beside the check in the same change, so the check is proven against it before either is trusted.",
                },
                {
                    kind: "text",
                    text: "Narrowing is where a correct check silently loses its subject, and it is the point where a check matches a shape has to stay true. A rule is authored against a case and then scoped for precision, every refinement is judged on the false positives it removes, and nobody re-runs the true positive, so a scope that excludes the motivating case reads exactly like a scope that got tighter. The cheapest scoping is the harmful one, because it keys on the property the correct members share rather than on the property the defect has. Re-running the motivating case after every scoping costs a sentence, and it is the only step that separates a check that became precise from one that became blind.",
                },
                { caption: "the order", kind: "mermaid", text: ORDER_DIAGRAM },
            ],
            title: "Check, prove, then build",
        },
    ],
    title: "The check comes first",
};

export const BUILD_SECTIONS: readonly Section[] = [DETECT_SECTION, GATE_SECTION, ORDER_SECTION];