@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/gitattributes_presence_grep.py

@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify the repo-root ``.gitattributes`` carries the canonical contract.
+
+Why this validator exists. The supply-chain release contract requires
+the repository to ship a ``.gitattributes`` file at its root that pins
+line-ending normalisation (``* text=auto eol=lf``), declares binary
+asset classes (``*.png binary``, ``*.jpg`` or ``*.jpeg`` ``binary``),
+preserves SVG as text for diffability (``*.svg text``), and applies
+``export-ignore`` to ephemeral / developer-only trees (``.plans/``,
+``tests/``, ``.github/``) so source-archive consumers receive only
+shippable content. Absence of any one of these contract elements is a
+supply-chain drift class that this validator surfaces at the
+pre-emission gate.
+
+Detection strategy. Open ``<root>/.gitattributes``; tokenise on lines
+(comments and blanks ignored); look for each required pattern via a
+permissive whitespace-tolerant regex. Each missing element produces a
+finding whose ``drift_class`` field names the violation. The validator
+does NOT attempt to enforce ordering, repetition, or stylistic
+consistency — only presence.
+
+Exit semantics. Exits 0 (PASS) when every required contract element is
+present; exits 2 (FAIL) on any drift class. The exit-2 convention
+matches the conformity-gate orchestrator's ``EXIT_FAIL`` constant.
+"""
+
+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] = "gitattributes-presence-grep"
+RULE_ANCHOR: Final[str] = "supply-chain .gitattributes contract"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+GITATTRIBUTES_FILENAME: Final[str] = ".gitattributes"
+
+# Drift class identifiers — surface in findings so the operator can
+# route each failure to its remediation path without re-parsing prose.
+DRIFT_FILE_ABSENT: Final[str] = "file-absent"
+DRIFT_MISSING_TEXT_EOL_BASELINE: Final[str] = "missing-text-eol-baseline"
+DRIFT_MISSING_BINARY_DECLARATION: Final[str] = "missing-binary-declaration"
+DRIFT_MISSING_EXPORT_IGNORE: Final[str] = "missing-export-ignore"
+
+# Required-element regexes. Each pattern is whitespace-tolerant so the
+# operator may freely align columns; none require a specific order.
+# ``re.MULTILINE`` lets ``^`` match at line starts so commented-out
+# variants (lines beginning with ``#``) are not matched.
+_TEXT_EOL_RE: Final[re.Pattern[str]] = re.compile(
+    r"^\s*\*\s+text=auto\s+eol=lf\b",
+    re.MULTILINE,
+)
+_PNG_BINARY_RE: Final[re.Pattern[str]] = re.compile(
+    r"^\s*\*\.png\s+binary\b",
+    re.MULTILINE,
+)
+# Accept either ``*.jpg`` or ``*.jpeg`` as the JPEG declaration.
+_JPG_BINARY_RE: Final[re.Pattern[str]] = re.compile(
+    r"^\s*\*\.jpe?g\s+binary\b",
+    re.MULTILINE,
+)
+_SVG_TEXT_RE: Final[re.Pattern[str]] = re.compile(
+    r"^\s*\*\.svg\s+text\b",
+    re.MULTILINE,
+)
+
+# Export-ignore patterns. Accept both trailing-slash (``.plans/``) and
+# bare-name (``.plans``) glob forms — git honours both.
+_EXPORT_IGNORE_PATHS: Final[tuple[str, ...]] = (".plans", "tests", ".github")
+
+
+def _export_ignore_re(path: str) -> re.Pattern[str]:
+    """Compile a permissive export-ignore matcher for *path*.
+
+    Accepts ``.plans/ export-ignore`` and ``.plans export-ignore`` forms,
+    plus glob variants like ``.plans/** export-ignore``. The leading
+    anchor is ``^`` under MULTILINE so commented lines do not match.
+    """
+    escaped = re.escape(path)
+    return re.compile(
+        rf"^\s*{escaped}(?:/\S*|/?)\s+export-ignore\b",
+        re.MULTILINE,
+    )
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One missing-contract-element occurrence."""
+
+    drift_class: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    root: str
+    path: str | None
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "path": self.path,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def check(root: Path) -> GrepResult:
+    """Inspect ``<root>/.gitattributes`` and return a structured verdict.
+
+    Pre-conditions: *root* names a directory the operator wishes to
+    audit (typically the repository root).
+    Post-conditions: ``result.passed`` is True iff the file exists and
+    contains every required contract element; otherwise ``findings``
+    enumerates each drift class.
+    """
+    path = root / GITATTRIBUTES_FILENAME
+    if not path.is_file():
+        finding = Finding(
+            drift_class=DRIFT_FILE_ABSENT,
+            detail=(
+                f"{GITATTRIBUTES_FILENAME} is absent at repository root "
+                f"({path}); the supply-chain contract requires it"
+            ),
+        )
+        return GrepResult(
+            grep=GREP_NAME,
+            root=str(root),
+            path=str(path),
+            passed=False,
+            findings=[finding],
+        )
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        finding = Finding(
+            drift_class=DRIFT_FILE_ABSENT,
+            detail=f"{GITATTRIBUTES_FILENAME} unreadable at {path}: {exc}",
+        )
+        return GrepResult(
+            grep=GREP_NAME,
+            root=str(root),
+            path=str(path),
+            passed=False,
+            findings=[finding],
+        )
+
+    findings: list[Finding] = []
+
+    if not _TEXT_EOL_RE.search(content):
+        findings.append(
+            Finding(
+                drift_class=DRIFT_MISSING_TEXT_EOL_BASELINE,
+                detail=(
+                    "baseline `* text=auto eol=lf` declaration missing; "
+                    "line-ending normalisation is unpinned"
+                ),
+            )
+        )
+
+    if not _PNG_BINARY_RE.search(content):
+        findings.append(
+            Finding(
+                drift_class=DRIFT_MISSING_BINARY_DECLARATION,
+                detail="`*.png binary` declaration missing",
+            )
+        )
+
+    if not _JPG_BINARY_RE.search(content):
+        findings.append(
+            Finding(
+                drift_class=DRIFT_MISSING_BINARY_DECLARATION,
+                detail="`*.jpg binary` (or `*.jpeg binary`) declaration missing",
+            )
+        )
+
+    if not _SVG_TEXT_RE.search(content):
+        findings.append(
+            Finding(
+                drift_class=DRIFT_MISSING_BINARY_DECLARATION,
+                detail=(
+                    "`*.svg text` declaration missing; SVG must be kept "
+                    "diffable as text rather than treated as binary"
+                ),
+            )
+        )
+
+    for ignore_path in _EXPORT_IGNORE_PATHS:
+        if not _export_ignore_re(ignore_path).search(content):
+            findings.append(
+                Finding(
+                    drift_class=DRIFT_MISSING_EXPORT_IGNORE,
+                    detail=(
+                        f"`{ignore_path}/ export-ignore` declaration "
+                        "missing; ephemeral / developer-only tree would "
+                        "leak into source archives"
+                    ),
+                )
+            )
+
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        path=str(path),
+        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/harden_runner_grep.py

@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify every workflow job opens with a conformant harden-runner step.
+
+Why this enforcement exists. The workflow hardening contract requires
+every GitHub Actions workflow at ``.github/workflows/*.yml`` to invoke
+``step-security/harden-runner@v2`` as the FIRST step of every job and
+configure ``egress-policy: block`` (steady-state) or ``egress-policy:
+audit`` (initial deployment phase). The action installs network-egress
+controls before any user-supplied step runs; placing it second leaves a
+window where checkout / dependency-fetch / arbitrary action steps can
+exfiltrate before the egress policy engages.
+
+Detection strategy. The validator walks ``<root>/.github/workflows/`` for
+``*.yml`` and ``*.yaml`` files, parses each via ``yaml.safe_load``, and
+for every job in ``jobs:`` inspects the ``steps[]`` sequence. Three drift
+classes surface:
+
+- ``harden-runner-action-absent`` — no step in the job uses
+  ``step-security/harden-runner``.
+- ``harden-runner-not-first-step`` — the action is present but not
+  ``steps[0]``.
+- ``egress-policy-too-permissive`` — the step's ``with:`` block omits
+  ``egress-policy`` or sets it to a value other than ``block`` / ``audit``
+  (``log`` and any other free-form value are rejected; the canonical
+  taxonomy is closed).
+
+Workflows-absent tolerance. When ``<root>/.github/workflows/`` does not
+exist (a repository in its earliest scaffold state), the validator exits
+0 with ``not-yet-materialised: true`` so the gate does not block bootstrap
+work that hasn't yet authored CI.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+import yaml
+
+# A bare ``${{ inputs.<name> }}`` expression — the reusable-workflow shape
+# where egress-policy is parameterized by a workflow_call input.
+_INPUTS_EXPR: Final[re.Pattern[str]] = re.compile(
+    r"^\$\{\{\s*inputs\.([A-Za-z_][\w-]*)\s*\}\}$"
+)
+
+GREP_NAME: Final[str] = "harden-runner-grep"
+RULE_ANCHOR: Final[str] = "harden-runner egress baseline"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+WORKFLOWS_SUBPATH: Final[str] = ".github/workflows"
+ACTION_NAME: Final[str] = "step-security/harden-runner"
+CONFORMANT_EGRESS_POLICIES: Final[frozenset[str]] = frozenset({"block", "audit"})
+
+DRIFT_ABSENT: Final[str] = "harden-runner-action-absent"
+DRIFT_NOT_FIRST: Final[str] = "harden-runner-not-first-step"
+DRIFT_PERMISSIVE: Final[str] = "egress-policy-too-permissive"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One job's harden-runner drift."""
+
+    workflow: str
+    job: str
+    drift: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    root: str
+    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,
+            "passed": self.passed,
+            "not-yet-materialised": self.not_yet_materialised,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _uses_harden_runner(uses_value: object) -> bool:
+    """Return True iff a ``uses:`` value references step-security/harden-runner."""
+    if not isinstance(uses_value, str):
+        return False
+    # Strip any ``@<ref>`` suffix so ``@v2``, ``@v2.10``, and a 40-char SHA
+    # pin all match identically.
+    name = uses_value.split("@", 1)[0].strip()
+    return name == ACTION_NAME
+
+
+def _workflow_call_inputs(document: dict[object, object]) -> dict[object, object]:
+    """Return the ``on.workflow_call.inputs`` mapping, or empty when absent.
+
+    GitHub Actions ``on:`` is coerced by PyYAML (YAML 1.1) to the boolean
+    key ``True``; handle both the string ``"on"`` and boolean ``True`` keys.
+    """
+    on_block = document.get("on", document.get(True))
+    if not isinstance(on_block, dict):
+        return {}
+    workflow_call = on_block.get("workflow_call")
+    if not isinstance(workflow_call, dict):
+        return {}
+    inputs = workflow_call.get("inputs")
+    return inputs if isinstance(inputs, dict) else {}
+
+
+def _resolve_egress(egress: object, inputs: dict[object, object]) -> object:
+    """Resolve a ``${{ inputs.<name> }}`` egress-policy to the input default.
+
+    A reusable workflow may parameterize egress-policy via a ``workflow_call``
+    input; the conformant value is then the input's declared ``default``. A
+    literal egress value (not an inputs expression) is returned unchanged.
+    """
+    if not isinstance(egress, str):
+        return egress
+    match = _INPUTS_EXPR.match(egress.strip())
+    if match is None:
+        return egress
+    spec = inputs.get(match.group(1))
+    if isinstance(spec, dict) and "default" in spec:
+        return spec["default"]
+    return egress
+
+
+def _inspect_job(
+    workflow: str,
+    job_name: str,
+    job: object,
+    workflow_inputs: dict[object, object] | None = None,
+) -> list[Finding]:
+    """Return drift findings for one job; empty list when conformant."""
+    if not isinstance(job, dict):
+        return []
+    # Reusable-workflow callers have no inline steps; harden-runner is
+    # step-level and cannot apply. A job declaring a top-level ``uses:``
+    # field and lacking a ``steps:`` field is structurally exempt.
+    if "uses" in job and "steps" not in job:
+        return []
+    steps = job.get("steps")
+    if not isinstance(steps, list) or not steps:
+        return [
+            Finding(
+                workflow=workflow,
+                job=job_name,
+                drift=DRIFT_ABSENT,
+                detail="job has no steps[] sequence",
+            )
+        ]
+    # Locate harden-runner step(s).
+    hr_indices = [
+        i
+        for i, step in enumerate(steps)
+        if isinstance(step, dict) and _uses_harden_runner(step.get("uses"))
+    ]
+    if not hr_indices:
+        return [
+            Finding(
+                workflow=workflow,
+                job=job_name,
+                drift=DRIFT_ABSENT,
+                detail=f"no step uses {ACTION_NAME}",
+            )
+        ]
+    first_idx = hr_indices[0]
+    findings: list[Finding] = []
+    if first_idx != 0:
+        first_step = steps[0]
+        first_uses = first_step.get("uses") if isinstance(first_step, dict) else None
+        findings.append(
+            Finding(
+                workflow=workflow,
+                job=job_name,
+                drift=DRIFT_NOT_FIRST,
+                detail=(
+                    f"{ACTION_NAME} appears at steps[{first_idx}]; "
+                    f"steps[0] uses={first_uses!r}"
+                ),
+            )
+        )
+    # Inspect the egress-policy on the first harden-runner step.
+    hr_step = steps[first_idx]
+    with_block = hr_step.get("with") if isinstance(hr_step, dict) else None
+    egress = with_block.get("egress-policy") if isinstance(with_block, dict) else None
+    # A reusable workflow may parameterize egress-policy via a workflow_call
+    # input (``${{ inputs.<name> }}``); resolve it to the input's declared
+    # default so a conformant default is not flagged as too-permissive.
+    egress = _resolve_egress(egress, workflow_inputs or {})
+    if egress is None:
+        findings.append(
+            Finding(
+                workflow=workflow,
+                job=job_name,
+                drift=DRIFT_PERMISSIVE,
+                detail="egress-policy key absent from with: block",
+            )
+        )
+    elif not isinstance(egress, str) or egress not in CONFORMANT_EGRESS_POLICIES:
+        findings.append(
+            Finding(
+                workflow=workflow,
+                job=job_name,
+                drift=DRIFT_PERMISSIVE,
+                detail=(
+                    f"egress-policy={egress!r}; expected one of "
+                    f"{sorted(CONFORMANT_EGRESS_POLICIES)}"
+                ),
+            )
+        )
+    return findings
+
+
+def _inspect_workflow(path: Path, root: Path) -> list[Finding]:
+    """Parse a workflow file; return drift findings across all its jobs."""
+    rel = str(path.relative_to(root)).replace("\\", "/")
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return [
+            Finding(
+                workflow=rel,
+                job="<workflow>",
+                drift=DRIFT_ABSENT,
+                detail=f"unreadable workflow: {exc}",
+            )
+        ]
+    try:
+        document = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        return [
+            Finding(
+                workflow=rel,
+                job="<workflow>",
+                drift=DRIFT_ABSENT,
+                detail=f"YAML parse error: {exc}",
+            )
+        ]
+    if not isinstance(document, dict):
+        return [
+            Finding(
+                workflow=rel,
+                job="<workflow>",
+                drift=DRIFT_ABSENT,
+                detail="workflow root is not a mapping",
+            )
+        ]
+    jobs = document.get("jobs")
+    if not isinstance(jobs, dict) or not jobs:
+        # A workflow with no jobs has nothing to harden; skip silently.
+        return []
+    workflow_inputs = _workflow_call_inputs(document)
+    findings: list[Finding] = []
+    for job_name, job in jobs.items():
+        findings.extend(_inspect_workflow_job(rel, job_name, job, workflow_inputs))
+    return findings
+
+
+def _inspect_workflow_job(
+    workflow: str,
+    job_name: object,
+    job: object,
+    workflow_inputs: dict[object, object] | None = None,
+) -> list[Finding]:
+    name = str(job_name) if not isinstance(job_name, str) else job_name
+    return _inspect_job(workflow, name, job, workflow_inputs)
+
+
+def check_root(root: Path) -> GrepResult:
+    """Walk ``<root>/.github/workflows/`` and audit every workflow.
+
+    Pre-conditions: ``root`` is the repository root.
+    Post-conditions: ``result.passed`` is True iff every job in every
+    discovered workflow opens with ``step-security/harden-runner@v2`` (or
+    a pinned variant) and declares ``egress-policy: block`` / ``audit``.
+    When the workflows directory is absent, returns passed=True with
+    ``not_yet_materialised=True``.
+    """
+    workflows_dir = root / WORKFLOWS_SUBPATH
+    if not workflows_dir.is_dir():
+        return GrepResult(
+            grep=GREP_NAME,
+            root=str(root),
+            passed=True,
+            not_yet_materialised=True,
+        )
+    findings: list[Finding] = []
+    candidates = sorted([*workflows_dir.glob("*.yml"), *workflows_dir.glob("*.yaml")])
+    for workflow_path in candidates:
+        findings.extend(_inspect_workflow(workflow_path, root))
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _main(argv: list[str]) -> int:
+    root = Path(argv[1]) if len(argv) >= 2 else Path.cwd()
+    result = check_root(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/hedging_grep.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag hedging vocabulary in prescriptive contexts.
+
+Why this enforcement exists. The definitiveness rule M8 requires every
+prescription to be unconditional or to carry the conditions that branch
+its outcomes — silent hedges ("usually", "typically", "should probably")
+soften prescriptions before they land, leaving the reader to guess at the
+binding form. The mechanical row in the pre-emission gate scans for the
+closed vocabulary and surfaces every occurrence. The operator triages
+each hit on one of the three paths declared in the definitiveness rule:
+promote to unconditional form with conditions named, demote to an
+explicit conditional with branches enumerated, or remove the prescription
+entirely (option set is underdetermined; route to inquiry).
+
+Scope. Hits inside fenced code blocks (between triple-backtick fences) and
+inside inline-code spans (single-backtick delimited) are excluded. Fenced
+blocks typically quote external material, sample inputs, or commands;
+inline-code spans typically cite a forbidden token meta-linguistically (a
+doc that names the hedging vocabulary it forbids) rather than hedge a
+prescription. Hits in prose are reported with line numbers; the operator
+decides whether each hit is a genuine hedge or a quotation.
+"""
+
+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 closed hedging vocabulary per the definitiveness rule M8 §Hedging
+# vocabulary — eliminate or qualify. Word-boundary regex prevents partial
+# matches inside larger words ("usually" matches; "unusually" does not).
+HEDGING_VOCABULARY: Final[tuple[str, ...]] = (
+    "maybe",
+    "might",
+    "could",
+    "should probably",
+    "usually",
+    "generally",
+    "typically",
+    "mostly",
+    "often",
+    "perhaps",
+    "possibly",
+    "somewhat",
+    "fairly",
+    "roughly",
+    "broadly",
+)
+
+# Compile a single combined regex to scan once per line. The `(?i)` makes the
+# match case-insensitive — `Usually` at sentence start hedges identically.
+HEDGING_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?i)\b(?:" + "|".join(re.escape(w) for w in HEDGING_VOCABULARY) + r")\b"
+)
+
+# Fenced code block delimiter. The standard Markdown form opens and closes
+# with a triple backtick at column 0 (or with whitespace prefix in some
+# dialects); we use the column-0 form per the host's discovered Markdown
+# convention.
+CODE_FENCE_RE: Final[re.Pattern[str]] = re.compile(r"^```")
+
+# Inline-code span: a single-backtick-delimited run on one line. A hedge word
+# quoted inside backticks is a meta-linguistic citation (a doc naming the
+# vocabulary it forbids), not a prescription that hedges, so these spans are
+# blanked before the prose scan. The column-preserving blank mirrors the
+# inline-code exclusion in binding_reciprocity_grep.
+INLINE_CODE_RE: Final[re.Pattern[str]] = re.compile(r"`[^`]*`")
+
+GREP_NAME: Final[str] = "hedging-grep"
+RULE_ANCHOR: Final[str] = "M8 definitiveness §Hedging"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One hedge occurrence outside a fenced code block."""
+
+    line: int
+    match: str
+    context: str
+    rule: str = RULE_ANCHOR
+
+
+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 iff zero hedges were found
+    outside fenced code blocks and inline-code spans.
+    """
+    findings: list[Finding] = []
+    inside_fence = False
+    for line_index, 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
+        # Blank inline-code spans (same-length spaces preserve columns) so a
+        # hedge word cited inside backticks — a doc that forbids the `usually`
+        # vocabulary — is read as a citation, not a prescription that hedges.
+        scanned = INLINE_CODE_RE.sub(lambda m: " " * len(m.group(0)), line)
+        for match in HEDGING_RE.finditer(scanned):
+            findings.append(
+                Finding(
+                    line=line_index,
+                    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))