resint 0.1.0__py3-none-any.whl

resint/__init__.py

@@ -0,0 +1,39 @@
+"""resint -- a linter for research papers.
+
+The public surface is deliberately small. Everything a wrapper needs is here:
+build a Paper, run rules over it, format the result. The CLI is one consumer
+of this API and holds no analysis of its own, which is what keeps the next
+surface -- Action, MCP server, editor extension -- a thin file rather than a
+rewrite.
+"""
+
+from .config import Config, discover, parse as parse_config
+from .engine import Report, run
+from .ir.finding import Finding, Severity, Tier
+from .ir.span import Source, Span
+from .parse.document import paper_from_latex, paper_from_path
+from .rules import REGISTRY, Context, Registry, Rule, load_all, rule
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Config",
+    "Context",
+    "Finding",
+    "REGISTRY",
+    "Registry",
+    "Report",
+    "Rule",
+    "Severity",
+    "Source",
+    "Span",
+    "Tier",
+    "__version__",
+    "discover",
+    "load_all",
+    "paper_from_latex",
+    "paper_from_path",
+    "parse_config",
+    "rule",
+    "run",
+]

resint/cli.py

@@ -0,0 +1,246 @@
+"""Command line entry point.
+
+Deliberately thin. Every surface after this one -- GitHub Action, MCP server,
+editor extension -- wraps the same library, so any analysis that leaks into
+here is analysis that has to be rewritten for surface two. Nothing in this
+module decides anything about a paper; it parses arguments, calls the
+library, and formats what comes back.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from .config import Config, ConfigError, discover, parse as parse_config
+from .engine import run
+from .ir.finding import Severity
+from .parse.document import paper_from_path
+from .parse.repo import read_repo
+from .report.sarif import render as render_sarif
+from .report.terminal import render
+from .resolve import CachingResolver, NullResolver
+from .resolve.http import HttpResolver
+from .rules import load_all
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_USAGE = 2
+
+
+def _load_config(args: argparse.Namespace, target: Path) -> Config:
+    if args.no_config:
+        return Config()
+    if args.config:
+        path = Path(args.config)
+        if not path.is_file():
+            raise ConfigError(f"no such config file: {path}")
+        return parse_config(path.read_text(encoding="utf-8"), path)
+    return discover(target)
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    target = Path(args.target)
+    if not target.exists():
+        print(f"resint: no such file: {target}", file=sys.stderr)
+        return EXIT_USAGE
+
+    try:
+        config = _load_config(args, target)
+    except ConfigError as exc:
+        print(f"resint: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+    registry = load_all()
+
+    # Only bibliographic metadata leaves the machine -- titles and DOIs of
+    # works the paper already cites publicly. The manuscript itself is never
+    # transmitted. --offline skips it entirely, at the cost of the reference
+    # rules abstaining rather than reporting.
+    resolver = (
+        NullResolver()
+        if args.offline
+        else CachingResolver(HttpResolver(mailto=args.mailto))
+    )
+
+    started = time.perf_counter()
+    paper = paper_from_path(target, bib=args.bib, resolver=resolver)
+
+    # Only build the repository IR when a repository was actually given.
+    # Walking a tree nobody asked about is the kind of cost that makes a
+    # linter feel slow for no benefit.
+    repo = None
+    if args.repo:
+        needed = {
+            req
+            for r in registry.all()
+            for req in r.requires
+            if req.startswith("repo.")
+        }
+        repo = read_repo(args.repo, needs=needed)
+
+    report = run(
+        paper,
+        repo=repo,
+        registry=registry,
+        has_provider=False,
+        min_severity=Severity(args.min_severity) if args.min_severity else None,
+        config=config,
+    )
+    elapsed = time.perf_counter() - started
+
+    if args.format == "json":
+        print(
+            json.dumps(
+                {
+                    "version": __version__,
+                    "target": str(target),
+                    "findings": [f.to_dict() for f in report.findings],
+                    "unchecked": report.unchecked,
+                    "notes": report.notes,
+                    "skipped": report.skipped,
+                    "counts": report.counts(),
+                },
+                indent=2,
+            )
+        )
+    elif args.format == "sarif":
+        print(render_sarif(report, registry, version=__version__))
+    else:
+        print(render(report, target.name, elapsed))
+
+    if args.fail_on == "none":
+        return EXIT_OK
+    counts = report.counts()
+    floor = {"high": ("high",), "med": ("high", "med"), "low": ("high", "med", "low")}
+    triggered = any(counts[level] for level in floor[args.fail_on])
+    return EXIT_FINDINGS if triggered else EXIT_OK
+
+
+def _cmd_rules(args: argparse.Namespace) -> int:
+    registry = load_all()
+    rules = registry.all()
+    if args.tier:
+        rules = [r for r in rules if r.tier.value == args.tier]
+    if args.family:
+        rules = [r for r in rules if r.family == args.family]
+
+    if args.format == "json":
+        print(
+            json.dumps(
+                [
+                    {
+                        "id": r.id,
+                        "severity": r.severity.value,
+                        "tier": r.tier.value,
+                        "requires": list(r.requires),
+                        "needs_repo": r.needs_repo,
+                        "cannot_detect": r.cannot_detect,
+                    }
+                    for r in rules
+                ],
+                indent=2,
+            )
+        )
+        return EXIT_OK
+
+    for r in rules:
+        extra = "  --repo" if r.needs_repo else ""
+        print(f"{r.id:<30} {r.severity.value:<5} {r.tier.value}{extra}")
+        print(f"    cannot detect: {r.cannot_detect}")
+        print()
+    print(f"{len(rules)} rules")
+    return EXIT_OK
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    path = Path(args.path) / ".resint.yml"
+    if path.exists() and not args.force:
+        print(f"resint: {path} already exists (use --force to overwrite)", file=sys.stderr)
+        return EXIT_USAGE
+
+    path.write_text(TEMPLATE, encoding="utf-8")
+    print(f"wrote {path}")
+    return EXIT_OK
+
+
+TEMPLATE = """\
+# resint configuration. Commit this alongside the paper.
+version: 1
+
+# Every suppression states a reason. That is deliberate: this file is the
+# record of each judgement made about the work, and a silenced finding with
+# no explanation is unauditable six months later.
+#
+# Suppressed findings still appear in JSON and SARIF output marked with their
+# reason, so a suppression can never hide a regression.
+suppress:
+  # - rule: bib/metadata-drift
+  #   match: "[vaswani2017]"
+  #   reason: "Cites the proceedings version deliberately."
+  #   expires: "2027-01-01"
+
+# Turn a rule off entirely when it does not apply to this work.
+rules:
+  # stats/grim: off        # no integer-scale response data here
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="resint", description="A linter for research papers."
+    )
+    parser.add_argument("--version", action="version", version=f"resint {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="check a paper")
+    check.add_argument("target", help="path to a .tex source file")
+    check.add_argument("--repo", default=None, help="path to the paper's repository")
+    check.add_argument(
+        "--bib", default=None, help="bibliography (default: the .bib beside the source)"
+    )
+    check.add_argument(
+        "--format", choices=["term", "json", "sarif"], default="term"
+    )
+    check.add_argument("--min-severity", choices=["low", "med", "high"], default=None)
+    check.add_argument(
+        "--fail-on",
+        choices=["high", "med", "low", "none"],
+        default="high",
+        help="lowest severity that exits non-zero (default: high)",
+    )
+    check.add_argument(
+        "--offline",
+        action="store_true",
+        help="skip reference lookups; the bib rules abstain rather than guess",
+    )
+    check.add_argument(
+        "--mailto", default=None, help="contact address for the Crossref polite pool"
+    )
+    check.add_argument("--config", default=None, help="path to a .resint.yml")
+    check.add_argument(
+        "--no-config", action="store_true", help="ignore any .resint.yml"
+    )
+    check.set_defaults(fn=_cmd_check)
+
+    rules = sub.add_parser("rules", help="list rules and their blind spots")
+    rules.add_argument("--tier", choices=["deterministic", "model-assisted"], default=None)
+    rules.add_argument("--family", default=None, help="e.g. stats, bib, numbers")
+    rules.add_argument("--format", choices=["term", "json"], default="term")
+    rules.set_defaults(fn=_cmd_rules)
+
+    init = sub.add_parser("init", help="write a .resint.yml")
+    init.add_argument("path", nargs="?", default=".", help="directory (default: .)")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(fn=_cmd_init)
+
+    args = parser.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

resint/config.py

@@ -0,0 +1,191 @@
+"""Project configuration and suppression.
+
+A suppression requires a stated reason. That is the whole design: a linter
+that lets findings be silenced without explanation accumulates a config file
+nobody can audit, and in this domain the config file is the record of every
+judgement an author made about their own work.
+
+Suppression happens at the reporting layer, never during evaluation. The
+finding is still produced, still counted, and still present in JSON output
+marked with its reason. A suppression can therefore never hide a regression
+from the corpus, and every suppression doubles as a labelled false positive
+for the rule that produced it.
+
+The parser is a small YAML subset rather than a dependency. resint installs
+with nothing but the standard library, and a config format that needs a
+third-party parser would trade that away for two levels of nesting.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+
+CONFIG_NAMES = (".resint.yml", ".resint.yaml")
+
+_KEY = re.compile(r"^(?P<indent>\s*)(?P<dash>- )?(?P<key>[A-Za-z_][\w./-]*)\s*:\s*(?P<value>.*)$")
+_ITEM = re.compile(r"^(?P<indent>\s*)- (?P<value>.+)$")
+
+
+class ConfigError(ValueError):
+    """Raised when a config file cannot be honoured as written."""
+
+
+@dataclass(frozen=True, slots=True)
+class Suppression:
+    rule: str
+    reason: str
+    match: str | None = None
+    expires: date | None = None
+
+    def expired(self, today: date | None = None) -> bool:
+        if self.expires is None:
+            return False
+        return (today or date.today()) > self.expires
+
+    def applies_to(self, finding) -> bool:
+        if finding.rule_id != self.rule:
+            return False
+        if self.match and self.match not in finding.message:
+            return False
+        return True
+
+
+@dataclass
+class Config:
+    suppressions: list[Suppression] = field(default_factory=list)
+    disabled: set[str] = field(default_factory=set)
+    path: Path | None = None
+
+    def apply(self, findings, today: date | None = None) -> tuple[list, list[str]]:
+        """Return (findings with suppressions marked, notes about the config)."""
+        notes: list[str] = []
+        live = [s for s in self.suppressions if not s.expired(today)]
+
+        for stale in (s for s in self.suppressions if s.expired(today)):
+            notes.append(
+                f"suppression for {stale.rule} expired on {stale.expires}; "
+                "the finding is reported again"
+            )
+
+        out = []
+        for finding in findings:
+            match = next((s for s in live if s.applies_to(finding)), None)
+            out.append(finding.suppress(match.reason) if match else finding)
+
+        used = {s.rule for f in out if f.suppressed for s in live if s.applies_to(f)}
+        for unused in {s.rule for s in live} - used:
+            notes.append(
+                f"suppression for {unused} matched nothing; the rule may have "
+                "changed or the finding may already be fixed"
+            )
+
+        return out, notes
+
+    def enabled(self, rule_id: str) -> bool:
+        return rule_id not in self.disabled
+
+
+def _strip_comment(line: str) -> str:
+    out, quote = [], None
+    for ch in line:
+        if quote:
+            if ch == quote:
+                quote = None
+        elif ch in "\"'":
+            quote = ch
+        elif ch == "#":
+            break
+        out.append(ch)
+    return "".join(out)
+
+
+def _unquote(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value
+
+
+def parse(text: str, path: Path | None = None) -> Config:
+    """Parse the .resint.yml subset: top-level keys, one list of mappings."""
+    config = Config(path=path)
+    section: str | None = None
+    current: dict[str, str] | None = None
+    raw_suppressions: list[dict[str, str]] = []
+
+    for lineno, original in enumerate(text.splitlines(), 1):
+        line = _strip_comment(original).rstrip()
+        if not line.strip():
+            continue
+
+        top = _KEY.match(line)
+        if top and not top.group("indent") and not top.group("dash"):
+            key, value = top.group("key"), _unquote(top.group("value"))
+            if key in ("suppress", "rules"):
+                section = key
+                current = None
+                continue
+            section = None
+            continue
+
+        if section == "suppress":
+            item = _ITEM.match(line)
+            if item:
+                current = {}
+                raw_suppressions.append(current)
+                inner = _KEY.match("  " + item.group("value"))
+                if inner:
+                    current[inner.group("key")] = _unquote(inner.group("value"))
+                continue
+            nested = _KEY.match(line)
+            if nested and current is not None:
+                current[nested.group("key")] = _unquote(nested.group("value"))
+            continue
+
+        if section == "rules":
+            nested = _KEY.match(line)
+            if nested:
+                state = _unquote(nested.group("value")).lower()
+                if state in ("off", "false", "no", "disabled"):
+                    config.disabled.add(nested.group("key"))
+            continue
+
+    for index, entry in enumerate(raw_suppressions, 1):
+        rule = entry.get("rule")
+        if not rule:
+            raise ConfigError(f"suppression {index} has no rule")
+        reason = entry.get("reason", "").strip()
+        if not reason:
+            raise ConfigError(
+                f"suppression {index} for {rule!r} has no reason. "
+                "Every suppression must say why, so the file stays auditable."
+            )
+        expires = None
+        if entry.get("expires"):
+            try:
+                expires = date.fromisoformat(entry["expires"])
+            except ValueError as exc:
+                raise ConfigError(
+                    f"suppression {index} for {rule!r}: {exc}"
+                ) from exc
+        config.suppressions.append(
+            Suppression(
+                rule=rule, reason=reason, match=entry.get("match"), expires=expires
+            )
+        )
+
+    return config
+
+
+def discover(start: Path) -> Config:
+    """Find the nearest config walking up from ``start``."""
+    here = start if start.is_dir() else start.parent
+    for directory in (here, *here.parents):
+        for name in CONFIG_NAMES:
+            candidate = directory / name
+            if candidate.is_file():
+                return parse(candidate.read_text(encoding="utf-8"), candidate)
+    return Config()

resint/engine.py

@@ -0,0 +1,122 @@
+"""Rule selection and execution.
+
+Selection is the interesting part. A rule is skipped -- silently, and without
+being counted as passing -- whenever the run cannot satisfy what it declared:
+no repository for a repo rule, no provider for a model-assisted one. The
+report says which rules did not run and why, because "no findings" and "did
+not look" are different statements and conflating them is how a checker
+becomes misleading.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .config import Config
+from .ir.finding import Finding, Severity, Tier
+from .rules import REGISTRY, Context, Registry, Rule, load_all
+
+_SEVERITY_RANK = {Severity.HIGH: 0, Severity.MED: 1, Severity.LOW: 2}
+
+
+@dataclass
+class Report:
+    findings: list[Finding] = field(default_factory=list)
+    skipped: dict[str, str] = field(default_factory=dict)
+    unchecked: list[str] = field(default_factory=list)
+    ran: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def used_model(self) -> bool:
+        return any(f.tier is Tier.MODEL_ASSISTED for f in self.findings)
+
+    def counts(self) -> dict[str, int]:
+        out = {"high": 0, "med": 0, "low": 0}
+        for f in self.findings:
+            if not f.suppressed:
+                out[f.severity.value] += 1
+        return out
+
+    def summary(self) -> str:
+        c = self.counts()
+        total = sum(c.values())
+        noun = "finding" if total == 1 else "findings"
+        return (
+            f"{total} {noun} "
+            f"({c['high']} high, {c['med']} med, {c['low']} low)"
+        )
+
+
+def selectable(
+    rules: list[Rule], *, has_repo: bool, has_provider: bool
+) -> tuple[list[Rule], dict[str, str]]:
+    """Split rules into those this run can honestly execute, and why not."""
+    runnable, skipped = [], {}
+    for r in rules:
+        if r.needs_repo and not has_repo:
+            skipped[r.id] = "no repository supplied"
+        elif r.tier is Tier.MODEL_ASSISTED and not has_provider:
+            skipped[r.id] = "no model provider configured"
+        else:
+            runnable.append(r)
+    return runnable, skipped
+
+
+def required_slices(rules: list[Rule]) -> set[str]:
+    return {req for r in rules for req in r.requires}
+
+
+def run(
+    paper,
+    repo=None,
+    *,
+    registry: Registry | None = None,
+    has_provider: bool = False,
+    min_severity: Severity | None = None,
+    config: Config | None = None,
+) -> Report:
+    reg = registry or load_all()
+    settings = config or Config()
+    candidates = [r for r in reg.all() if settings.enabled(r.id)]
+    runnable, skipped = selectable(
+        candidates, has_repo=repo is not None, has_provider=has_provider
+    )
+    for disabled in sorted(settings.disabled):
+        if disabled in reg:
+            skipped[disabled] = "disabled in .resint.yml"
+
+    report = Report(skipped=skipped, ran=[r.id for r in runnable])
+    report.unchecked = list(getattr(paper, "unchecked", []))
+
+    if repo is not None:
+        report.unchecked.extend(getattr(repo, "unchecked", []))
+
+    ctx = Context(paper=paper, repo=repo)
+    for rule in runnable:
+        report.findings.extend(rule.run(ctx))
+    report.unchecked.extend(ctx.abstentions)
+
+    # Rules may discover during evaluation that an input was ambiguous.
+    # Those notes are collected after the run rather than before, since a
+    # rule abstaining is exactly the moment the reason becomes known.
+    for note in getattr(paper, "unchecked", []):
+        if note not in report.unchecked:
+            report.unchecked.append(note)
+
+    # Suppression is a reporting concern, applied after every rule has run:
+    # a suppressed finding still exists, is still counted in JSON, and can
+    # therefore never hide a regression from the corpus.
+    report.findings, notes = settings.apply(report.findings)
+    report.notes.extend(notes)
+
+    if min_severity is not None:
+        floor = _SEVERITY_RANK[min_severity]
+        report.findings = [
+            f for f in report.findings if _SEVERITY_RANK[f.severity] <= floor
+        ]
+
+    report.findings.sort(
+        key=lambda f: (_SEVERITY_RANK[f.severity], f.rule_id, f.anchors[0].start)
+    )
+    return report