import { TEXT_LANGUAGE, TYPESCRIPT_LANGUAGE } from "#configuration/constants/code.constants";
import type { Section } from "#types/document.types";
import { TAXONOMY_SECTION_ICON } from "#configuration/icons/taxonomy.icons";
import { TAXONOMY_SECTION_ID } from "#core/ids/taxonomy.ids";

const VOCABULARY_SHAPE =
    'export const LAYERS = ["domain", "application", "processing", "runtime", "infrastructure", "operations", "product"] as const;\n\nexport const taxonomy = {\n    containers: {\n        "<governed-root>": ["<container>", "<container>"],\n    },\n    specialContainers: {\n        "<governed-root>": ["<flat-bucket>"],\n    },\n    concerns: [\n        { folder: "registries", tag: "registry", layer: "infrastructure" },\n        { folder: "validators", tag: "validator", layer: "processing" },\n        { folder: "strings", tag: "strings", layer: "product" },\n    ],\n    subjects: ["base", "<domain-noun>", "<domain-noun>"],\n    variants: ["<facet>", "<facet>"],\n    grammar: {\n        separator: ".",\n        maxDepthFromRoot: 3,\n        compoundMarkers: ["test", "spec", "generated"],\n    },\n} as const;\n\ntype Config = typeof taxonomy;\nexport type Subject = Config["subjects"][number];\nexport type Variant = Config["variants"][number];\nexport type ConcernTag = Config["concerns"][number]["tag"];\nexport type GovernedRoot = keyof Config["containers"];\n\ntype Assert<Name extends string, Overlap> = [Overlap] extends [never] ? true : [Name, Overlap];\n\nexport const NO_SUBJECT_CONCERN_OVERLAP: Assert<"subject is already a concern tag", Extract<Subject, ConcernTag>> = true;\nexport const NO_VARIANT_SUBJECT_OVERLAP: Assert<"variant is already a subject", Extract<Variant, Subject>> = true;\nexport const EVERY_LAYER_DECLARED: Assert<"concern layer is not in the spine", Exclude<Config["concerns"][number]["layer"], (typeof LAYERS)[number]>> = true;';

const GRAMMAR_SAMPLE =
    "folder = <container> | <subject> | <concern>       one word, never a dot\nfile   = <subject>.<concern>.<ext>\n       | <subject>.<variant>.<concern>.<ext>        only when two files would collide\n\ndepth  = container(1) → subject(2, optional) → concern(3) → file\n         a role may be skipped, never repeated, never revisited\n         the file's parent is always the concern folder\n         the file's concern tag equals its parent folder";

const PLACEMENT_DIAGRAM =
    'flowchart TB\n    engine["engine · a container, one grouping axis"]\n    registries["registries · a concern folder, files of one role"]\n    page["page.registry.ts"]\n    route["route.registry.ts"]\n    form["form · a subject folder"]\n    panel["panel · a subject folder"]\n    fv["validators"]\n    pv["validators"]\n    field["field.validator.ts"]\n    layout["layout.validator.ts"]\n    engine --> registries --> page\n    registries --> route\n    engine --> form --> fv --> field\n    engine --> panel --> pv --> layout\n    form -. two sets of validators must not merge .- panel';

const WORD_DIAGRAM =
    'flowchart LR\n    word["A word at a slot"]\n    role{"A role a file plays?"}\n    thing{"A thing the system has?"}\n    concern["The concern list · the file\'s tag"]\n    subject["The subject list · the first slot of a name"]\n    rejected["Rejected · a process, an adjective, a grouping label"]\n    split["The file gets its real role, or splits"]\n    word --> role\n    role -- registry, validator, renderer --> concern\n    role -- no --> thing\n    thing -- form, panel, route --> subject\n    thing -- timing, lazy, misc, helper --> rejected --> split';

const JURISDICTION_DIAGRAM =
    'flowchart TB\n    tree["A tree"]\n    declared{"Declared as a governed root?"}\n    governed["Every file inside resolves to one legal path"]\n    foreign{"Carries another system\'s ownership markers?"}\n    upstream{"Authored elsewhere?"}\n    left["Left alone · a grammar that does not claim a tree enforces nothing in it"]\n    refused["Refused as a root · its names are identifiers another runtime resolves"]\n    exempt["Declared once as upstream · exempt from naming, tense and reference checks together"]\n    tree --> declared\n    declared -- yes --> foreign\n    foreign -- yes --> refused\n    foreign -- no --> governed\n    declared -- no --> upstream\n    upstream -- yes --> exempt\n    upstream -- no --> left';

const TAXONOMY_SECTION: Section = {
    icon: TAXONOMY_SECTION_ICON,
    id: TAXONOMY_SECTION_ID,
    intro: "Where a file lives and what its name says are one grammar, <cite>the grammar</cite>. A container, an optional subject, a concern, then the file, as <cite>one tree</cite> draws. The file's name ends with the concern of its folder, which is concern-folder correspondence. Every word comes from a closed vocabulary, placed as <cite>where a word goes</cite> draws and declared as <cite>the vocabulary</cite> types, and what the grammar claims and leaves alone is what <cite>jurisdiction</cite> draws. A file with two concerns is a split and never takes a vague name, which is one concern per file, and only an irreducible overlap between two tags for one concern takes the domain-ward tag, the precedence the layer spine on the architecture page holds. The grammar is what turns separation of concerns from advice into a check, and the layer spine is the classification axis it places every concern on.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Declare the closed vocabulary and the roots it governs. Parse every path against the grammar in a check. Resolve a collision sideways with a variant, never downward with another folder. Treat an undeclared word as a decision for a person, worked down a ladder: an existing word first, then the is-a test, then the filename is wrong, then the file is wrong. Create every file conformant, because there is no conversion queue.",
                    boundary:
                        "Files an ecosystem names for you keep their names. The grammar governs what you author, not what your tools require, and a tree carrying another system's ownership markers is never declared a governed root, because its names are identifiers that system resolves at runtime.",
                    cause: "Nothing parses a path, so a wrong placement fails no check and reads as a preference.",
                    decision: "Close the vocabulary and parse the path, rather than review placement by eye.",
                    failureMode:
                        "A helper folder appears. Then a utils folder. Then a second helper folder inside a feature. Six months later nobody can say where a new file goes.",
                    kind: "lesson",
                    principle:
                        "Placement is a grammar. A name is a claim about what the code does, verified against the code and never against the old name.",
                    problem:
                        "Separation of concerns as advice produces a different tree from every person who follows it.",
                    validation:
                        "Pick a file at random and derive its path from its contents alone. If the derived path differs from the real one, one of them is wrong, and the grammar says which.",
                },
                { code: GRAMMAR_SAMPLE, kind: "code", language: TEXT_LANGUAGE, title: "the grammar" },
                { caption: "one tree", kind: "mermaid", text: PLACEMENT_DIAGRAM },
            ],
            title: "One legal path per file",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "Positional slot resolution rather than lexical. A word is read by the slot it lands in, so a concern tag is a legal subject: a registry of pools and a pool named base use the same word in two slots with no ambiguity. The one lexical bar is that a subject never equals its concern. A subject folder exists if and only if a container holds two or more sets of one concern that must not merge, because optional grouping would give classification two right answers and make placement uncheckable. Sideways overflow relieves the rest: a collision takes the filename's variant slot and breadth takes a sibling subject folder, and the bounded nesting depth is why both slots exist.",
                },
                { caption: "where a word goes", kind: "mermaid", text: WORD_DIAGRAM },
            ],
            title: "Slots, not words",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "Declared jurisdiction decides what the grammar reaches. A key in the configuration is a governed root, and no declaration means no enforcement, so a tree outside jurisdiction keeps its own names. A declaration is a claim verified against the disk: a root declared ahead of the folder governs nothing, fails nothing and reads as coverage. Material authored elsewhere is declared once as an upstream root, and that one declaration exempts it from the naming, tense and reference checks together, because all three fail such a tree and not one of the failures is a defect in it.",
                },
                { caption: "jurisdiction", kind: "mermaid", text: JURISDICTION_DIAGRAM },
            ],
            title: "Jurisdiction is declared",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "Classification is judgement and structure is machine-decidable, and the line between them is where the tooling stops. A check reports that a name does not parse or that a tag disagrees with its folder. It never decides what a file is; the layer spine on the architecture page carries the classification rule. The reshape of an existing tree is therefore a manual identity migration, one container at a time with the gate green between each, and moves and renames carries the rest.",
                },
            ],
            title: "Judgement classifies, the check parses",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "The vocabulary is one typed declaration, and its type is what makes it closed: each slot's legal words are a union derived from the data rather than written a second time, and a flat bucket is declared rather than inferred from shape.",
                },
                {
                    kind: "text",
                    text: "The declaration then asserts its own consistency at compile time. A subject that is already a concern tag, a variant that is already a subject, or a concern whose layer is outside the spine fails to compile, so the vocabulary cannot go inconsistent without the whole gate refusing to load. A configuration that carries data and its own consistency proofs, and no reasoning, is the shape every closed vocabulary here takes.",
                },
                { code: VOCABULARY_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "the vocabulary" },
            ],
            title: "A vocabulary that proves itself",
        },
    ],
    title: "Placement is a grammar",
};

export const TAXONOMY_SECTIONS: readonly Section[] = [TAXONOMY_SECTION];