@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/orphan_output_grep.py

@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag artifacts emitted to non-canonical locations or without provenance.
+
+Why this enforcement exists. The canonical-layout rule M12 + the
+systemicity rule M14 require every emitted artifact to land at a
+ratified output directory and to declare its producer (provenance
+frontmatter, header comment, or registry entry). Orphan outputs —
+artifacts the host's reference graph does not consume — fragment the
+project surface and resist maintenance. The pre-emission gate's
+mechanical bar 12 (M12 canonical layout) catches two failure modes: location drift (artifact
+not under any ratified output directory) and provenance absence (no
+frontmatter / header / registry entry naming the producer).
+
+Detection strategy. The grep accepts a content body and an artifact
+path. It checks the path against the ratified output-directory list
+discovered from the host's existing layout (`src/`, `lib/`, `tests/`,
+`site/`, `.github/`, plus the host-discovery default harness-config
+subtree — for example `~/.claude/` for the Claude Code harness).
+When the path is outside every ratified directory, that is one finding. When the content body lacks a provenance marker
+(YAML frontmatter `provenance:` field, comment-line `provenance:`
+marker, or a `Bindings` section binding the artifact to its producer),
+that is another finding.
+"""
+
+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
+
+# Ratified output-directory prefixes. The set is conservative — it covers
+# the canonical surfaces the host project emits to. New artifact classes
+# either land at one of these prefixes or surface an inquiry to the
+# operator before silent installation.
+RATIFIED_OUTPUT_PREFIXES: Final[tuple[str, ...]] = (
+    "src/",
+    "lib/",
+    "tests/",
+    "site/",
+    ".github/",
+    "rules/",
+    "skills/",
+    "commands/",
+    "agents/",
+    "hooks/",
+    "tools/",
+    "scripts/",
+    "assets/",
+    "schemas/",
+    "templates/",
+    "memory/",
+    ".plans/",
+    "output-styles/",
+    "statuslines/",
+)
+
+# Root-level singletons that are canonical by filename, not by directory
+# prefix. README, LICENSE, CHANGELOG, CONTRIBUTING etc. land at the repo
+# root by universal convention. Harness-config singleton settings.json
+# lives at the harness config root for every integrated harness —
+# `~/.claude/settings.json` for Claude Code, `.vscode/settings.json` for
+# VS Code, `~/.cursor/settings.json` for Cursor, etc. — and is canonical
+# by basename per the module docstring's harness-config-subtree clause.
+RATIFIED_ROOT_FILENAMES = frozenset(
+    {
+        "README.md",
+        "LICENSE",
+        "LICENSE.md",
+        "LICENSE.txt",
+        "CHANGELOG.md",
+        "CONTRIBUTING.md",
+        "SECURITY.md",
+        "SUPPORT.md",
+        "CODE_OF_CONDUCT.md",
+        "GOVERNANCE.md",
+        "AUTHORS.md",
+        "NOTICE",
+        "NOTICE.md",
+        "NOTICE.txt",
+        "CODEOWNERS",
+        "FUNDING.yml",
+        "CITATION.cff",
+        ".gitignore",
+        ".gitattributes",
+        ".editorconfig",
+        "pyproject.toml",
+        "setup.py",
+        "setup.cfg",
+        "requirements.txt",
+        "package.json",
+        "Cargo.toml",
+        "go.mod",
+        "Makefile",
+        "CLAUDE.md",
+        "settings.json",
+    }
+)
+
+# Provenance markers — any one of these in the content body satisfies
+# the M14 producer-attribution requirement. Source-language artifacts
+# satisfy provenance via the canonical SPDX authorship-header banner
+# enforced by `file-header-grep`; the SPDX-License-Identifier line is
+# the machine-readable producer-attribution marker per the REUSE
+# specification, mirroring how Markdown artifacts satisfy it via the
+# `## Bindings` section or frontmatter `description:` field.
+PROVENANCE_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?:provenance:|## Bindings\b|^---\s*$.*?\bdescription:|SPDX-License-Identifier:)",
+    re.MULTILINE | re.DOTALL,
+)
+
+# Trivial-by-extension carve-out: data files (`.json`, `.yml`, `.yaml`,
+# `.toml`) and lockfiles can satisfy provenance via their parent
+# package-manifest contract; per-file frontmatter is not required for
+# these classes.
+TRIVIAL_PROVENANCE_EXTENSIONS: Final[frozenset[str]] = frozenset(
+    {".json", ".yaml", ".yml", ".toml", ".lock", ".cfg", ".ini"}
+)
+
+# Trivial-by-basename carve-out: files whose format convention does not admit
+# a per-file provenance banner and whose provenance is satisfied structurally.
+# `.SRCINFO` is a machine-parseable manifest generated from `PKGBUILD` — a
+# banner would corrupt the parser's input. `py.typed` is the PEP 561 inline-
+# type marker: conventionally zero-byte (a banner would defeat the marker), and
+# its provenance is the package contract that ships it — the `apothem`
+# `[tool.setuptools.package-data]` entry in `pyproject.toml`.
+TRIVIAL_PROVENANCE_BASENAMES: Final[frozenset[str]] = frozenset(
+    {".SRCINFO", "py.typed"}
+)
+
+# Memory-index carve-out: the auto-memory convention defines `MEMORY.md` as a
+# frontmatter-free index — one index line per memory, no per-file frontmatter.
+# Its producer attribution is structural: it is the index every memory topic
+# file points back to, and the topic files it indexes carry their own
+# frontmatter. Requiring a provenance marker from the index itself is a
+# category error; a memory-index write would otherwise fail-close the harness's
+# per-project memory tree (the `MEMORY.md` write the operator makes at session
+# end has no frontmatter to satisfy `PROVENANCE_RE`).
+MEMORY_INDEX_BASENAMES: Final[frozenset[str]] = frozenset({"MEMORY.md"})
+
+GREP_NAME: Final[str] = "orphan-output-grep"
+RULE_ANCHOR: Final[str] = "M12 canonical-layout + M14 systemicity"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    issue: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+def _is_under_ratified_prefix(path: Path) -> bool:
+    """Return True iff the path is under a ratified prefix or is a root-level singleton."""
+    posix = path.as_posix()
+    if any(prefix in posix for prefix in RATIFIED_OUTPUT_PREFIXES):
+        return True
+    # Root-level canonical files (README, LICENSE, etc.) match by name.
+    return path.name in RATIFIED_ROOT_FILENAMES
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content + path; return a structured result."""
+    findings: list[Finding] = []
+    if path is not None and not _is_under_ratified_prefix(path):
+        findings.append(
+            Finding(
+                issue="non-canonical location",
+                detail=(
+                    f"path {path.as_posix()!r} is not under any ratified output "
+                    f"prefix; surface as an inquiry before emission"
+                ),
+            )
+        )
+    requires_provenance = path is None or (
+        path.suffix.lower() not in TRIVIAL_PROVENANCE_EXTENSIONS
+        and path.name not in TRIVIAL_PROVENANCE_BASENAMES
+        and path.name not in MEMORY_INDEX_BASENAMES
+    )
+    if requires_provenance and PROVENANCE_RE.search(content) is None:
+        findings.append(
+            Finding(
+                issue="provenance absent",
+                detail=(
+                    "content lacks a provenance marker (YAML `provenance:` field, "
+                    "header `## Bindings` section, or frontmatter description); "
+                    "the producer of this artifact is unrecorded"
+                ),
+            )
+        )
+    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/permissions_minimum_scope_grep.py

@@ -0,0 +1,299 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify every GitHub Actions workflow declares a minimum-scope ``permissions:`` block.
+
+Why this enforcement exists. GitHub Actions workflows inherit a
+default-broad permissions surface (``write-all`` on the repository
+token) unless they explicitly narrow it. A workflow that silently
+consumes the default scope hands every job the keys to the repository
+- contents write, packages write, deployments write, issues write -
+regardless of whether the job's actual work requires any of them. The
+minimum-scope discipline requires each workflow to declare a top-level
+``permissions:`` block enumerating only the scopes its jobs need; the
+default-broad surface is replaced with an audit-friendly,
+least-privilege grant.
+
+Detection. Walks ``<root>/.github/workflows/*.yml`` (and ``.yaml``).
+For each workflow:
+
+1. Verify a top-level ``permissions:`` key exists.
+2. Verify the block is NOT ``permissions: write-all`` (the over-scoped
+   default).
+3. Surface an advisory when ``contents: write`` is granted but no
+   push-style step is detected (heuristic for undocumented permission
+   elevation).
+
+Drift classes:
+
+- ``missing-top-level-permissions-block``
+- ``overscoped-permission`` (``write-all`` declared)
+- ``undocumented-permission-elevation`` (advisory; ``contents: write``
+  declared without an observable push step)
+
+Special case. When ``<root>/.github/workflows/`` does not exist, the
+validator exits 0 with ``not-yet-materialised: true`` so projects that
+have not yet introduced CI workflows are not blocked by the gate.
+
+Exit semantics. Exits 0 when every workflow carries a conformant
+permissions block; exits 2 with a JSON report listing per-workflow
+drift classes otherwise. Advisory-severity findings (the
+``undocumented-permission-elevation`` class) do NOT trigger exit 2 on
+their own — they surface in the JSON for operator review without
+blocking the gate.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Final
+
+import yaml
+
+GREP_NAME: Final[str] = "permissions-minimum-scope-grep"
+RULE_ANCHOR: Final[str] = "minimum-scope workflow permissions"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+SEVERITY_BLOCKING: Final[str] = "blocking"
+SEVERITY_ADVISORY: Final[str] = "advisory"
+
+# Drift class identifiers surfaced in finding payloads.
+DRIFT_MISSING: Final[str] = "missing-top-level-permissions-block"
+DRIFT_OVERSCOPED: Final[str] = "overscoped-permission"
+DRIFT_UNDOCUMENTED_ELEVATION: Final[str] = "undocumented-permission-elevation"
+
+# Heuristic tokens that suggest a workflow performs a push-style write to
+# the repository — when any of these appears in a step's ``run`` body or
+# in a third-party action ``uses:`` reference, the ``contents: write``
+# grant is considered justified and the advisory does not fire.
+_PUSH_STEP_TOKENS: Final[tuple[str, ...]] = (
+    "git push",
+    "git commit",
+    "git tag",
+    "peter-evans/create-pull-request",
+    "stefanzweifel/git-auto-commit-action",
+    "ad-m/github-push-action",
+    "softprops/action-gh-release",
+    "actions/create-release",
+    "ncipollo/release-action",
+)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One workflow-level permissions drift."""
+
+    workflow: str
+    drift_class: str
+    severity: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated walk result for a single workflows-directory sweep."""
+
+    grep: str
+    root: str
+    workflows_dir: str
+    workflow_count: int
+    passed: bool
+    not_yet_materialised: bool = False
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "workflows_dir": self.workflows_dir,
+            "workflow_count": self.workflow_count,
+            "not_yet_materialised": self.not_yet_materialised,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _iter_workflow_files(workflows_dir: Path) -> list[Path]:
+    """Return every ``*.yml`` / ``*.yaml`` file at the workflows root.
+
+    The walk is non-recursive: GitHub Actions only picks up workflows
+    that sit directly under ``.github/workflows/``; nested directories
+    are ignored by the platform and so by this validator.
+    """
+    files: list[Path] = []
+    for pattern in ("*.yml", "*.yaml"):
+        files.extend(workflows_dir.glob(pattern))
+    return sorted(files)
+
+
+def _has_push_step(parsed: dict[str, Any]) -> bool:
+    """Heuristic: does any job step suggest a push-style write?
+
+    Inspects every job's ``steps`` list for a ``run:`` body containing
+    a push-style command, or a ``uses:`` reference to a known
+    push-style action. The heuristic is intentionally permissive — a
+    false negative (advisory fires when push is actually present)
+    surfaces in the JSON for operator triage rather than blocking.
+    """
+    jobs = parsed.get("jobs")
+    if not isinstance(jobs, dict):
+        return False
+    for job in jobs.values():
+        if not isinstance(job, dict):
+            continue
+        steps = job.get("steps")
+        if not isinstance(steps, list):
+            continue
+        for step in steps:
+            if not isinstance(step, dict):
+                continue
+            run_body = step.get("run")
+            uses_ref = step.get("uses")
+            haystack_parts: list[str] = []
+            if isinstance(run_body, str):
+                haystack_parts.append(run_body)
+            if isinstance(uses_ref, str):
+                haystack_parts.append(uses_ref)
+            haystack = "\n".join(haystack_parts).lower()
+            if any(token.lower() in haystack for token in _PUSH_STEP_TOKENS):
+                return True
+    return False
+
+
+def _grants_contents_write(permissions: object) -> bool:
+    """Return True when the ``permissions:`` block grants ``contents: write``."""
+    if not isinstance(permissions, dict):
+        return False
+    contents = permissions.get("contents")
+    return isinstance(contents, str) and contents.strip().lower() == "write"
+
+
+def _classify_workflow(
+    workflow: Path,
+    parsed: dict[str, Any] | None,
+) -> list[Finding]:
+    """Classify a single workflow's permissions surface.
+
+    Returns the per-workflow finding list. An unparseable workflow
+    (YAML error, non-mapping root) yields a blocking finding under
+    ``missing-top-level-permissions-block`` because the validator
+    cannot prove the block exists.
+    """
+    rel = workflow.name
+    if parsed is None or not isinstance(parsed, dict):
+        return [
+            Finding(
+                workflow=rel,
+                drift_class=DRIFT_MISSING,
+                severity=SEVERITY_BLOCKING,
+                detail=(
+                    "workflow YAML did not parse as a mapping; cannot verify "
+                    "top-level permissions block"
+                ),
+            )
+        ]
+    if "permissions" not in parsed:
+        return [
+            Finding(
+                workflow=rel,
+                drift_class=DRIFT_MISSING,
+                severity=SEVERITY_BLOCKING,
+                detail=(
+                    "no top-level `permissions:` key; workflow inherits the "
+                    "default-broad GitHub Actions permissions surface "
+                    "(equivalent to write-all)"
+                ),
+            )
+        ]
+    permissions = parsed["permissions"]
+    findings: list[Finding] = []
+    if isinstance(permissions, str) and permissions.strip().lower() == "write-all":
+        findings.append(
+            Finding(
+                workflow=rel,
+                drift_class=DRIFT_OVERSCOPED,
+                severity=SEVERITY_BLOCKING,
+                detail=(
+                    "`permissions: write-all` grants the default-broad surface; "
+                    "replace with explicit per-scope grants (e.g. `contents: read`)"
+                ),
+            )
+        )
+    if _grants_contents_write(permissions) and not _has_push_step(parsed):
+        findings.append(
+            Finding(
+                workflow=rel,
+                drift_class=DRIFT_UNDOCUMENTED_ELEVATION,
+                severity=SEVERITY_ADVISORY,
+                detail=(
+                    "`contents: write` granted but no push-style step "
+                    "(git push / release-action / create-pull-request) "
+                    "was detected; verify the elevation is required"
+                ),
+            )
+        )
+    return findings
+
+
+def check(root: Path) -> GrepResult:
+    """Walk every workflow under ``<root>/.github/workflows/``.
+
+    Pre-conditions: ``root`` is the project root containing a
+    ``.github/workflows/`` directory (or not — the absence case is
+    tolerated). Post-conditions: ``result.passed`` is True iff every
+    workflow carries a top-level ``permissions:`` block that is not
+    ``write-all``; advisory findings do not affect ``passed``.
+    """
+    workflows_dir = root / ".github" / "workflows"
+    if not workflows_dir.is_dir():
+        return GrepResult(
+            grep=GREP_NAME,
+            root=str(root),
+            workflows_dir=str(workflows_dir),
+            workflow_count=0,
+            passed=True,
+            not_yet_materialised=True,
+            findings=[],
+        )
+    workflows = _iter_workflow_files(workflows_dir)
+    findings: list[Finding] = []
+    for workflow in workflows:
+        try:
+            raw = workflow.read_text(encoding="utf-8")
+            parsed = yaml.safe_load(raw)
+        except (OSError, UnicodeDecodeError, yaml.YAMLError):
+            parsed = None
+        findings.extend(_classify_workflow(workflow, parsed))
+    blocking = [f for f in findings if f.severity == SEVERITY_BLOCKING]
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        workflows_dir=str(workflows_dir),
+        workflow_count=len(workflows),
+        passed=not blocking,
+        not_yet_materialised=False,
+        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))