graincheck 0.1.0__py3-none-any.whl

graincheck/__init__.py

@@ -0,0 +1,5 @@
+"""graincheck — find analytical SQL that returns a plausible number and a wrong one."""
+from .scanner import scan_sql, scan_path, to_markdown, to_report, load_uniques  # noqa: F401
+from .rules import Finding, ALL_RULES                                  # noqa: F401
+
+__version__ = "0.1.0"

graincheck/__main__.py

@@ -0,0 +1,299 @@
+"""graincheck CLI.
+
+    graincheck scan ./models --manifest target/manifest.json --dialect snowflake --report out.html
+    graincheck explain fct_customer_revenue --path ./models --manifest target/manifest.json
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .scanner import (scan_path, to_markdown, to_report, compile_advice,
+                      dbt_project_root, load_uniques)
+from .explain import explain
+from .coverage import measure_full, to_text as coverage_text
+from .coverage import FORMULAS as COVERAGE_FORMULAS
+from .exceptions import to_text as exceptions_text
+from . import emit as emit_tests, history as cov_history, incumbent
+
+
+def _auto_manifest(path: Path, given: str | None) -> Path | None:
+    if given:
+        return Path(given)
+    root = dbt_project_root(path)
+    if root is None:
+        return None
+    candidate = root / "target" / "manifest.json"
+    return candidate if candidate.exists() else None
+
+
+def _make_output_utf8_safe():
+    """Stop a legacy console codepage from crashing the whole run.
+
+    Every message this tool prints contains an em dash, and several contain arrows and middle dots.
+    On Windows, `sys.stdout` uses the locale encoding, and the default codepage of `cmd.exe` in the
+    US locale is **cp437**, which has no em dash. So:
+
+        C:\\> graincheck coverage .
+        UnicodeEncodeError: 'charmap' codec can't encode character '\\u2014' ...
+
+    — a traceback and exit 1, on a correct project, before printing a single finding. Reproduced here
+    with PYTHONIOENCODING=cp437 and PYTHONIOENCODING=ascii; both crashed at the same character.
+
+    This is the one class of failure that no amount of checking the SQL would ever have found, because
+    every test and every health check has run on Linux with a UTF-8 locale. It is also the one the
+    user would have hit first.
+
+    UTF-8 is the fix where the stream supports it. Where it does not, `errors="replace"` means a
+    console that cannot render an em dash prints `?` instead of killing the process — a cosmetic loss
+    is always the right trade against losing the output entirely. Wrapped in try/except because a
+    stream may be an object with no `reconfigure` (pytest's capture, a pipe someone replaced), and
+    failing to improve the console must never itself be the crash.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError, OSError):
+            try:
+                stream.reconfigure(errors="replace")
+            except (AttributeError, ValueError, OSError):
+                pass
+
+
+def _write_output(path_str: str, text: str, what: str) -> bool:
+    """Write an output file, or explain why not — never a traceback.
+
+    A user typing `--report reports/scan.html` before `reports/` exists got a raw
+    FileNotFoundError traceback after the scan had already finished, which loses the whole run's work
+    to a one-word mistake. The parent directory is created when it can be, and every remaining failure
+    (a permission problem, a path that is a directory, a full disk) becomes one sentence on stderr and
+    a nonzero exit.
+    """
+    p = Path(path_str)
+    try:
+        if p.parent and not p.parent.exists():
+            p.parent.mkdir(parents=True, exist_ok=True)
+            print(f"  created {p.parent}{os.sep}", file=sys.stderr)
+        p.write_text(text, encoding="utf-8")
+    except OSError as e:
+        print(f"could not write the {what} to {path_str}: {e.strerror or e}. "
+              f"The scan itself completed; only the file write failed.", file=sys.stderr)
+        return False
+    print(f"wrote {path_str}")
+    return True
+
+
+def _validate_dialect(name):
+    """Reject an unknown dialect before any work happens. Returns an error string, or "".
+
+    This is the most dangerous bug found in the whole stress pass, and it passed every check that
+    existed. `--dialect postgress` — one letter — does not raise. sqlglot is asked for the dialect
+    per file, every parse fails, every model lands in "could not be parsed", and the run ends:
+
+        Scanned **30 models**. Found **0** issues to review: 0 high, 0 medium, 0 low.
+        exit 0
+
+    A CI job with `--fail-on high` goes green on a project that was never read. That is precisely the
+    silent pass this tool exists to argue against, produced by the tool itself, and it is far worse
+    than any wrong finding: a wrong finding gets argued with, and this gets trusted.
+
+    sqlglot's own error even carries the suggestion, so there is no reason not to surface it.
+    """
+    if not name:
+        return ""
+    try:
+        import sqlglot
+        sqlglot.parse_one("SELECT 1", read=name)
+        return ""
+    except Exception as e:
+        msg = str(e)
+        if "Unknown dialect" not in msg:
+            return ""          # a parse problem with a valid dialect is not our business here
+    try:
+        from sqlglot.dialects import Dialects
+        known = sorted(d.value for d in Dialects if d.value)
+    except Exception:           # pragma: no cover
+        known = []
+    hint = ""
+    if known:
+        close = [k for k in known if k.startswith(name[:3].lower()) or name.lower().startswith(k)]
+        if close:
+            hint = f" Did you mean {' or '.join(close)}?"
+    return (f"unknown dialect '{name}'.{hint}\n"
+            + (f"  known dialects: {', '.join(known)}\n" if known else "")
+            + "  Refusing to continue: an unknown dialect makes every model fail to parse, and the "
+              "run would report zero findings on a project it never read.")
+
+
+def main(argv=None):
+    """CLI entry point, and the only place that turns an interrupt into an exit code.
+
+    A scan of a 2,000-model repository takes about ninety seconds, so pressing Ctrl-C is not an edge
+    case — it is something every user does, probably on their first run while they work out which
+    directory they meant. Before this wrapper they got a twenty-line traceback ending in
+    `KeyboardInterrupt`, which reads exactly like a crash.
+
+    128 + SIGINT (130) is the shell convention for "interrupted", and it is what `grep`, `curl` and
+    `git` return. A broken pipe gets the same treatment: `graincheck scan . | head -20` closes the
+    pipe under a still-printing process, and that must not look like a defect either.
+
+    Returns the process exit code: 0 normally, 1 when --fail-on is met or an output file could not be
+    written, 130 on Ctrl-C.
+    """
+    try:
+        return _main(argv)
+    except KeyboardInterrupt:
+        print("\ninterrupted.", file=sys.stderr)
+        return 130
+    except BrokenPipeError:
+        # The reader went away (`| head`). Close stdout before the interpreter tries to flush it,
+        # or Python prints its own "Exception ignored" noise at shutdown.
+        try:
+            sys.stdout.close()
+        except Exception:
+            pass
+        return 141
+
+
+def _main(argv=None):
+    _make_output_utf8_safe()
+    p = argparse.ArgumentParser(
+        prog="graincheck",
+        description="Catch metric logic errors before they reach production. Deterministic analytical-SQL integrity: grain, joins and aggregation.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="scan a directory of .sql files")
+    s.add_argument("path")
+    s.add_argument("--dialect", default=None, help="snowflake | bigquery | databricks | postgres | ...")
+    s.add_argument("--manifest", default=None,
+                   help="path to dbt target/manifest.json; auto-detected inside a dbt project")
+    s.add_argument("--json", dest="json_out", default=None)
+    s.add_argument("--report", default=None, help="client-facing report (.md or .html by extension)")
+    s.add_argument("--name", default=None, help="project name shown in the report header")
+    s.add_argument("--raw", action="store_true", help="terse developer listing instead of the report")
+    s.add_argument("--fail-on", default=None, choices=["high", "medium", "low"],
+                   help="exit 1 if any finding at or above this severity")
+    s.add_argument("--no-coverage", action="store_true",
+                   help="skip the join-key coverage measurement")
+
+    c = sub.add_parser("coverage",
+                       help="how many of this project's join keys are proven unique by a test")
+    c.add_argument("path")
+    c.add_argument("--dialect", default=None)
+    c.add_argument("--manifest", default=None)
+    c.add_argument("--json", dest="json_out", default=None)
+    c.add_argument("--emit-tests", dest="emit_tests", default=None,
+                   help="write a ready-to-paste schema.yml proving every unproven join key")
+    c.add_argument("--history", default=None,
+                   help="append this run to a JSON Lines file and show what moved since last time")
+
+    x = sub.add_parser("explain", help="walk through one model: grain, join path, risk, remediation")
+    x.add_argument("model", help="model name (file stem) or a path to a .sql file")
+    x.add_argument("--path", default=".", help="directory to search for the model (default: .)")
+    x.add_argument("--dialect", default=None)
+    x.add_argument("--manifest", default=None)
+
+    a = p.parse_args(argv)
+
+    problem = _validate_dialect(getattr(a, "dialect", None))
+    if problem:
+        print(problem, file=sys.stderr)
+        return 2
+
+    if a.cmd == "coverage":
+        root = Path(a.path)
+        rows, paths, summary = measure_full(root, a.dialect, _auto_manifest(root, a.manifest))
+        print(coverage_text(rows, summary, paths=paths))
+
+        project = dbt_project_root(root) or root
+        badges = incumbent.primary_key_tested(project)
+        fc = incumbent.find(rows, project)
+        fc_text = incumbent.to_text(fc, len(badges))
+        if fc_text:
+            print("\n" + fc_text)
+
+        if a.history:
+            cov_history.append(Path(a.history), summary, project)
+            print("\n" + cov_history.to_text(cov_history.read(Path(a.history))))
+
+        if a.emit_tests:
+            n = emit_tests.write(rows, Path(a.emit_tests))
+            print(f"\nwrote {a.emit_tests} — {n} relation(s) with a test that would prove the key")
+
+        if a.json_out and not _write_output(a.json_out, json.dumps(
+                {"summary": summary, "formulas": COVERAGE_FORMULAS,
+                 "joins": [r.to_dict() for r in rows],
+                 "metric_paths": [p.to_dict() for p in paths],
+                 "false_comfort": [x.to_dict() for x in fc]}, indent=2), "JSON output"):
+            return 1
+
+        return 0
+
+    if a.cmd == "explain":
+        root = Path(a.path)
+        print(explain(root, a.model, a.dialect, _auto_manifest(root, a.manifest)))
+        return 0
+
+    path = Path(a.path)
+    manifest = _auto_manifest(path, a.manifest)
+    findings, errors, n, uniques = scan_path(path, a.dialect, manifest)
+
+    advice = compile_advice(path, n, len(errors))
+    if advice:
+        print(f"\n  NOTE: {advice}\n", file=sys.stderr)
+    if manifest:
+        bad = load_uniques(manifest).get("__unreadable_manifest__")
+        if bad:
+            print(f"  WARNING: the manifest could not be read — {next(iter(next(iter(bad))))}\n"
+                  "  Continuing without it. Declared uniqueness tests are therefore unknown, so "
+                  "fan-out findings will say the grain could not be verified rather than being "
+                  "silently downgraded.", file=sys.stderr)
+            manifest = None
+    if manifest and not a.manifest:
+        print(f"  using manifest: {manifest}", file=sys.stderr)
+    elif not manifest:
+        print("  no dbt manifest found — join grain cannot be verified against declared uniqueness "
+              "tests. Fan-out findings will say so.", file=sys.stderr)
+
+    cov_summary = None
+    if not a.no_coverage:
+        _, _, cov_summary = measure_full(path, a.dialect, manifest)
+
+    name = a.name or path.resolve().name
+    if a.raw:
+        report = to_markdown(findings, errors, n, uniques)
+    else:
+        fmt = "html" if (a.report or "").lower().endswith((".html", ".htm")) else "md"
+        report = to_report(findings, errors, n, uniques, name, fmt, cov_summary)
+    write_failed = False
+    if a.report:
+        write_failed |= not _write_output(a.report, report, "report")
+    else:
+        print(report)
+    ex_text = exceptions_text(getattr(findings, "exceptions", None),
+                              getattr(findings, "suppressed", []))
+    if ex_text:
+        print("\n" + ex_text)
+
+    if a.json_out:
+        write_failed |= not _write_output(a.json_out, json.dumps(
+            {"findings": [f.to_dict() for f in findings],
+             "reviewed_exceptions": [f.to_dict()
+                                     for f in getattr(findings, "suppressed", [])],
+             "errors": errors,
+             "models_scanned": n, "models_parsed": n - len(errors),
+             "join_key_coverage": cov_summary,
+             "compile_advice": advice}, indent=2), "JSON output")
+
+    if write_failed:
+        return 1
+    if a.fail_on:
+        order = {"high": 0, "medium": 1, "low": 2}
+        if any(order.get(f.severity, 9) <= order[a.fail_on] for f in findings):
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

graincheck/_deps.py

@@ -0,0 +1,45 @@
+"""One warning, about one missing dependency, in a module that imports nothing.
+
+PyYAML is not optional. `schema.yml` is graincheck's only source of declared uniqueness when a project
+has not been compiled — which is the case graincheck exists for, since not making the user run
+`dbt compile` first is half the pitch. Three modules import yaml to read those files.
+
+It was missing from `pyproject.toml`'s dependency list, and each ImportError was swallowed with
+`return {}`. So a clean `pip install graincheck` produced a tool that read no schema files and said
+nothing about it. That is not a reduced answer, it is a DIFFERENT one:
+
+    four-line project, schema.yml declares customer_id unique
+      with PyYAML:     0 findings
+      without PyYAML:  1 finding, JOIN_FANOUT, high impact
+
+A correct join reported as a fan-out, at normal confidence, with no indication that the evidence
+proving it safe was never opened. Of the six defects found in the packaging pass this was the only one
+that produced a confident wrong answer rather than a crash, which makes it the worst of them.
+
+The dependency is declared now. This module is the belt to that braces: if PyYAML is ever absent
+anyway — an old install, a stripped container, a conda environment assembled by hand — the user is
+told, once per thing it cost, on stderr, in terms of what it does to the findings.
+
+It lives in its own module because `incumbent` and `exceptions` both need it and both are imported by
+`scanner`; hanging it off `scanner` created a circular import.
+"""
+from __future__ import annotations
+
+import sys
+
+_WARNED: set[str] = set()
+
+
+def warn_no_yaml(what: str) -> None:
+    """Report that PyYAML is missing and what it cost. Idempotent per `what`."""
+    if what in _WARNED:
+        return
+    _WARNED.add(what)
+    print(f"  WARNING: PyYAML is not installed, so {what} were not read. Findings will be WRONG, "
+          f"not merely fewer — a join your schema.yml proves safe will be reported as a fan-out. "
+          f"Fix with: pip install pyyaml", file=sys.stderr)
+
+
+def reset_for_tests() -> None:
+    """Forget what has been warned about, so a test can assert the warning appears."""
+    _WARNED.clear()