code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/rules/corpus_runner.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+import os
+import signal
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- fixed argv, isolated local lint processes only.
+import threading
+import time
+from typing import TYPE_CHECKING, Final
+
+from sarj_standards.libs.corpus.snapshot import selected_files, snapshot_inventory, verify_inventory
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import BinaryIO
+
+    from sarj_standards.libs.corpus import CorpusSource
+
+_SAFE_ENVIRONMENT: Final = frozenset(
+    {"HOME", "LANG", "LC_ALL", "LC_CTYPE", "PATH", "SYSTEMDRIVE", "SYSTEMROOT", "TMPDIR", "VIRTUAL_ENV"}
+)
+_MAX_BATCH_SIZE = 1_000
+_DEFAULT_MAX_OUTPUT_BYTES = 1_048_576
+_MAX_OUTPUT_BYTES = 8 * 1_048_576
+_MAX_ARGV_BYTES = 64 * 1024
+_DEFAULT_MAX_FILES_PER_CORPUS = 50_000
+_DEFAULT_MAX_BATCHES = 1_000
+_READ_SIZE = 65_536
+
+
+@dataclass(frozen=True, slots=True)
+class CorpusBatchResult:
+    corpus: str
+    ordinal: int
+    files: int
+    returncode: int
+    stdout_lines: int
+    stderr_lines: int
+    elapsed: timedelta
+    stdout_bytes: int = 0
+    stderr_bytes: int = 0
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class IsolatedCorpusReport:
+    batches: tuple[CorpusBatchResult, ...]
+
+    @property
+    def files(self) -> int:
+        return sum(batch.files for batch in self.batches)
+
+    @property
+    def stdout_lines(self) -> int:
+        return sum(batch.stdout_lines for batch in self.batches)
+
+    @property
+    def elapsed(self) -> timedelta:
+        return sum((batch.elapsed for batch in self.batches), start=timedelta())
+
+
+class CorpusLintError(RuntimeError):
+    """A corpus batch timed out or the linter failed to execute."""
+
+
+@dataclass(frozen=True, slots=True)
+class _StreamSummary:
+    retained_bytes: int
+    total_bytes: int
+    lines: int
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _ProcessResult:
+    returncode: int
+    stdout: _StreamSummary
+    stderr: _StreamSummary
+
+
+def run_isolated_corpora(
+    sources: tuple[CorpusSource, ...],
+    command: tuple[str, ...],
+    *,
+    batch_size: int = 250,
+    timeout: timedelta = timedelta(minutes=2),
+    max_output_bytes: int = _DEFAULT_MAX_OUTPUT_BYTES,
+    total_timeout: timedelta = timedelta(minutes=15),
+    max_files_per_corpus: int = _DEFAULT_MAX_FILES_PER_CORPUS,
+    max_batches: int = _DEFAULT_MAX_BATCHES,
+    accepted_returncodes: frozenset[int] = frozenset({0, 1}),
+) -> IsolatedCorpusReport:
+    if not sources:
+        msg = "isolated corpus evaluation requires at least one corpus"
+        raise ValueError(msg)
+    if not command or any(not argument for argument in command):
+        msg = "isolated corpus evaluation requires a non-empty command"
+        raise ValueError(msg)
+    if not 1 <= batch_size <= _MAX_BATCH_SIZE:
+        msg = f"batch size must be between 1 and {_MAX_BATCH_SIZE}"
+        raise ValueError(msg)
+    if timeout <= timedelta():
+        msg = "corpus batch timeout must be positive"
+        raise ValueError(msg)
+    if not 1 <= max_output_bytes <= _MAX_OUTPUT_BYTES:
+        msg = f"corpus batch output limit must be between 1 and {_MAX_OUTPUT_BYTES} bytes"
+        raise ValueError(msg)
+    if total_timeout <= timedelta():
+        msg = "corpus total timeout must be positive"
+        raise ValueError(msg)
+    if max_files_per_corpus <= 0 or max_batches <= 0:
+        msg = "corpus file and batch limits must be positive"
+        raise ValueError(msg)
+    if not accepted_returncodes:
+        msg = "accepted return codes must not be empty"
+        raise ValueError(msg)
+
+    results: list[CorpusBatchResult] = []
+    deadline = time.monotonic() + total_timeout.total_seconds()
+    for source in sources:
+        verified, files = verify_inventory(source)
+        if len(files) > max_files_per_corpus:
+            msg = f"corpus {source.report_name} exceeds the {max_files_per_corpus}-file evaluation limit"
+            raise CorpusLintError(msg)
+        batches = argv_batches(files, command, batch_size=batch_size)
+        if len(results) + len(batches) > max_batches:
+            msg = f"corpus evaluation exceeds the {max_batches}-batch limit"
+            raise CorpusLintError(msg)
+        for ordinal, batch in enumerate(batches, start=1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                msg = f"corpus evaluation exceeded {total_timeout.total_seconds():g}s total"
+                raise CorpusLintError(msg)
+            results.append(
+                _run_batch(
+                    source,
+                    command,
+                    batch,
+                    ordinal=ordinal,
+                    timeout=min(timeout, timedelta(seconds=remaining)),
+                    max_output_bytes=max_output_bytes,
+                    accepted_returncodes=accepted_returncodes,
+                )
+            )
+        try:
+            if selected_files(source) != files:
+                msg = f"corpus {source.report_name} changed during evaluation"
+                raise CorpusLintError(msg)
+            after = snapshot_inventory(source, files)
+        except (OSError, ValueError) as error:
+            msg = f"corpus {source.report_name} changed during evaluation"
+            raise CorpusLintError(msg) from error
+        if after.digest != verified.digest or after.revision != verified.revision:
+            msg = f"corpus {source.report_name} changed during evaluation"
+            raise CorpusLintError(msg)
+    return IsolatedCorpusReport(tuple(results))
+
+
+def argv_batches(
+    files: tuple[Path, ...],
+    command: tuple[str, ...],
+    *,
+    batch_size: int,
+) -> tuple[tuple[Path, ...], ...]:
+    base_bytes = sum(len(os.fsencode(argument)) + 1 for argument in command)
+    if base_bytes >= _MAX_ARGV_BYTES:
+        msg = "corpus linter command exceeds the argv byte budget"
+        raise CorpusLintError(msg)
+    batches: list[tuple[Path, ...]] = []
+    current: list[Path] = []
+    current_bytes = base_bytes
+    for path in files:
+        argument_bytes = len(os.fsencode(str(path))) + 1
+        if current and (len(current) >= batch_size or current_bytes + argument_bytes > _MAX_ARGV_BYTES):
+            batches.append(tuple(current))
+            current = []
+            current_bytes = base_bytes
+        if current_bytes + argument_bytes > _MAX_ARGV_BYTES:
+            msg = "one corpus path exceeds the argv byte budget"
+            raise CorpusLintError(msg)
+        current.append(path)
+        current_bytes += argument_bytes
+    if current:
+        batches.append(tuple(current))
+    return tuple(batches)
+
+
+def _run_batch(
+    source: CorpusSource,
+    command: tuple[str, ...],
+    files: tuple[Path, ...],
+    *,
+    ordinal: int,
+    timeout: timedelta,
+    max_output_bytes: int,
+    accepted_returncodes: frozenset[int],
+) -> CorpusBatchResult:
+    relative_files = tuple(path.relative_to(source.root).as_posix() for path in files if path.is_file())
+    if not relative_files:
+        msg = f"corpus {source.report_name} batch {ordinal} contains no existing files"
+        raise CorpusLintError(msg)
+    environment = {
+        name: value
+        for name, value in os.environ.items()  # ruff: ignore[banned-api] -- intentionally discard hook-local state.
+        if name in _SAFE_ENVIRONMENT
+    }
+    started = time.monotonic()
+    try:
+        completed = _run_process(
+            (*command, *relative_files),
+            cwd=source.root,
+            env=environment,
+            timeout=timeout,
+            max_output_bytes=max_output_bytes,
+        )
+    except subprocess.TimeoutExpired as error:
+        msg = f"corpus {source.report_name} batch {ordinal} exceeded {timeout.total_seconds():g}s"
+        raise CorpusLintError(msg) from error
+    except OSError as error:
+        msg = f"corpus {source.report_name} batch {ordinal} failed to execute"
+        raise CorpusLintError(msg) from error
+    elapsed = timedelta(seconds=time.monotonic() - started)
+    if completed.stdout.truncated or completed.stderr.truncated:
+        msg = f"corpus {source.report_name} batch {ordinal} exceeded the output limit"
+        raise CorpusLintError(msg)
+    if completed.returncode not in accepted_returncodes:
+        msg = f"corpus {source.report_name} batch {ordinal} exited with {completed.returncode}"
+        raise CorpusLintError(msg)
+    return CorpusBatchResult(
+        corpus=source.report_name,
+        ordinal=ordinal,
+        files=len(relative_files),
+        returncode=completed.returncode,
+        stdout_lines=completed.stdout.lines,
+        stderr_lines=completed.stderr.lines,
+        elapsed=elapsed,
+        stdout_bytes=completed.stdout.total_bytes,
+        stderr_bytes=completed.stderr.total_bytes,
+        stdout_truncated=completed.stdout.truncated,
+        stderr_truncated=completed.stderr.truncated,
+    )
+
+
+def _run_process(
+    argv: tuple[str, ...],
+    *,
+    cwd: Path,
+    env: dict[str, str],
+    timeout: timedelta,
+    max_output_bytes: int,
+) -> _ProcessResult:
+    deadline = time.monotonic() + timeout.total_seconds()
+    process = subprocess.Popen(  # ruff: ignore[subprocess-without-shell-equals-true] -- argv is never interpreted by a shell.
+        argv,
+        cwd=cwd,
+        env=env,
+        shell=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        start_new_session=os.name == "posix",
+    )
+    stdout = process.stdout
+    stderr = process.stderr
+    if stdout is None or stderr is None:  # pragma: no cover - PIPE guarantees both streams.
+        process.kill()
+        msg = "corpus process did not expose output pipes"
+        raise OSError(msg)
+
+    summaries: list[_StreamSummary | None] = [None, None]
+    exceeded = threading.Event()
+    threads = (
+        threading.Thread(target=_drain_stream, args=(stdout, max_output_bytes, exceeded, summaries, 0), daemon=True),
+        threading.Thread(target=_drain_stream, args=(stderr, max_output_bytes, exceeded, summaries, 1), daemon=True),
+    )
+    for thread in threads:
+        thread.start()
+    try:
+        returncode = _wait_for_process(process, exceeded, deadline, argv, timeout)
+    except subprocess.TimeoutExpired:
+        _terminate_process_group(process)
+        _ = process.wait()
+        for thread in threads:
+            thread.join()
+        raise
+
+    for thread in threads:
+        thread.join(max(0.0, deadline - time.monotonic()))
+    if any(thread.is_alive() for thread in threads):
+        _terminate_process_group(process)
+        for thread in threads:
+            thread.join()
+        raise subprocess.TimeoutExpired(argv, timeout.total_seconds())
+
+    stdout_summary, stderr_summary = summaries
+    if stdout_summary is None or stderr_summary is None:  # pragma: no cover - threads always assign on EOF.
+        msg = "corpus process output could not be summarized"
+        raise OSError(msg)
+    return _ProcessResult(returncode, stdout_summary, stderr_summary)
+
+
+def _wait_for_process(
+    process: subprocess.Popen[bytes],
+    exceeded: threading.Event,
+    deadline: float,
+    argv: tuple[str, ...],
+    timeout: timedelta,
+) -> int:
+    while process.poll() is None and not exceeded.is_set():
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise subprocess.TimeoutExpired(argv, timeout.total_seconds())
+        try:
+            _ = process.wait(timeout=min(0.05, remaining))
+        except subprocess.TimeoutExpired:
+            continue
+    if exceeded.is_set() and process.poll() is None:
+        _terminate_process_group(process)
+    return process.wait()
+
+
+def _drain_stream(
+    stream: BinaryIO,
+    max_output_bytes: int,
+    exceeded: threading.Event,
+    summaries: list[_StreamSummary | None],
+    index: int,
+) -> None:
+    retained_bytes = 0
+    total_bytes = 0
+    newline_count = 0
+    has_trailing_content = False
+    truncated = False
+    try:
+        while chunk := stream.read(_READ_SIZE):
+            total_bytes += len(chunk)
+            newline_count += chunk.count(b"\n")
+            has_trailing_content = not chunk.endswith(b"\n")
+            remaining = max_output_bytes - retained_bytes
+            if remaining > 0:
+                retained_bytes += min(len(chunk), remaining)
+            if len(chunk) > remaining:
+                truncated = True
+                exceeded.set()
+                break
+    finally:
+        stream.close()
+    summaries[index] = _StreamSummary(
+        retained_bytes,
+        total_bytes,
+        newline_count + int(has_trailing_content),
+        truncated,
+    )
+
+
+def _terminate_process_group(process: subprocess.Popen[bytes]) -> None:
+    if os.name == "posix":
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            return
+    else:  # pragma: no cover - CI exercises POSIX process-group cleanup.
+        process.kill()

sarj_standards/libs/rules/evaluation.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import StrEnum
+from typing import TYPE_CHECKING, Protocol
+
+from sarj_standards.libs.corpus import CorpusSnapshot
+
+from .contracts import EvaluationCase, ExpectedOutcome, Finding, RuleProblem
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class RuleEvaluator(Protocol):
+    def __call__(self, case: EvaluationCase, /) -> Sequence[Finding]: ...
+
+
+class PromotionDecision(StrEnum):
+    REJECT = "reject"
+    WARN = "warn"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationThresholds:
+    max_false_positives: int = 0
+    max_false_negatives: int = 0
+    minimum_cases_for_error: int = 20
+    minimum_positives_for_error: int = 1
+    minimum_negatives_for_error: int = 1
+
+    def __post_init__(self) -> None:
+        if (
+            min(
+                self.max_false_positives,
+                self.max_false_negatives,
+                self.minimum_cases_for_error,
+                self.minimum_positives_for_error,
+                self.minimum_negatives_for_error,
+            )
+            < 0
+        ):
+            msg = "evaluation thresholds must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class CaseEvaluation:
+    case_id: str
+    path: str
+    expected: ExpectedOutcome
+    findings: tuple[Finding, ...]
+
+    @property
+    def matched(self) -> bool:
+        return bool(self.findings)
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationEvidence:
+    corpora: tuple[CorpusSnapshot, ...]
+    sample_method: str
+    elapsed: timedelta
+    baseline: timedelta
+    maximum_slowdown: float = 1.25
+
+    def __post_init__(self) -> None:
+        if not self.corpora or not all(corpus.verified for corpus in self.corpora) or not self.sample_method.strip():
+            msg = "evaluation evidence requires verified corpora and a sampling method"
+            raise ValueError(msg)
+        if self.elapsed < timedelta() or self.baseline <= timedelta() or self.maximum_slowdown <= 0:
+            msg = "evaluation timings require a positive baseline and slowdown budget"
+            raise ValueError(msg)
+
+    @property
+    def within_performance_budget(self) -> bool:
+        return self.elapsed <= self.baseline * self.maximum_slowdown
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationReport:
+    problem_key: str
+    rule_id: str
+    cases: tuple[CaseEvaluation, ...]
+    thresholds: EvaluationThresholds
+    evidence: EvaluationEvidence | None = None
+
+    @property
+    def true_positives(self) -> int:
+        return sum(case.expected is ExpectedOutcome.MATCH and case.matched for case in self.cases)
+
+    @property
+    def true_negatives(self) -> int:
+        return sum(case.expected is ExpectedOutcome.NO_MATCH and not case.matched for case in self.cases)
+
+    @property
+    def false_positives(self) -> int:
+        return sum(case.expected is ExpectedOutcome.NO_MATCH and case.matched for case in self.cases)
+
+    @property
+    def false_negatives(self) -> int:
+        return sum(case.expected is ExpectedOutcome.MATCH and not case.matched for case in self.cases)
+
+    @property
+    def duplicate_locations(self) -> tuple[tuple[str, int, int], ...]:
+        duplicates: list[tuple[str, int, int]] = []
+        for case in self.cases:
+            seen: set[tuple[int, int]] = set()
+            for finding in case.findings:
+                location = (finding.line, finding.column)
+                if location in seen:
+                    duplicates.append((case.case_id, *location))
+                seen.add(location)
+        return tuple(duplicates)
+
+    @property
+    def decision(self) -> PromotionDecision:
+        if (
+            self.false_positives > self.thresholds.max_false_positives
+            or self.false_negatives > self.thresholds.max_false_negatives
+            or self.duplicate_locations
+            or not self.cases
+        ):
+            return PromotionDecision.REJECT
+        if self.false_positives or self.false_negatives:
+            return PromotionDecision.WARN
+        positives = self.true_positives + self.false_negatives
+        negatives = self.true_negatives + self.false_positives
+        if (
+            len(self.cases) < self.thresholds.minimum_cases_for_error
+            or positives < self.thresholds.minimum_positives_for_error
+            or negatives < self.thresholds.minimum_negatives_for_error
+            or self.evidence is None
+            or not self.evidence.within_performance_budget
+        ):
+            return PromotionDecision.WARN
+        return PromotionDecision.ERROR
+
+
+def evaluate(
+    problem: RuleProblem,
+    rule_id: str,
+    cases: Sequence[EvaluationCase],
+    evaluator: RuleEvaluator,
+    *,
+    thresholds: EvaluationThresholds | None = None,
+    evidence: EvaluationEvidence | None = None,
+) -> EvaluationReport:
+    unsupported = [case.report_id for case in cases if case.language not in problem.languages]
+    if unsupported:
+        msg = f"cases use languages outside the problem: {', '.join(unsupported)}"
+        raise ValueError(msg)
+    outcomes: list[CaseEvaluation] = []
+    for index, case in enumerate(cases, start=1):
+        findings = tuple(evaluator(case))
+        wrong = sorted({finding.rule_id for finding in findings if finding.rule_id != rule_id})
+        if wrong:
+            msg = f"candidate {rule_id} returned findings for: {', '.join(wrong)}"
+            raise ValueError(msg)
+        outcomes.append(
+            CaseEvaluation(
+                f"<private:{index}>" if case.private else case.report_id,
+                case.report_path,
+                case.expected,
+                _report_findings(case, findings),
+            )
+        )
+    return EvaluationReport(problem.key, rule_id, tuple(outcomes), thresholds or EvaluationThresholds(), evidence)
+
+
+def _report_findings(case: EvaluationCase, findings: Sequence[Finding]) -> tuple[Finding, ...]:
+    if not case.private:
+        return tuple(findings)
+    return tuple(Finding(finding.rule_id, finding.line, finding.column, "<private-finding>") for finding in findings)

sarj_standards/libs/setup/__init__.py

@@ -0,0 +1,4 @@
+from .repository import SetupPlan, apply_setup, plan_setup
+
+
+__all__ = ["SetupPlan", "apply_setup", "plan_setup"]

sarj_standards/libs/setup/repository.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from sarj_standards.libs.adoption.lifecycle import Command, execute
+from sarj_standards.libs.repository import hooks
+
+
+@dataclass(frozen=True, slots=True)
+class SetupPlan:
+    root: Path
+    commands: tuple[Command, ...]
+    install_hooks: bool = True
+
+
+def plan_setup(root: Path) -> SetupPlan:
+    resolved = root.resolve()
+    commands = (
+        *(
+            Command("Python package", ("uv", "sync", "--frozen"), resolved / "packages" / name)
+            for name in ("python", "sql", "iac", "standards")
+        ),
+        Command(
+            "TypeScript package",
+            ("npm", "ci", "--ignore-scripts", "--no-audit", "--no-fund"),
+            resolved / "packages" / "typescript",
+        ),
+        Command(
+            "Documentation site",
+            ("npm", "ci", "--ignore-scripts", "--no-audit", "--no-fund"),
+            resolved / "apps" / "docs",
+        ),
+    )
+    return SetupPlan(resolved, install_hooks=True, commands=commands)
+
+
+def apply_setup(plan: SetupPlan) -> int:
+    hook_status = hooks.install(plan.root) if plan.install_hooks else 0
+    return hook_status or execute(plan.commands)

sarj_standards/schemas/__init__.py

@@ -0,0 +1,4 @@
+from ._paths import RULE_CATALOG, RULE_CATALOG_SCHEMA, SCHEMAS_DIR
+
+
+__all__ = ["RULE_CATALOG", "RULE_CATALOG_SCHEMA", "SCHEMAS_DIR"]

sarj_standards/schemas/_paths.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+
+SCHEMAS_DIR = Path(__file__).resolve().parent
+RULE_CATALOG = SCHEMAS_DIR / "rule-catalog.v1.json"
+RULE_CATALOG_SCHEMA = SCHEMAS_DIR / "rule-catalog.v1.schema.json"
+SLACK_AUTOMATIONS_SCHEMA = SCHEMAS_DIR / "slack-automations.v1.schema.json"