Merge branch 'main' into issue/4-ci-node24-actions

Author: AngriestBird

docs/indexes.md

@@ -130,10 +130,13 @@ practice that's a few KB of paradox script and ~1 ms.
 
 1. Inherit `GenericTxtIndex` in `src/md_mcp/indexes/<name>.py`.
 2. Set the class attributes: `cache_version`, `cache_name`, `subdir`,
-   `pattern`, `content_prefilter`, `primary_key`.
+   `pattern`, `primary_key`.
 3. Define a **module-level** parser fn (so `ProcessPoolExecutor` can pickle it)
    with signature `(abs_path: str, relpath: str) -> Optional[List[dict]]`.
-   Return `None` for "can't parse"; `[]` for "no records found".
+   Return `None` for "can't parse"; `[]` for "no records found". Have it read
+   the file and do its own cheap substring check up front (see `event.py`,
+   `idea.py`, `gfx.py`) so files that obviously don't contain the record kind
+   skip the full parse.
 4. Set `parser_fn = _your_parser_fn` on the class.
 5. Add the class to `src/md_mcp/indexes/__init__.py`.
 6. Wire into `server.py`: instantiate once, pass to resolver/analysis tools.

src/md_mcp/indexes/base.py

@@ -321,7 +321,6 @@ class GenericTxtIndex:
         * `cache_name: str`     — file basename under `<cache_dir>/v<ver>/`
         * `subdir: str`         — path under each root, e.g. `events`
         * `pattern: str`        — glob like `*.txt`
-        * `content_prefilter`   — cheap substring test before parsing
         * `parser_fn`           — *module-level* function
                                   `(abs_path: str, relpath: str) -> Optional[list[dict]]`
                                   (must be picklable for ProcessPoolExecutor)
@@ -337,7 +336,6 @@ class GenericTxtIndex:
     cache_name: str = ""
     subdir: str = ""
     pattern: str = "*.txt"
-    content_prefilter: tuple = ()
     primary_key: str = "id"
 
     def __init__(

src/md_mcp/indexes/event.py

@@ -6,30 +6,21 @@
 from typing import Optional
 
 from ..paradox import parse_string
-from ..paradox.schema import extract_event_records
+from ..paradox.schema import EVENT_KINDS, extract_event_records
 from ..util.encoding import read_text
 from .base import GenericTxtIndex
 
 logger = logging.getLogger(__name__)
 
 
-_EVENT_TOKENS = (
-    "country_event",
-    "news_event",
-    "state_event",
-    "unit_leader_event",
-    "operative_leader_event",
-)
-
-
 def _parse_event_file(abs_path: str, relpath: str) -> Optional[list[dict]]:
     """Top-level so ProcessPoolExecutor can pickle and dispatch this."""
     try:
         text = read_text(abs_path)
     except OSError as e:
         logger.warning("event index: cannot read %s: %s", abs_path, e)
         return None
-    if not any(tok in text for tok in _EVENT_TOKENS):
+    if not any(tok in text for tok in EVENT_KINDS):
         return []
     try:
         root = parse_string(text, error_prefix=f"In file {relpath}:\n")

src/md_mcp/indexes/gfx.py

@@ -20,28 +20,16 @@
 from typing import Optional
 
 from ..paradox import parse_string
-from ..paradox.schema import extract_sprite_records
+from ..paradox.schema import SPRITE_KINDS, extract_sprite_records
 from ..util.encoding import read_text
 from .base import GenericTxtIndex
 
 logger = logging.getLogger(__name__)
 
-_SPRITE_KINDS = (
-    "spriteType",
-    "corneredTileSpriteType",
-    "frameAnimatedSpriteType",
-    "maskedShieldType",
-    "progressbartype",
-    "barChartType",
-    "PieChartType",
-    "LineChartType",
-    "scrollingSprite",
-)
-
 # Match `<kind> = {`. Case-sensitive because HOI4 itself is case-sensitive on identifiers
 # (per general-rules.md). Field-name regexes stay case-insensitive — `name` and
 # `texturefile` are *property* keys inside a sprite block and the engine is lenient there.
-_SPRITE_OPEN_RE = re.compile(r"\b(" + "|".join(_SPRITE_KINDS) + r")\s*=\s*\{")
+_SPRITE_OPEN_RE = re.compile(r"\b(" + "|".join(SPRITE_KINDS) + r")\s*=\s*\{")
 _NAME_RE = re.compile(r'\bname\s*=\s*"([^"\\]*(?:\\.[^"\\]*)*)"', re.IGNORECASE)
 _NAME_BARE_RE = re.compile(r"\bname\s*=\s*([A-Za-z_][\w.]*)", re.IGNORECASE)
 _TEXTUREFILE_RE = re.compile(r'\btexturefile\s*=\s*"([^"]+)"', re.IGNORECASE)

src/md_mcp/paradox/schema.py

@@ -1,13 +1,13 @@
 """Schema projections — extract typed information from a parsed AST.
 
-The TS `schema.ts` exposes a full `convertNodeToJson(node, schemaDef)` system. For
-Milestone 1, we only need:
+The TS `schema.ts` exposes a full `convertNodeToJson(node, schemaDef)` system. This
+module covers the subset the MCP server needs:
 
   * `to_json(node)` — convert any Node to a JSON-serialisable dict (used by `parse_file`
     and `parse_string` MCP tools)
   * `extract_focus_ids(root)` — port of `extractFocusIds` from `previewdef/focustree/schema.ts`
-
-Additional extractors (events, decisions, ideas, sprites) land in Milestone 2.
+  * Extractors for events, decisions, ideas, and sprites, plus the `EVENT_KINDS` /
+    `SPRITE_KINDS` container-kind lists that `indexes/` reuses to stay in sync.
 """
 
 from __future__ import annotations
@@ -214,15 +214,21 @@ def _get_id(node: Node) -> str | None:
 # ---------------------------------------------------------------------------
 
 
-_EVENT_KINDS = frozenset(
-    {"country_event", "news_event", "state_event", "unit_leader_event", "operative_leader_event"}
+# Canonical list of event container kinds — indexes/event.py reuses this for its
+# text prefilter so a new kind only needs to be added here.
+EVENT_KINDS = (
+    "country_event",
+    "news_event",
+    "state_event",
+    "unit_leader_event",
+    "operative_leader_event",
 )
 
 
 def _iter_event_definitions(root: Node) -> Iterator[tuple[Node, str]]:
     """Yield `(node, id_str)` for every node satisfying the event hierarchy."""
     for top in root.children():
-        if top.name in _EVENT_KINDS:
+        if top.name in EVENT_KINDS:
             id_str = _get_id(top)
             if id_str:
                 yield top, id_str
@@ -477,18 +483,18 @@ def _looks_like_slot_wrapper(node: Node) -> bool:
 # ---------------------------------------------------------------------------
 
 
-_SPRITE_KINDS = frozenset(
-    {
-        "spriteType",
-        "corneredTileSpriteType",
-        "frameAnimatedSpriteType",
-        "maskedShieldType",
-        "progressbartype",
-        "barChartType",
-        "PieChartType",
-        "LineChartType",
-        "scrollingSprite",
-    }
+# Canonical list of sprite container kinds — indexes/gfx.py reuses this to build
+# its regex scanner, so order must stay deterministic (a plain tuple, not a set).
+SPRITE_KINDS = (
+    "spriteType",
+    "corneredTileSpriteType",
+    "frameAnimatedSpriteType",
+    "maskedShieldType",
+    "progressbartype",
+    "barChartType",
+    "PieChartType",
+    "LineChartType",
+    "scrollingSprite",
 )
 
 
@@ -503,7 +509,7 @@ def _iter_sprite_definitions(root: Node) -> Iterator[tuple[Node, str, str]]:
         if not (top.name and top.name.lower().startswith("spritetypes")):
             continue
         for sprite in top.children():
-            if sprite.name not in _SPRITE_KINDS:
+            if sprite.name not in SPRITE_KINDS:
                 continue
             name_node = sprite.get("name")
             if name_node is None:

src/md_mcp/tools/linting_tools.py

@@ -29,7 +29,7 @@
 from typing import Callable, Optional, Sequence
 
 from ..util.response import BUDGET_BYTES, enforce_budget
-from ..validators import SLOW_VALIDATORS, ValidatorRunner
+from ..validators import SEVERITY_RANK, SLOW_VALIDATORS, ValidatorRunner
 from .lint_validators import run_validators_for_lint, select_validators
 
 _LINT_LINE_RE = re.compile(r"^(?P<file>[^:]+):(?P<line>\d+):\s*(?P<msg>.+)$")
@@ -44,8 +44,6 @@
 # ANSI escape stripper for scripts that emit colour codes.
 _ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
 
-_SEVERITY_RANK = {"info": 0, "warning": 1, "error": 2}
-
 # Leave room for status fields and stderr within the response budget.
 _MAX_REVIEW_REPORT_BYTES = max(1, BUDGET_BYTES - 12_000)
 
@@ -579,8 +577,8 @@ def _maybe(files_list: Optional[list[str]], runner: Callable[[], dict]) -> dict:
             overall[sev] = overall.get(sev, 0) + 1
         all_issues.extend(v_issues)
 
-    floor = _SEVERITY_RANK.get(severity_min, 0)
-    filtered = [i for i in all_issues if _SEVERITY_RANK.get(i.get("severity", "info"), 0) >= floor]
+    floor = SEVERITY_RANK.get(severity_min, 0)
+    filtered = [i for i in all_issues if SEVERITY_RANK.get(i.get("severity", "info"), 0) >= floor]
     truncated = len(filtered) > limit if limit >= 0 else False
     issues_capped = filtered[:limit] if limit >= 0 else filtered
 

src/md_mcp/tools/validation_tools.py

@@ -10,9 +10,7 @@
 
 from ..config import Settings
 from ..util.response import coerce_int, enforce_budget, paginate
-from ..validators import SLOW_VALIDATORS, ValidatorRunner, available_validators
-
-_SEVERITY_RANK = {"info": 0, "warning": 1, "error": 2}
+from ..validators import SEVERITY_RANK, SLOW_VALIDATORS, ValidatorRunner, available_validators
 
 
 def validate_list_tool(
@@ -60,8 +58,8 @@ def _filter_and_cap(
     limit: int,
 ) -> tuple[list[dict], bool, int]:
     """Apply severity floor + cap. Returns (kept, truncated, total_after_filter)."""
-    floor = _SEVERITY_RANK.get(severity_min, 0)
-    filtered = [i for i in issues if _SEVERITY_RANK.get(i.get("severity", "info"), 0) >= floor]
+    floor = SEVERITY_RANK.get(severity_min, 0)
+    filtered = [i for i in issues if SEVERITY_RANK.get(i.get("severity", "info"), 0) >= floor]
     total = len(filtered)
     if limit >= 0 and total > limit:
         return filtered[:limit], True, total

src/md_mcp/validators/__init__.py

@@ -4,4 +4,13 @@
 # paths ("*" in lint, validator=None in validate); reachable by explicit name.
 SLOW_VALIDATORS: frozenset = frozenset({"unused_scripted", "unused_textures"})
 
-__all__ = ["SLOW_VALIDATORS", "ValidatorInfo", "ValidatorRunner", "available_validators"]
+# Shared severity ordering for `severity_min` floor filters in lint/validate tools.
+SEVERITY_RANK = {"info": 0, "warning": 1, "error": 2}
+
+__all__ = [
+    "SEVERITY_RANK",
+    "SLOW_VALIDATORS",
+    "ValidatorInfo",
+    "ValidatorRunner",
+    "available_validators",
+]

tests/test_indexes_m2.py

@@ -3,6 +3,9 @@
 from __future__ import annotations
 
 from md_mcp.indexes import DecisionIndex, EventIndex, GfxIndex, IdeaIndex
+from md_mcp.indexes.event import _parse_event_file
+from md_mcp.indexes.gfx import _parse_gfx_file
+from md_mcp.indexes.idea import _parse_idea_file
 
 
 def test_gfx_index_builds(fake_mod_root, cache_dir):
@@ -71,3 +74,27 @@ def test_idea_index_categories(fake_mod_root, cache_dir):
     assert acme is not None and acme["category"] == "tank_manufacturer"
     # The slot wrapper itself (designer / law) must NOT be indexed as an idea.
     assert "designer" not in i.list_keys()
+
+
+# The unclosed brace makes a real parse fail (return None), so these pass only
+# if the prefilter short-circuits before parsing.
+_TOKEN_FREE_MALFORMED = "some_unrelated_block = { foo = bar"
+
+
+def test_event_parser_skips_files_without_event_tokens(tmp_path):
+    """No `country_event`/`news_event`/etc. token means the file is skipped pre-parse."""
+    f = tmp_path / "no_events.txt"
+    f.write_text(_TOKEN_FREE_MALFORMED, encoding="utf-8")
+    assert _parse_event_file(str(f), "no_events.txt") == []
+
+
+def test_idea_parser_skips_files_without_ideas_token(tmp_path):
+    f = tmp_path / "no_ideas.txt"
+    f.write_text(_TOKEN_FREE_MALFORMED, encoding="utf-8")
+    assert _parse_idea_file(str(f), "no_ideas.txt") == []
+
+
+def test_gfx_parser_skips_files_without_sprite_token(tmp_path):
+    f = tmp_path / "no_sprites.gfx"
+    f.write_text(_TOKEN_FREE_MALFORMED, encoding="utf-8")
+    assert _parse_gfx_file(str(f), "no_sprites.gfx") == []

tests/test_ref_audit.py

@@ -116,7 +116,8 @@ def test_sites_carry_file_line_and_referrer(audit_mod):
     entry = next(e for e in out["unresolved"] if e["ref"] == "TST_missing_focus")
     site = entry["sites"][0]
     assert site["file"] == "common/national_focus/TST_audit.txt"
-    assert isinstance(site["line"], int) and site["line"] > 1
+    # Hand-counted from _FOCUS_FILE: the `prerequisite = { ... }` line.
+    assert site["line"] == 20
     assert site["via"] == "prerequisite"
     assert site["referrer"] == "TST_audit_child"