#!/usr/bin/env python3
"""The reading order of the decision records: its topics are written here, its records are not.

A number identifies a record and never changes, so the reading order is not the order of the numbers.
It is the six topics `02-DECISIONS/README.md` writes down, in order, and each record's own topic. The
records live in the knowledge base (ADR 0290, issue 426), which reads these lines through the records
module and refuses a record whose topic is not one of them; the list of records under a topic is its
answer to `knowledge-base.holds` with that topic, never stored here (ADR 0248, hq issue 297).

    python3 00-META/checks/index.py            check

It fails when the README's reading order is missing or names a topic twice, and when the README stores
a list of records again — the index markers, or a line of a generated list. The last one is what keeps
the conflict of issue 297 from coming back. Whether every record's topic is one of the six is the
knowledge base's rule `topic`, judged when a record is proposed.
"""

import io
import re
import sys

README = "02-DECISIONS/README.md"

# A topic in the README's reading order, e.g.
#   1. **What the mesh is** — `topic: the mesh`. What it is for, ...
# The knowledge base (mesh-knowledge, reference.go) reads the same line, so the form is a contract.
TOPIC_LINE = re.compile(r"^\d+\.\s+\*\*(?P<label>[^*]+)\*\*\s+—\s+`topic:\s*(?P<topic>[^`]+)`", re.M)

# What a stored list looks like: the old markers, or a line of the list index.py used to print.
STORED = [
    (re.compile(r"<!--\s*index:(start|end)\s*-->"), "an index marker"),
    (re.compile(r"^- \*\*\d{4}\*\* — \[", re.M), "a line of a generated list"),
]


def reading_order(text=None):
    """The topics, in order, as (topic, label) pairs, from the README."""
    if text is None:
        text = io.open(README, encoding='utf-8').read()
    return [(m.group("topic").strip(), m.group("label").strip()) for m in TOPIC_LINE.finditer(text)]


def main():
    if "--print" in sys.argv:
        print("index: the records live in the knowledge base (ADR 0290). Read a topic's with "
              "`knowledge-base.holds` and that topic, through the mesh MCP server.")
        return 2

    text = io.open(README, encoding='utf-8').read()
    topics = reading_order(text)

    problems = []
    if not topics:
        problems.append("%s writes no reading order: no line of the form "
                        "'1. **Label** — `topic: name`. ...'; the knowledge base refuses every "
                        "record without it" % README)
    names = [t for t, _ in topics]
    if len(set(names)) != len(names):
        problems.append("%s names a topic twice in its reading order" % README)
    for pattern, what in STORED:
        if pattern.search(text):
            problems.append("%s stores a list of records (%s). The records live in the knowledge base, "
                            "and a topic's list is `knowledge-base.holds` with that topic" % (README, what))

    for p in problems:
        print("index: " + p)
    if problems:
        return 1
    print("index: %d topics in the reading order, no stored list" % len(topics))
    return 0


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