@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/always_on_budget_grep.py

@@ -0,0 +1,318 @@
+# SPDX-License-Identifier: MIT
+
+"""always-on-budget-grep: token-budget conformity matcher for always-on rules.
+
+Why this enforcement exists. Always-on rules load into every session's
+context as standing directives; aggregate body length is a multiplier on
+every turn's cost. The token-budget-discipline rule caps each always-on
+body at MAX_SUBSTANTIVE_TOKENS substantive tokens, with a pre-emptive
+warn-band at WARN_BAND_THRESHOLD nudging authors to plan a path-filtered
+companion sub-rule before the hard ceiling triggers. Bodies above the
+ceiling are decomposed into the demand-load companion-sub-rule pattern
+ratified at rules/context-management.md and its companion
+rules/context-management-scratch.md.
+
+Substantive-token counter. The count is a whitespace-separated token
+count over the rule body with three regions excluded:
+
+  1. YAML frontmatter — content between the opening `---` and the second
+     `---` delimiters at file head. Frontmatter declares the rule's
+     classification, not its directive content.
+  2. The trailing `## Bindings (§0.j five-direction)` section — bindings
+     are pointers to peer artifacts, not standing directives. They
+     consume context but do not raise body-content load.
+  3. Companion-sub-rule pointer lines — any line containing the literal
+     string `(Companion Sub-Rule Anchor)`. The pointer line names a
+     demand-load surface; the surface itself loads on path-filter match
+     and counts against its own (path-filtered) sibling rule, not the
+     parent always-on body.
+
+Verdict matrix.
+  pass — the rule is not always-on (alwaysApply false OR pathFilter
+         non-empty), or the substantive-token count is at or below the
+         MAX_SUBSTANTIVE_TOKENS ceiling. WARN_BAND_THRESHOLD-MAX
+         counts produce an advisory in the finding payload but still
+         pass the gate.
+  FAIL — the substantive-token count exceeds MAX_SUBSTANTIVE_TOKENS;
+         the rule must be decomposed into a path-filtered companion
+         sub-rule with the parent body retaining only load-bearing
+         anchors plus the `(Companion Sub-Rule Anchor)` pointer.
+
+Invocation. The matcher accepts either a single rule path on argv, a
+directory (recurses over `*.md`), or `--stdin` reading the
+rule body. When invoked with no path, defaults to scanning `rules/`
+relative to the current working directory.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+# ---------------------------------------------------------------------------
+# Module identity
+# ---------------------------------------------------------------------------
+
+GREP_NAME: Final[str] = "always-on-budget-grep"
+RULE_ANCHOR: Final[str] = "D1 token-budget-discipline §Always-on body budget"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+# ---------------------------------------------------------------------------
+# Budget constants
+# ---------------------------------------------------------------------------
+
+MAX_SUBSTANTIVE_TOKENS: Final[int] = 500
+WARN_BAND_THRESHOLD: Final[int] = 450
+
+# ---------------------------------------------------------------------------
+# Region-exclusion markers
+# ---------------------------------------------------------------------------
+
+FRONTMATTER_DELIM: Final[str] = "---"
+BINDINGS_HEADING_PREFIX: Final[str] = "## Bindings"
+COMPANION_POINTER: Final[str] = "(Companion Sub-Rule Anchor)"
+RULE_GLOB: Final[str] = "*.md"
+DEFAULT_SCAN_DIR: Final[str] = "rules"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One per-rule budget verdict."""
+
+    path: str
+    always_on: bool
+    substantive_tokens: int
+    over_budget: bool
+    warn_band: bool
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "passed": self.passed,
+            "max-substantive-tokens": MAX_SUBSTANTIVE_TOKENS,
+            "warn-band-threshold": WARN_BAND_THRESHOLD,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def parse_frontmatter(content: str) -> tuple[dict[str, str], str]:
+    """Split frontmatter from body.
+
+    Args:
+        content: full rule file content.
+
+    Returns:
+        Tuple of (frontmatter mapping, body text). Frontmatter values are
+        stripped of surrounding quotes; missing keys yield an empty
+        mapping. When no frontmatter is present, returns ({}, content).
+
+    The parser tolerates a leading authorship-header banner (HTML comment
+    block on Markdown rules) preceding the frontmatter — it locates the
+    first `---` delimiter line that opens a YAML block whose immediate
+    content lines look like `key: value` pairs.
+    """
+    lines = content.splitlines()
+    start_index = -1
+    for i, line in enumerate(lines):
+        if line.strip() == FRONTMATTER_DELIM:
+            start_index = i
+            break
+    if start_index == -1:
+        return {}, content
+    end_index = -1
+    for i in range(start_index + 1, len(lines)):
+        if lines[i].strip() == FRONTMATTER_DELIM:
+            end_index = i
+            break
+    if end_index == -1:
+        return {}, content
+    fm: dict[str, str] = {}
+    for raw in lines[start_index + 1 : end_index]:
+        if ":" not in raw:
+            continue
+        key, _, value = raw.partition(":")
+        fm[key.strip()] = value.strip().strip('"').strip("'")
+    body = "\n".join(lines[end_index + 1 :])
+    return fm, body
+
+
+def is_always_on(frontmatter: dict[str, str]) -> bool:
+    """Classify a rule as always-on per its frontmatter.
+
+    A rule is always-on iff `alwaysApply` is the literal string `true`
+    AND `pathFilter` is empty (absent or whitespace-only). Path-filtered
+    rules demand-load on glob match and are exempt from the body budget.
+    """
+    apply_value = frontmatter.get("alwaysApply", "").lower()
+    path_filter = frontmatter.get("pathFilter", "").strip()
+    return apply_value == "true" and path_filter == ""
+
+
+def strip_bindings_section(body: str) -> str:
+    """Remove the trailing `## Bindings (§0.j five-direction)` section.
+
+    Bindings are reciprocal pointers to peer artifacts, not standing
+    directives; they are excluded from the substantive token count per
+    the rule's exclusion list.
+    """
+    lines = body.splitlines()
+    cut = -1
+    for i, line in enumerate(lines):
+        if line.lstrip().startswith(BINDINGS_HEADING_PREFIX):
+            cut = i
+            break
+    if cut == -1:
+        return body
+    return "\n".join(lines[:cut])
+
+
+def strip_companion_pointers(body: str) -> str:
+    """Remove every line containing the companion-sub-rule pointer.
+
+    The pointer line names a demand-load surface; the surface itself is
+    weighed against its own path-filtered sibling rule, not the parent
+    always-on body.
+    """
+    return "\n".join(
+        line for line in body.splitlines() if COMPANION_POINTER not in line
+    )
+
+
+def count_substantive_tokens(body: str) -> int:
+    """Count whitespace-separated tokens in the post-exclusion body.
+
+    The count is reproducible and platform-stable; markdown markers are
+    counted as tokens because they consume context just as words do.
+    """
+    return len(body.split())
+
+
+def measure(content: str) -> tuple[bool, int]:
+    """Measure the always-on classification and the substantive token count.
+
+    Returns:
+        Tuple of (always_on, substantive_token_count). When the rule is
+        not always-on, the count is still reported for transparency but
+        the verdict is always pass.
+    """
+    frontmatter, body = parse_frontmatter(content)
+    always_on = is_always_on(frontmatter)
+    body_no_bindings = strip_bindings_section(body)
+    body_no_pointers = strip_companion_pointers(body_no_bindings)
+    return always_on, count_substantive_tokens(body_no_pointers)
+
+
+def check_file(path: Path) -> Finding:
+    """Apply the matcher to a single rule file."""
+    content = path.read_text(encoding="utf-8")
+    always_on, tokens = measure(content)
+    over = always_on and tokens > MAX_SUBSTANTIVE_TOKENS
+    warn = always_on and (not over) and tokens >= WARN_BAND_THRESHOLD
+    return Finding(
+        path=str(path),
+        always_on=always_on,
+        substantive_tokens=tokens,
+        over_budget=over,
+        warn_band=warn,
+    )
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Per-Write dispatch entry consumed by `conformity/gate.py`.
+
+    Measures one rule body's substantive-token count. The orchestrator
+    invokes this on every Write/Edit; non-rule paths and non-always-on
+    rules pass without a finding.
+
+    Pre-conditions: `content` is the artifact about to be emitted; `path`
+    is the target file path or None.
+    Post-conditions: `result.passed` is True iff the artifact is not an
+    over-budget always-on rule body.
+    """
+    path_str = str(path) if path is not None else "<stdin>"
+    if path is not None and not path_str.endswith(".md"):
+        return GrepResult(grep=GREP_NAME, passed=True, findings=[])
+    always_on, tokens = measure(content)
+    over = always_on and tokens > MAX_SUBSTANTIVE_TOKENS
+    warn = always_on and (not over) and tokens >= WARN_BAND_THRESHOLD
+    finding = Finding(
+        path=path_str,
+        always_on=always_on,
+        substantive_tokens=tokens,
+        over_budget=over,
+        warn_band=warn,
+    )
+    if not over:
+        return GrepResult(grep=GREP_NAME, passed=True, findings=[])
+    return GrepResult(grep=GREP_NAME, passed=False, findings=[finding])
+
+
+def discover_rule_files(target: Path) -> list[Path]:
+    """Resolve a target into the rule files to inspect."""
+    if target.is_file():
+        return [target]
+    if target.is_dir():
+        return sorted(target.rglob(RULE_GLOB))
+    raise FileNotFoundError(f"target does not exist: {target}")
+
+
+def _read_stdin_finding() -> Finding:
+    content = sys.stdin.read()
+    always_on, tokens = measure(content)
+    over = always_on and tokens > MAX_SUBSTANTIVE_TOKENS
+    warn = always_on and (not over) and tokens >= WARN_BAND_THRESHOLD
+    return Finding(
+        path="<stdin>",
+        always_on=always_on,
+        substantive_tokens=tokens,
+        over_budget=over,
+        warn_band=warn,
+    )
+
+
+def _resolve_target(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path(DEFAULT_SCAN_DIR)
+
+
+def _main(argv: list[str]) -> int:
+    if len(argv) >= 2 and argv[1] == STDIN_FLAG:
+        finding = _read_stdin_finding()
+        result = GrepResult(
+            grep=GREP_NAME,
+            passed=not finding.over_budget,
+            findings=[finding],
+        )
+        print(result.to_json())
+        return EXIT_PASS if result.passed else EXIT_FAIL
+
+    target = _resolve_target(argv)
+    paths = discover_rule_files(target)
+    findings = [check_file(p) for p in paths]
+    failed = [f for f in findings if f.over_budget]
+    result = GrepResult(
+        grep=GREP_NAME,
+        passed=not failed,
+        findings=findings,
+    )
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/conformity/bare_except_grep.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag bare except clauses without typed exceptions or re-raise.
+
+Why this enforcement exists. The code-craft rule M13.3 forbids bare
+`except:` and broad `except Exception:` that swallow errors silently.
+Caught exceptions are typed and either handled with rationale or
+re-raised with context. The pre-emission gate's mechanical bar 13 (M13 code craft)
+catches both bare-clause shapes and the broad-Exception form (without
+re-raise) and surfaces each occurrence so the operator either narrows
+the type or adds a `raise` so the failure propagates.
+
+Detection strategy. The grep walks Python source for `except:` (no
+type spec), `except Exception:` / `except BaseException:` (broad), and
+the parenthesized-tuple form that contains a broad type
+(`except (ValueError, Exception):`); within each clause's body it
+inspects whether the body contains a `raise` statement. A clause that
+catches broadly without re-raising is the canonical violation; bare
+`except:` is always flagged.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from apothem.conformity._grep_base import GrepResult, run_grep
+
+# Bare or broad except shapes. Bare `except:` matches with no type
+# specifier; broad forms catch the root exception types either directly
+# (`except Exception:`) or inside a tuple (`except (ValueError, Exception):`).
+# The match groups capture the form for the finding's report.
+BARE_EXCEPT_RE: Final[re.Pattern[str]] = re.compile(
+    r"^(\s*)except\s*(?:"
+    r":"  # bare `except:`
+    r"|("  # group 2: a broad spec including the trailing colon
+    r"(?:Exception|BaseException)(?:\s+as\s+\w+)?\s*:"  # broad single type
+    r"|\([^)]*\b(?:Exception|BaseException)\b[^)]*\)(?:\s+as\s+\w+)?\s*:"  # broad tuple
+    r"))"
+)
+RAISE_RE: Final[re.Pattern[str]] = re.compile(r"^\s+raise\b")
+# A re-raise written inline after the `except ...:` colon — `except
+# Exception: raise` or `except Exception: log(); raise`. Matched at the
+# start of the inline body or immediately after a `;` statement separator,
+# so an inline re-raise is recognized as faithfully as a subsequent-line one.
+INLINE_RAISE_RE: Final[re.Pattern[str]] = re.compile(r"(?:^|;)\s*raise\b")
+GREP_NAME: Final[str] = "bare-except-grep"
+RULE_ANCHOR: Final[str] = "M13.3 error handling"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    line: int
+    form: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+def _clause_has_raise(lines: list[str], clause_index: int, indent: int) -> bool:
+    """Walk the clause body until dedent; return True iff any line is a raise."""
+    body_indent_min = indent + 1
+    for line in lines[clause_index + 1 :]:
+        if not line.strip():
+            continue
+        leading = len(line) - len(line.lstrip())
+        if leading < body_indent_min:
+            return False
+        if RAISE_RE.match(line):
+            return True
+    return False
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content; return a structured result."""
+    findings: list[Finding] = []
+    lines = content.splitlines()
+    for index, line in enumerate(lines):
+        match = BARE_EXCEPT_RE.match(line)
+        if match is None:
+            continue
+        indent = len(match.group(1))
+        is_bare = match.group(2) is None
+        form = "bare except:" if is_bare else "broad except: " + match.group(2).strip()
+        # Bare except is always a finding. Broad except is a finding only
+        # when the clause body contains no `raise` — counting both a
+        # subsequent indented line and an inline re-raise on the `except`
+        # line itself (`except Exception: raise`), so a faithful inline
+        # re-raise is not flagged as a swallow.
+        inline_body = line[match.end() :]
+        has_raise = bool(INLINE_RAISE_RE.search(inline_body)) or _clause_has_raise(
+            lines, index, indent
+        )
+        if is_bare or not has_raise:
+            detail = (
+                "bare except swallows every exception class"
+                if is_bare
+                else "broad except without re-raise; narrow the type or add raise"
+            )
+            findings.append(Finding(line=index + 1, form=form, detail=detail))
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(path) if path is not None else None,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(run_grep(check, sys.argv))

package/src/apothem/conformity/binding_reciprocity_grep.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag binding declarations using non-canonical arrow notation.
+
+Why this enforcement exists. The bidirectional-binding rule M10 declares
+five canonical arrows — `→` (Drives), `←` (Driven by), `↑` (Established by),
+`↓` (rare downward; reserved), and `↔` (Cross-bound with) — that every
+Bindings section uses verbatim. ASCII substitutes (`->`, `<-`, `<->`) and
+emoji-arrow variants are notation drift; they break sibling-convergence and
+the mechanical reciprocity walk that future cross-file matchers will perform.
+This grep enforces the in-file shape of the Bindings section: heading is
+present and well-named, every arrow is from the canonical set, no ASCII
+arrows appear in the Bindings region.
+
+Cross-file reciprocity check (full half-edge detection across the rule set)
+is out of scope for this per-file grep — it requires a corpus walk that
+the orchestrator at `gate.py` will assemble. The per-file
+contribution here is the notation discipline within each Bindings section.
+
+Code is excluded from the arrow scan: fenced code blocks and inline-code spans
+inside a Bindings section legitimately quote ASCII arrows (a Python return
+annotation, a shell pipe, a CLI usage snippet), which are quotations rather than
+Bindings notation.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from apothem.conformity._grep_base import GrepResult, run_grep
+
+# The canonical Bindings section heading per the §0.j five-direction notation.
+# Rule files use `## Bindings (§0.j five-direction)`; some siblings drop the
+# parenthetical. Both are accepted as valid section markers; the grep starts
+# scanning at the first match and stops at the next H1/H2 heading.
+BINDINGS_HEADING_RE: Final[re.Pattern[str]] = re.compile(
+    r"^##\s+Bindings(?:\s+\(§0\.j\s+five-direction\))?\s*$"
+)
+NEXT_HEADING_RE: Final[re.Pattern[str]] = re.compile(r"^##?\s+\S")
+
+# ASCII substitute arrows that are notation drift. The rule's spec lists
+# them explicitly as forbidden alternatives.
+FORBIDDEN_ARROWS: Final[tuple[str, ...]] = (
+    "->",
+    "<-",
+    "<->",
+    "<=",
+    "=>",
+)
+FORBIDDEN_ARROW_RE: Final[re.Pattern[str]] = re.compile(
+    "|".join(re.escape(a) for a in FORBIDDEN_ARROWS)
+)
+
+# The canonical arrow alphabet. Any character outside this set inside an arrow
+# context is suspect, but we only flag the explicit ASCII substitutes since
+# free-form prose may legitimately contain any Unicode character.
+CANONICAL_ARROWS: Final[frozenset[str]] = frozenset({"→", "←", "↑", "↓", "↔"})
+
+# Code spans inside the Bindings section legitimately quote ASCII arrows — a
+# Python return annotation (`f() -> str`), a shell pipe, a CLI usage snippet —
+# so fenced blocks and inline-code spans are excluded from the arrow scan.
+_CODE_FENCE_RE: Final[re.Pattern[str]] = re.compile(r"^```")
+_INLINE_CODE_RE: Final[re.Pattern[str]] = re.compile(r"`[^`]*`")
+
+GREP_NAME: Final[str] = "binding-reciprocity-grep"
+RULE_ANCHOR: Final[str] = "M10 bidirectional-binding §Notation"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One notation-drift occurrence inside the Bindings section."""
+
+    line: int
+    match: str
+    context: str
+    rule: str = RULE_ANCHOR
+
+
+def _bindings_region(lines: list[str]) -> tuple[int, int] | None:
+    """Locate the Bindings section as a (start, end) line-range pair.
+
+    Returns a 1-indexed inclusive start line and exclusive end line, or
+    None if no Bindings section is present in the artifact.
+    """
+    start: int | None = None
+    for i, line in enumerate(lines):
+        if start is None:
+            if BINDINGS_HEADING_RE.match(line):
+                start = i + 1  # First content line after the heading.
+            continue
+        # Past the heading; the section ends at the next heading.
+        if NEXT_HEADING_RE.match(line):
+            return start, i
+    if start is not None:
+        return start, len(lines)
+    return None
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content; return a structured result.
+
+    Pre-conditions: `content` is the artifact body about to be emitted.
+    Post-conditions: `result.passed` is True when either the Bindings
+    section is absent (not every artifact has one) or the section uses
+    only canonical arrow notation.
+    """
+    lines = content.splitlines()
+    region = _bindings_region(lines)
+    if region is None:
+        return GrepResult(
+            grep=GREP_NAME,
+            path=str(path) if path is not None else None,
+            passed=True,
+        )
+    findings: list[Finding] = []
+    start, end = region
+    inside_fence = False
+    for offset, line in enumerate(lines[start - 1 : end], start=start):
+        if _CODE_FENCE_RE.match(line):
+            inside_fence = not inside_fence
+            continue
+        if inside_fence:
+            continue
+        # Blank inline-code spans (same-length spaces preserve columns) so a
+        # quoted ASCII arrow inside backticks is not read as notation drift.
+        scanned = _INLINE_CODE_RE.sub(lambda m: " " * len(m.group(0)), line)
+        for match in FORBIDDEN_ARROW_RE.finditer(scanned):
+            findings.append(
+                Finding(
+                    line=offset,
+                    match=match.group(),
+                    context=line.strip(),
+                )
+            )
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(path) if path is not None else None,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(run_grep(check, sys.argv))