patch_overrides.py

#!/usr/bin/env python3
"""Let a sidecar file correct subtopic and topic without editing bank files.

tools/section_gaps.py and tools/section_triage.py found blocks whose
origin.section was captured wrong, and in seven of them that wrong heading also
produced a wrong topic tag. Both need fixing, and the obvious way - editing
content/banks/mineru/*.json - is the wrong way: those files are regenerated by
import_mineru_bank.py, so the next re-import silently discards every
correction.

So corrections live in content/subtopic_overrides.json instead, keyed by source
block rather than by question id. Block keys survive a re-import; question ids
do not necessarily, and a per-question file would need re-checking every time
the extraction changed. One entry covers a whole block, which is the unit the
defect actually occurs in.

The override runs last in _hydrate, after the section backfill, so it wins over
both the heading and anything in the bank file. Entries carry "apply": false
until a human flips them, meaning a generated file does nothing until reviewed.

Two edits:

  1. content.overrides()   load and index the sidecar, cached like every other
                           content read and cleared by invalidate()
  2. content._hydrate      apply a matching entry's subtopic and topic

An override may move a question to a different subject, because some of these
belong to one: the depth-first-search questions sitting under
discrete-mathematics/graph-theory are algorithms/graph-traversal questions.
item["subject"] is already whatever the question says rather than whatever file
it sits in, so this needs no further change.

Run patch_subtopic.py first - this patch anchors on its output.

CRLF-safe and idempotent. Run from the repo root:  python patch_overrides.py
"""
import io
import os
import sys

EDITS = [
    # ---- 1. loader -----------------------------------------------------
    ('core/content.py',
     'def normalise_topic(conn, subject_slug, topic_slug, name=""):',

     'def overrides(reload=False):\n'
     '    """Block key -> correction, from content/subtopic_overrides.json.\n'
     '\n'
     '    Keyed "<volume>|<chapter>.<block>" so a correction outlives the\n'
     '    re-import that would renumber or rename individual questions. Entries\n'
     '    with apply false are ignored, so a freshly generated file is inert\n'
     '    until somebody has read it.\n'
     '    """\n'
     '    if reload or "overrides" not in _cache:\n'
     '        data = _read_json(\n'
     '            os.path.join(CONTENT_DIR, "subtopic_overrides.json"), {}\n'
     '        ) or {}\n'
     '        out = {}\n'
     '        for key, spec in (data.get("overrides") or {}).items():\n'
     '            if not isinstance(spec, dict) or not spec.get("apply"):\n'
     '                continue\n'
     '            entry = {}\n'
     '            if "subtopic" in spec:\n'
     '                entry["subtopic"] = _norm_key(spec.get("subtopic") or "")\n'
     '            topic = (spec.get("topic") or "").strip()\n'
     '            if "/" in topic:\n'
     '                subject, tslug = topic.split("/", 1)\n'
     '                entry["subject"] = subject\n'
     '                entry["topic"] = tslug\n'
     '            if entry:\n'
     '                out[key] = entry\n'
     '        _cache["overrides"] = out\n'
     '    return _cache["overrides"]\n'
     '\n'
     '\n'
     'def _block_key(origin):\n'
     '    """"<volume>|<chapter>.<block>" for a question\'s origin, or ""."""\n'
     '    if not isinstance(origin, dict):\n'
     '        return ""\n'
     '    parts = (origin.get("ref") or "").split(".")\n'
     '    if len(parts) < 3 or not parts[1].isdigit():\n'
     '        return ""\n'
     '    return "%s|%s.%d" % (origin.get("volume") or "", parts[0], int(parts[1]))\n'
     '\n'
     '\n'
     'def normalise_topic(conn, subject_slug, topic_slug, name=""):'),

    # ---- 2. apply in _hydrate ------------------------------------------
    ('core/content.py',
     '            item["subtopic"] = _norm_key(origin["section"])\n'
     '    item.setdefault("subtopic", "")',

     '            item["subtopic"] = _norm_key(origin["section"])\n'
     '    item.setdefault("subtopic", "")\n'
     '    # Last word on both fields. A blank subtopic here is deliberate and\n'
     '    # not a failure: where the heading is wrong but nobody knows the right\n'
     '    # one, empty costs granularity while wrong misroutes every search that\n'
     '    # would otherwise have found the question.\n'
     '    fix = overrides().get(_block_key(q.get("origin")))\n'
     '    if fix:\n'
     '        item.update(fix)'),
]


def main():
    changed = skipped = 0
    for path, old, new in EDITS:
        if not os.path.isfile(path):
            sys.exit("missing %s - run this from the repo root" % path)
        s = io.open(path, encoding="utf-8", newline="").read()
        crlf = "\r\n" in s
        o = old.replace("\n", "\r\n") if crlf else old
        n = new.replace("\n", "\r\n") if crlf else new
        if n in s:
            print("  skip    %-26s already applied" % path)
            skipped += 1
            continue
        if s.count(o) != 1:
            sys.exit(
                "  ERROR   %s: anchor found %d times, expected 1.%s"
                % (path, s.count(o),
                   " Run patch_subtopic.py first." if "subtopic" in old else "")
            )
        io.open(path, "w", encoding="utf-8", newline="").write(s.replace(o, n, 1))
        print("  patched %-26s ok" % path)
        changed += 1
    print("\n  %d edit(s) applied, %d already present" % (changed, skipped))
    if changed:
        print("  Next: python tools/propose_overrides.py")
    return 0


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