gravitar 0.1.0__py3-none-any.whl

gravitar/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gravitar/__main__.py

@@ -0,0 +1,4 @@
+from gravitar.cli import main
+
+if __name__ == "__main__":
+    main()

gravitar/analysis/__init__.py

@@ -0,0 +1 @@
+"""Confidence scoring and (Milestone 8) raw-SQL signature classification."""

gravitar/analysis/confidence.py

@@ -0,0 +1,90 @@
+"""Confidence scoring.
+
+Callers (compare.py, migrations.py) don't have a single Alembic op call backing
+every finding — several categories come from a full static schema diff rather
+than one operation. `base_confidence` is therefore keyed by the *resolution
+signal* a finding was built from, not by op type directly: "ast_fully_resolved"
+covers every v1 category built from a complete static comparison, "unknown_type"
+covers a type neither side's introspection could normalize, and
+"raw_sql_unresolved" covers an `op.execute()` call the migration parser can't
+see into.
+
+`unresolved_penalty`/`corroboration_bonus` are fixed per-item deductions/bonuses
+so the raw-SQL signature classifier can plug real unresolved AST nodes
+and matched SQL signatures into `score_finding` without this formula changing
+shape.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from gravitar.schema import Evidence
+
+# base_confidence(op_type) — see module docstring for why this is keyed by
+# resolution signal rather than Alembic op type.
+_BASE_CONFIDENCE: dict[str, float] = {
+    "ast_fully_resolved": 1.0,
+    "unknown_type": 0.5,
+    "raw_sql_unresolved": 0.3,
+    # Lower than raw_sql_unresolved: the raw-SQL classifier *did* recover the
+    # operation's structure (we know exactly what it's trying to do), but the
+    # table/column it names isn't present in the schema state being built — a
+    # concrete, concerning signal, not mere ambiguity.
+    "orphaned_reference": 0.2,
+}
+
+# Fixed per-item deduction/bonus.
+UNRESOLVED_NODE_PENALTY = 0.15
+SIGNATURE_MATCH_BONUS = 0.2
+
+
+def base_confidence(signal: str) -> float:
+    """Fixed lookup table entry for a resolution signal (Section 4)."""
+    return _BASE_CONFIDENCE[signal]
+
+
+def unresolved_penalty(_node: object) -> float:
+    """Fixed deduction per AST node the walker could not statically resolve."""
+    return UNRESOLVED_NODE_PENALTY
+
+
+def corroboration_bonus(_signature: str) -> float:
+    """Fixed addition per raw-SQL pattern the Section 5 classifier matched."""
+    return SIGNATURE_MATCH_BONUS
+
+
+def score_finding(
+    signal: str,
+    detail: str,
+    *,
+    unresolved_nodes: Sequence[object] = (),
+    matched_signatures: Sequence[str] = (),
+) -> tuple[float, list[Evidence]]:
+    """Compute a finding's confidence score and its evidence trail (Section 4).
+
+    `evidence[0]` always records the base signal; one entry follows per
+    unresolved node (negative weight) and per matched signature (positive
+    weight), in that order, so the trail is reproducible from its inputs alone.
+    """
+    base = base_confidence(signal)
+    evidence: list[Evidence] = [Evidence(signal=signal, weight=base, detail=detail)]
+    total = base
+
+    for node in unresolved_nodes:
+        penalty = unresolved_penalty(node)
+        total -= penalty
+        evidence.append(Evidence(signal="unresolved_node", weight=-penalty, detail=str(node)))
+
+    for matched_signature in matched_signatures:
+        bonus = corroboration_bonus(matched_signature)
+        total += bonus
+        evidence.append(
+            Evidence(signal="sql_pattern_match", weight=bonus, detail=matched_signature)
+        )
+
+    return clamp(total), evidence
+
+
+def clamp(value: float) -> float:
+    return max(0.0, min(1.0, value))

gravitar/analysis/demotion.py

@@ -0,0 +1,95 @@
+"""Demote-only-when-explained. SPEC-16 Amendment v1.1 Decision #2 + R3.
+
+A finding whose table (or column) is in-scope for an ``Unresolved`` note gets
+demoted one tier (``error``/``warning`` → ``review``). The note's id goes in
+``explaining_notes`` so the output can show *which* notes caused the demotion
+— T3 requires that demotion never deletes and always shows the reason.
+
+Unscoped (global) notes — ``tables=None`` — never demote: they can't claim to
+explain any specific finding, so promoting them to a demotion mechanism would
+mean one unreadable migration anywhere demotes every finding in the whole
+repo. Decision #2 is explicit about this ("global notes lower confidence
+only"). The confidence-lowering happens inside the comparator's existing
+``unresolved_node`` evidence contribution, not here.
+
+Column-level scope (``columns=["t.c"]``) is a tighter filter than table
+scope (``tables=["t"]``): a note that names a column only demotes findings
+on that exact column, not every finding on its table. Table-level scope
+demotes any finding on that table.
+"""
+
+from __future__ import annotations
+
+from gravitar.schema import DriftFinding, Unresolved
+
+
+def demote_explained_findings(
+    findings: list[DriftFinding], taint: dict[str, list[Unresolved]]
+) -> list[DriftFinding]:
+    """Return a new list of findings with any that are in-scope for a
+    taint note demoted a tier (``kind="review"``, ``demoted_from=<orig>``,
+    ``explaining_notes=[note ids]``).
+
+    No side effects on the input list; a finding not covered by taint
+    passes through unchanged (same dict identity, not a copy — so the
+    rest of the pipeline doesn't accidentally break reference equality).
+    """
+    out: list[DriftFinding] = []
+    for finding in findings:
+        explaining = _notes_explaining(finding, taint)
+        if not explaining:
+            out.append(finding)
+            continue
+        out.append(_demoted(finding, explaining))
+    return out
+
+
+def _notes_explaining(
+    finding: DriftFinding, taint: dict[str, list[Unresolved]]
+) -> list[Unresolved]:
+    """Which taint notes explain this finding — the test for demotion."""
+    table = finding["table"]
+    column = finding["column"]
+    if table is None:
+        # A finding without a table (broken_chain gap/cycle etc.) is a
+        # revision-level claim, not a table-level one — no table-scoped
+        # note can explain it. Only global notes could, and Decision #2
+        # excludes those from demotion.
+        return []
+    table_notes = taint.get(table, [])
+    if not table_notes:
+        return []
+    # Narrow further by column if the note names columns explicitly:
+    # a note scoped to ``columns=["t.other"]`` doesn't explain a finding
+    # on ``t.this``, even though it's tainting the same table.
+    out: list[Unresolved] = []
+    qualified = f"{table}.{column}" if column else None
+    for note in table_notes:
+        if note["columns"] is None:
+            # Table-level scope — explains any finding on this table.
+            out.append(note)
+            continue
+        # Column-level scope — must mention this exact column.
+        if qualified and qualified in note["columns"]:
+            out.append(note)
+    return out
+
+
+def _demoted(finding: DriftFinding, explaining: list[Unresolved]) -> DriftFinding:
+    return DriftFinding(
+        category=finding["category"],
+        severity=finding["severity"],
+        table=finding["table"],
+        column=finding["column"],
+        model_value=finding["model_value"],
+        migration_value=finding["migration_value"],
+        message=finding["message"],
+        suggestion=finding["suggestion"],
+        confidence=finding["confidence"],
+        source=finding["source"],
+        evidence=finding["evidence"],
+        live_verified=finding["live_verified"],
+        kind="review",
+        demoted_from=finding["severity"],
+        explaining_notes=[n["id"] for n in explaining],
+    )

gravitar/analysis/live_corroboration.py

@@ -0,0 +1,166 @@
+"""Live (read-only) database corroboration.
+
+Strictly optional, off by default: nothing in this module runs unless the
+caller (cli.py) passes a `--live-db-url`. This is corroboration, not a data
+source — it only resolves ambiguity in findings the static reconstruction
+already produced, one targeted read-only column lookup per low-confidence
+finding, never a schema dump.
+
+Nothing here ever logs or stores the connection URL itself ("never
+persisted... including logs") — failure messages report the exception *type*
+only, never its text, since a driver's error message can itself embed the DSN.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from sqlalchemy import create_engine, inspect
+from sqlalchemy.engine import Engine
+
+from gravitar.analysis.confidence import clamp
+from gravitar.schema import DriftFinding, Evidence
+from gravitar.schema.types import normalize_type
+
+logger = logging.getLogger("gravitar.live_corroboration")
+
+# Only findings the static path was already unsure about are worth a live
+# round-trip; anything at or above this is left alone (Section 4).
+LIVE_CORROBORATION_THRESHOLD = 0.7
+LIVE_CORROBORATION_BONUS = 0.3
+
+
+@dataclass(frozen=True)
+class LiveColumn:
+    type: str
+    nullable: bool
+
+
+def corroboration_bonus_live(confidence: float) -> float:
+    return clamp(confidence + LIVE_CORROBORATION_BONUS)
+
+
+def corroborate(findings: list[DriftFinding], live_db_url: str) -> list[DriftFinding]:
+    """Corroborate every finding below LIVE_CORROBORATION_THRESHOLD against a
+    live database. Connects once, runs the targeted per-finding lookups, and
+    closes before returning (Section 5) — never a persistent pool.
+
+    Never raises: a connection failure fails soft (Section 5), logging one
+    warning (exception type only — see module docstring) and returning
+    `findings` completely unchanged, exactly as if this had never been called.
+    """
+    try:
+        engine = create_engine(live_db_url)
+        with engine.connect():
+            pass  # fail fast on bad credentials/unreachable host, before touching findings
+    except Exception as e:
+        logger.warning("live-db corroboration disabled: could not connect (%s)", type(e).__name__)
+        return findings
+
+    try:
+        return [_corroborate_finding(engine, finding) for finding in findings]
+    finally:
+        engine.dispose()
+
+
+def _corroborate_finding(engine: Engine, finding: DriftFinding) -> DriftFinding:
+    if finding["confidence"] >= LIVE_CORROBORATION_THRESHOLD:
+        return finding
+    if finding["table"] is None or finding["column"] is None:
+        return finding
+
+    live_column = _introspect_single_column(engine, finding["table"], finding["column"])
+    if live_column is None:
+        # Section 6: no live value either way (table/column doesn't exist
+        # live, or its type can't be normalized) is a neutral result, not
+        # evidence for or against — leave the finding exactly as it was.
+        return finding
+
+    return _apply_corroboration(finding, live_column)
+
+
+def _introspect_single_column(engine: Engine, table: str, column: str) -> LiveColumn | None:
+    """One targeted, read-only reflection query for a single named column —
+    never a blanket schema sweep (Section 2 Non-goals).
+    """
+    try:
+        inspector = inspect(engine)
+        if not inspector.has_table(table):
+            return None
+        for col in inspector.get_columns(table):
+            if col["name"] != column:
+                continue
+            type_str = normalize_type(col["type"])
+            if type_str.startswith("unknown:"):
+                # Section 6: a live type Gravitar's own canonical vocabulary
+                # can't represent doesn't corroborate anything — don't guess.
+                return None
+            return LiveColumn(type=type_str, nullable=bool(col["nullable"]))
+    except Exception as e:
+        logger.debug(
+            "live-db corroboration: could not introspect %s.%s (%s)",
+            table,
+            column,
+            type(e).__name__,
+        )
+        return None
+    return None
+
+
+def _apply_corroboration(finding: DriftFinding, live_column: LiveColumn) -> DriftFinding:
+    if finding["category"] == "orphaned_reference":
+        # migration_value is raw SQL text and model_value is always None for
+        # this category — neither is a type string to compare against, so
+        # the column's mere existence live is itself the corroborating
+        # signal (the reference wasn't a typo/dead end after all).
+        return _bump(
+            finding,
+            corroboration_bonus_live(finding["confidence"]),
+            LIVE_CORROBORATION_BONUS,
+            "live schema confirms the table/column exists",
+        )
+
+    matched_side = _matching_side(finding, live_column.type)
+    if matched_side is not None:
+        return _bump(
+            finding,
+            corroboration_bonus_live(finding["confidence"]),
+            LIVE_CORROBORATION_BONUS,
+            f"live schema matches {matched_side}",
+        )
+    # Live state contradicts both sides — this is now a confirmed,
+    # high-confidence finding, not a low-confidence one (Section 4).
+    return _bump(finding, 1.0, 1.0, "live schema matches neither migration nor model")
+
+
+def _matching_side(finding: DriftFinding, live_type: str) -> str | None:
+    if finding["migration_value"] == live_type:
+        return "migration"
+    if finding["model_value"] == live_type:
+        return "model"
+    return None
+
+
+def _bump(finding: DriftFinding, confidence: float, weight: float, detail: str) -> DriftFinding:
+    evidence = [
+        *finding["evidence"],
+        Evidence(signal="live_db_corroboration", weight=weight, detail=detail),
+    ]
+    return DriftFinding(
+        category=finding["category"],
+        severity=finding["severity"],
+        table=finding["table"],
+        column=finding["column"],
+        model_value=finding["model_value"],
+        migration_value=finding["migration_value"],
+        message=finding["message"],
+        suggestion=finding["suggestion"],
+        confidence=confidence,
+        source=finding["source"],
+        evidence=evidence,
+        live_verified=True,
+        kind=finding["kind"],
+        demoted_from=finding["demoted_from"],
+        explaining_notes=finding["explaining_notes"],
+    )

gravitar/analysis/sql_patterns.py

@@ -0,0 +1,141 @@
+"""Signature-based raw-SQL classification.
+
+Recovers structured schema-operation intent from the string argument of an
+`op.execute("<raw sql>")` call, entirely statically: a lightweight, non-validating
+tokenizer (whitespace/keyword split, not a grammar parser — see Non-goals) followed
+by matching against a fixed library of common schema-mutating SQL shapes. A string
+that doesn't match any shape is not an error: it stays unresolved and the caller
+(migrations.py) keeps scoring it at the "raw_sql_unresolved" base confidence.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Matches, in order of preference: a single-quoted string literal (with SQL's ''
+# escape for an embedded quote), a double-quoted identifier, a parenthesis or comma
+# as its own token, a bare identifier/keyword, or — the non-validating fallback —
+# any other single non-space character. Every character in the input is consumed by
+# some alternative, so this never raises and never loops without making progress;
+# SQL it can't make sense of just degrades into tokens that fail every pattern
+# below (Section 6's first failure mode: no-match, never a crash).
+_TOKEN_RE = re.compile(r"""'(?:[^']|'')*'|"[^"]*"|[(),;]|[A-Za-z_][A-Za-z0-9_.]*|\S""", re.VERBOSE)
+
+
+def tokenize(sql: str) -> list[str]:
+    return _TOKEN_RE.findall(sql)
+
+
+@dataclass(frozen=True)
+class SqlMatch:
+    pattern_id: str
+    table: str
+    column: str | None = None
+
+
+def _keyword(token: str, expected: str) -> bool:
+    return token.upper() == expected
+
+
+def _identifier(token: str) -> str:
+    return token.strip("\"'")
+
+
+def _strip_trailing_semicolon(tokens: list[str]) -> list[str]:
+    return tokens[:-1] if tokens and tokens[-1] == ";" else tokens
+
+
+def _match_add_column(tokens: list[str]) -> SqlMatch | None:
+    # ALTER TABLE <t> ADD COLUMN <c> <type...>
+    if len(tokens) < 6:
+        return None
+    if not (
+        _keyword(tokens[0], "ALTER")
+        and _keyword(tokens[1], "TABLE")
+        and _keyword(tokens[3], "ADD")
+        and _keyword(tokens[4], "COLUMN")
+    ):
+        return None
+    return SqlMatch("sql:add_column", table=_identifier(tokens[2]), column=_identifier(tokens[5]))
+
+
+def _match_drop_column(tokens: list[str]) -> SqlMatch | None:
+    # ALTER TABLE <t> DROP COLUMN <c>
+    if len(tokens) != 6:
+        return None
+    if not (
+        _keyword(tokens[0], "ALTER")
+        and _keyword(tokens[1], "TABLE")
+        and _keyword(tokens[3], "DROP")
+        and _keyword(tokens[4], "COLUMN")
+    ):
+        return None
+    return SqlMatch("sql:drop_column", table=_identifier(tokens[2]), column=_identifier(tokens[5]))
+
+
+def _match_alter_column_type(tokens: list[str]) -> SqlMatch | None:
+    # ALTER TABLE <t> ALTER COLUMN <c> TYPE <type...>
+    if len(tokens) < 8:
+        return None
+    if not (
+        _keyword(tokens[0], "ALTER")
+        and _keyword(tokens[1], "TABLE")
+        and _keyword(tokens[3], "ALTER")
+        and _keyword(tokens[4], "COLUMN")
+        and _keyword(tokens[6], "TYPE")
+    ):
+        return None
+    return SqlMatch(
+        "sql:alter_column_type", table=_identifier(tokens[2]), column=_identifier(tokens[5])
+    )
+
+
+def _match_create_index(tokens: list[str]) -> SqlMatch | None:
+    # CREATE INDEX <idx> ON <t> ( <cols> )
+    if len(tokens) < 7:
+        return None
+    if not (
+        _keyword(tokens[0], "CREATE") and _keyword(tokens[1], "INDEX") and _keyword(tokens[3], "ON")
+    ):
+        return None
+    return SqlMatch("sql:create_index", table=_identifier(tokens[4]))
+
+
+def _match_create_unique_index(tokens: list[str]) -> SqlMatch | None:
+    # CREATE UNIQUE INDEX <idx> ON <t> ( <cols> )
+    if len(tokens) < 8:
+        return None
+    if not (
+        _keyword(tokens[0], "CREATE")
+        and _keyword(tokens[1], "UNIQUE")
+        and _keyword(tokens[2], "INDEX")
+        and _keyword(tokens[4], "ON")
+    ):
+        return None
+    return SqlMatch("sql:create_unique_index", table=_identifier(tokens[5]))
+
+
+# Order matters: CREATE UNIQUE INDEX must be tried before CREATE INDEX, since the
+# latter's fixed-position checks would otherwise misread "UNIQUE" as the index name.
+_MATCHERS = [
+    _match_add_column,
+    _match_drop_column,
+    _match_alter_column_type,
+    _match_create_unique_index,
+    _match_create_index,
+]
+
+
+def match(sql: str) -> SqlMatch | None:
+    """Match a raw SQL string against the Section 5 pattern library.
+
+    Returns None on no match — including for SQL the tokenizer can't make sense
+    of — never raises.
+    """
+    tokens = _strip_trailing_semicolon(tokenize(sql))
+    for matcher in _MATCHERS:
+        result = matcher(tokens)
+        if result is not None:
+            return result
+    return None

gravitar/baseline.py

@@ -0,0 +1,88 @@
+"""Baseline/ratchet storage. SPEC-16 Amendment R14 (remainder).
+
+A baseline is a snapshot of the finding ids present at a known-good point
+in time. Each subsequent ``gravitar check`` compares against it: findings
+in the baseline are "unchanged" and do not fail CI, findings not in the
+baseline are "new" and do. The pattern lets a drifty project onboard
+Gravitar without turning its CI red on day one — teams accept the
+current state as the floor, then ratchet from there.
+
+Stored as JSON at ``<repo>/.gravitar/baseline.json`` by default. Finding
+identity is :func:`gravitar.feedback.ids.finding_id` (stable across
+runs; see Section 3.1), so a baseline survives refactors that don't
+move the drift itself.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+BASELINE_RELATIVE_PATH = Path(".gravitar") / "baseline.json"
+BASELINE_VERSION = 1
+
+
+def baseline_path_for(repo_path: Path) -> Path:
+    return repo_path / BASELINE_RELATIVE_PATH
+
+
+def load_baseline(baseline_path: Path) -> set[str] | None:
+    """Read the baseline's finding ids, or None if no baseline exists.
+
+    Missing file is the common case (no baseline configured) — never an
+    error. A malformed baseline is loud: a project should not silently
+    behave as if it had no baseline when the file is actually corrupt,
+    because baselined findings would suddenly fail CI.
+    """
+    if not baseline_path.exists():
+        return None
+    try:
+        data = json.loads(baseline_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{baseline_path}: malformed JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise ValueError(f"{baseline_path}: expected an object, got {type(data).__name__}")
+    finding_ids = data.get("finding_ids")
+    if not isinstance(finding_ids, list):
+        raise ValueError(f"{baseline_path}: 'finding_ids' must be a list")
+    return {str(fid) for fid in finding_ids}
+
+
+def write_baseline(baseline_path: Path, finding_ids: list[str]) -> None:
+    """Write the baseline atomically. Creates ``.gravitar/`` on first use.
+
+    The ids are sorted so repeat runs that produce the same set yield a
+    byte-identical file — a `git diff` on the baseline shows only genuine
+    drift additions/removals rather than key reorderings.
+    """
+    baseline_path.parent.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, Any] = {
+        "version": BASELINE_VERSION,
+        "created_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        "finding_ids": sorted(set(finding_ids)),
+    }
+    tmp = baseline_path.with_suffix(baseline_path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(baseline_path)
+
+
+def clear_baseline(baseline_path: Path) -> bool:
+    """Remove the baseline file. Returns True if a baseline was removed,
+    False if there was nothing to remove."""
+    if not baseline_path.exists():
+        return False
+    baseline_path.unlink()
+    return True
+
+
+def read_baseline_metadata(baseline_path: Path) -> dict[str, Any] | None:
+    """Return the full baseline payload (version, created_at, finding_ids)
+    for ``baseline show``. None if no baseline exists."""
+    if not baseline_path.exists():
+        return None
+    data = json.loads(baseline_path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{baseline_path}: expected an object")
+    return data