v0.1.0-pre.012

scripts/audit_khadhroony_workspace_rules.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # file: scripts/audit_khadhroony_workspace_rules.py
-# version: 5
+# version: 6
 
 """Audit mechanically verifiable rules specific to khadhroony-bot3."""
 
@@ -207,6 +207,77 @@ def audit_kb_lib_symbol_prefixes(root: pathlib.Path) -> list[Violation]:
     return violations
 
 
+def audit_reserved_decoder_scaffolds(root: pathlib.Path) -> list[Violation]:
+    """Reject temporary decoder migration markers and incomplete reserved decoders."""
+
+    violations: list[Violation] = []
+    decoder_root = root / "kb-lib/src/decoder"
+    forbidden = (
+        "MIGRATION_BOUNDARIES",
+        "LEGACY_CRATE",
+        "MIGRATION_STATUS",
+        "source-preserved-pending-port",
+    )
+    struct_pattern = re.compile(r"^pub struct (Dc[A-Za-z0-9]+Decoder);$", re.MULTILINE)
+    for path in sorted(decoder_root.rglob("*.rs")):
+        relative = path.relative_to(root).as_posix()
+        text = path.read_text(encoding="utf-8")
+        for marker in forbidden:
+            offset = text.find(marker)
+            if offset >= 0:
+                violations.append(
+                    Violation(
+                        "KH_DC001",
+                        relative,
+                        text[:offset].count("\n") + 1,
+                        f"temporary decoder migration marker `{marker}` is forbidden",
+                    )
+                )
+        if "Reserved protocol decoder for `" not in text:
+            continue
+        struct_match = struct_pattern.search(text)
+        if struct_match is None:
+            violations.append(
+                Violation(
+                    "KH_DC002",
+                    relative,
+                    1,
+                    "reserved decoder must expose one `Dc*Decoder` unit struct",
+                )
+            )
+            continue
+        type_name = struct_match.group(1)
+        implementation = f"impl crate::DcApiProtocolDecoder for crate::{type_name} {{"
+        if implementation not in text:
+            violations.append(
+                Violation(
+                    "KH_DC003",
+                    relative,
+                    text[: struct_match.start()].count("\n") + 1,
+                    f"`{type_name}` must implement `DcApiProtocolDecoder`",
+                )
+            )
+        if "fn program_ids(&self) -> &'static [&'static str]" not in text:
+            violations.append(
+                Violation(
+                    "KH_DC004",
+                    relative,
+                    1,
+                    "reserved decoder must declare its exact Program ID boundary",
+                )
+            )
+        if "crate::DcApiDecoderSupport::Maybe" not in text:
+            violations.append(
+                Violation(
+                    "KH_DC005",
+                    relative,
+                    1,
+                    "reserved decoder must remain explicitly `Maybe` until implemented",
+                )
+            )
+    return violations
+
+
 def audit_token2022_naming(root: pathlib.Path) -> list[Violation]:
     """Reject obsolete internal Token2022 spellings while preserving legacy evidence."""
 
@@ -242,6 +313,38 @@ def audit_token2022_naming(root: pathlib.Path) -> list[Violation]:
     return violations
 
 
+def audit_private_kb_lib_paths_in_active_docs(root: pathlib.Path) -> list[Violation]:
+    """Reject documentation that presents private kb-lib modules as public APIs."""
+
+    violations: list[Violation] = []
+    candidates = [
+        root / "README.md",
+        root / "ROADMAP.md",
+        root / "RULES.md",
+        root / "kb-lib/README.md",
+        root / "kb-program-ids/README.md",
+    ]
+    candidates.extend(sorted((root / "docs").glob("*.md")))
+    candidates.extend(sorted((root / "docs").glob("*.json")))
+    pattern = re.compile(r"kb_lib::(?:decoder|executor|materializer|model)::")
+    for path in candidates:
+        if not path.is_file():
+            continue
+        relative = path.relative_to(root).as_posix()
+        for index, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            match = pattern.search(line)
+            if match is not None:
+                violations.append(
+                    Violation(
+                        "KH_API001",
+                        relative,
+                        index,
+                        f"private kb-lib module path `{match.group(0)}` is forbidden in active documentation",
+                    )
+                )
+    return violations
+
+
 def audit_wincode_resolution(root: pathlib.Path) -> list[Violation]:
     """Require the currently compatible Solana wincode dependency family."""
 
@@ -317,7 +420,9 @@ def main() -> int:
         audit_tracing(root)
         + audit_kb_lib_tracing(root)
         + audit_kb_lib_symbol_prefixes(root)
+        + audit_reserved_decoder_scaffolds(root)
         + audit_token2022_naming(root)
+        + audit_private_kb_lib_paths_in_active_docs(root)
         + audit_solana_types(root)
         + audit_wincode_resolution(root)
     )