@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/brand_mark_grep.py

@@ -0,0 +1,272 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag brand-mark display/identifier form drift on brand-touched surfaces.
+
+Why this enforcement exists. The brand-mark convention sub-mandate (the
+display brand ``Apothem`` PascalCase versus the identifier
+``apothem`` lowercase) carries a per-surface canonical form: human-
+readable display surfaces render PascalCase; machine-resolved identifier
+surfaces honor ecosystem-normalized lowercase (PEP-503, URL conventions,
+package-manager naming). A wordmark spelled lowercase on a display
+surface, or a Python distribution name spelled PascalCase, is drift the
+M9 visual leverage + M14 sibling convergence + M3 ten-dimension
+consistency bars catch at the pre-emission gate.
+
+Detection strategy. Per-line scan over the brand-touched glob set. Each
+occurrence of ``\\b(apothem|Apothem)\\b`` is classified against two
+high-confidence pattern sets: an identifier-context set (URL paths,
+package-manager install commands, environment variables, file basenames,
+Python imports, suite folder, repo path) and a display-context set
+(Markdown H1 with brand-name, site-title metadata, frontmatter title:,
+alt-text, OG/Twitter meta-title, SVG title/desc). Drift findings emit
+only when the classification is high-confidence: PascalCase form on an
+identifier-context line, or lowercase form on a display-context line.
+Unclassified occurrences pass; the unclassified occurrences are cataloged in the operator's normalization review pass.
+
+Path filter. The matcher early-exits on out-of-scope paths so tooling,
+tests, rules, hooks, plan-suite scratch, and the ecosystem's own
+internal Markdown corpus are not inspected. In-scope paths are the
+brand-touched globs enumerated at ``IN_SCOPE_PREFIXES`` and
+``IN_SCOPE_FILENAMES``.
+"""
+
+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
+
+# Brand-mark occurrence regex. Word-boundary anchors prevent partial
+# matches inside identifiers like ``ahmed-g-gad/apothem-internals`` (which
+# remains a single match starting at the canonical token).
+BRAND_RE: Final[re.Pattern[str]] = re.compile(r"\b(apothem|Apothem)\b")
+
+# Identifier-context line patterns. When a line matches one of these,
+# the canonical form on that line is lowercase ``apothem``. A
+# PascalCase ``Apothem`` occurrence on such a line is identifier-on-
+# display-surface drift.
+IDENTIFIER_CONTEXT_PATTERNS: Final[tuple[re.Pattern[str], ...]] = tuple(
+    re.compile(pat, re.IGNORECASE)
+    for pat in (
+        # URL paths
+        r"github\.com/[\w-]+/apothem",
+        r"apothem\.ahmedgad\.com",
+        r"pypi\.org/project/apothem",
+        # Package-manager install commands
+        r"\bpip\s+install\s+\S*apothem",
+        r"\bbrew\s+install\s+\S*apothem",
+        r"\bscoop\s+install\s+\S*apothem",
+        r"\bwinget\s+install\s+\S*apothem",
+        r"\bpacman\s+-S\s+\S*apothem",
+        r"\b(apt|dnf|yum)\s+install\s+\S*apothem",
+        # CLI invocations
+        r"\$\s*apothem\b",
+        r"\bapothem\s+--",
+        # Python module references
+        r"\bimport\s+apothem\b",
+        r"\bfrom\s+apothem\b",
+        # Versioned/typed file basenames
+        r"\bapothem-v?\d",
+        r"\bapothem[_.]\d",
+        r"\bapothem\.(rb|json|ya?ml|toml|spec|whl|tar|deb|rpm)\b",
+        # Env-var prefix (upper-snake identifier form)
+        r"\bAPOTHEM_\w+",
+        # Suite folder path
+        r"/.plans/[\w-]*apothem",
+        # Repo path under owner
+        r"\bahmed-g-gad/[\w-]*apothem",
+        # PEP-621 distribution name field
+        r'^\s*name\s*=\s*"apothem"',
+        # Homebrew formula filename
+        r"/Formula/apothem",
+        # Scoop manifest filename
+        r"/bucket/apothem\.json",
+        # Winget package-identifier segment
+        r"ahmed-g-gad\.apothem",
+        # PKGBUILD pkgname
+        r"\bpkgname=apothem",
+        # Docker image
+        r"\bahmed-g-gad/apothem",
+    )
+)
+
+# Display-context line patterns. When a line matches one of these, the
+# canonical form on that line is PascalCase ``Apothem``. A lowercase
+# ``apothem`` occurrence on such a line (outside URL/identifier sub-
+# expressions also on the line) is display-form drift.
+DISPLAY_CONTEXT_PATTERNS: Final[tuple[re.Pattern[str], ...]] = tuple(
+    re.compile(pat)
+    for pat in (
+        # Markdown H1/H2 referencing the brand
+        r"^#{1,6}\s+.*(?:Apothem|apothem)",
+        # Site metadata fields
+        r"^\s*site_name\s*:",
+        r"^\s*site_description\s*:",
+        # YAML frontmatter title field
+        r'^\s*title\s*:\s*["\']?(?:Apothem|apothem)',
+        # alt-text attribute
+        r'\balt\s*=\s*["\'][^"\']*(?:Apothem|apothem)',
+        # SVG accessibility elements
+        r"<(?:title|desc|text)[^>]*>(?:Apothem|apothem)",
+        # OG / Twitter meta tags
+        r"\b(?:og:title|og:site_name|twitter:title|twitter:image:alt)\b",
+        # JSON-LD name field
+        r'"name"\s*:\s*"(?:Apothem|apothem)"',
+        # CLI banner H1 wording
+        r"\bApothem\s+v\d",
+        # Homebrew formula desc field
+        r'^\s*desc\s+"',
+        # PEP-621 description field
+        r'^\s*description\s*=\s*"',
+        # AUR pkgdesc / .deb Description / .rpm Summary
+        r"^\s*pkgdesc\s*=",
+        r"^\s*Description\s*:",
+        r"^\s*Summary\s*:",
+        # Winget ShortDescription / Description
+        r"^\s*(?:ShortDescription|Description|PackageName)\s*:",
+    )
+)
+
+# In-scope path prefixes (relative to project root). The matcher's
+# classification only fires when the inspected path starts with one of
+# these or matches one of the IN_SCOPE_FILENAMES bare basenames.
+IN_SCOPE_PREFIXES: Final[tuple[str, ...]] = (
+    "site/",
+    "assets/",
+    ".github/",
+    "bin/",
+)
+
+# In-scope bare filenames (root-level singletons).
+IN_SCOPE_FILENAMES: Final[frozenset[str]] = frozenset(
+    {
+        "README.md",
+        "CHANGELOG.md",
+        "SUPPORT.md",
+        "SECURITY.md",
+        "LICENSE",
+        "pyproject.toml",
+        "scripts/installer/install.sh",
+        "scripts/installer/install.ps1",
+        "scripts/installer/update.sh",
+        "scripts/installer/update.ps1",
+        "scripts/installer/uninstall.sh",
+        "scripts/installer/uninstall.ps1",
+    }
+)
+
+GREP_NAME: Final[str] = "brand-mark-grep"
+RULE_ANCHOR: Final[str] = (
+    "rules/plain-language.md (brand-mark display/identifier casing)"
+)
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+DISPLAY_FORM: Final[str] = "Apothem"
+IDENTIFIER_FORM: Final[str] = "apothem"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One brand-mark form-drift occurrence."""
+
+    line: int
+    match: str
+    drift: str  # "display-form-on-identifier-surface" | "identifier-form-on-display-surface"
+    context: str
+    rule: str = RULE_ANCHOR
+
+
+def _in_scope(path: Path | None) -> bool:
+    """Decide whether the path is a brand-touched surface.
+
+    Pre-conditions: `path` is the artifact's emission destination (or
+    None when scanning stdin without a target path).
+    Post-conditions: returns True iff the path matches an in-scope
+    prefix or an in-scope bare filename.
+    """
+    if path is None:
+        return True  # CLI use without a target path; classify by content alone.
+    # Normalize to forward-slash for cross-platform glob match.
+    rel = path.as_posix()
+    if path.name in IN_SCOPE_FILENAMES:
+        return True
+    for prefix in IN_SCOPE_PREFIXES:
+        if rel.startswith(prefix) or f"/{prefix}" in rel:
+            return True
+    return False
+
+
+def _classify(line: str, match_text: str) -> str | None:
+    """Return a drift label when the occurrence is high-confidence drift.
+
+    Returns None when the occurrence is acceptable or unclassifiable.
+    """
+    is_identifier_context = any(p.search(line) for p in IDENTIFIER_CONTEXT_PATTERNS)
+    is_display_context = any(p.search(line) for p in DISPLAY_CONTEXT_PATTERNS)
+
+    if is_identifier_context and not is_display_context:
+        # Lowercase form is canonical; PascalCase is drift.
+        if match_text == DISPLAY_FORM:
+            return "display-form-on-identifier-surface"
+        return None
+    if is_display_context and not is_identifier_context:
+        # PascalCase form is canonical; lowercase is drift.
+        if match_text == IDENTIFIER_FORM:
+            return "identifier-form-on-display-surface"
+        return None
+    # Mixed or unclassified: do not flag (catalog in normalization walk).
+    return None
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content for per-surface brand-mark form drift.
+
+    Pre-conditions: `content` is the artifact body about to be emitted;
+    `path` is its destination relative to the project root (or None for
+    stdin without a target).
+    Post-conditions: `result.passed` is True iff zero high-confidence
+    drift occurrences are found on in-scope paths.
+    """
+    if not _in_scope(path):
+        return GrepResult(
+            grep=GREP_NAME,
+            path=str(path) if path is not None else None,
+            passed=True,
+            findings=[],
+        )
+
+    findings: list[Finding] = []
+    inside_fence = False
+    for line_index, line in enumerate(content.splitlines(), start=1):
+        if line.startswith("```"):
+            inside_fence = not inside_fence
+            continue
+        if inside_fence:
+            continue
+        for occurrence in BRAND_RE.finditer(line):
+            drift = _classify(line, occurrence.group())
+            if drift is None:
+                continue
+            findings.append(
+                Finding(
+                    line=line_index,
+                    match=occurrence.group(),
+                    drift=drift,
+                    context=line.strip()[:200],
+                )
+            )
+    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/commented_out_code_grep.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag substantial commented-out code blocks left in source.
+
+Why this enforcement exists. The code-craft rule M13.1 forbids commented-
+out source code: source control is the canonical archive. Why-not-what
+comments are welcome; disabled logic is not. The pre-emission gate's
+mechanical bar 13 (M13 code craft) catches multi-line runs of comment-prefixed lines that
+contain code-shaped tokens and surfaces each block so the operator
+restores the code or deletes the dead block.
+
+Detection: a per-language comment-prefix table identifies the prefix; the
+grep accumulates consecutive prefixed lines whose stripped bodies match a
+code-shape heuristic (keywords, name=value, name(args), arrow operators).
+A run of three or more such lines is a finding; pure prose comments
+(headers, citations, why-not-what explanations) pass clean.
+"""
+
+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
+
+
+@dataclass(frozen=True)
+class CommentPrefix:
+    """One language's line-comment prefix and the file extensions it covers."""
+
+    label: str
+    prefix: str
+    extensions: tuple[str, ...]
+
+
+# Per-language line-comment prefixes. The set covers the languages the
+# host project commonly emits (Python, shell, YAML, TOML use `#`; the
+# C-family languages and JavaScript use `//`). The label is the language
+# name shown in the finding so the operator can route the cleanup.
+COMMENT_PREFIXES: Final[tuple[CommentPrefix, ...]] = (
+    CommentPrefix(
+        "hash-prefix (Python / shell / YAML / TOML / Ruby)",
+        "#",
+        (".py", ".sh", ".bash", ".ps1", ".yml", ".yaml", ".toml", ".rb"),
+    ),
+    CommentPrefix(
+        "slash-slash (JS / TS / Go / Rust / C / C++ / Java / Swift)",
+        "//",
+        (
+            ".js",
+            ".ts",
+            ".tsx",
+            ".jsx",
+            ".go",
+            ".rs",
+            ".c",
+            ".cpp",
+            ".h",
+            ".hpp",
+            ".java",
+            ".swift",
+            ".kt",
+        ),
+    ),
+)
+
+# Code-shaped-token signatures. A commented line whose stripped body
+# contains one of these patterns is treated as commented-out code rather
+# than prose. The set favors precision — common prose words don't match.
+CODE_SIGNATURE_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?:"
+    r"\b(?:def|class|import|from|return|if|elif|else|for|while|try|except|"
+    r"finally|with|lambda|async|await|yield|raise|assert)\b"
+    r"|\b(?:function|const|let|var|require|export|module|interface|type|"
+    r"struct|enum|impl|fn|pub|use|package)\b"
+    r"|[A-Za-z_]\w*\s*=\s*[^=]"  # `name = value` (not `==`)
+    r"|[A-Za-z_]\w*\s*\([^)]*\)"  # `name(args)`
+    r"|->|=>"  # arrow functions / type hints
+    r")"
+)
+
+# Minimum consecutive commented-code lines that constitute a block. Two-line
+# runs are typically a TODO + a code snippet; three or more is a definitive
+# block per the rule's intent.
+MIN_BLOCK_LINES: Final[int] = 3
+
+GREP_NAME: Final[str] = "commented-out-code-grep"
+RULE_ANCHOR: Final[str] = "M13.1 why-not-what comments"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One commented-out-code block occurrence."""
+
+    start_line: int
+    end_line: int
+    language: str
+    line_count: int
+    rule: str = RULE_ANCHOR
+
+
+def _select_prefix(path: Path | None) -> CommentPrefix:
+    """Return the comment prefix matching the file extension, or hash by default.
+
+    Stdin input has no extension — the hash prefix is the conservative default
+    since it covers the largest surface in this ecosystem.
+    """
+    if path is not None:
+        suffix = path.suffix.lower()
+        for entry in COMMENT_PREFIXES:
+            if suffix in entry.extensions:
+                return entry
+    return COMMENT_PREFIXES[0]
+
+
+def _is_commented_code(stripped_body: str) -> bool:
+    """Decide whether a commented line's body looks like code rather than prose."""
+    return CODE_SIGNATURE_RE.search(stripped_body) is not None
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content; return a structured result.
+
+    Pre-conditions: `content` is the source body about to be emitted.
+    Post-conditions: `result.passed` is True iff no run of
+    `MIN_BLOCK_LINES` or more consecutive commented lines contains
+    code-shaped tokens.
+    """
+    prefix = _select_prefix(path)
+    findings: list[Finding] = []
+    run_start: int | None = None
+    run_length = 0
+
+    def flush(end_line: int) -> None:
+        if run_start is not None and run_length >= MIN_BLOCK_LINES:
+            findings.append(
+                Finding(
+                    start_line=run_start,
+                    end_line=end_line,
+                    language=prefix.label,
+                    line_count=run_length,
+                )
+            )
+
+    for line_index, line in enumerate(content.splitlines(), start=1):
+        stripped = line.lstrip()
+        is_comment = stripped.startswith(prefix.prefix)
+        body = stripped[len(prefix.prefix) :].strip() if is_comment else ""
+        if not is_comment or not _is_commented_code(body):
+            flush(line_index - 1)
+            run_start = None
+            run_length = 0
+            continue
+        if run_start is None:
+            run_start = line_index
+            run_length = 1
+        else:
+            run_length += 1
+    if run_start is not None:
+        flush(run_start + run_length - 1)
+    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/completion_claim_grep.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag unsupported completion / guarantee claims in cohort prose.
+
+Why this enforcement exists. Spec §4.2 (Output Honesty, Validity, and
+Determinism) demands evidence that requirements are truly complete, including
+checks against "done" claims that would require a rerun to prove. A command,
+agent, or skill that promises an absolute, unconditional outcome — "guaranteed
+to pass", "always works", "100% complete", "cannot fail" — asserts a result the
+prose cannot back with evidence; the claim reads as honest completion when it is
+actually an unprovable guarantee. This matcher detects a closed set of such
+absolute-guarantee phrases so the dishonest-completion pattern surfaces before
+emission.
+
+What this is NOT. This is a deliberately narrow guard against *absolute,
+unconditional* guarantees, not a ban on the words "done" or "complete".
+Evidence-gated completion language ("complete when every verification passes",
+"not complete until zero findings remain", "declare complete once the suite is
+verified") is correct and is not matched. Distinguishing a merely-unsupported
+"done" from an evidence-gated one requires judgment beyond a mechanical grep;
+that broader class is documented as out of scope per the spec's
+"detected or documented as out of scope" acceptance, and this grep covers the
+mechanically-detectable absolute-guarantee subset.
+
+Scope. Only cohort prose (`.md` under commands / agents / skills / rules /
+output-styles / hooks messages) is scanned; code, schemas, and plan-suite
+artifacts are skipped. Files that define this discipline (quoting the phrases as
+anti-pattern examples) are excluded by path, and hits inside fenced code blocks
+are excluded — a fenced block quotes commands or anti-pattern examples rather
+than carrying the artifact's own directive prose (mirroring hedging_grep).
+"""
+
+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
+
+# Closed set of absolute / unconditional completion-or-guarantee claims. Each is
+# unprovable in directive prose: proving it would require a rerun, and even then
+# the universal quantifier ("always", "never", "100%", "cannot") cannot be
+# discharged. The patterns are anchored to the guarantee structure to keep the
+# false-positive rate near zero.
+_CLAIM_PATTERNS: Final[tuple[tuple[str, re.Pattern[str]], ...]] = (
+    (
+        "guaranteed-outcome",
+        re.compile(r"guaranteed to (?:pass|work|succeed|complete)", re.IGNORECASE),
+    ),
+    (
+        "absolute-percentage",
+        re.compile(
+            r"100%\s+(?:complete|guaranteed|certain|reliable|done|airtight)",
+            re.IGNORECASE,
+        ),
+    ),
+    ("cannot-fail", re.compile(r"\bcannot (?:fail|possibly fail)\b", re.IGNORECASE)),
+    ("will-never-fail", re.compile(r"\bwill never (?:fail|break)\b", re.IGNORECASE)),
+    (
+        "always-succeeds",
+        re.compile(r"\balways (?:passes|works|succeeds)\b", re.IGNORECASE),
+    ),
+    ("never-fails", re.compile(r"\bnever (?:fails|breaks)\b", re.IGNORECASE)),
+    (
+        "definitely-works",
+        re.compile(r"\bdefinitely (?:works|passes|complete)\b", re.IGNORECASE),
+    ),
+)
+
+# Cohort-prose directories whose `.md` files carry directive / output prose.
+_COHORT_DIRS: Final[tuple[str, ...]] = (
+    "commands",
+    "agents",
+    "skills",
+    "rules",
+    "output-styles",
+    "hooks",
+)
+
+# Files that define the completion-honesty discipline and quote the banned
+# phrases as anti-pattern examples; excluded so the definition is not a finding.
+_EXCLUDED_BASENAMES: Final[frozenset[str]] = frozenset(
+    {
+        "completion_claim_grep.py",
+    }
+)
+
+# Fenced code block delimiter (triple backtick at column 0), mirroring
+# hedging_grep.CODE_FENCE_RE. A claim inside a fenced block is a quoted command
+# or anti-pattern example, not the artifact's own prescriptive prose, so it is
+# excluded from the scan.
+_CODE_FENCE_RE: Final[re.Pattern[str]] = re.compile(r"^```")
+
+GREP_NAME: Final[str] = "completion-claim-grep"
+RULE_ANCHOR: Final[str] = "rules/session-closure.md (verifiable-close output honesty)"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One unsupported-completion-claim occurrence."""
+
+    line: int
+    kind: str
+    text: str
+    rule: str = RULE_ANCHOR
+
+
+def _in_scope(path: Path | None) -> bool:
+    """Return True when *path* is cohort prose subject to the scan.
+
+    A None path (stdin) is in scope so direct invocations are checked; a
+    concrete path must be a `.md` under a cohort directory and not excluded.
+    """
+    if path is None:
+        return True
+    if path.suffix.lower() != ".md":
+        return False
+    if path.name in _EXCLUDED_BASENAMES:
+        return False
+    parts = set(path.parts)
+    return any(directory in parts for directory in _COHORT_DIRS)
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan *content* for absolute-guarantee completion claims.
+
+    Pre-conditions: *content* is the artifact body about to be emitted; *path*
+    is its destination (used for cohort-scope restriction and exclusion).
+    Post-conditions: ``result.passed`` is True when no absolute-guarantee phrase
+    from the closed set appears, or when *path* is out of scope.
+    """
+    if not _in_scope(path):
+        return GrepResult(grep=GREP_NAME, path=_path_str(path), passed=True)
+
+    findings: list[Finding] = []
+    inside_fence = False
+    for line_number, line in enumerate(content.splitlines(), start=1):
+        if _CODE_FENCE_RE.match(line):
+            # Toggle fence state — opening and closing fences both match.
+            inside_fence = not inside_fence
+            continue
+        if inside_fence:
+            continue
+        for kind, pattern in _CLAIM_PATTERNS:
+            match = pattern.search(line)
+            if match:
+                findings.append(
+                    Finding(line=line_number, kind=kind, text=match.group(0))
+                )
+    return GrepResult(
+        grep=GREP_NAME,
+        path=_path_str(path),
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _path_str(path: Path | None) -> str | None:
+    return str(path) if path is not None else None
+
+
+if __name__ == "__main__":
+    sys.exit(run_grep(check, sys.argv))