import { IDIOM_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { IDIOM_SECTION_ID } from "#core/ids/grammar.ids";
import { PAG_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";

const INPUT_SAMPLE =
    'READ <file> FROM <path> INTO <content>        # non-destructive · the source is unchanged\nLOAD <settings> FROM <file>                    # acquisition with parsing\nEXTRACT <fields> FROM <record> INTO <values>   # isolation · the source keeps its meaning\nFIND <pattern> IN <scope> INTO <found>          # existence · boolean, non-invasive\nGLOB "<pattern>" INTO <files>                  # discovery by shape\nGREP "<term>" IN <path> INTO <matches>          # discovery by content';

const OUTPUT_SAMPLE =
    "WRITE <content> TO <file>                       # idempotent where it overwrites\nCREATE <report> FROM <data> USING <template>     # a candidate set or an artifact\nAPPEND <item> TO <collection>                    # growth without retraction\nREPORT <status>                                  # a statement to a reader, never a state\n\nCONVERT <data> TO <format>\nFILTER <items> TO <kept> WHERE <condition>       # removes, preserves order\nMERGE <sources> INTO <target>\nSPLIT <data> BY <delimiter> INTO <segments>";

const CONTROL_SAMPLE =
    'VALIDATE <data> AGAINST <schema>                 # conformance\nVERIFY <condition>                               # a boolean, non-modifying\nANALYZE <state> FOR <errors> INTO <found>        # deep examination, may delegate\nCOMPARE <actual> AGAINST <expected> INTO <diff>\nRANK <candidates> BY <score> INTO <ordered>       # score-driven ordering\n\nEXECUTE <command> WITH <params>                  # side effects possible\nTASK "<objective>" WITH agent: <role> -> <result>\nSEND <message> TO <recipient>\nAWAIT <response> INTO <result>\nSET <state> = <value>                            # assignment · idempotent\nLINK <source> TO <target>                        # a bidirectional association';

const GUARANTEE_DIAGRAM =
    'flowchart TB\n    verb["A verb"]\n    guarantee["Its semantic contract · what it promises about the source and the result"]\n    reader["A reader relies on the contract"]\n    model["The model completes the pattern the contract names"]\n    check["A scan can hold the contract · a READ that mutates is a defect"]\n    verb --> guarantee\n    guarantee --> reader\n    guarantee --> model\n    guarantee --> check';

const PREPOSITION_DIAGRAM =
    'flowchart LR\n    from["FROM · the origin"]\n    in["IN · the container searched"]\n    into["INTO · the destination bound"]\n    to["TO · the destination intended"]\n    using["USING · the mechanism"]\n    against["AGAINST · the reference"]\n    for["FOR · the purpose"]\n    with["WITH · the parameters"]\n    from ~~~ in ~~~ into ~~~ to\n    using ~~~ against ~~~ for ~~~ with';

export const IDIOM_SECTION: Section = {
    icon: IDIOM_SECTION_ICON,
    id: IDIOM_SECTION_ID,
    intro: "Each verb carries a semantic contract, and the contract is what a document relies on rather than what any particular tool happens to do: a read leaves its source unchanged whatever tool performs it. The contracts are listed by what each verb promises, <cite>input verbs</cite> about the source, <cite>output verbs</cite> about the result, <cite>control verbs</cite> about effects, and <cite>three readers</cite> is who a contract serves. The prepositions carry the relations between the operands, as <cite>the prepositions</cite> declares them, and a verb's contract plus its preposition is the whole meaning of a line.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Read when the source must survive, extract when meaning must, find when only existence matters, filter when order must hold, execute when a side effect is the point. Bind the operands with the preposition that names their relation. Rely on the guarantee downstream, and treat a line whose behaviour breaks it as a defect in the line.",
                    boundary:
                        "A contract is a promise the grammar makes about the intent; whether the party executing the line honours it is what verification is for.",
                    cause: "A verb the model has seen carry one guarantee across many contexts carries it into the completion; a verb used loosely carries every meaning it has ever had.",
                    decision:
                        "Choose the verb by the guarantee the line needs rather than by the tool that will perform it.",
                    failureMode:
                        "A document says process the items, the model reads, filters, writes and deletes under one word, and the reviewer cannot say which of those the author meant.",
                    kind: "lesson",
                    principle: "A verb is a semantic contract, and a preposition is a declared relation.",
                    problem: "A verb with no stated guarantee means whatever the model completes it as.",
                    validation:
                        "Read a line and state what it promises about its source and its result. A line whose promise you cannot state uses a verb loosely, and the repair is the verb whose guarantee matches the intent.",
                },
                {
                    kind: "text",
                    text: "A contract promises one of three things: what happens to the source, what the result is, or what effects the line may have. Two carry the most weight. An execute may have side effects, and saying so is what keeps each one from being a hidden side effect. A report is a statement to a reader and never a state anything later reads as the truth.",
                },
                {
                    kind: "text",
                    text: "A line with the wrong preposition is a line whose operands are in the wrong relation, and the model completes the relation it was given.",
                },
                { code: INPUT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "input verbs" },
                { code: OUTPUT_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "output verbs" },
                { code: CONTROL_SAMPLE, kind: "code", language: PAG_LANGUAGE, title: "control verbs" },
                { caption: "three readers", kind: "mermaid", text: GUARANTEE_DIAGRAM },
                { caption: "the prepositions", kind: "mermaid", text: PREPOSITION_DIAGRAM },
            ],
            title: "Verbs and their contracts",
        },
    ],
    title: "Instruction patterns",
};