syntopica-codeality-py 0.2.0__py3-none-any.whl

codeality_py/__init__.py

@@ -0,0 +1 @@
+"""Structural linter and config scaffolder for Python projects."""

codeality_py/assets/codeality-py-ci.yml

@@ -0,0 +1,51 @@
+name: Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.13']
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+
+      - name: Check the lockfile is current
+        run: uv lock --check
+
+      # Every extra and every group: the gate audits and tests the environment
+      # it runs in, and a group-only install leaves out the extras the tests
+      # import.
+      - name: Install from the lockfile
+        run: uv sync --locked --all-extras --all-groups
+        env:
+          UV_PYTHON: ${{ matrix.python-version }}
+
+      - name: Run the quality gate
+        run: uv run codeality-py gate --json
+
+      - name: Type-check with pyrefly, without blocking
+        continue-on-error: true
+        run: |
+          uv run --with pyrefly pyrefly check --output-format json > pyrefly.json || true
+
+      - name: Upload the pyrefly shadow report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: pyrefly-shadow-${{ matrix.python-version }}
+          path: pyrefly.json
+          retention-days: 90

codeality_py/assets/codeality-py.toml

@@ -0,0 +1,19 @@
+# codeality-py configuration - https://github.com/syntopica/codeality
+schema-version = 1
+source-roots = ["src"]
+test-roots = ["tests"]
+respect-gitignore = true
+coverage-threshold = 80
+
+[limits]
+max-file-lines = 150
+test-max-file-lines = 300
+
+# A role states what a file is. Prefer a role over a suppression: it explains
+# the file instead of silencing an alarm.
+[roles]
+data = []
+registry = []
+entrypoint = []
+generated = []
+namespace-init = []

codeality_py/assets/importlinter.ini

@@ -0,0 +1,12 @@
+; Managed by codeality-py, scaffolded only with --profile app. Declare the real
+; layers of the project; an empty contract enforces nothing.
+[importlinter]
+root_package = CHANGE_ME
+
+[importlinter:contract:layers]
+name = Layered architecture
+type = layers
+layers =
+    cli
+    services
+    domain

codeality_py/assets/mypy.ini

@@ -0,0 +1,7 @@
+; Managed by codeality-py.
+[mypy]
+strict = True
+warn_unreachable = True
+show_error_codes = True
+pretty = True
+exclude = (?x)(^build/|^dist/|/migrations/)

codeality_py/assets/pyproject-sections.toml

@@ -0,0 +1,34 @@
+# Sections codeality-py merges into an existing pyproject.toml. It owns these
+# tables and nothing else; comments and key order elsewhere are preserved.
+
+# Without known_first_party, deptry reports every internal import as DEP003.
+[tool.deptry]
+known_first_party = ["CHANGE_ME"]
+
+[tool.deptry.per_rule_ignores]
+DEP002 = []
+# Test tooling legitimately lives in a dev group and is imported only by tests.
+DEP004 = ["pytest", "pytest_asyncio", "pytest_cov"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 80
+
+[dependency-groups]
+quality = [
+  "syntopica-codeality-py>=0.1,<1",
+  "deptry>=0.20,<1",
+  "mypy>=1.11,<2",
+  "pip-audit>=2.7,<3",
+  "pytest>=8,<10",
+  "pytest-cov>=5,<8",
+  "ruff>=0.15,<1",
+]

codeality_py/assets/ruff.toml

@@ -0,0 +1,51 @@
+# Managed by codeality-py. Rules are listed explicitly: ALL expands silently on
+# every ruff upgrade, turning a dependency bump into a lint failure.
+line-length = 100
+target-version = "py311"
+
+[lint]
+select = [
+  "E",    # pycodestyle errors
+  "W",    # pycodestyle warnings
+  "F",    # pyflakes
+  "I",    # import sorting
+  "N",    # pep8-naming
+  "UP",   # pyupgrade
+  "B",    # bugbear
+  "A",    # builtin shadowing
+  "C4",   # comprehensions
+  "DTZ",  # naive datetimes
+  "T20",  # print in library code
+  "SIM",  # simplifiable code
+  "RET",  # return control flow
+  "ARG",  # unused arguments
+  "PTH",  # pathlib over os.path
+  "ERA",  # commented-out code
+  "PL",   # pylint: complexity, branches, statements
+  "RUF",  # ruff-specific
+  "D",    # docstrings; replaces interrogate
+  # bandit, curated: the full S set is intentionally noisy in tests and in
+  # subprocess-heavy code.
+  "S102", "S103", "S104", "S105", "S106", "S107", "S108",
+  "S301", "S302", "S303", "S304", "S305", "S306",
+  "S324", "S501", "S506", "S508", "S509",
+  "S608", "S609", "S612",
+]
+ignore = [
+  # Conflicts with the formatter; keeping these on fights ruff format forever.
+  "E501", "W191", "E111", "E114", "E117", "D206", "D300", "COM812", "ISC001",
+  "D203",  # incompatible with D211
+  "D107",  # an __init__ that stores its arguments has nothing to add to the class docstring
+  "D213",  # incompatible with D212
+]
+
+[lint.per-file-ignores]
+# **/ so the pattern also reaches nested test roots such as host/tests.
+"**/tests/**" = ["D", "S101", "S105", "S106", "S108", "ARG", "PLR"]
+"**/conftest.py" = ["D"]
+
+[lint.pydocstyle]
+convention = "google"
+
+[format]
+docstring-code-format = true

codeality_py/baseline/__init__.py

@@ -0,0 +1 @@
+"""Recording and classifying migration debt."""

codeality_py/baseline/baseline_file.py

@@ -0,0 +1,15 @@
+"""The recorded debt of one project."""
+
+from dataclasses import dataclass, field
+
+BASELINE_SCHEMA_VERSION = 1
+BASELINE_FILENAME = ".codeality-py-baseline.json"
+
+
+@dataclass(frozen=True, slots=True)
+class BaselineFile:
+    """Fingerprints of the findings a project has agreed to carry."""
+
+    entries: frozenset[str] = field(default_factory=frozenset)
+    schema_version: int = BASELINE_SCHEMA_VERSION
+    tool_version: str = ""

codeality_py/baseline/classified_findings.py

@@ -0,0 +1,14 @@
+"""How current findings relate to the recorded baseline."""
+
+from dataclasses import dataclass
+
+from codeality_py.model.finding import Finding
+
+
+@dataclass(frozen=True, slots=True)
+class ClassifiedFindings:
+    """New findings block; known ones are tracked debt; resolved ones are stale."""
+
+    new: tuple[Finding, ...]
+    known: tuple[Finding, ...]
+    resolved: tuple[str, ...]

codeality_py/baseline/classify_findings.py

@@ -0,0 +1,18 @@
+"""Split current findings into new, known and resolved."""
+
+from codeality_py.baseline.baseline_file import BaselineFile
+from codeality_py.baseline.classified_findings import ClassifiedFindings
+from codeality_py.model.finding import Finding
+
+
+def classify_findings(findings: tuple[Finding, ...], baseline: BaselineFile) -> ClassifiedFindings:
+    """Return the findings split against the baseline.
+
+    A baseline entry with no current finding is resolved, and reporting it is
+    what stops dead debt being carried forever.
+    """
+    new = tuple(finding for finding in findings if finding.fingerprint not in baseline.entries)
+    known = tuple(finding for finding in findings if finding.fingerprint in baseline.entries)
+    current = {finding.fingerprint for finding in findings}
+    resolved = tuple(sorted(baseline.entries - current))
+    return ClassifiedFindings(new=new, known=known, resolved=resolved)

codeality_py/baseline/finding_context.py

@@ -0,0 +1,19 @@
+"""Describe what a finding is about, independently of where it sits."""
+
+import re
+
+_WHITESPACE = re.compile(r"\s+")
+
+
+def finding_context(text: str, line: int) -> str:
+    """Return the normalised source of the offending line.
+
+    The line number itself must not enter a fingerprint - inserting a line
+    above a violation would make every finding below it look new. The content
+    of the offending line is stable under that edit and still tells two
+    different violations in one file apart.
+    """
+    lines = text.splitlines()
+    if not 1 <= line <= len(lines):
+        return ""
+    return _WHITESPACE.sub(" ", lines[line - 1]).strip()

codeality_py/baseline/fingerprint.py

@@ -0,0 +1,21 @@
+"""Identify a finding by what it is, not by where it sits."""
+
+import hashlib
+
+from codeality_py.model.finding import Finding
+
+FINGERPRINT_VERSION = 1
+
+
+def fingerprint(finding: Finding, context: str) -> str:
+    """Return a stable identity for this finding.
+
+    The line number is deliberately excluded: inserting a line above a query
+    must not make every finding in the file look new. The context carries the
+    offending line's content and its occurrence, so a genuinely new violation
+    still gets its own fingerprint.
+    """
+    material = "|".join(
+        [str(FINGERPRINT_VERSION), finding.code.value, finding.location.path, context]
+    )
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()[:16]

codeality_py/baseline/fingerprint_context.py

@@ -0,0 +1,27 @@
+"""Decide what identifies a finding, per rule."""
+
+from codeality_py.baseline.finding_context import finding_context
+from codeality_py.model.finding import Finding
+from codeality_py.model.rule_code import RuleCode
+
+#: Rules that report once per file. Their anchor is line 1, whose content says
+#: nothing about the violation, and the subject of a size finding is a count
+#: that moves with every edit.
+FILE_LEVEL = frozenset({RuleCode.BPY001, RuleCode.BPY004})
+
+#: Rules whose subject names the thing that is wrong and is unique in the file.
+SUBJECT_LEVEL = frozenset({RuleCode.BPY002, RuleCode.BPY003})
+
+
+def fingerprint_context(finding: Finding, text: str) -> str:
+    """Return the text identifying this finding within its file.
+
+    A file-level rule identifies itself. A naming rule identifies the symbol.
+    Everything else can fire many times in one file, so it is identified by the
+    offending line's content, which survives edits elsewhere in the file.
+    """
+    if finding.code in FILE_LEVEL:
+        return ""
+    if finding.code in SUBJECT_LEVEL:
+        return finding.subject or ""
+    return finding_context(text, finding.location.line)

codeality_py/baseline/read_baseline.py

@@ -0,0 +1,32 @@
+"""Read the recorded baseline, refusing an incompatible one."""
+
+import json
+from pathlib import Path
+
+from codeality_py.baseline.baseline_file import BASELINE_SCHEMA_VERSION, BaselineFile
+from codeality_py.config.config_error import ConfigError
+
+
+def read_baseline(path: Path) -> BaselineFile:
+    """Return the baseline, or an empty one when the file is absent.
+
+    An incompatible schema is a configuration error rather than a silent
+    reclassification of every finding as new or known.
+    """
+    if not path.is_file():
+        return BaselineFile()
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ConfigError(f"{path.name} could not be read: {error}") from error
+    version = document.get("schema_version")
+    if version != BASELINE_SCHEMA_VERSION:
+        raise ConfigError(
+            f"baseline schema_version must be {BASELINE_SCHEMA_VERSION}, found {version!r}; "
+            "run 'codeality-py baseline update' to rewrite it"
+        )
+    return BaselineFile(
+        entries=frozenset(document.get("entries", ())),
+        schema_version=version,
+        tool_version=document.get("tool_version", ""),
+    )

codeality_py/baseline/write_baseline.py

@@ -0,0 +1,18 @@
+"""Write the baseline atomically and deterministically."""
+
+import json
+from pathlib import Path
+
+from codeality_py.baseline.baseline_file import BaselineFile
+
+
+def write_baseline(path: Path, baseline: BaselineFile) -> None:
+    """Write the baseline through a temporary file, sorted for a clean diff."""
+    document = {
+        "schema_version": baseline.schema_version,
+        "tool_version": baseline.tool_version,
+        "entries": sorted(baseline.entries),
+    }
+    temporary = path.with_suffix(f"{path.suffix}.tmp")
+    temporary.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)

codeality_py/cli.py

@@ -0,0 +1,22 @@
+"""Command-line entry point for codeality-py."""
+
+from importlib.metadata import version
+
+import click
+
+from codeality_py.commands.baseline_command import baseline_command
+from codeality_py.commands.check_command import check_command
+from codeality_py.commands.gate_command import gate_command
+from codeality_py.commands.init_command import init_command
+
+
+@click.group(name="codeality-py")
+@click.version_option(version("syntopica-codeality-py"), prog_name="codeality-py")
+def cli() -> None:
+    """Structural linter and config scaffolder for Python."""
+
+
+cli.add_command(baseline_command)
+cli.add_command(check_command)
+cli.add_command(gate_command)
+cli.add_command(init_command)

codeality_py/commands/__init__.py

@@ -0,0 +1 @@
+"""The CLI commands."""

codeality_py/commands/baseline_check_command.py

@@ -0,0 +1,36 @@
+"""Report current findings against the recorded baseline."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from codeality_py.baseline.baseline_file import BASELINE_FILENAME
+from codeality_py.baseline.classify_findings import classify_findings
+from codeality_py.baseline.read_baseline import read_baseline
+from codeality_py.commands.checked_project import checked_project
+from codeality_py.commands.project_option import PROJECT_OPTION
+from codeality_py.report.exit_code import ExitCode
+
+
+@click.command(name="check")
+@PROJECT_OPTION
+@click.option("--check-stale", is_flag=True, help="Also fail on entries nothing reports any more.")
+def baseline_check_command(project: Path, check_stale: bool) -> None:
+    """Fail on new findings, and on stale debt when asked."""
+    root, result = checked_project(project)
+    classified = classify_findings(result.findings, read_baseline(root / BASELINE_FILENAME))
+    click.echo(
+        f"{len(classified.new)} new, {len(classified.known)} known, "
+        f"{len(classified.resolved)} resolved"
+    )
+    for finding in classified.new:
+        click.echo(
+            f"{finding.location.path}:{finding.location.line}: "
+            f"{finding.code.value} {finding.message}"
+        )
+    sys.exit(
+        ExitCode.FINDINGS
+        if classified.new or (check_stale and classified.resolved)
+        else ExitCode.OK
+    )

codeality_py/commands/baseline_command.py

@@ -0,0 +1,15 @@
+"""The ``baseline`` command group: the only writer of recorded debt."""
+
+import click
+
+from codeality_py.commands.baseline_check_command import baseline_check_command
+from codeality_py.commands.baseline_update_command import baseline_update_command
+
+
+@click.group(name="baseline")
+def baseline_command() -> None:
+    """Record and inspect migration debt. Only this group ever writes one."""
+
+
+baseline_command.add_command(baseline_check_command)
+baseline_command.add_command(baseline_update_command)

codeality_py/commands/baseline_update_command.py

@@ -0,0 +1,24 @@
+"""Record every current finding as accepted debt."""
+
+from importlib.metadata import version
+from pathlib import Path
+
+import click
+
+from codeality_py.baseline.baseline_file import BASELINE_FILENAME, BaselineFile
+from codeality_py.baseline.write_baseline import write_baseline
+from codeality_py.commands.checked_project import checked_project
+from codeality_py.commands.project_option import PROJECT_OPTION
+
+
+@click.command(name="update")
+@PROJECT_OPTION
+def baseline_update_command(project: Path) -> None:
+    """Write the baseline. This and nothing else records debt."""
+    root, result = checked_project(project)
+    recorded = BaselineFile(
+        entries=frozenset(finding.fingerprint for finding in result.findings),
+        tool_version=version("syntopica-codeality-py"),
+    )
+    write_baseline(root / BASELINE_FILENAME, recorded)
+    click.echo(f"recorded {len(recorded.entries)} findings as baseline debt")

codeality_py/commands/check_command.py

@@ -0,0 +1,45 @@
+"""The read-only ``check`` command."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from codeality_py.config.config_error import ConfigError
+from codeality_py.config.load_config import load_config
+from codeality_py.engine.check_project import check_project
+from codeality_py.parsing.infrastructure_error import InfrastructureError
+from codeality_py.report.exit_code import ExitCode
+from codeality_py.report.render_json_report import render_json_report
+from codeality_py.report.render_text_report import render_text_report
+
+
+@click.command(name="check")
+@click.option(
+    "--project",
+    "project",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path(),
+    help="Project root to check. Defaults to the working directory.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Report format. JSON goes to stdout alone.",
+)
+def check_command(project: Path, output_format: str) -> None:
+    """Run the structural rules. This command never writes."""
+    try:
+        config = load_config(project.resolve())
+        result = check_project(config)
+    except ConfigError as error:
+        click.echo(f"configuration error: {error}", err=True)
+        sys.exit(ExitCode.CONFIGURATION)
+    except InfrastructureError as error:
+        click.echo(f"infrastructure error: {error}", err=True)
+        sys.exit(ExitCode.INFRASTRUCTURE)
+    rendered = render_json_report(result) if output_format == "json" else render_text_report(result)
+    click.echo(rendered)
+    sys.exit(ExitCode.FINDINGS if result.findings else ExitCode.OK)

codeality_py/commands/checked_project.py

@@ -0,0 +1,26 @@
+"""Load a project's configuration and run the checker over it."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from codeality_py.config.config_error import ConfigError
+from codeality_py.config.load_config import load_config
+from codeality_py.engine.check_project import check_project
+from codeality_py.engine.check_result import CheckResult
+from codeality_py.parsing.infrastructure_error import InfrastructureError
+from codeality_py.report.exit_code import ExitCode
+
+
+def checked_project(project: Path) -> tuple[Path, CheckResult]:
+    """Return the resolved root and its findings, exiting on any failure."""
+    root = project.resolve()
+    try:
+        return root, check_project(load_config(root))
+    except ConfigError as error:
+        click.echo(f"configuration error: {error}", err=True)
+        sys.exit(ExitCode.CONFIGURATION)
+    except InfrastructureError as error:
+        click.echo(f"infrastructure error: {error}", err=True)
+        sys.exit(ExitCode.INFRASTRUCTURE)

codeality_py/commands/gate_command.py

@@ -0,0 +1,33 @@
+"""The ``gate`` command: the whole quality chain, defined once."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from codeality_py.config.config_error import ConfigError
+from codeality_py.config.load_config import load_config
+from codeality_py.gate.run_gate import run_gate
+from codeality_py.report.exit_code import ExitCode
+from codeality_py.report.render_gate_report import render_gate_report
+
+
+@click.command(name="gate")
+@click.option(
+    "--project",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path(),
+    help="Project root to gate. Defaults to the working directory.",
+)
+@click.option("--fail-fast", is_flag=True, help="Stop at the first blocking failure.")
+@click.option("--json", "as_json", is_flag=True, help="Emit the machine-readable summary.")
+def gate_command(project: Path, fail_fast: bool, as_json: bool) -> None:
+    """Run ruff, mypy, the structural rules, deptry, pip-audit and pytest."""
+    try:
+        config = load_config(project.resolve())
+    except ConfigError as error:
+        click.echo(f"configuration error: {error}", err=True)
+        sys.exit(ExitCode.CONFIGURATION)
+    result = run_gate(config, fail_fast)
+    click.echo(render_gate_report(result, as_json))
+    sys.exit(result.exit_code())

codeality_py/commands/init_command.py

@@ -0,0 +1,53 @@
+"""The ``init`` command: plan by default, merge on request, never shadow."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from codeality_py.init.apply_init import apply_init
+from codeality_py.init.plan_disposition import PlanDisposition
+from codeality_py.init.plan_init import plan_init
+from codeality_py.report.exit_code import ExitCode
+
+
+@click.command(name="init")
+@click.option(
+    "--project",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path(),
+    help="Project root to scaffold. Defaults to the working directory.",
+)
+@click.option("--check", "check_only", is_flag=True, help="Plan only; exit 2 on any conflict.")
+@click.option("--apply", "should_apply", is_flag=True, help="Write creates and merges.")
+@click.option("--force", is_flag=True, help="Also replace conflicting managed files.")
+@click.option("--ci", "with_ci", is_flag=True, help="Also scaffold the CI workflow.")
+@click.option(
+    "--profile",
+    type=click.Choice(["lib", "app"]),
+    default="lib",
+    help="app additionally scaffolds an import-linter contract.",
+)
+def init_command(  # noqa: PLR0913, PLR0917 - one parameter per click option
+    project: Path,
+    check_only: bool,
+    should_apply: bool,
+    force: bool,
+    with_ci: bool,
+    profile: str,
+) -> None:
+    """Scaffold the quality configuration by merging, never by shadowing."""
+    root = project.resolve()
+    plan = plan_init(root, profile, with_ci)
+    for managed in plan:
+        # A nested project's workflow lives at the repository root, outside it.
+        path = managed.path.resolve()
+        shown = path.relative_to(root) if path.is_relative_to(root) else path
+        click.echo(f"{managed.disposition.value:>9}  {shown}  ({managed.detail})")
+    if should_apply or force:
+        written = apply_init(plan, force)
+        click.echo(f"wrote {len(written)} files")
+    conflicts = [item for item in plan if item.disposition is PlanDisposition.CONFLICT]
+    if conflicts and check_only:
+        sys.exit(ExitCode.CONFIGURATION)
+    sys.exit(ExitCode.OK)

codeality_py/commands/project_option.py

@@ -0,0 +1,12 @@
+"""The --project option shared by every command."""
+
+from pathlib import Path
+
+import click
+
+PROJECT_OPTION = click.option(
+    "--project",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path(),
+    help="Project root. Defaults to the working directory.",
+)

codeality_py/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration loading and validation."""