import { ANATOMY_READING_ICON, ANATOMY_SECTION_ICON } from "#configuration/icons/anatomy.icons";
import {
    DERIVED_SECTION_ID,
    DIAGNOSES_SECTION_ID,
    PARTS_SECTION_ID,
    READING_TAB,
    SPINE_SECTION_ID,
    WALK_SECTION_ID,
} from "#core/ids/anatomy.ids";
import type { Section, Tab, TabbedMeta } from "#types/document.types";

export const ANATOMY_META: TabbedMeta = {
    subtitle:
        "The client source of this site, parsed on every build. This tab says what the page measures and how to read it. The tree tab is the source as it sits on disk: every folder and file, and for each file the syntax walk, the definitions with their call edges, and the source itself.",
    title: "The Anatomy",
    version: "1.0.0",
};

export const ANATOMY_ATTRIBUTION =
    "The anatomy is derived from this site's client source on every build and published here in full.";

const READING_LABEL = "Reading";

export const MEASUREMENTS_TAG = "the measurements";
export const IMPORTS_TAG = "the import graph";
export const STRUCTURE_TAG = "structure";
export const FLOW_TAG = "logical flow";
export const DATA_FLOW_TAG = "data flow";
export const LAYERS_TAG = "the layers";
export const FINDINGS_TAG = "the findings";
export const SAMPLE_WALK_TAG = "a walk";
export const LEGEND_TAG = "the legend";

export const ANATOMY_CHAPTER: readonly Section[] = [
    {
        icon: ANATOMY_SECTION_ICON,
        id: DERIVED_SECTION_ID,
        intro: "This tab is the one thing on the page I wrote; it says how to read the rest. Every panel, every number and the whole tree tab come out of the build: it parsed every source file of the site's client, built the call graph, ran the diagnoses and laid every syntax node on a grid. The page renders that output by shape, which is what derived state on the methodology page asks of any state. The module's totals are <cite>the measurements</cite>, and the edges between its containers are <cite>the import graph</cite>.",
        subsections: [
            {
                blocks: [
                    {
                        application:
                            "Read every number on this page as a measurement taken at build time. Open the tree tab to see the source as it sits on disk; open a file to see its walk, its definitions and its source. Where a number here disagrees with the tree you can read, the tree is right and this page is stale.",
                        boundary:
                            "The page describes the client source the reader is looking at and nothing behind it. The tooling that produced it, the documents that govern it and the checks that gate it are not on this tree, so they are not on this page.",
                        cause: "A description written by hand is a second copy of the tree, and a second copy disagrees with the first from the day one of them moves.",
                        decision:
                            "Publish the derivation and not a description of it, so the page can only be as wrong as the build that produced it.",
                        failureMode:
                            "An architecture page names three containers and the tree holds four, the fourth added the week after the page was written, and every reader of the page reasons about a tree that no longer exists.",
                        kind: "lesson",
                        principle:
                            "A page about a system is derived from the system in the same build that renders it, or it is a claim.",
                        problem:
                            "A page that describes a codebase is prose about the codebase, and prose has no mechanism that makes it wrong when the codebase changes.",
                        validation:
                            "Pick any file on the tree tab and open the same file on disk. The definitions, the line count and the imports on the page match the file, or the page was not derived from it.",
                    },
                    {
                        kind: "text",
                        text: "The measurements are the same ones the quality tooling reads: how many definitions the parser found, how many call edges it resolved between them, how many calls it could not resolve, and the diagnoses it ran. A call the parser cannot resolve is counted and never guessed, so the resolution rate is a measured fraction and not a hope.",
                    },
                    {
                        kind: "text",
                        text: "The import graph folds every import a file makes to the container that owns the imported file, so an edge is a container reaching into another container, counted. The direction axis on the architecture page says which way those edges may run; this graph says which way they do.",
                    },
                ],
                title: "What the reader is seeing",
            },
        ],
        title: "This page is derived",
    },
    {
        icon: ANATOMY_SECTION_ICON,
        id: PARTS_SECTION_ID,
        intro: "A system is a graph on the architecture page names four parts, and each one is measured here. The components are the definitions, the relations are the call edges between them, the schema is the set of diagnoses the parser can run, and the propagation is the fan-in every definition carries. The shape of the whole is <cite>structure</cite>, and the order in which it runs is <cite>logical flow</cite>.",
        subsections: [
            {
                blocks: [
                    {
                        kind: "text",
                        text: "Every definition carries an in-degree and an out-degree, and the two decide its flow class: an entry has callers and no callees, a leaf has callees and no callers, a relay has both, and an isolated definition has neither. The flow classes are counted per file, per folder and for the whole tree, so a container that is mostly leaves and a container that is mostly relays read differently before a single file is opened.",
                    },
                    {
                        kind: "text",
                        text: "Definitions own what, code owns how is what the split between the two charts shows: the structure is what exists and how it is arranged, the logical flow is what calls what when it runs. Both are read from the same syntax trees, so they cannot disagree with each other, only with a tree that has moved since the build.",
                    },
                ],
                title: "Components, relations, schema, propagation",
            },
        ],
        title: "The four parts, measured",
    },
    {
        icon: ANATOMY_SECTION_ICON,
        id: SPINE_SECTION_ID,
        intro: "Every file on the tree tab carries its subject, its concern and, where the name declares one, its variant, read off the file name the way placement is a grammar parses it, and every concern is tagged to a layer of the layer spine. The layers the tree lands on are <cite>the layers</cite>, and what moves between the containers at runtime is <cite>data flow</cite>.",
        subsections: [
            {
                blocks: [
                    {
                        kind: "text",
                        text: "A folder's role is read from its depth and its name: the first folder under the member is a container, a folder whose name is a concern folder is a concern, and anything between is a subject folder that exists only because two sets of one concern must not merge. A file whose name the grammar cannot parse carries no slots and no layer, and the page says so rather than guessing one.",
                    },
                    {
                        kind: "text",
                        text: "The layer a file lands on is a derivation from its concern and never a fact somebody typed, which is why the same file shows the same layer on this page and in every check that reads the tree. A folder shows the layer of its concern, and a container shows none, because a container groups by axis and not by layer.",
                    },
                ],
                title: "Roles, slots and layers",
            },
        ],
        title: "Containers on the spine",
    },
    {
        icon: ANATOMY_SECTION_ICON,
        id: DIAGNOSES_SECTION_ID,
        intro: "The diagnoses are the schema applied to the graph: a call cycle, a definition nothing consumes, a definition declared twice, a file that reaches across too many concerns, and an import cycle between modules. What they found is <cite>the findings</cite>, and a zero there is a measured zero, the difference unknown is not pass draws. One concern folder's walk is <cite>a walk</cite>, so the reading below has something to read.",
        subsections: [
            {
                blocks: [
                    {
                        kind: "text",
                        text: "Each diagnosis names the control whose absence lets the decay in, the way an anti-pattern is a decay path teaches, and carries the remedy that reverses it. A finding on this page lands on the file it names, in that file's record on the tree tab, so the reader can open the walk and the source the finding is about.",
                    },
                    {
                        kind: "text",
                        text: "A diagnosis that runs and finds nothing is different from one that never ran, which is the honest gaps on the architecture page. The diagnoses here are the ones the parser runs on every build; a predicate the method calls for that this parser does not compute is declared absent on that page, never assumed clean here.",
                    },
                ],
                title: "What the schema can say",
            },
        ],
        title: "What the diagnoses found",
    },
    {
        icon: ANATOMY_SECTION_ICON,
        id: WALK_SECTION_ID,
        intro: "A walk lays every meaningful syntax node of a file on a hexagonal grid in the order the parser met them, so a file is a path the eye can follow: down when the code nests, up when it returns, sideways when it continues. The states are <cite>the legend</cite>: what declares, what calls, what writes, what reads, what branches and what merely holds structure.",
        subsections: [
            {
                blocks: [
                    {
                        kind: "text",
                        text: "The arrows mark the direction every few steps, and a flagged cell carries the severity of the finding that flagged it. Every cell is a reference into the data the walk ships beside it, so the vector stays a shape and the text lives in a file the page reads by reference, the same way a code panel is cited from the prose.",
                    },
                    {
                        kind: "text",
                        text: "Drag to pan, scroll to zoom, and select a cell to read what it is: the file and line, the syntax kind and the text. A folder's walk is its files in order, and a file's walk is that file alone, so the tree can be read at either scale. A walk shows syntax and never semantics; what a call resolves to is the call graph's to say, and the definitions beside each file say it.",
                    },
                ],
                title: "States, arrows and cells",
            },
        ],
        title: "Reading a walk",
    },
];

export const ANATOMY_CONTENT: readonly Tab[] = [
    { icon: ANATOMY_READING_ICON, id: READING_TAB, label: READING_LABEL, layout: "chapter", sections: ANATOMY_CHAPTER },
];