import { PAG_LANGUAGE, TEXT_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";
import { WELLFORMED_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { WELLFORMED_SECTION_ID } from "#core/ids/grammar.ids";

const DEFECT_SAMPLE =
    "# no declaration · a document with no stated kind\n%% META %%:\nTHIS WORKFLOW EXECUTES <what it is for>\n\n# a bare iteration · reads as a count, completes as one\nFOR <item> IN <collection>:\nFOR EACH <item> IN <collection>:\n\n# a lowercase keyword · a word, not a token\nif <condition>\nIF <condition>:\n\n# a node with no gate · a unit nothing can prove closed\n# NODE 2 — CONVERT   [epistemic · formalisation · computation · yields: procedure]\n    COMPOSE_ARTIFACT <shaped> FROM <row> USING <rules>\n# NODE 2 — CONVERT   [epistemic · formalisation · computation · yields: procedure]\n    COMPOSE_ARTIFACT <shaped> FROM <row> USING <rules>\n    HANDOFF GATE:\n      [check] every <row> converted (evidence: one <shaped> per row) over: <rows> measured: <converted> / <rows>\n      [check] <shaped> holds one entry per <row> (evidence: the two counts match)\n      [check] every entry conforms to <rules> (evidence: VALIDATE_ARTIFACT passed on each)\n      result: pass -> NODE 3 | mismatch -> REPAIR (owner: NODE 2) | unknown -> BLOCKED\n\n# a vague check · a judgement in a gate\n[check] data looks good\n[check] <data>.<field> matches <pattern> (evidence: the match returned true)\n\n# a check with no evidence · a claim the gate cannot settle\n[check] <report> is complete\n[check] <report> names every entry in <findings> (evidence: each finding's id present)\n\n# a gate with no population · a verdict about nothing\n[check] every <file> conforms (evidence: the validator's report)\n[check] every <file> conforms (evidence: the validator's report) over: <files> measured: <conforming> / <files>\n\n# an unknown left unrouted · the third verdict absorbed into pass\nresult: pass -> NODE 3 | failure -> REPAIR (owner: NODE 2)\nresult: pass -> NODE 3 | failure -> REPAIR (owner: NODE 2) | unknown -> BLOCKED\n\n# a write with no refusal · an irreversible act with no condition to stop it\nPERSIST_ARTIFACT <shaped> TO <destination>\nrefuse: <destination> changed since it was read before PERSIST_ARTIFACT\n\n# an invariant with no objector · a property nothing would disagree with\nINVARIANT one-writer: a record has exactly one writer\nINVARIANT one-writer: a record has exactly one writer over: every record binds: every party objector: [check] one open fence per record\n\n# a bare invariant block · a bullet under a head, with no set, no parties, no objector\nALWAYS:\n  - VALIDATE at node boundaries\nINVARIANT validate-at-boundary: every node validates its output over: every node binds: the reader objector: [check] the gate ran\n\n# a prose directive · an instruction the model must interpret\nGet the customer data and check it\nREAD_RESOURCE <records> INTO <held>\nVALIDATE_ARTIFACT <held> AGAINST <schema>";

const SCAN_SAMPLE =
    "document: <name>\n  defect      for_without_each\n  locus       NODE 2, line 4\n  found       FOR <item> IN <collection>:\n  expected    FOR EACH <item> IN <collection>:\n  fix         insert EACH after FOR\n\n  defect      gate_without_population\n  locus       NODE 3, gate\n  found       three checks, none with a set\n  expected    at least one check measured over a declared set\n  fix         name the set and the count measured over it\n\n  defect      unknown_unrouted\n  locus       NODE 3, result line\n  found       pass and failure arms only\n  expected    an unknown arm routed to BLOCKED\n  fix         add the third arm\n\n  defect      invariant_without_objector\n  locus       cross-node invariants, one-writer\n  found       a property with no objector\n  expected    the check that would disagree, or none as declared debt\n  fix         name the objector\n\nverdict: ill_formed";

const DEBUG_SAMPLE =
    "# a value undefined in a later node\n# cause · declared inside a branch, so it exists only there\nIF <condition>:\n    DECLARE <result>: object\n\nDECLARE <result>: object\nIF <condition>:\n    SET <result>.<value> = <data>\n\n# a gate that always fails\n# cause · the check names a value the node never produced\n    APPEND <item> TO <processed-items>\nHANDOFF GATE:\n    [check] <processed-list> populated (evidence: a count above zero)\n\n    APPEND <item> TO <processed-items>\nHANDOFF GATE:\n    [check] <processed-items> populated (evidence: a count above zero)\n\n# a contract that reads forward\n# cause · the input names an output a later node yields\n# NODE 2 — ANALYSIS\nCONTRACT:\n  input: <report> from NODE 3\n\n# NODE 2 — ANALYSIS\nCONTRACT:\n  input: <files> from NODE 1";

const SCAN_DIAGRAM =
    'flowchart TB\n    doc["A document"]\n    scan["A deterministic scan · tokens, never patterns"]\n    defects["The defect set · each named for the shape it catches"]\n    well["well_formed"]\n    ill["ill_formed · each defect with its locus and its fix"]\n    doc --> scan --> defects\n    defects -- empty --> well\n    defects -- non-empty --> ill';

const TRUST_DIAGRAM =
    'flowchart LR\n    fluent["Reads fluently"]\n    trusted1["Trusted · and wrong in the details nobody read"]\n    scanned["Passes the scan"]\n    trusted2["Trusted · because a mechanism said so"]\n    fluent -. the tempting path .-> trusted1\n    scanned --> trusted2';

export const WELLFORMED_SECTION: Section = {
    icon: WELLFORMED_SECTION_ICON,
    id: WELLFORMED_SECTION_ID,
    intro: "A document is trusted after static analysis for defects, never because it reads fluently, the two routes <cite>two routes to trust</cite> contrasts and <cite>the scan</cite> draws. The defects are named for the shape each catches, and each has one fix, paired as <cite>defect set</cite> lists them and reported as <cite>scan result</cite> shows. The syntactic ones: a missing declaration, a bare iteration, a lowercase keyword, a conditional with no colon, a malformed node tag, a node declared twice. The epistemic ones: a node with no gate, a gate outside three to five checks, a check that is a judgement, a check with no evidence, a gate with no population or an empty one, an unknown left unrouted. Then a write with no refusal, an artifact with no freshness, an input naming no source, an invariant missing its set, its parties or its objector, and a bare invariant block. The scan is the terminate stage applied to the document itself: it yields one boolean, and it reads tokens rather than patterns, so its verdict has repeatability.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Scan a document for the defect set before it is walked and after every edit. Report each defect with its locus, what was found, what was expected and the one fix, so a reader repairs the line rather than re-reading the document. Trust a document only on an empty defect set, and treat a fluent document that fails the scan as ill-formed however well it reads.",
                    boundary:
                        "Well-formedness is structure, not meaning. A document can pass every scan and still ask for the wrong thing, and that is what the gates, the review and the method exist to catch.",
                    cause: "Fluency is a property of prose, and the defects that break a document are properties of tokens the prose reader does not see.",
                    decision:
                        "Scan the tokens rather than match a pattern or read for fluency, because only a token scan reports a locus a reader can go to.",
                    failureMode:
                        "A document reads well, a bare iteration completes as a count, the node produces one result instead of many, and the gate that would have caught it was never written.",
                    kind: "lesson",
                    principle: "A document is trusted after a deterministic scan, not because it reads well.",
                    problem: "A document that reads well is walked as if it had been checked.",
                    validation:
                        "Plant one defect from the set in a passing document and scan it. A scan that stays green cannot catch that class, and a scan that reports it with the wrong locus is matching a pattern rather than reading tokens.",
                },
                {
                    kind: "text",
                    text: "The defect set is the grammar's failure taxonomy, and it is derived rather than collected: each epistemic defect is one of the ways a representation escapes its check, which the architecture page's the honest gaps and the methodology's coverage is derived name from the other side. A check with no population is the gate that passed over nothing, and an unknown left unrouted is the verdict that absorbed a third value into pass. A write with no refusal is the irreversible act with no condition to stop it, an input naming no source is a dependency inferred from a name, and an invariant with no objector is a property nothing would disagree with. Each defect has one repair, which is what lets a scanner state it, and the scan is token-based and free of pattern languages, a fact about the scanner and not about the grammar, whose conditions may carry a pattern literal.",
                },
                {
                    kind: "text",
                    text: "Three defects the scan does not catch present as gate failures, <cite>gate failures</cite> shows them, and all three are found by tracing a value from the node that yields it to the node that reads it. A contract whose input names a later node's output is the one whose repair is the decomposition rather than the line, because the node is in the wrong place.",
                },
                { code: DEFECT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "defect set" },
                { code: SCAN_SAMPLE, kind: "code", language: TEXT_LANGUAGE, title: "scan result" },
                { code: DEBUG_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "gate failures" },
                { caption: "the scan", kind: "mermaid", text: SCAN_DIAGRAM },
                { caption: "two routes to trust", kind: "mermaid", text: TRUST_DIAGRAM },
            ],
            title: "The defect set and the scan",
        },
    ],
    title: "Well-formedness",
};