#!/usr/bin/env python3
# /// script
# requires-python = ">=3.9"
# ///
"""okf-export — an Obsidian-style vault folder in, an OKF bundle out that okf-check can gate once each note
has frontmatter.

Note tools count only `[[wikilinks]]` for backlinks and graphs, so a team that edits in one cannot
switch its source to OKF links without losing those features. This command lets the vault stay the
single source: it writes a separate bundle that okf-check can gate once each note carries its own YAML frontmatter
with a non-empty `type` field (the export copies frontmatter and writes none into your notes). The vault is only read.

Usage:
    okf-export <vault> <out>
"""
from __future__ import annotations

import argparse
import bisect
import datetime
import functools
import itertools
import os
import re
import shutil
import stat
import sys
import tempfile
import unicodedata
from pathlib import Path
from urllib.parse import quote as _quote

VENDOR = Path(__file__).resolve().parent.parent / "vendor"
# The pinned copies go FIRST: a yaml module inherited from the environment must not outrank the pin
# (plugin/vendor/VENDOR.md, "The vendored copy wins, on purpose").
sys.dont_write_bytecode = True   # an import must not leave scripts/__pycache__ in the installed plugin (plugin.test.sh Z-2)
sys.path[:0] = [str(VENDOR / "pyyaml"), str(VENDOR), str(Path(__file__).resolve().parent)]
import yaml  # noqa: E402
from okf_validate import OKF_VERSION, load_frontmatter, split_frontmatter  # noqa: E402  (the validator's own reader, so both agree)
from okf_guard import OUTSIDE_WHY, NoteRefused, opened_outside, path_exists, path_is_dir, path_is_file, read_note, refusal  # noqa: E402  (a note is opened only when regular and within the cap)

# A file name that is not UTF-8 (ext4 allows it) reaches Python as a name with lone surrogates: quote() percent-encodes its raw bytes
# (%FF) instead of raising; a report line shows it with backslash escapes (nasty-inputs.test.sh, invalid-utf8-name).
quote = functools.partial(_quote, errors="surrogateescape")

# `[[target#heading|alias]]`. An embed `![[x]]` transcludes x, which a Markdown link cannot say, so it is left as written.
WIKILINK = re.compile(r"(?<!!)\[\[([^\[\]]+)\]\]")

# CommonMark: a fence opens with 3+ backticks or tildes, up to 3 spaces in, and closes on a run of the
# same character at least as long. An ATX heading is 1-6 '#' and a space; closing '#'s are not text.
# The info string of a backtick fence holds no backtick, and a closing fence has no info string (4.5).
FENCE = re.compile(r"^ {0,3}(`{3,}(?=[^`]*$)|~{3,})")
FENCE_CLOSE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*$")
ATX = re.compile(r"^ {0,3}#{1,6}(?:[ \t]+(.*?)(?:[ \t]+#+)?)?[ \t]*$")   # the text is optional: a lone `#` is an empty heading (4.2)
# An indented code block is 4 spaces or a tab in; it cannot interrupt a paragraph.
INDENTED = re.compile(r"^(?: {4}| {0,3}\t)")
LIST_ITEM = re.compile(r"^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)")
# A list item's content starts after the marker and 1-4 spaces; with none, or 5 and more (code in the item), one column
# after the marker. A line after a blank line belongs to the item only if it is indented at least that far (CommonMark
# 0.31.2, 5.2 List items). Tabs count to the next stop of 4 columns (2.2 Tabs).
ITEM_CONTENT = re.compile(r"^( {0,3}(?:[-*+]|\d{1,9}[.)]))( *)(.?)")


# The same two patterns matched at an offset into a line (re.match(text, pos)): a marker line is read by walking it once.
LIST_AT = re.compile(LIST_ITEM.pattern[1:])
ITEM_AT = re.compile(ITEM_CONTENT.pattern[1:])


def break_tail(text: str):
    """(start, char): a thematic break can only be a line's tail made of one of - * _ and spaces; this is where that run
    starts, so a check from any later offset costs no scan of the line again."""
    tail = text.rstrip(" \t")
    ch = tail[-1:]
    j = len(tail)
    if ch and ch in "-*_":
        while j and tail[j - 1] in (ch, " ", "\t"):
            j -= 1
    return j, ch


def break_at(text: str, pos: int, tail) -> bool:
    """THEMATIC.match(text[pos:]) without the slice: up to 3 spaces, then 3 or more of one break character and spaces."""
    j, ch = tail
    if pos < j or not ch or ch not in "-*_":
        return False
    q = pos
    while q < len(text) and text[q] == " " and q - pos < 4:
        q += 1
    return q - pos <= 3 and text[q:q + 1] == ch and text.count(ch, q) >= 3


def indent_width(line: str) -> int:
    wide = line.expandtabs(4)
    return len(wide) - len(wide.lstrip(" "))
# A code span closes on a backtick run of exactly its opening length. CODE_SPAN is for a title, whose backslashes
# link_text doubles; a note's body is read by raw_inlines.
CODE_SPAN = re.compile(r"(?<!`)(`+)(?!`).+?(?<!`)\1(?!`)")
BACKTICKS = re.compile(r"`+")
# CommonMark 0.31.2, 6.5 Autolinks and 6.6 Raw HTML. Whitespace there is spaces, tabs and line endings (not Unicode
# spaces, which Python's \s would take). A comment, a processing instruction, a declaration and a CDATA section end on
# their first terminator: raw_inlines finds that with str.find, so an unclosed one costs one scan of the paragraph.
_WS = r"[ \t\r\n]"
AUTOLINK = re.compile(r"<(?:[A-Za-z][A-Za-z0-9+.-]{1,31}:[^<>\x00-\x20]*|[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9]"
                      r"(?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*)>")
HTML_TAG = re.compile(rf"<[A-Za-z][A-Za-z0-9-]*(?:{_WS}+[A-Za-z_:][A-Za-z0-9_.:-]*(?:{_WS}*={_WS}*"
                      rf"(?:[^ \"'=<>`\x00-\x20]+|'[^']*'|\"[^\"]*\"))?)*{_WS}*/?>|</[A-Za-z][A-Za-z0-9-]*{_WS}*>")
HTML_ENDED = (("<!-->", None), ("<!--->", None), ("<!--", "-->"), ("<![CDATA[", "]]>"), ("<?", "?>"))
DECLARATION = re.compile(r"<![A-Za-z]")
INLINE_START = re.compile(r"[\\`<]")
ASCII_PUNCT = frozenset("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~")


def raw_inlines(text: str) -> list[tuple[int, int]]:
    """(start, end) of each code span (6.1), autolink (6.5) and raw HTML item (6.6) in a paragraph's text, read left to
    right as CommonMark reads them: whichever starts first wins, so a backtick inside a tag is the tag's and a `<` inside a
    span is the span's. A backtick run opens a span that the next run of the same length closes, even on a later line; a
    run with no closer is text. Outside them a backslash escapes the punctuation character after it."""
    runs = [m.span() for m in BACKTICKS.finditer(text)]
    starts = [a for a, _ in runs]
    by_len: dict[int, list[int]] = {}
    for k, (a, b) in enumerate(runs):
        by_len.setdefault(b - a, []).append(k)
    found: dict[str, tuple[int, int]] = {}   # terminator -> (searched from, found at): one find answers every start up to there

    def ends(term: str, pos: int) -> int:
        hit = found.get(term)
        if hit is None or not (hit[0] <= pos and (hit[1] < 0 or pos <= hit[1])):
            hit = found[term] = (pos, text.find(term, pos))
        return hit[1]

    out, p = [], 0
    while True:
        m = INLINE_START.search(text, p)
        if not m:
            return out
        p = m.start()
        c = text[p]
        if c == "\\":
            p += 2 if text[p + 1:p + 2] in ASCII_PUNCT else 1   # at the end the slice is "", which is not in the set
            continue
        if c == "`":   # p is a run's start, or one past an escaped first backtick
            k = bisect.bisect_right(starts, p) - 1
            b = runs[k][1]
            later = by_len.get(b - p, [])
            at = bisect.bisect_right(later, k)
            if at == len(later):
                p = b
            else:
                out.append((p, runs[later[at]][1]))
                p = runs[later[at]][1]
            continue
        end = None
        a = AUTOLINK.match(text, p) or HTML_TAG.match(text, p)
        if a:
            end = a.end()
        else:
            for opener, term in HTML_ENDED:
                if text.startswith(opener, p):
                    if term is None:
                        end = p + len(opener)
                    else:
                        q = ends(term, p + len(opener))
                        end = q + len(term) if q >= 0 else None
                    break
            else:
                if DECLARATION.match(text, p):
                    q = ends(">", p + 2)
                    end = q + 1 if q >= 0 else None
        if end is None:
            p += 1
        else:
            out.append((p, end))
            p = end


# A GFM table's delimiter row (`|---|:-:|`): table rows are read one by one, not as one paragraph. It starts a table only
# when it has as many cells as the header row above it (GFM 0.29, 4.10); otherwise both lines are paragraph text.
TABLE_DELIM = re.compile(r"\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$")
LINE_PREFIX = re.compile(r"[ \t>]*")
CELL_BAR = re.compile(r"(?<!\\)\|")   # a bar that splits cells; `\|` is a literal bar


def cells(row: str) -> int:
    """The number of cells GFM reads in a table row: bars split cells, a leading and a trailing bar are not cells."""
    row = row.strip()
    row = row[1:] if row.startswith("|") else row
    row = row[:-1] if row.endswith("|") and not row.endswith("\\|") else row
    return len(CELL_BAR.findall(row)) + 1


def raw_ranges(lines: list[str], rows, joins: set) -> dict[int, list[tuple[int, int]]]:
    """For each body line, the code spans, autolinks and raw HTML items that touch it, as (start, end) offsets into that
    line (a start below 0 or an end past the line: the item goes on from the line before or into the next). The lines of a
    paragraph (body_lines `joins`) are read as one text, a later line's container prefix (spaces, tabs, `>`) blanked out,
    as CommonMark strips it; the rows of a table, from its header row on, are read one by one."""
    groups, cur = [], None
    for i, line, code, _ in rows:
        if code or not line.strip():
            cur = None
            continue
        if cur is None or i not in joins:
            cur = []
            groups.append(cur)
        cur.append(i)
    out: dict[int, list[tuple[int, int]]] = {}
    for g in groups:
        for j in range(1, len(g)):
            body = lines[g[j]][LINE_PREFIX.match(lines[g[j]]).end():].rstrip("\r\n")
            head = lines[g[j - 1]][LINE_PREFIX.match(lines[g[j - 1]]).end():].rstrip("\r\n")
            if "|" in body and "|" in head and TABLE_DELIM.match(body) and cells(body) == cells(head):
                groups += [[i] for i in g[j - 1:]]
                del g[j - 1:]
                break
        if not g:
            continue
        parts, bases, at = [], [], 0
        for n, i in enumerate(g):
            line = lines[i]
            if n:
                cut = LINE_PREFIX.match(line).end()
                line = " " * cut + line[cut:]
            parts.append(line)
            bases.append(at)
            at += len(line)
        for s, e in raw_inlines("".join(parts)):
            for n in range(bisect.bisect_right(bases, s) - 1, bisect.bisect_right(bases, e - 1)):
                out.setdefault(g[n], []).append((s - bases[n], e - bases[n]))
    return out


# A problem line quotes link text and file names from the vault, and a person or Claude reads it: control characters
# become "?" (the edit hook's set, 0.9.13 review).
CONTROL = re.compile("[\x00-\x1f\x7f-\x9f\u2028\u2029]")
# A setext heading: the paragraph above is the heading text, underlined with = (level 1) or - (level 2).
SETEXT = re.compile(r"^ {0,3}(?:=+|-+)[ \t]*$")
# A thematic break: three or more of one of - * _ (spaces between allowed). Under a paragraph a - line is a setext underline.
THEMATIC = re.compile(r"^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$")


def split_lines(text: str) -> list[str]:
    """The lines as an editor counts them, line ends kept: \n, \r\n or a lone \r ends a line (str.splitlines also splits
    at \f, \x1c and \u2028, which moved every later line number of the report; 0.9.14 re-verify)."""
    return re.findall(r"[^\r\n]*(?:\r\n|\n|\r)|[^\r\n]+$", text)


def plugin_version() -> str:
    """The plugin's version, from .claude-plugin/plugin.json (the one place bump-version.sh moves for this tool)."""
    import json
    try:
        return json.loads((Path(__file__).resolve().parent.parent / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))["version"]
    except (OSError, ValueError, KeyError):
        return "unknown"


def fold(name: str) -> str:
    """A name compared without case: NFC, then lower() (okf_guard._fold, the rule okf-check uses)."""
    return unicodedata.normalize("NFC", name).lower()


# github-slugger keeps what GitHub's Onigmo calls a word character: Alphabetic, Mark, Decimal_Number and Connector_Punctuation
# (checked against github-slugger 2.0.0 over every code point). Alphabetic is the letters, Nl, and the circled and squared
# Latin letters (Other_Alphabetic symbols); `\w` would drop the marks and U+203F-like characters and keep ² and ¼.
ENCLOSED_LETTERS = re.compile("[\u24b6-\u24e9\U0001f130-\U0001f149\U0001f150-\U0001f169\U0001f170-\U0001f189]")


def slug(heading: str) -> str:
    """The anchor GitHub gives a heading (github-slugger): lower case, everything dropped that is not a word character,
    a space or '-', each space a '-'. A tab or any other control or format character is dropped, not turned into a space.
    The heading's own Unicode form is kept (a decomposed heading gets a decomposed anchor): github-slugger and github.com
    do not normalise, and the NFC link `#caf%C3%A9` does not jump to the id `cafe` + U+0301. A link is matched to a heading
    on the NFC of both sides (`matching_anchor`)."""
    def kept(c: str) -> bool:
        cat = unicodedata.category(c)
        return c in " -" or cat[0] in "LM" or cat in ("Nd", "Nl", "Pc") or bool(ENCLOSED_LETTERS.match(c))
    return "".join(filter(kept, heading.strip().lower())).replace(" ", "-")


def frontmatter_len(lines: list[str]) -> int:
    """Lines taken by the YAML block at the top (spec 4: '---' on its own line, then a closing '---'); 0 if none."""
    if lines and lines[0].lstrip("\ufeff").rstrip() == "---":   # a byte order mark is not part of the fence line; an indented '---' is no fence
        for i in range(1, len(lines)):
            if lines[i].strip() == "---":
                return i + 1
    return 0


# The container prefix of a line: the run of spaces, tabs, '>' markers and list markers before its text. Only a tab in it
# is a column count (2.2 Tabs); a tab in the text is text (a heading `a<TAB>b` is `ab`).
PREFIX = re.compile(r"(?:[ \t]+|>|(?:[-*+]|\d{1,9}[.)])(?=[ \t]|$))*")


def dedent(line: str, cols: int) -> str:
    """The line with up to `cols` columns of leading space taken off: its text as the list item it sits in sees it."""
    end = PREFIX.match(line).end()
    wide = line[:end].expandtabs(4) + line[end:]
    return wide[min(cols, indent_width(line)):]


# HTML block starts (CommonMark 0.31.2, 4.6), each with the line that ends it; None: a blank line ends it. The last kind,
# a lone complete tag, cannot interrupt a paragraph.
HTML_TAGS = ("address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|"
             "dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h1|h2|h3|h4|h5|h6|head|header|hr|html|iframe|"
             "legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|"
             "tbody|td|tfoot|th|thead|title|tr|track|ul")
HTML_BLOCKS = [
    (re.compile(r"^ {0,3}<(?:script|pre|style|textarea)(?:[ \t>]|$)", re.I), re.compile(r"</(?:script|pre|style|textarea)>", re.I)),
    (re.compile(r"^ {0,3}<!--"), re.compile(r"-->")),
    (re.compile(r"^ {0,3}<\?"), re.compile(r"\?>")),
    (re.compile(r"^ {0,3}<![A-Za-z]"), re.compile(r">")),
    (re.compile(r"^ {0,3}<!\[CDATA\["), re.compile(r"\]\]>")),
    (re.compile(rf"^ {{0,3}}</?(?:{HTML_TAGS})(?:[ \t>]|/>|$)", re.I), None),
]
HTML_TAG_LINE = re.compile(r"^ {0,3}(?:<[A-Za-z][A-Za-z0-9-]*(?:\s+[A-Za-z_:][\w.:-]*(?:\s*=\s*(?:[^\s\"'=<>`]+|'[^']*'|\"[^\"]*\"))?)*"
                           r"\s*/?>|</[A-Za-z][A-Za-z0-9-]*\s*>)\s*$")
# A block quote marker (5.1): up to 3 spaces, then '>'.
QUOTE = re.compile(r"^ {0,3}>")
# A link reference definition (4.7) on one line: it is no paragraph and cannot interrupt one.
LINK_DEF = re.compile(r"^ {0,3}\[(?:[^\]\\]|\\.)+\]:")


# Block quotes inside list items inside block quotes ... are read by nested calls of body_lines: one level per call. Past
# this depth the note is named and copied unchanged (Python's own limit would end the run with a traceback near 500).
NEST_MAX = 100


class TooDeep(Exception):
    """A note whose block quotes and list items nest deeper than NEST_MAX."""


def quote_depth(text: str):
    """(content, depth): a block quote line's text after its '>' markers, and how many there were."""
    m = re.match(r"(?: {0,3}>[ \t]?)+", text)
    return (text[m.end():], m.group(0).count(">")) if m else (text, 0)


def holds_paragraph(t: str) -> bool:
    """Whether the content `t` of a quote line leaves a paragraph open in the list item or quote it ends in: not when the
    item is empty or its content starts a block (a heading, a fence, a break, an HTML block) or is indented code (5 or
    more spaces after the marker, or 4 in a quote). Tabs are already spaces here (dedent)."""
    while True:
        g = ITEM_CONTENT.match(t)
        if g and LIST_ITEM.match(t) and not THEMATIC.match(t):
            if not g.group(3) or len(g.group(2)) > 4:
                return False
            t = t[len(g.group(1)) + len(g.group(2)):]
        elif QUOTE.match(t):
            t = quote_depth(t)[0]
        else:
            return bool(t.strip()) and not (ATX.match(t) or FENCE.match(t) or THEMATIC.match(t) or INDENTED.match(t)
                                            or any(h[0].match(t) for h in HTML_BLOCKS))


# What quote_block feeds the quote's reader for a lazy line that the reader could misread as a block start or an underline:
# plain paragraph text. Its own text is not kept, so a setext heading over it is not named (a link to it fails loudly).
LAZY_TEXT = "\x00"


def more(lines, i: int) -> bool:
    """Whether `lines` has a line `i`: a list, or a QuoteLines that reads its quote only up to the line asked for."""
    return lines.has(i) if isinstance(lines, QuoteLines) else i < len(lines)


class QuoteLines:
    """The contents of one block quote as its reader asks for them: quote_block is read one line further only when the
    reader reaches that line, so a quote the reader ends early (at a lazy line it rejects) costs no read ahead to the end of
    the quote (review round 1 of the block-quote rows: a note of such quotes took 80 s for 12000 lines). `idx[k]` is the
    note line of content line k; `lazy` holds the k of each line with no '>'."""
    def __init__(self, rows):
        self.rows, self.lines, self.idx, self.lazy = rows, [], [], set()

    def has(self, k: int) -> bool:
        while len(self.lines) <= k:
            row = next(self.rows, None)
            if row is None:
                return False
            if row[2]:
                self.lazy.add(len(self.lines))
            self.idx.append(row[0])
            self.lines.append(row[1])
        return True

    def __getitem__(self, k: int) -> str:
        self.has(k)
        return self.lines[k]   # past the end: IndexError, as a list


def quote_block(lines, start: int, first: str, at: int):
    """Yield (line index, content, lazy) for each line of the block quote that starts at `start` with the quote line `first`
    (its text, markers included): the lines that carry a '>' (read against the item content at `at`) with one '>' taken
    off, and the lines with no '>' that may be lazy lines of a paragraph (5.1, `lazy` True). body_lines reads the contents
    (through QuoteLines, one line at a time), so a quote in this quote is read by a nested call, and keeps a lazy line only
    if that reader has a paragraph open there (SC-export417): `para` here is a line test that errs towards True, so it takes
    every line CommonMark may take, and the reader drops the ones it does not. A tab in a container prefix needs no care here: CommonMark (2.2, and
    cmark) counts its columns from the start of the line, and `dedent` has already expanded the prefix of every line that way."""
    def starts_block(t):
        return ATX.match(t) or FENCE.match(t) or THEMATIC.match(t) or any(h[0].match(t) for h in HTML_BLOCKS)

    para, fence = False, 0   # a paragraph may be open; the quote level of an open fence (0: none)
    listed = False   # a list marker was seen: an indented line may be item text, not code, so it never ends `para`
    j, text = start, first
    while True:
        if j > start:
            if not more(lines, j):
                break
            line = lines[j].rstrip("\r\n")
            if not line.strip():
                break   # a blank line ends the quote
            text = dedent(line, at)
        inner, depth = quote_depth(text)
        if j > start and depth and indent_width(line) < at:
            break   # a line with its own '>' that is not indented into the item ends the item, and the quote in it
        if not depth:   # lazy: only under a paragraph, and not a line that starts a block of its own
            # a lone tag is no block start under a paragraph (7), but `para` may be wrong: the quote ends, which can only hide
            if fence or not para or LIST_ITEM.match(text) or starts_block(text) or HTML_TAG_LINE.match(text):
                break
        elif fence and depth >= fence:   # in the fence: its content keeps any deeper '>'
            para = False
            if FENCE_CLOSE.match(re.sub(r"^(?: {0,3}>[ \t]?){%d}" % fence, "", text)):
                fence = 0
        else:   # a lower level ends a deeper fence (its quote ends), so the line is read afresh
            fence = depth if FENCE.match(inner) else 0
            listed = listed or bool(LIST_ITEM.match(inner))
            # an indented line with no paragraph open is code (it cannot interrupt one, 4.4), so no paragraph is open
            # after it, unless a list is in the quote: there it may be item text, and `para` errs towards True
            para = not fence and bool(inner.strip()) and not starts_block(inner) and (para or listed or not INDENTED.match(inner)) \
                and (not LIST_ITEM.match(inner) or holds_paragraph(inner))
        if depth:
            yield j, re.sub(r"^ {0,3}>[ \t]?", "", text, count=1), False
        else:   # a lazy line is paragraph text; if its indent could read as a block start of the item (a '>' here is indented 4 or more), or it is an underline (no lazy line is one, 5.1), it is fed as LAZY_TEXT
            t = text.lstrip()
            yield j, LAZY_TEXT if starts_block(t) or LIST_ITEM.match(t) or t.startswith(">") or SETEXT.match(t) else text, True
        j += 1


def item_interrupts(text: str) -> bool:
    """Whether the list item on `text` may start a list under an open paragraph: it has content, and an ordered one
    starts at 1 (5.2 List items)."""
    g = ITEM_CONTENT.match(text)
    marker = g.group(1).strip()
    return bool(g.group(3)) and (marker in ("-", "*", "+") or int(marker[:-1]) == 1)


def body_lines(lines: list[str], nested: bool = False, level: int = 0, joins: set | None = None):
    """Yield (index, line, in_code, heading) for each body line. in_code is True inside a fence, fence lines included,
    and on the lines of an indented code block or of an HTML block, in a quote too (raw HTML holds no Markdown); heading
    is the text of a heading that ends on this line (ATX, or the underline of a setext heading), else None. Blocks are read the way CommonMark 0.31.2 reads them, inside list items
    too (5.2): each line is matched against the content of the item it sits in, a marker line's own content included.
    A blank line is never code: it holds no link, and the log reader counts it.

    A block quote (5.1) is read as a container too: its lines, '>' taken off, are read by this same reader (nested=True),
    inside a list item as well, and quotes nest. A line with no '>' stays in the quote only if this reader, reading the
    quote, goes on with an open paragraph on it (a lazy line); at the first one it does not, the quote ends there and the
    line is read out here (SC-export417).

    `joins`, when given, collects the index of each line that goes on with the paragraph of the line before it (lazily
    too), so a caller can read a paragraph's inline text as one piece (raw_ranges)."""
    items = []             # content indents of the open list items, outer first
    empty = False          # the innermost item has no content yet: a blank line ends it
    para = []              # the lines of the open paragraph, as its item sees them (setext heading text)
    fence, fence_at = "", 0   # the open fence and the content indent it sits at
    html, html_at = False, 0  # an open HTML block: its end pattern (None: a blank line), the content indent
    code = False           # inside an indented code block
    quoted = {}            # results for the lines of a block quote read ahead: index -> (in_code, heading)
    for i in itertools.count(0 if nested else frontmatter_len(lines)):
        if not more(lines, i):
            break
        raw = lines[i]
        if i in quoted:
            c, h = quoted.pop(i)
            yield i, raw, c, h
            continue
        line = raw.rstrip("\r\n")   # matched without its line end: `$` in SETEXT and THEMATIC must see a CRLF line too
        w = indent_width(line)
        if (fence or html is not False) and line.strip() and w < (fence_at if fence else html_at):
            fence, html = "", False   # the item ends and its fence or HTML block with it
        if fence:
            m = FENCE_CLOSE.match(dedent(line, fence_at))
            if m and m.group(1)[0] == fence[0] and len(m.group(1)) >= len(fence):
                fence = ""
            yield i, raw, True, None
            continue
        if html is not False:
            if html is None and not line.strip():
                html = False   # a blank line ends it; the blank line is read below
            else:
                if html is not None and html.search(line):
                    html = False
                yield i, raw, True, None
                continue
        if not line.strip():
            if empty:
                items.pop()
            empty, para = False, []
            yield i, raw, False, None
            continue
        depth = bisect.bisect_right(items, w)   # the items this line's indent keeps it inside (items only grow)
        text = dedent(line, items[depth - 1] if depth else 0)
        if para and depth == len(items) and SETEXT.match(text):
            heading = None if LAZY_TEXT in para else " ".join(x.strip() for x in para)   # LAZY_TEXT: quote_block
            para = []
            yield i, raw, False, heading
            continue
        brk = THEMATIC.match(text)
        item = LIST_ITEM.match(text) and not brk   # `- - -` is a thematic break, not an item
        starts = [h for h in HTML_BLOCKS if h[0].match(text)]
        # a line outside the deepest item (depth < len(items)) is a sibling or an outer item, which a paragraph never holds
        interrupts = (item and (depth < len(items) or item_interrupts(text))) or brk or FENCE.match(text) or ATX.match(text) or starts or QUOTE.match(text)
        if para and not interrupts:
            para.append(raw.strip())   # a paragraph goes on, lazily too; the text as written: a tab in it is no column count
            if joins is not None:
                joins.add(i)
            yield i, raw, False, None
            continue
        del items[depth:]   # the line is outside the deeper items: they end
        empty, para = False, []
        if code and not INDENTED.match(text):
            code = False
        at = items[-1] if items else 0
        pos, tail = 0, item and break_tail(text)   # dedent expanded the tabs of the container prefix
        while item:   # a marker line: open the item, then read its own content as the item's first line
            g = ITEM_AT.match(text, pos)
            marker, spaces, rest = len(g.group(1)), len(g.group(2)), g.group(3)
            width = marker + spaces if rest and 1 <= spaces <= 4 else marker + 1   # the content indent (ITEM_CONTENT)
            pos += width
            at = (items[-1] if items else 0) + width
            items.append(at)
            if not rest:
                empty = True
                break
            item = LIST_AT.match(text, pos) and not break_at(text, pos, tail)
        text = text[pos:]   # one slice per line: the cost stays linear in its length
        if not empty and QUOTE.match(text):   # a block quote: read its lines with this reader, then go on after it
            if level >= NEST_MAX or level + quote_depth(text)[1] > NEST_MAX:   # `level` counts nested reads; `depth` below is the list-item depth of one line
                raise TooDeep()   # the second test reads the line's markers once: a line of 10^6 '>' costs one pass, not one per level
            contents, inner = QuoteLines(quote_block(lines, i, text, at)), set()
            for k, _, c, h in body_lines(contents, nested=True, level=level + 1, joins=inner):
                if k in contents.lazy and k not in inner:
                    break   # no paragraph open: no lazy line, the quote ends before it (an earlier line's result never depends on it)
                quoted[contents.idx[k]] = (c, h)
                if joins is not None and k in inner:
                    joins.add(contents.idx[k])
            para, code = [], False
            c, h = quoted.pop(i)
            yield i, raw, c, h
            continue
        heading, in_code = None, False
        starts = [h for h in HTML_BLOCKS if h[0].match(text)]   # again: a marker line's content may start one
        m = ATX.match(text)
        f = FENCE.match(text)
        if empty:
            pass
        elif code or INDENTED.match(text):
            code = in_code = True
        elif m:
            heading = m.group(1) or ""   # None: a lone `#`, a heading with no text
        elif f:
            fence, fence_at, in_code = f.group(1), at, True
        elif THEMATIC.match(text) or LINK_DEF.match(text):
            pass
        elif starts or HTML_TAG_LINE.match(text):
            end = starts[0][1] if starts else None
            html, html_at = (False if end is not None and end.search(text[text.index("<") + 1:]) else end), at
            # Raw HTML holds no Markdown, so a [[link]] in it is text (4.6; Obsidian reads none either), inside a quote too
            # (D23-a): a line with no '>' after it is no lazy line here, so the quote's reader ends the quote before it.
            in_code = True
        else:
            para = [text]
        yield i, raw, in_code, heading


def read_text(path: Path, root: Path) -> str:
    """The note as written: no newline translation (a CRLF note stays CRLF), a BOM kept. Raises UnicodeDecodeError.

    Bounded: main() leaves a refused note out of `files`, and this refuses one that changed after that, also one whose
    real path left `root` (the vault, or the bundle being written) since the listing (NoteRefused)."""
    return read_note(path, "utf-8", "strict", newline="", root=root)


def copy_from(src: Path, dest: Path, root: Path) -> None:
    """shutil.copy2 of a file of `root`, judged on the opened descriptor: a file that is no longer regular, or whose real
    path left `root` since the listing, is refused (NoteRefused) and nothing is written. Mode and times are copied."""
    fd = os.open(src, os.O_RDONLY | os.O_NONBLOCK | getattr(os, "O_NOCTTY", 0))
    with os.fdopen(fd, "rb") as fh:
        st = os.fstat(fh.fileno())
        if not stat.S_ISREG(st.st_mode):
            raise NoteRefused("not a regular file (device/pipe/...)")
        if opened_outside(src, root, st):
            raise NoteRefused(OUTSIDE_WHY.replace("bundle", "vault"))
        with open(dest, "wb") as out:
            shutil.copyfileobj(fh, out)
    os.chmod(dest, stat.S_IMODE(st.st_mode))
    os.utime(dest, ns=(st.st_atime_ns, st.st_mtime_ns))


@functools.lru_cache(maxsize=None)   # one read per target, however many links point at it
def heading_slugs(path: Path, root: Path) -> set[str]:
    try:
        lines = [l.rstrip("\r\n") for l in split_lines(read_text(path, root).lstrip("\ufeff"))]   # a BOM is not part of the first heading line
    except (UnicodeDecodeError, NoteRefused):   # NoteRefused: the target changed since the listing; its anchor is not looked up
        return set()   # the target is reported on its own as not valid UTF-8; a heading in it cannot be found
    found, counts = set(), {}
    try:
        for _, _, _, h in body_lines(lines):
            if h is None:
                continue
            # github-slugger: a repeated anchor gets the next number whose anchor is free (Foo, Foo-1, Foo: foo, foo-1, foo-2)
            base = anchor = slug(h)
            n = counts.get(base, 0)
            while anchor in found:
                n += 1
                anchor = f"{base}-{n}"
            counts[base] = n
            found.add(anchor)
    except TooDeep:
        pass   # the note is named on its own (main); its headings past the cap are not known
    return found


def matching_anchor(anchor: str, known: set[str]) -> str | None:
    """The anchor of a heading in `known` that a link to `anchor` names: the exact one first, else the one equal on NFC
    (the smallest, so the choice does not depend on set order); None when there is none."""
    if anchor in known:
        return anchor
    want = unicodedata.normalize("NFC", anchor)
    return min((a for a in known if unicodedata.normalize("NFC", a) == want), default=None)


# Spec 9 log input, read from a vault log.md: a level-2 heading (`## 2026-05-22`) whose lines are that day's entries,
# or a dated list item (`- 2026-05-22: text`). Every `## ` heading must be an ISO date, as the validator's check_log
# requires; headings of level 3-6 are entry text. DATEISH also catches near-misses (2026/05/22, 2026-5-2), and an item
# date is the whole token up to a space or ':' (2026-05-221, 2026-05-01-extra), so a bad date is reported, never split.
DATEISH = r"\d{4}[-/.]\d{1,2}[-/.]\d{1,2}"
LEVEL2 = re.compile(r"^##[ \t]+(.*?)[ \t]*$")
DATED_ITEM = re.compile(rf"^[ \t]*[-*+][ \t]+({DATEISH}[^\s:]*)[ \t]*:?[ \t]*(.*)$")
TITLE = re.compile(r"^#[ \t]+(.*?)[ \t]*$")


def iso_day(text: str) -> str | None:
    """Spec 9: date headings MUST use ISO 8601 YYYY-MM-DD; it must also be a real day."""
    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", text):
        return None
    try:
        return datetime.date.fromisoformat(text).isoformat()
    except ValueError:
        return None


def is_log(rel: Path) -> bool:
    """Spec 3.1 reserves log.md; compared case-folded, as a case-insensitive disk (macOS APFS, Windows) compares it (X-18)."""
    return rel.name.casefold() == "log.md"


def vault_out_rel(rel: Path, root_name: str) -> Path:
    """Spec 3.1: index.md is reserved and MUST NOT be a concept, so a vault's index.md note becomes the
    folder note dir/<dir>.md (the vault root's takes the vault folder's name). The folder is kept."""
    if rel.name.casefold() == "index.md":   # casefold: on a case-insensitive disk Index.md IS index.md
        return rel.parent / f"{rel.parent.name or root_name}.md"
    if is_log(rel):
        return rel.parent / "log.md"   # spec 3.1 names it in lower case; a case-sensitive disk tells Log.md apart
    return rel


def shared_outputs(files: list[Path], root_name: str) -> list[tuple[Path, Path, Path]]:
    """(first, second, output) for each output path that two or more renamed inputs would be written to:
    Index.md and index.md in one folder both become <folder>.md. Only renamed files are compared: a renamed file
    against a note that already has that name is the clash check in main(), and a.md next to A.md stay two files."""
    groups: dict[Path, list[Path]] = {}
    for rel in files:
        if vault_out_rel(rel, root_name) != rel:
            groups.setdefault(vault_out_rel(rel, root_name), []).append(rel)
    return [(g[0], g[1], out) for out, g in groups.items() if len(g) > 1]


def name_key(name: str, case: bool = True) -> str:
    """What a disk that normalises names (macOS APFS) compares: NFC; with case, also canonical caseless matching, NFC of the
    casefold of the NFC form (casefold alone leaves U+0390 and U+03AA U+0301 apart, though APFS holds one file for both)."""
    nfc = unicodedata.normalize("NFC", name)
    return unicodedata.normalize("NFC", nfc.casefold()) if case else nfc


def case_clashes(files: list[Path], root_name: str, case: bool = True) -> list[tuple[Path, Path]]:
    """(first, second) for each two output names in one folder that differ only in Unicode normalisation (NFC against
    NFD: macOS APFS stores both as one file) and, with case, also in case (macOS, Windows): the disk writes both to one
    file or folder. Named by their vault paths. Two names in different folders clash at the folders, so a pair is
    reported once, where it starts."""
    names: dict[Path, Path] = {}   # output name -> vault path; a folder keeps its name
    for rel in files:
        out = vault_out_rel(rel, root_name)
        names[out] = rel
        for d in out.parents:
            if d != Path("."):
                names.setdefault(d, d)
    first: dict[tuple[Path, str], Path] = {}
    pairs = []
    for out in sorted(names):
        key = (out.parent, name_key(out.name, case))
        if key in first:
            pairs.append((names[first[key]], names[out]))
        else:
            first[key] = out
    return pairs


def case_insensitive(folder: Path) -> bool:
    """Whether the disk that holds folder (or will: an output not made yet goes in its nearest existing parent) folds
    case. Nothing is written: the nearest folder whose name is ASCII with a letter and sits in a folder on that disk is
    compared with its case-swapped name, so a kill -9 in the probe leaves nothing behind. Only when no such folder
    exists (the output's nearest folder is a volume's mount folder, or every folder name between it and the mount folder is
    non-ASCII or has no letter) is a temp folder made there and removed; a kill -9 in that window can still leave a
    .okf-case-* folder. Raises OSError if it cannot be written."""
    while not folder.exists():
        folder = folder.parent
    dev = folder.stat().st_dev
    for p in (folder, *folder.parents):
        # ASCII only: a non-ASCII name's swapcase need not be a name the disk folds to it ('ıx'.swapcase() is 'IX', which
        # APFS keeps apart from 'ıx'; the probe then said case-sensitive and a note was written over, review round 1)
        if not p.name.isascii() or p.name.swapcase() == p.name:
            continue
        if p.parent.stat().st_dev != dev:
            break   # p is a mount folder: its name, and every folder above, is looked up on another disk
        other = p.with_name(p.name.swapcase())
        return other.exists() and os.path.samefile(p, other)   # a case-sensitive disk may hold the swapped name as another folder
    probe = Path(tempfile.mkdtemp(prefix=".okf-case-", dir=folder))
    try:
        (probe / "a").touch()
        return (probe / "A").exists()
    finally:
        shutil.rmtree(probe)


def build_log(rel: Path, lines: list[str], problems: list[str]) -> str | None:
    """A spec 9 log from a vault log.md's dated lines: date groups, newest first, no frontmatter, the vault log's own
    `# Title` kept (else `# Log`). Whatever cannot go into the log goes to `problems`, so nothing is dropped silently:
    frontmatter, a bad date, a `## ` heading that is not a date (with the count of lines left out under it), a line
    under no date, a log with no dated entry (then None: no log is written)."""
    lines = [lines[0].lstrip("\ufeff"), *lines[1:]] if lines else lines   # a BOM is not part of the title line (X-17)
    name = rel.as_posix()
    if frontmatter_len(lines):
        problems.append(f"{name}:1: frontmatter dropped, a spec log has none")
    groups: dict[str, list[str]] = {}
    current: str | None = None     # the day of the last ## heading; "" under a rejected heading
    item_day: str | None = None    # the day of the last dated item, which an indented line continues; "" if rejected
    title: str | None = None
    blank = False                  # a blank line since the last kept line: one is kept between two lines of a day
    rejected: list | None = None   # [index in problems, lines left out] of the rejected heading being read

    def close_rejected() -> None:
        if rejected:
            n = rejected[1]
            problems[rejected[0]] += f" ({n} line{'' if n == 1 else 's'} under it left out)"

    def keep(day: str, text: str) -> None:
        nonlocal blank
        group = groups.setdefault(day, [])
        if blank and group:
            group.append("")
        group.append(CONTROL.sub("?", text))   # the log is read by people and agents (X-20)
        blank = False

    for i, line, code, _ in body_lines(lines):
        text, where = line.rstrip("\r\n"), f"{name}:{i + 1}"
        if not code:
            if not text.strip():
                blank = True
                continue
            heading = LEVEL2.match(text)
            if heading:
                close_rejected()
                rejected, item_day, blank = None, None, False
                current = iso_day(heading.group(1)) or ""
                if not current:
                    problems.append(f"{where}: heading {heading.group(1)} is not an ISO YYYY-MM-DD date")
                    rejected = [len(problems) - 1, 0]
                continue
            item = DATED_ITEM.match(text)
            if item:
                item_day = iso_day(item.group(1)) or ""
                if item_day:
                    keep(item_day, f"* {item.group(2)}")
                else:
                    problems.append(f"{where}: date {item.group(1)} is not an ISO YYYY-MM-DD day")
                continue
            if title is None and current is None and item_day is None and TITLE.match(text):
                title = TITLE.match(text).group(1)   # the vault log's own title, which a [[#Title]] link may name
                continue
        if item_day is not None and text[:1] in (" ", "\t"):
            if item_day:
                keep(item_day, text)   # an indented line continues the dated item above it (item 3)
            continue
        item_day = None
        if current is None:
            problems.append(f"{where}: line belongs to no date: {text.strip()}")
        elif current:
            keep(current, text)
        else:
            rejected[1] += 1
    close_rejected()
    days = sorted(groups, reverse=True)
    if not days:
        problems.append(f"{name}:1: no dated entry, no log written")
        return None
    head = f"# {CONTROL.sub('?', title) if title else 'Log'}\n"
    return head + "".join(f"\n## {d}\n" + "".join(f"{e}\n" for e in groups[d]) for d in days)


def link_text(text: str) -> str:
    """Text for the inside of [...] in an index line: one line, no control characters, brackets and backslashes escaped
    (a title is a YAML block scalar or a free string from the vault; 0.9.15 review)."""
    text = CONTROL.sub("?", " ".join(text.split())).encode("utf-8", "surrogateescape").decode("utf-8", "replace")
    out, pos = [], 0
    for span in CODE_SPAN.finditer(text):   # inside a code span a backslash is literal (CommonMark 6.1): no escapes there
        out += [re.sub(r"([\\\[\]])", r"\\\1", text[pos:span.start()]), span.group(0)]
        pos = span.end()
    return "".join(out) + re.sub(r"([\\\[\]])", r"\\\1", text[pos:])


def entry(path: Path, root: Path) -> str:
    """One spec 8 index line: `* [title](file) - description`, the title falling back to the file name."""
    try:   # a BOM is not part of the frontmatter fence; a note that is not UTF-8 was copied as it is (X-11)
        raw, _ = split_frontmatter(read_text(path, root).lstrip("\ufeff"))
    except (UnicodeDecodeError, NoteRefused):   # NoteRefused: the written file changed since; the index lists its name only
        raw = None
    try:
        meta = load_frontmatter(raw) if raw is not None else {}
    except (yaml.YAMLError, ValueError):   # okf-check reports the bad frontmatter; the index still lists the file
        meta = {}
    meta = meta if isinstance(meta, dict) else {}
    title = meta.get("title") if isinstance(meta.get("title"), str) else path.stem
    desc = CONTROL.sub("?", " ".join(meta["description"].split())) if isinstance(meta.get("description"), str) else ""
    return f"* [{link_text(title)}]({quote(path.name)})" + (f" - {desc}" if desc else "") + "\n"


def write_indexes(out: Path, concepts: list[Path]) -> None:
    """Spec 8: an index.md in every folder that holds a concept, directly or below. No frontmatter, except the
    root's okf_version (spec 8, 12). A Concepts section, then a Folders section; an empty one is left out."""
    folders: dict[Path, tuple[list[Path], set[str]]] = {}
    for c in concepts:
        folders.setdefault(c.parent, ([], set()))[0].append(c)
        d = c.parent
        while d != Path("."):
            folders.setdefault(d.parent, ([], set()))[1].add(d.name)
            d = d.parent
    for d, (names, subs) in folders.items():
        sections = []
        if names:
            sections.append("# Concepts\n\n" + "".join(entry(out / c, out) for c in sorted(names)))
        if subs:
            sections.append("# Folders\n\n" + "".join(f"* [{link_text(s)}]({quote(s)}/)\n" for s in sorted(subs)))
        head = f'---\nokf_version: "{OKF_VERSION}"\n---\n' if d == Path(".") else ""
        (out / d / "index.md").write_text(head + "\n".join(sections), encoding="utf-8")


def fail(msg: str) -> int:
    print(f"okf-export: {CONTROL.sub('?', msg)}", file=sys.stderr)   # it can name vault files (X-10)
    return 2


def link_refusal(vault: Path, rel: Path) -> str | None:
    """Why a file is not exported because of where it really is, else None: it leads outside the vault, or into a dot file
    or folder of it. Named by its link text, never by the host path it resolves to."""
    full = vault / rel
    target = full.resolve()
    if target.is_relative_to(vault):
        if not any(part.startswith(".") for part in target.relative_to(vault).parts):
            return None
        where = "into a hidden file or folder"
    else:
        where = "outside the vault"
    if not full.is_symlink():
        return f"a file under a symlinked folder that leads {where}"
    text = os.readlink(full)
    # An absolute link's text IS a path of this machine: it is not printed.
    return f"a symlink to {'an absolute link' if os.path.isabs(text) else text}, which leads {where}"


def is_file(vault: Path, p: Path, failed: list) -> bool:
    """Path.is_file(), except that a path whose stat fails is not a traceback with host paths in it. In a folder that cannot be
    entered (mode 0400) it is not a file here: unreadable_links names that folder once. Anywhere else the file is named in
    `failed` ("could not be examined"), never dropped in silence (NFS root_squash, FUSE, a privacy block). Path.is_file()
    answers False for a stat that fails since Python 3.14, so the stat is asked of okf_guard, which raises on every version."""
    try:
        return path_is_file(p)
    except OSError as err:
        if os.access(p.parent, os.X_OK):
            failed.append((p.relative_to(vault), f"a file that could not be examined ({err.strerror})"))
        return False


def unreadable_links(vault: Path) -> list[tuple[Path, str]]:
    """Symlinks that the file listing silently drops: one to a folder (it is not entered, so its notes would vanish), a broken
    one and a loop. Each is named instead. Dot folders are not entered and dot names are left out, as everywhere else."""
    out = []
    # A folder that cannot be listed is named too: rglob and os.walk both pass over it without a word, and its notes would vanish.
    cannot_list = lambda err: out.append((Path(err.filename).relative_to(vault), "a folder that cannot be listed: its files are not exported"))
    for top, dirs, names in os.walk(vault, onerror=cannot_list):
        dirs[:] = [d for d in dirs if not d.startswith(".")]
        if not os.access(top, os.X_OK):   # lists, but nothing in it can be examined (mode 0400): named once, not its sub-folders
            out.append((Path(top).relative_to(vault), "a folder that cannot be entered: its files are not exported"))
            dirs.clear()
            continue
        for name in dirs + names:
            full = os.path.join(top, name)
            if not name.startswith(".") and os.path.islink(full) and not os.path.isfile(full):
                what = "a symlink to a folder: the folder is not followed, its notes are not exported" if os.path.isdir(full) \
                    else "a symlink that leads nowhere (broken, or a loop)"
                out.append((Path(full).relative_to(vault), what))
    return sorted(out)


def hidden_hard_links(vault: Path, files: list[Path], outside: list | None = None) -> list[tuple[Path, str]]:
    """Visible files that are the same file as one under a dot name: a hard link has no target path to follow, so (device,
    inode) is the only tell. Inode numbers repeat across devices, hence the device in the key. st_nlink > 1 is the cheap
    pre-check: the vault is walked only when a visible file has a second name. A hard link to a file OUTSIDE the vault
    cannot be refused (it looks like a file that lives here), but `outside` collects it when given, as GNU tar --check-links
    does: a file whose st_nlink is higher than the names of it found in the vault (the names are counted over every regular
    file the walk meets, visible or under a dot name)."""
    multi, gone = [], []
    for rel in files:
        try:
            st = os.stat(vault / rel)
        except OSError as err:   # gone since the listing: not exported, and said so
            gone.append((rel, f"a file that could not be examined ({err.strerror})"))
            continue
        if st.st_nlink > 1 and st.st_ino:   # an inode of 0 is made up by some network and FUSE volumes
            multi.append((rel, (st.st_dev, st.st_ino), st.st_nlink))
    if not multi:
        return gone
    hidden, unlisted, names_seen = set(), [], {}
    for top, _, names in os.walk(vault, onerror=lambda err: unlisted.append(Path(err.filename).relative_to(vault))):
        under_dot = any(part.startswith(".") for part in Path(top).relative_to(vault).parts)
        for name in names:
            try:
                st = os.lstat(os.path.join(top, name))   # lstat: a symlink is not the file it points to
            except OSError:
                if under_dot or name.startswith("."):
                    unlisted.append(Path(top).relative_to(vault))
                continue
            if stat.S_ISREG(st.st_mode):
                names_seen[(st.st_dev, st.st_ino)] = names_seen.get((st.st_dev, st.st_ino), 0) + 1
                if under_dot or name.startswith("."):
                    hidden.add((st.st_dev, st.st_ino))
    # Fail closed: in a folder nobody may list, the other name of a file may be hidden, and nothing says so.
    why = f"a file with more than one name, while the folder {min(unlisted).as_posix()} cannot be listed or entered to rule out a hard link to a hidden file" if unlisted else ""
    if outside is not None and not unlisted:   # with a folder nobody may list the count is not known: the file is refused above
        outside += [(rel, f"a file with {nlink} names, {names_seen.get(ident, 0)} of them in the vault; the other names are outside it")
                    for rel, ident, nlink in multi if ident not in hidden and nlink > names_seen.get(ident, 0) and not os.path.islink(vault / rel)]
    return gone + [(rel, "a hard link to a hidden file or folder of the vault" if ident in hidden else why) for rel, ident, _ in multi if ident in hidden or why]


HELP_TOP = """\
okf-export - write a vault of [[wikilinked]] notes out as an OKF bundle (the vault stays the source).

What it does:
  - turns [[note]], [[note|alias]], [[note#heading]] and [[#heading]] into relative Markdown links, and checks
    each target and heading (a target is matched as Obsidian matches it)
  - copies frontmatter, code and raw HTML blocks unchanged, and every file that is not a note
  - leaves out dot files and folders (.obsidian, .git) and names each file it skips
  - renames a vault index.md note to dir/dir.md (index.md is reserved), writes a generated index.md in every folder that
    holds a note (okf_version at the root), and turns a vault log.md into the dated log the spec describes

Every note needs YAML frontmatter with a non-empty type field before okf-check passes it: the export copies frontmatter
unchanged and writes none into your notes, so a vault without it exports with exit 0 and okf-check then refuses the
bundle at L1 (§11.1, and §11.2 for an empty, non-string or missing type).

Nothing is written when it stops with exit 2. Run okf-check on <out> after exit 0 or 1.
"""

HELP_END = """\
Exit codes:
  0  exported, nothing to report
  1  exported, and the report on stdout lists a problem as file:line: a missing or ambiguous target or heading, a
     malformed log, or a file that was skipped or refused (the bundle is still written)
  2  nothing was written: <vault> is not a readable folder, <out> is not empty, is inside the vault or cannot be
     written, or two notes would be written to one name; also a command-line error

Environment variables: none.

Example:
  okf-export ~/vault ./bundle
  okf-check ./bundle
After exit 2 nothing was written: do not check ./bundle.

See also: okf-check (gate the bundle) and okf-verify (check what it cites). The README has the full reference.
"""


def main() -> int:
    ap = argparse.ArgumentParser(prog="okf-export", usage="okf-export <vault> <out>",
                                 formatter_class=argparse.RawDescriptionHelpFormatter, description=HELP_TOP, epilog=HELP_END)
    ap.add_argument("--version", action="version", version=f"okf-export {plugin_version()}", help="print the version and exit")
    ap.add_argument("vault", type=Path, help="the Obsidian-style folder of notes to read; it is only read, never changed")
    ap.add_argument("out", type=Path, help="where the bundle is written: a new folder, or an empty one; never inside the vault")
    args = ap.parse_args()
    for stream in (sys.stdout, sys.stderr):   # a vault name that is not UTF-8 must print, not end the run
        if hasattr(stream, "reconfigure"):   # a caller that swapped in a StringIO keeps it
            stream.reconfigure(errors="backslashreplace")
    vault, out = args.vault.resolve(), args.out.resolve()
    # Exit 2 before anything is written: the vault is only read, and <out> is never merged into.
    try:
        vault_is_folder = path_is_dir(vault)
    except OSError as err:   # a folder above it that nobody may enter: not the same as "not a folder"
        return fail(f"{args.vault} cannot be read: {err.strerror}")
    if not vault_is_folder:
        return fail(f"{args.vault} is not a folder")
    if out == vault or vault in out.parents:
        return fail(f"{args.out} is inside the vault {args.vault}; choose a folder outside it")
    try:
        out_exists, out_is_folder = path_exists(out), path_is_dir(out)
        if out_exists and out_is_folder and any(out.iterdir()):   # iterdir raises for a folder nobody may enter, on every Python
            return fail(f"{args.out} exists and is not empty")
    except OSError as err:
        return fail(f"cannot write to {args.out}: {err.strerror}")
    if out_exists and not out_is_folder:
        return fail(f"{args.out} exists and is not a folder")
    # Dot files and folders hold note-tool settings (.obsidian), VCS data (.git) or OS clutter (.DS_Store), not knowledge.
    failed: list[tuple[Path, str]] = []
    files = sorted(rel for rel in (p.relative_to(vault) for p in vault.rglob("*") if is_file(vault, p, failed))
                   if not any(part.startswith(".") for part in rel.parts))
    # A *.md that is not a regular file (device, pipe, folder) or is over okf_check.max_note_bytes is not exported and is
    # never opened; it is reported with the other problems. rglob("*") would list an oversize note, so it goes here.
    refused = sorted((rel, why) for rel, why in ((p.relative_to(vault), refusal(p)) for p in vault.rglob("*.md")) if why
                     and not any(part.startswith(".") for part in rel.parts))
    # A symlink inside the vault that leads outside it would copy text from elsewhere into the bundle: it is left out and
    # named by its name and link text (never the host path it resolves to). One that stays inside the vault is exported as
    # before. rglob does not enter a symlinked folder (Python 3.9 and 3.12 measured), so only a file symlink gets here.
    # The dot rule above also holds for where a link leads: one that resolves to a dot file or folder (.obsidian, .git) is left
    # out the same way, or the exclusion would be one `ln -s` away from the settings and VCS data it exists to keep out.
    refused += sorted((rel, why) for rel in files for why in [link_refusal(vault, rel)] if why)
    refused += unreadable_links(vault)
    refused += failed
    named = {rel for rel, _ in refused}
    warned: list[tuple[Path, str]] = []
    refused += hidden_hard_links(vault, [rel for rel in files if rel not in named], warned)
    skip = {rel for rel, _ in refused}
    files = [rel for rel in files if rel not in skip]
    fileset = set(files)
    by_name: dict[str, list[Path]] = {}
    by_name_ci: dict[str, list[Path]] = {}
    by_path_ci: dict[str, list[Path]] = {}
    for p in files:
        by_name.setdefault(p.name, []).append(p)
        by_name_ci.setdefault(fold(p.name), []).append(p)   # NFC + lower(), as Obsidian: casefold() would match ß to ss
        by_path_ci.setdefault(fold(p.as_posix()), []).append(p)

    def resolve(name: str) -> list[Path]:
        """Obsidian's rule: a target with '/' is a vault-root path, a bare name is a file name anywhere
        in the vault. Either may leave out '.md'. An exact match wins; otherwise case is ignored, as Obsidian
        ignores it, and two files that differ only in case are both returned (ambiguous). The case-insensitive step also
        reads both names in Unicode NFC (macOS may store café decomposed), as okf_guard.obsidian_path does for okf-check."""
        if "/" in name:
            exact = [p for p in (Path(name), Path(name + ".md")) if p in fileset][:1]
            return exact or by_path_ci.get(fold(name)) or by_path_ci.get(fold(name + ".md")) or []
        return (by_name.get(name) or by_name.get(name + ".md")
                or by_name_ci.get(fold(name)) or by_name_ci.get(fold(name + ".md")) or [])

    out_rel = functools.partial(vault_out_rel, root_name=vault.name)

    # S10-E2: a rename onto an existing note would overwrite it. Stop before anything is written.
    # Names are compared case-folded, the way a case-insensitive disk (macOS APFS, Windows) compares them.
    folded = {p.as_posix().casefold() for p in files}
    clashes = [(rel, out_rel(rel)) for rel in files if rel.name.casefold() == "index.md" and out_rel(rel).as_posix().casefold() in folded]
    # The same for the log (X-19): log.md and Log.md can share a folder only on a case-sensitive disk; both become log.md.
    clashes += [(rel, out_rel(rel)) for rel in files if is_log(rel) and rel != out_rel(rel)
                and any(p != rel and p.as_posix().casefold() == out_rel(rel).as_posix().casefold() for p in files)]
    for rel, new in clashes:
        if new == rel:
            fail(f"{rel.as_posix()} is the folder note of a folder named index, which leaves it no other name; rename the folder in the vault")
        else:
            fail(f"{rel.as_posix()} would be renamed to {new.as_posix()}, which already exists; rename one of them in the vault")
    # Two renamed inputs that share one output name would overwrite each other: Index.md and index.md.
    shared = shared_outputs(files, vault.name)
    for first, second, new in shared:
        fail(f"{first.as_posix()} and {second.as_posix()} would both be written to {new.as_posix()}; rename one of them in the vault")
    # NFC and NFD spellings of one name are one file on macOS (APFS), whatever the case: decided from the names, before any
    # write and on every disk, because a bundle that is copied there would lose a note.
    unicode_pairs = case_clashes(files, vault.name, case=False)
    for first, second in unicode_pairs:
        look_alike = unicodedata.normalize("NFC", first.as_posix()) == unicodedata.normalize("NFC", second.as_posix())
        names = " and ".join((p.as_posix().encode("ascii", "backslashreplace").decode() if look_alike else p.as_posix()) for p in (first, second))
        fail(f"{names} would be written over each other: their output names differ only in Unicode normalisation, and a disk"
             " such as macOS APFS stores both as one file; rename one of them in the vault")
    if clashes or shared or unicode_pairs:
        return 2
    # A case-sensitive vault may hold Notes.md and notes.md, which a case-folding output disk (macOS, Windows) writes
    # to one file. Only there do names that differ only in case clash, so the disk is probed only for such a
    # pair: an ordinary export makes nothing in or beside <out> for the probe.
    base = out
    while not base.exists():
        base = base.parent
    if not os.access(base, os.W_OK | os.X_OK):
        return fail(f"cannot write to {args.out}: Permission denied")
    try:
        folded_pairs = case_clashes(files, vault.name)
        folded_pairs = folded_pairs if folded_pairs and case_insensitive(out) else []
    except OSError as err:
        return fail(f"cannot write to {args.out}: {err.strerror}")
    for first, second in folded_pairs:
        fail(f"{first.as_posix()} and {second.as_posix()} would be written over each other: {args.out} is on a disk"
             " that does not tell upper from lower case; rename one of them in the vault")
    if folded_pairs:
        return 2

    problems: list[str] = [f"{rel.as_posix()} — {why}: skipped" for rel, why in refused]
    problems += [f"{rel.as_posix()} — {why}: exported" for rel, why in warned]   # a warning: the file is exported
    dropped: set[Path] = set()   # refused at the copy (changed since the listing): not written, so not indexed
    for rel in files:
        dest = out / out_rel(rel)
        dest.parent.mkdir(parents=True, exist_ok=True)
        try:   # each read judges the opened file: one that changed or left the vault since the listing is not written
            if rel.suffix != ".md":
                copy_from(vault / rel, dest, vault)
                continue
            try:
                lines = split_lines(read_text(vault / rel, vault))
            except UnicodeDecodeError:
                problems.append(f"{rel.as_posix()}:1: not valid UTF-8, copied unchanged")
                copy_from(vault / rel, dest, vault)
                continue
        except NoteRefused as err:
            problems.append(f"{rel.as_posix()} — {str(err).replace('bundle', 'vault')}: skipped")
            dropped.add(rel)
            continue
        except OSError as err:   # a note nobody may read (mode 000): named and skipped, never a traceback (nasty-inputs.test.sh)
            problems.append(f"{rel.as_posix()} — {err.strerror or err}: skipped")
            dropped.add(rel)
            continue
        try:
            joins: set[int] = set()
            rows = list(body_lines(lines, joins=joins))
        except TooDeep:
            try:
                copy_from(vault / rel, dest, vault)
            except NoteRefused as err:
                problems.append(f"{rel.as_posix()} — {str(err).replace('bundle', 'vault')}: skipped")
                dropped.add(rel)
                continue
            except OSError as err:
                problems.append(f"{rel.as_posix()} — {err.strerror or err}: skipped")
                dropped.add(rel)
                continue
            problems.append(f"{rel.as_posix()}:1: block quotes and list items nested deeper than {NEST_MAX} levels: copied unchanged, its links not rewritten")
            continue
        raw = raw_ranges(lines, rows, joins)
        for i, line, code, _ in rows:
            if code:
                continue
            no = i + 1

            def link(m: re.Match) -> str:
                # The alias separator is the first bar; a table cell writes it as \|. Only that one is unescaped: a later \| stays
                # as written (it is literal text in a code span, and a bare bar would split a table cell).
                body = m.group(1)
                bar = body.find("|")
                ref, alias = (body, "") if bar < 0 else (body[:bar - 1 if body[bar - 1:bar] == "\\" else bar], body[bar + 1:])
                name, _, heading = ref.partition("#")
                found = resolve(name) if name else [rel]
                if len(found) != 1:
                    what = "ambiguous target" if found else "missing target"
                    names = ", ".join(p.as_posix() for p in found)
                    problems.append(f"{rel.as_posix()}:{no}: {what} {m.group(0)}" + (f": {names}" if names else ""))
                    return m.group(0)
                # Spec 6.1 allows a relative or a bundle-absolute (/...) link; the relative form is what the ticket
                # asks for. Percent-encoded: a CommonMark link destination cannot hold a space.
                href = quote(os.path.relpath(out_rel(found[0]), rel.parent).replace(os.sep, "/")) if name else ""
                if heading and found[0].suffix != ".md":
                    href += "#" + quote(heading, safe="=&")   # a PDF page link: the fragment is the viewer's, not a heading
                elif heading:
                    anchor = matching_anchor(slug(heading), heading_slugs(vault / found[0], vault))
                    if anchor is None:
                        problems.append(f"{rel.as_posix()}:{no}: missing heading {m.group(0)}")
                        return m.group(0)
                    href += "#" + anchor
                text = alias or (f"{name} > {heading}" if name and heading else name or heading)
                return f"[{text}]({href})"

            # A link is rewritten unless a code span, an autolink or a raw HTML item covers or cuts through it (its start or
            # end inside one), on this line or from the line before: a span wholly inside the alias, `[[a|`b`]]`, stays in
            # the new link text. CommonMark binds a code span tighter than a link.
            spans = raw.get(i, ())

            def outside(m: re.Match) -> str:
                cut = any(s < m.start() < e or s < m.end() < e for s, e in spans)   # a boundary strictly inside a span
                return m.group(0) if cut else link(m)
            lines[i] = WIKILINK.sub(outside, line)
        if is_log(rel):   # spec 3.1: reserved, so never a concept; it becomes the spec 9 log
            log = build_log(rel, lines, problems)
            if log is not None:
                dest.write_text(log, encoding="utf-8")
            continue
        dest.write_bytes("".join(lines).encode("utf-8"))   # bytes: no newline translation on the way out either
    write_indexes(out, [out_rel(rel) for rel in files if rel.suffix == ".md" and not is_log(rel) and rel not in dropped])
    for p in problems:
        print(CONTROL.sub("?", p))
    return 1 if problems else 0


if __name__ == "__main__":
    sys.exit(main())
