//! Human-facing documentation for the mdwright TOML schema.
//!
//! The configuration schema and the prose that explains it change
//! together. Keeping the field catalogue in this crate gives the CLI
//! initializer and the generated documentation one source of truth
//! instead of two tables that can drift.

/// Build the generated configuration reference page.
#[must_use]
pub fn render_reference_markdown() -> String {
    let mut out = String::with_capacity(8192);
    out.push_str(REFERENCE_PREAMBLE);
    out.push_str("<!-- BEGIN GENERATED: do not edit. Regenerate by running `cargo xtask doc-config`. -->\n\n");
    render_reference_section(&mut out, "[lint]", "lint.");
    render_reference_section(&mut out, "[fmt]", "fmt.");
    render_reference_section(&mut out, "[parse]", "parse.");
    render_reference_section(&mut out, "[render]", "render.");
    out.push_str("<!-- END GENERATED -->\n");
    out
}

/// Build a documented standalone `.mdwright.toml` using the current
/// defaults for every known option.
#[must_use]
pub fn render_default_toml() -> String {
    let mut out = String::with_capacity(12_288);
    out.push_str("# mdwright configuration\n");
    out.push_str("#\n");
    out.push_str("# Generated by `mdwright config init`. Every key below is set to\n");
    out.push_str("# mdwright's current default. Edit or delete values to fit this project.\n");

    let mut current_table = "";
    for field in SCHEMA_FIELDS {
        let Some((table, key)) = field.key.rsplit_once('.') else {
            continue;
        };
        if table == current_table {
            out.push('\n');
        } else {
            current_table = table;
            out.push('\n');
            out.push('[');
            out.push_str(table);
            out.push_str("]\n");
        }
        out.push_str("# Type: ");
        out.push_str(field.ty);
        out.push_str(".\n");
        for line in field.description.lines() {
            out.push_str("# ");
            out.push_str(line);
            out.push('\n');
        }
        out.push_str(key);
        out.push_str(" = ");
        out.push_str(field.default);
        out.push('\n');
    }

    out
}

/// One row in the configuration reference and default-file template.
struct FieldDoc {
    /// Dotted TOML path, e.g. `"fmt.wrap"`.
    key: &'static str,
    /// Human-readable type, e.g. `"\"keep\" | \"no\" | int"`.
    ty: &'static str,
    /// Default value as it appears in TOML, e.g. `"\"keep\""`.
    default: &'static str,
    /// Prose description, one sentence.
    description: &'static str,
    /// CLI flag that overrides this key, or `None` for file-only knobs.
    cli_override: Option<&'static str>,
}

const SCHEMA_FIELDS: &[FieldDoc] = &[
    // ---- [lint] ------------------------------------------------------
    FieldDoc {
        key: "lint.preset",
        ty: "\"default\" | \"all\" | \"none\"",
        default: "\"default\"",
        description: "Baseline lint rule set. Use `default` for curated defaults, `all` for every registered rule, or `none` with `lint.select` for an explicit set.",
        cli_override: Some("--rules"),
    },
    FieldDoc {
        key: "lint.select",
        ty: "array of string",
        default: "[]",
        description: "Exact lint rule names to enable when `lint.preset = \"none\"`. Preset names are not valid rule names here.",
        cli_override: Some("--rules"),
    },
    FieldDoc {
        key: "lint.extend-select",
        ty: "array of string",
        default: "[]",
        description: "Lint rule names to add on top of `lint.preset`.",
        cli_override: Some("--rules"),
    },
    FieldDoc {
        key: "lint.ignore",
        ty: "array of string",
        default: "[]",
        description: "Lint rule names to remove after applying `lint.preset`, `lint.select`, and `lint.extend-select`.",
        cli_override: Some("--rules"),
    },
    FieldDoc {
        key: "lint.exclude",
        ty: "array of string",
        default: "[]",
        description: "Gitignore-style patterns. Matching files are dropped from lint runs. Patterns are anchored to the directory containing the config file.",
        cli_override: None,
    },
    FieldDoc {
        key: "lint.info-strings.extra",
        ty: "array of string",
        default: "[]",
        description: "Project-specific additions to the `info-string-typo` allowlist. The stdlib default allowlist still applies.",
        cli_override: None,
    },
    FieldDoc {
        key: "lint.render.renderer",
        ty: "\"mathjax-v3\" | \"katex\"",
        default: "\"mathjax-v3\"",
        description: "Math renderer the `math/render-compat` rule should check against.",
        cli_override: None,
    },
    FieldDoc {
        key: "lint.render.packages",
        ty: "array of string",
        default: "[]",
        description: "Renderer packages/extensions to load on top of the renderer's default autoload set (e.g. `[\"mhchem\", \"physics\"]`). Consumed by the `math/render-compat` rule.",
        cli_override: None,
    },
    FieldDoc {
        key: "lint.render.macros",
        ty: "table",
        default: "{}",
        description: "User-declared macros known to be in scope, keyed by command name (no leading backslash). Each entry is either `name = arity` or `name = { arity = N }`.",
        cli_override: None,
    },
    // ---- [fmt] -------------------------------------------------------
    FieldDoc {
        key: "fmt.profile",
        ty: "\"preserve\" | \"mdformat\"",
        default: "\"preserve\"",
        description: "Formatter style profile. `preserve` keeps mdwright's identity-oriented defaults; `mdformat` applies mdformat-compatible defaults where verified rewrites can preserve semantics. Explicit `[fmt]` keys override profile defaults.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.wrap",
        ty: "\"keep\" | \"no\" | int",
        default: "\"keep\"",
        description: "Wrap mode for prose paragraphs. `keep` leaves existing breaks alone; `no` forbids new breaks; an integer enforces that display-column budget for breakable lines in every formatter profile.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.wrap-strategy",
        ty: "\"stable\" | \"balanced\"",
        default: "\"stable\"",
        description: "Reflow strategy used when `fmt.wrap` is an integer. `stable` greedily fills soft-break runs and is the default; `balanced` rebalances paragraphs for more even line lengths.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.italic",
        ty: "\"asterisk\" | \"underscore\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Italic delimiter canonicalisation. `preserve` leaves source bytes; `asterisk` or `underscore` opts into the post-pass rewrite. See [Style knobs](format/style.md).",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.strong",
        ty: "\"asterisk\" | \"underscore\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Strong-emphasis delimiter canonicalisation. Independent of `fmt.italic`: `*italic*` with `__strong__` is expressible.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.list-marker",
        ty: "\"dash\" | \"asterisk\" | \"plus\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Unordered-list bullet canonicalisation. Each marker is rewritten through a marker-local fact and the family commits only after verification.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.ordered-list",
        ty: "\"one\" | \"consistent\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Ordered-list number canonicalisation. `one` rewrites markers to `1.` only when verification preserves the list start; `consistent` renumbers each list from the source's first item; `preserve` keeps source numbering verbatim.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.thematic-break",
        ty: "\"dash\" | \"asterisk\" | \"underscore\" | \"underscore-70\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Thematic-break canonicalisation. Fixed character modes preserve the source repeat count and spacing; `underscore-70` rewrites the whole break line to mdformat's 70 underscores.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.trailing-newline",
        ty: "\"preserve\" | \"strip\" | \"ensure\" | bool",
        default: "\"preserve\"",
        description: "Trailing-newline policy at the document boundary. `true` is accepted as a synonym for `ensure` and `false` for `strip`.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.end-of-line",
        ty: "\"lf\" | \"crlf\" | \"keep\"",
        default: "\"lf\"",
        description: "Line-ending normalisation. `keep` adopts the first newline seen in the source.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.exclude",
        ty: "array of string",
        default: "[]",
        description: "Formatter-specific exclude globs, independent of `[lint] exclude`.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.heading-attrs",
        ty: "\"preserve\" | \"canonicalise\"",
        default: "\"preserve\"",
        description: "ATX heading `{#id .class key=val}` trailer emission. `preserve` emits the source trailer byte-verbatim. `canonicalise` emits id first, then classes, then key-value pairs.",
        cli_override: None,
    },
    // ---- [fmt.refs] --------------------------------------------------
    FieldDoc {
        key: "fmt.refs.placement",
        ty: "\"end\" | \"preserve\"",
        default: "\"end\"",
        description: "Where reference-link definitions are emitted: gathered and sorted at the end of the document, or kept in source order.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.refs.style",
        ty: "\"bare\" | \"angle\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Destination style for reference-link and inline-link URLs. `preserve` keeps each destination's source form; `bare` strips wrapping `<...>` where the bare form still parses; `angle` wraps every destination in `<...>`.",
        cli_override: None,
    },
    // ---- [fmt.footnotes] --------------------------------------------
    FieldDoc {
        key: "fmt.footnotes.placement",
        ty: "\"end\" | \"preserve\"",
        default: "\"preserve\"",
        description: "Where footnote definitions are emitted. Default is `preserve` because pulldown-cmark's HTML renderer ties footnote position to parse order; moving definitions would change the rendered HTML.",
        cli_override: None,
    },
    // ---- [fmt.tables] -----------------------------------------------
    FieldDoc {
        key: "fmt.tables.style",
        ty: "\"compact\" | \"align\" | \"preserve\"",
        default: "\"compact\"",
        description: "GFM table spacing policy. `compact` trims cell padding to one space on each side; `align` pads columns by display width; `preserve` keeps source cell spacing.",
        cli_override: None,
    },
    // ---- [fmt.lists] -------------------------------------------------
    FieldDoc {
        key: "fmt.lists.continuation-indent",
        ty: "\"marker-width\" | \"four-space\"",
        default: "\"marker-width\"",
        description: "Continuation indentation for wrapped list-item paragraphs. `marker-width` aligns to the source marker width; `four-space` matches mdformat's list continuation spelling.",
        cli_override: None,
    },
    // ---- [fmt.frontmatter] ------------------------------------------
    FieldDoc {
        key: "fmt.frontmatter.preserve",
        ty: "bool",
        default: "true",
        description: "Whether to emit document frontmatter byte-verbatim. `false` strips it.",
        cli_override: None,
    },
    // ---- [fmt.math] --------------------------------------------------
    FieldDoc {
        key: "fmt.math.normalise",
        ty: "bool",
        default: "false",
        description: "Whether whole-block math regions are normalised. Off by default because math bytes are opaque to CommonMark.",
        cli_override: None,
    },
    FieldDoc {
        key: "fmt.math.render",
        ty: "\"none\" | \"commonmark-katex\" | \"dollar\"",
        default: "\"none\"",
        description: "Math delimiter rendering policy for downstream renderers. `none` preserves source math regions; `commonmark-katex` records intent without rewriting; `dollar` rewrites bracket and paren math to dollar delimiters.",
        cli_override: None,
    },
    // ---- [parse.math] -----------------------------------------------
    FieldDoc {
        key: "parse.math.delimiters",
        ty: "\"tex\" | \"github\"",
        default: "\"tex\"",
        description: "Math delimiter recognition policy. `tex` recognises `\\(...\\)`, `\\[...\\]`, and LaTeX environments; `github` also recognises `$...$` and `$$...$$`.",
        cli_override: None,
    },
    // ---- [parse.extensions] -----------------------------------------
    FieldDoc {
        key: "parse.extensions.definition-lists",
        ty: "bool",
        default: "true",
        description: "Recognise `Term\\n: definition\\n` definition lists. Turn off on non-mkdocs corpora to suppress recognition.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.abbreviation-lists",
        ty: "bool",
        default: "true",
        description: "Recognise `*[ABBR]: definition` abbreviation declarations as a scan-and-preserve overlay. mdwright does not expand occurrences; the downstream renderer does.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.heading-attribute-lists",
        ty: "bool",
        default: "true",
        description: "Recognise `# Heading {#id .class}` trailers via pulldown's heading-attribute extension. When off, the trailer reads as plain text in the heading body.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.block-attribute-lists",
        ty: "bool",
        default: "true",
        description: "Recognise `{ .class }` on a line by itself after a non-empty block as a scan-and-preserve overlay. Inline attribute lists are out of scope.",
        cli_override: None,
    },
    // ---- [parse.extensions.gfm] -------------------------------------
    FieldDoc {
        key: "parse.extensions.gfm.autolinks",
        ty: "\"disabled\" | \"urls\" | \"urls-and-emails\"",
        default: "\"urls-and-emails\"",
        description: "Recognise GFM bare URL and email autolinks as document facts and render them as links. Use `urls` to leave bare emails as text or `disabled` for strict CommonMark-style text treatment.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.gfm.tagfilter",
        ty: "bool",
        default: "true",
        description: "Apply GFM tagfiltering when rendering or building semantic signatures. This escapes the raw HTML tags that cmark-gfm filters, without rewriting source bytes.",
        cli_override: None,
    },
    // ---- [parse.extensions.myst] ------------------------------------
    FieldDoc {
        key: "parse.extensions.myst.directive-containers",
        ty: "bool",
        default: "true",
        description: "Recognise MyST `:::{name}` directive containers with `:KEY: value` options as a scan-and-preserve overlay. mdwright does not expand directives; downstream renderers do.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.myst.inline-roles",
        ty: "bool",
        default: "true",
        description: "Recognise MyST `` {role}`payload` `` inline roles as a scan-and-preserve overlay inside paragraph text.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.myst.substitution-references",
        ty: "bool",
        default: "true",
        description: "Recognise MyST `{{name}}` inline substitution references as a scan-and-preserve overlay. Declarations live in YAML frontmatter and round-trip through the frontmatter path.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.myst.comments",
        ty: "bool",
        default: "true",
        description: "Recognise MyST `%` line comments at line-start as a scan-and-preserve overlay.",
        cli_override: None,
    },
    // ---- [parse.extensions.pandoc] ----------------------------------
    FieldDoc {
        key: "parse.extensions.pandoc.fenced-divs",
        ty: "bool",
        default: "true",
        description: "Recognise Pandoc `::: {.cls}` fenced div openers. The closer is a colon-only line of matching count.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.pandoc.short-form-divs",
        ty: "bool",
        default: "true",
        description: "Recognise Pandoc `:::name` fenced div openers.",
        cli_override: None,
    },
    FieldDoc {
        key: "parse.extensions.pandoc.inline-attribute-spans",
        ty: "bool",
        default: "true",
        description: "Recognise Pandoc `[content]{.cls}` inline attribute spans as a scan-and-preserve overlay.",
        cli_override: None,
    },
    // ---- [render] ----------------------------------------------------
    FieldDoc {
        key: "render.profile",
        ty: "\"pulldown\" | \"cmark-gfm\"",
        default: "\"pulldown\"",
        description: "HTML spelling profile for `mdwright render`. `pulldown` preserves the default renderer; `cmark-gfm` matches cmark-gfm spelling where parser semantics already agree.",
        cli_override: Some("--render-profile"),
    },
];

const REFERENCE_PREAMBLE: &str = r#"# Configuration

mdwright reads configuration from (in precedence order):

1. The file given via `--config PATH`.
2. The nearest ancestor config discovered by walking upward from the
   current directory. At each ancestor, candidates are tried in this
   order: `.mdwright.toml`, `mdwright.toml`,
   `pyproject.toml` containing a `[tool.mdwright]` table. The walk
   stops at the filesystem root or at the first directory containing
   `.git/` (the workspace boundary).
3. Built-in defaults.

A `pyproject.toml` *without* `[tool.mdwright]` does not stop the walk;
discovery continues to the parent directory. A `.mdwright.toml` wins
over a `pyproject.toml` in the same directory (matching ruff's
"more-specific-name first" rule).

Run `mdwright config init` to create a documented `.mdwright.toml`
starter file with every option set to its default.

## Single-file integration via `pyproject.toml`

For projects that already use `pyproject.toml`, the entire mdwright
configuration can live there under `[tool.mdwright]`:

```toml
# pyproject.toml
[tool.mdwright]
lint.preset = "default"
lint.extend-select = ["latex-command"]

[tool.mdwright.fmt]
wrap = 100
```

## CLI overrides

The following knobs accept CLI flags that take precedence over the
config file:

- `lint.preset`, `lint.select`, `lint.extend-select`, `lint.ignore`: `--rules`
- `render.profile`: `mdwright render --render-profile`
- `--no-suppress` toggles whether `<!-- mdwright: allow ... -->`
  comments are honoured; there is no config-file equivalent.

All `[fmt]` knobs are config-file-only.

## Schema reference

"#;

fn render_reference_section(out: &mut String, heading: &str, prefix: &str) {
    out.push_str("### `");
    out.push_str(heading);
    out.push_str("` and nested tables\n\n");
    out.push_str("| Key | Type | Default | CLI override | Description |\n");
    out.push_str("| --- | --- | --- | --- | --- |\n");
    for field in SCHEMA_FIELDS {
        if !field.key.starts_with(prefix) {
            continue;
        }
        let cli = field.cli_override.unwrap_or("none");
        let ty_escaped = field.ty.replace('|', "\\|");
        out.push_str("| `");
        out.push_str(field.key);
        out.push_str("` | ");
        out.push_str(&ty_escaped);
        out.push_str(" | `");
        out.push_str(field.default);
        out.push_str("` | `");
        out.push_str(cli);
        out.push_str("` | ");
        out.push_str(field.description);
        out.push_str(" |\n");
    }
    out.push('\n');
}
