@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/freshness_token_grep.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag freshness-narrative phrases on shipped public surfaces.
+
+Why this enforcement exists. The freshness-facade rule
+(``rules/freshness-facade.md``) keeps every shipped public surface a
+current-version-only facade: no AI-disclosure, no backward / legacy /
+obsolete replacement narrative, no placeholder / deferral, no
+fix-and-refinement story-of-becoming. This matcher is the freshness analogue
+of ``plain_language_grep`` — a distinct, non-overlapping token-class on the same
+shipped-surface scope. ``plain_language_grep`` forbids mechanistic vocabulary
+(``AI`` / ``agent`` / harness brands); this matcher forbids the narrative
+PHRASES that mark a surface telling the story of its own becoming.
+
+High-precision PHRASES, never bare words. Bare common words — ``legacy``,
+``deprecated``, ``retired``, ``placeholder``, ``backward`` — have legitimate
+uses (a Keep-a-Changelog ``Deprecated`` heading, a documented deprecation
+policy, a ``placeholder identity`` product feature) and are deliberately NOT
+denylisted. Only the narrative phrase forms ("replaces the legacy …",
+"coming soon", "AI-generated") are flagged, so the matcher catches the
+story-of-becoming without flagging the dictionary word. The forbidden phrases
+live in the package-relative denylist data file, never in this module.
+
+Scope. Corpus-level standalone validator. Walks the working tree under the
+supplied root and inspects ONLY shipped public surfaces: the repository
+root ``README.md`` and every ``*.md`` / ``*.mdx`` under
+``site/content/docs/``. Developer-only surfaces (rules, commands,
+matchers, plans, adapter modules) are out of scope — their process
+vocabulary is load-bearing, exactly as the plain-language boundary draws it.
+
+Detection. Each denylist phrase is matched case-insensitively. Pure-alpha
+phrases anchor at word boundaries; punctuation- or space-bearing phrases
+match as escaped literals. Matches inside fenced code blocks (triple
+backtick) are excluded — docs legitimately quote a forbidden phrase inside a
+sample or tool-output fence.
+
+Posture. The result carries an advisory flag, honoring apothem's agnostic
+gate posture; CI opts into strict enforcement separately. Exits 0 when zero
+findings across every in-scope file; exits 2 on any finding.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "freshness-token-grep"
+RULE_ANCHOR: Final[str] = "rules/freshness-facade.md"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# The denylist data file is package-relative: the conformity package ships
+# beside its ``schemas/`` sibling in both the repo checkout
+# (``src/apothem/{conformity,schemas}``) and the installed tree, so one parent
+# hop reaches it in either shape. The data file holds the forbidden phrases so
+# this module never names them.
+_DENYLIST_PATH: Final[Path] = (
+    Path(__file__).resolve().parents[1] / "schemas" / "freshness-token-denylist.txt"
+)
+
+# Shipped-surface scope. The root README and the documentation tree are the
+# user-facing release facade the freshness mandate holds to the current-version
+# bar.
+_README_FILENAME: Final[str] = "README.md"
+_DOCS_DIR: Final[str] = "site/content/docs"
+_TEXT_SUFFIXES: Final[frozenset[str]] = frozenset({".md", ".mdx"})
+
+# Fenced code-block delimiter — a line whose first non-whitespace content is
+# ```. Opening and closing fences both match; the scanner toggles state.
+_CODE_FENCE_RE: Final[re.Pattern[str]] = re.compile(r"^[ \t]*```")
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One freshness-narrative phrase on a shipped public surface."""
+
+    surface: str
+    kind: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated walk result for a single corpus sweep."""
+
+    grep: str
+    root: str
+    files_inspected: int
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "files_inspected": self.files_inspected,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+            "advisory": True,
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _load_tokens() -> list[str]:
+    """Parse the denylist data file into a list of forbidden phrases.
+
+    Pre-conditions: the package-relative denylist file exists.
+    Post-conditions: returns every non-empty, non-comment line, stripped.
+    """
+    try:
+        raw = _DENYLIST_PATH.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    tokens: list[str] = []
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        tokens.append(stripped)
+    return tokens
+
+
+def _compile_tokens(tokens: list[str]) -> re.Pattern[str] | None:
+    """Compile the denylist into one case-insensitive alternation regex.
+
+    Pure-alphabetic phrases anchor at word boundaries (``\\bphrase\\b``) so a
+    larger word is not flagged. Space- or punctuation-bearing phrases are
+    escaped literals — word boundaries do not apply cleanly across spaces and
+    ``-`` characters. Returns None when the denylist is empty. Longer phrases
+    are ordered first so the alternation prefers the most specific match.
+    """
+    if not tokens:
+        return None
+    alternatives: list[str] = []
+    for token in sorted(tokens, key=len, reverse=True):
+        if token.isalpha():
+            alternatives.append(r"\b" + re.escape(token) + r"\b")
+        else:
+            alternatives.append(re.escape(token))
+    return re.compile(r"(?i)(?:" + "|".join(alternatives) + r")")
+
+
+def _is_in_scope(rel_posix: str) -> bool:
+    """Return True iff a relative POSIX path is a shipped public surface.
+
+    In scope: the repository root ``README.md`` and any ``.md`` / ``.mdx``
+    under ``site/content/docs/``. Every other path is out of scope.
+    """
+    if rel_posix == _README_FILENAME:
+        return True
+    return rel_posix.startswith(_DOCS_DIR + "/")
+
+
+def _scan_file(path: Path, rel_posix: str, pattern: re.Pattern[str]) -> list[Finding]:
+    """Scan one text file; return findings outside fenced code blocks."""
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    findings: list[Finding] = []
+    inside_fence = False
+    for line_index, line in enumerate(content.splitlines(), start=1):
+        if _CODE_FENCE_RE.match(line):
+            inside_fence = not inside_fence
+            continue
+        if inside_fence:
+            continue
+        for match in pattern.finditer(line):
+            findings.append(
+                Finding(
+                    surface=rel_posix,
+                    kind="freshness-token",
+                    detail=f"line {line_index}: '{match.group()}'",
+                )
+            )
+    return findings
+
+
+def check(root: Path) -> GrepResult:
+    """Walk the corpus under ``root``; flag freshness-narrative phrases.
+
+    Pre-conditions: ``root`` is the repository root (or an arbitrary subtree).
+    Post-conditions: ``result.passed`` is True iff every shipped public
+    surface contained zero denylisted phrases outside fenced code blocks.
+    """
+    tokens = _load_tokens()
+    pattern = _compile_tokens(tokens)
+    findings: list[Finding] = []
+    inspected = 0
+    root_resolved = root.resolve()
+    if pattern is not None:
+        for suffix in sorted(_TEXT_SUFFIXES):
+            for path in root.rglob(f"*{suffix}"):
+                if not path.is_file():
+                    continue
+                try:
+                    rel_posix = path.resolve().relative_to(root_resolved).as_posix()
+                except ValueError:
+                    continue
+                if not _is_in_scope(rel_posix):
+                    continue
+                inspected += 1
+                findings.extend(_scan_file(path, rel_posix, pattern))
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        files_inspected=inspected,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    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/frontmatter_grep.py

@@ -0,0 +1,274 @@
+# SPDX-License-Identifier: MIT
+
+"""Validate per-artifact-class YAML frontmatter against required-key sets.
+
+Why this enforcement exists. Spec section 4.2 ratifies that every
+artifact carries YAML frontmatter delimited by ``---`` lines, with
+required-key sets that vary per artifact class (rules, agents, skills,
+commands, output styles each carry their own minimum schema). This
+validator extends the grep family with frontmatter checks; per-class
+JSON Schemas feed this validator's strict-mode.
+
+Detection strategy. The validator reads a file, locates the leading
+``---``-delimited frontmatter block, parses the YAML, and checks the
+required-key set for the inferred artifact class (inferred by the
+file's path under rules/, agents/, skills/, commands/, output-styles/).
+A missing required key, an unparseable YAML block, or an absent
+frontmatter block on a class that requires one is a finding. Frontmatter
+keys must use kebab-case per spec section 4.1; non-kebab-case keys are
+flagged. Schema-presence-driven strict-mode activates when per-class
+JSON Schemas exist at ``frontmatter/<class>.json`` inside the
+``schemas/`` directory shipped beside this package (one parent hop above
+this module in both the repo-checkout and installed layouts); until then
+the validator runs the baseline required-key check.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+# Required-key sets per artifact class, derived from the canonical
+# frontmatter schema declared at site/content/docs/reference/frontmatter-schema.mdx and the
+# minimum schemas observed across the rules/ + agents/ + skills/ +
+# commands/ + output-styles/ corpora.
+REQUIRED_KEYS: Final[dict[str, frozenset[str]]] = {
+    "rules": frozenset({"name", "description", "alwaysApply"}),
+    "agents": frozenset({"name", "description"}),
+    "skills": frozenset({"name", "description"}),
+    "commands": frozenset({"name", "description"}),
+    "output-styles": frozenset({"name", "description"}),
+    "hooks-messages": frozenset({"description"}),
+}
+
+# Kebab-case key shape per spec section 4.1. Frontmatter keys are
+# matched against this regex; uppercase / underscore / camelCase keys
+# are findings. The harness honors an explicit allow-list for keys
+# that originated in pre-ratification artifacts and are preserved by
+# sibling-convergence per host-discovery.
+KEBAB_KEY_RE: Final[re.Pattern[str]] = re.compile(r"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$")
+KEY_ALLOW_LIST: Final[frozenset[str]] = frozenset(
+    {
+        # Path-filter keys observed across rules/ predate the
+        # kebab-case ratification.
+        "pathFilter",
+        "alwaysApply",
+        # Argument-hint and disable-model-invocation surface inside
+        # commands frontmatter; both predate ratification.
+        "argument-hint",
+        "disable-model-invocation",
+        "allowed-tools",
+        # User-invocability flag on skills; camelCase predates the
+        # kebab-case ratification and is uniform across the skill corpus
+        # (preserved by sibling-convergence per host-discovery).
+        "userInvocable",
+        # Tools-list key on agents.
+        "tools",
+        "model",
+    }
+)
+
+FRONTMATTER_DELIMITER: Final[str] = "---"
+GREP_NAME: Final[str] = "frontmatter-grep"
+RULE_ANCHOR: Final[str] = (
+    "the per-class frontmatter JSON Schemas (src/apothem/schemas/)"
+)
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    path: str | None
+    artifact_class: str | None
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "path": self.path,
+            "artifact-class": self.artifact_class,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _infer_class(path: Path) -> str | None:
+    """Infer the artifact class from the path's top-level directory."""
+    parts = path.parts
+    if "rules" in parts:
+        return "rules"
+    if "agents" in parts:
+        return "agents"
+    if "skills" in parts:
+        return "skills"
+    if "commands" in parts:
+        return "commands"
+    if "output-styles" in parts:
+        return "output-styles"
+    if "hooks" in parts and "messages" in parts:
+        return "hooks-messages"
+    return None
+
+
+def _extract_frontmatter(content: str) -> tuple[str | None, int]:
+    """Return (frontmatter-yaml, body-start-line) or (None, 0).
+
+    The established sibling-convention across commands/, agents/, skills/,
+    rules/, and output-styles/ places the canonical authorship-header
+    banner (an HTML comment block opened with ``<!--`` and closed with
+    ``-->``) before the YAML frontmatter, separated by a blank line. The
+    extractor therefore tolerates a leading region of blank lines plus
+    one optional HTML-comment block before locating the opening ``---``
+    delimiter. Within the comment region, the closing ``-->`` may sit on
+    its own line or share a line with trailing content; the extractor
+    advances past the first line whose stripped contents end with
+    ``-->``.
+    """
+    lines = content.splitlines()
+    index = 0
+
+    while index < len(lines) and not lines[index].strip():
+        index += 1
+
+    if index < len(lines) and lines[index].lstrip().startswith("<!--"):
+        first_comment_line = lines[index].strip()
+        if first_comment_line.endswith("-->") and first_comment_line != "<!--":
+            index += 1
+        else:
+            index += 1
+            while index < len(lines) and not lines[index].strip().endswith("-->"):
+                index += 1
+            if index < len(lines):
+                index += 1
+
+    while index < len(lines) and not lines[index].strip():
+        index += 1
+
+    if index >= len(lines) or lines[index].strip() != FRONTMATTER_DELIMITER:
+        return None, 0
+
+    open_index = index
+    for close_index in range(open_index + 1, len(lines)):
+        if lines[close_index].strip() == FRONTMATTER_DELIMITER:
+            return (
+                "\n".join(lines[open_index + 1 : close_index]),
+                close_index + 1,
+            )
+    return None, 0
+
+
+def _parse_keys(yaml_block: str) -> list[str]:
+    """Extract top-level keys from the YAML block via line-shape parsing.
+
+    The validator does not depend on PyYAML; the frontmatter's surface
+    is shallow (top-level scalar keys plus the occasional list value)
+    and the shape can be read from the first column of each line. Keys
+    inside nested mappings or lists are intentionally excluded — only
+    top-level keys count toward the required-set check.
+    """
+    keys: list[str] = []
+    for raw in yaml_block.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if raw[0].isspace() or raw.startswith("-"):
+            continue
+        if ":" not in raw:
+            continue
+        key = raw.split(":", 1)[0].strip()
+        if key:
+            keys.append(key)
+    return keys
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Validate frontmatter for the inferred artifact class."""
+    findings: list[Finding] = []
+    artifact_class = _infer_class(path) if path is not None else None
+    yaml_block, _ = _extract_frontmatter(content)
+
+    if yaml_block is None:
+        if artifact_class is not None:
+            findings.append(
+                Finding(
+                    detail=(
+                        f"frontmatter block absent on artifact-class "
+                        f"{artifact_class!r}; required by spec section 4.2"
+                    )
+                )
+            )
+        return GrepResult(
+            grep=GREP_NAME,
+            path=str(path) if path is not None else None,
+            artifact_class=artifact_class,
+            passed=not findings,
+            findings=findings,
+        )
+
+    keys = _parse_keys(yaml_block)
+    keyset = set(keys)
+
+    if artifact_class is not None:
+        required = REQUIRED_KEYS.get(artifact_class, frozenset())
+        missing = required - keyset
+        for key in sorted(missing):
+            findings.append(
+                Finding(
+                    detail=(
+                        f"required key {key!r} missing from "
+                        f"{artifact_class!r} frontmatter"
+                    )
+                )
+            )
+
+    for key in keys:
+        if key in KEY_ALLOW_LIST:
+            continue
+        if not KEBAB_KEY_RE.match(key):
+            findings.append(
+                Finding(
+                    detail=(
+                        f"frontmatter key {key!r} is not kebab-case (spec section 4.1)"
+                    )
+                )
+            )
+
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(path) if path is not None else None,
+        artifact_class=artifact_class,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> tuple[str, Path | None]:
+    if len(argv) >= 2 and argv[1] != STDIN_FLAG:
+        path = Path(argv[1])
+        return path.read_text(encoding="utf-8"), path
+    return sys.stdin.read(), None
+
+
+def _main(argv: list[str]) -> int:
+    content, path = _read_input(argv)
+    result = check(content, path)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))