truthlint 0.1.0__py3-none-any.whl

truthlint/__init__.py

@@ -0,0 +1,10 @@
+"""truthlint - find where your repository contradicts itself.
+
+Finds the places where a repository's documentation, configuration, CI,
+containers and code contradict each other. Fully offline; never executes
+anything from the repository it inspects.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

truthlint/__main__.py

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

truthlint/cli.py

@@ -0,0 +1,408 @@
+"""Command-line interface (Typer)."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.markup import escape
+from rich.prompt import Prompt
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.text import Text
+
+from . import __version__
+from .engine import scan as run_scan
+from .fixes import EditConflict, apply_finding, build_patches, finding_patches, write_patch
+from .models import ScanResult, Severity
+from .render.json_report import render_json
+from .render.markdown import render_markdown
+from .render.terminal import render_explain, render_finding, render_profile, render_scan
+from .rules import DEEP_ONLY, RULES
+
+app = typer.Typer(
+    name="truthlint",
+    help="truthlint - find where your docs, configs, CI, containers and code contradict each other.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+out = Console(soft_wrap=False)
+err = Console(stderr=True)
+
+
+class ScanFormat(StrEnum):
+    terminal = "terminal"
+    json = "json"
+    markdown = "markdown"
+
+
+class ReportFormat(StrEnum):
+    markdown = "markdown"
+    json = "json"
+
+
+PathArg = Annotated[Path, typer.Argument(help="Repository to analyse.", show_default=True)]
+DeepOpt = Annotated[
+    bool,
+    typer.Option(
+        "--deep",
+        help="Also run heuristic checks (unused dependencies/env vars, stale doc paths, CI coverage) and read nested docs.",
+    ),
+]
+ExcludeOpt = Annotated[
+    list[str] | None,
+    typer.Option("--exclude", "-x", help="Glob to exclude (gitignore syntax). Repeatable."),
+]
+NoIgnoreOpt = Annotated[
+    bool, typer.Option("--no-gitignore", help="Do not honour .gitignore files.")
+]
+
+
+def _version(value: bool) -> None:
+    if value:
+        out.print(f"truthlint {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", "-V", callback=_version, is_eager=True, help="Show version and exit."
+        ),
+    ] = False,
+) -> None:
+    """truthlint investigates a repository and reports what it CLAIMS vs what it DOES."""
+
+
+def _do_scan(
+    path: Path, deep: bool, exclude: list[str] | None, no_gitignore: bool, quiet: bool = False
+) -> ScanResult:
+    if not path.exists() or not path.is_dir():
+        err.print(f"[red]error:[/] {escape(str(path))} is not a directory")
+        raise typer.Exit(2)
+    show = not quiet and err.is_terminal
+    if show:
+        with err.status("[magenta]Investigating repository…", spinner="dots") as status:
+            return run_scan(
+                path,
+                deep=deep,
+                exclude=exclude or [],
+                respect_gitignore=not no_gitignore,
+                progress=lambda m: status.update(f"[magenta]{m}…"),
+            )
+    return run_scan(path, deep=deep, exclude=exclude or [], respect_gitignore=not no_gitignore)
+
+
+def _write(text: str, output: Path | None) -> None:
+    if output is None:
+        sys.stdout.write(text if text.endswith("\n") else text + "\n")
+        sys.stdout.flush()
+    else:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(text, encoding="utf-8")
+        err.print(f"[green]✔[/] wrote {escape(str(output))}")
+
+
+@app.command()
+def scan(
+    path: PathArg = Path("."),
+    deep: DeepOpt = False,
+    exclude: ExcludeOpt = None,
+    no_gitignore: NoIgnoreOpt = False,
+    fmt: Annotated[
+        ScanFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = ScanFormat.terminal,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write the report to a file instead of stdout."),
+    ] = None,
+    limit: Annotated[
+        int, typer.Option(help="Max findings to print in the terminal (0 = all).")
+    ] = 25,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Show excerpts and patches for every finding.")
+    ] = False,
+    fail_under: Annotated[
+        int | None,
+        typer.Option(
+            "--fail-under",
+            help="Exit with code 1 if the Truth Score is below this value (CI gate).",
+        ),
+    ] = None,
+    fail_on: Annotated[
+        Severity | None,
+        typer.Option("--fail-on", help="Exit with code 1 if any finding is at least this severe."),
+    ] = None,
+) -> None:
+    """Investigate a repository and report contradictions between its claims and reality."""
+    result = _do_scan(
+        path, deep, exclude, no_gitignore, quiet=fmt != ScanFormat.terminal and output is None
+    )
+    if fmt == ScanFormat.json:
+        _write(render_json(result), output)
+    elif fmt == ScanFormat.markdown:
+        _write(render_markdown(result), output)
+    else:
+        if output:
+            with open(output, "w", encoding="utf-8") as fh:
+                console = Console(file=fh, width=120, force_terminal=False, color_system=None)
+                render_scan(console, result, limit=None if limit == 0 else limit, verbose=verbose)
+            err.print(f"[green]✔[/] wrote {escape(str(output))}")
+        else:
+            render_scan(out, result, limit=None if limit == 0 else limit, verbose=verbose)
+    _gate(result, fail_under, fail_on)
+
+
+def _gate(result: ScanResult, fail_under: int | None, fail_on: Severity | None) -> None:
+    failed = False
+    if fail_under is not None and result.truth.score < fail_under:
+        err.print(f"[red]✘ Truth Score {result.truth.score} is below --fail-under {fail_under}[/]")
+        failed = True
+    if fail_on is not None and any(f.severity.rank >= fail_on.rank for f in result.findings):
+        err.print(f"[red]✘ found {fail_on.value}-or-worse findings (--fail-on {fail_on.value})[/]")
+        failed = True
+    if failed:
+        raise typer.Exit(1)
+
+
+@app.command()
+def report(
+    path: PathArg = Path("."),
+    fmt: Annotated[
+        ReportFormat, typer.Option("--format", "-f", help="Report format.")
+    ] = ReportFormat.markdown,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Output file (default: stdout).")
+    ] = None,
+    deep: DeepOpt = False,
+    exclude: ExcludeOpt = None,
+    no_gitignore: NoIgnoreOpt = False,
+) -> None:
+    """Generate a full Markdown or JSON report with evidence, confidence and patches."""
+    result = _do_scan(path, deep, exclude, no_gitignore, quiet=output is None)
+    _write(render_markdown(result) if fmt == ReportFormat.markdown else render_json(result), output)
+
+
+@app.command()
+def explain(
+    issue_id: Annotated[
+        str,
+        typer.Argument(
+            help="Finding ID (e.g. TL201-3FA2C1, prefix allowed) or rule ID (e.g. TL201)."
+        ),
+    ],
+    path: PathArg = Path("."),
+    exclude: ExcludeOpt = None,
+    no_gitignore: NoIgnoreOpt = False,
+) -> None:
+    """Explain a finding in depth (evidence in context, rationale, proposed patch) or describe a rule."""
+    key = issue_id.strip().upper()
+    if key in RULES:
+        r = RULES[key]
+        out.print(
+            f"[bold]{r.id}[/] — [bold]{escape(r.title)}[/]  [dim]({r.category.value}, default severity {r.default_severity.value}{', --deep only' if r.id in DEEP_ONLY else ''})[/]\n"
+        )
+        out.print(Text(r.description + "\n"))
+        out.print("[bold]Why it matters[/]")
+        out.print(Text(r.rationale))
+        return
+    result = _do_scan(path, False, exclude, no_gitignore)
+    f = result.find(key)
+    if f is None:
+        result = _do_scan(
+            path, True, exclude, no_gitignore
+        )  # finding may come from a deep-only rule
+        f = result.find(key)
+    if f is None:
+        err.print(
+            f"[red]No finding matches {escape(repr(issue_id))}.[/] Run [bold]truthlint scan[/] to list current IDs (IDs are stable as long as the underlying issue is unchanged)."
+        )
+        raise typer.Exit(2)
+    render_explain(out, result, f)
+
+
+@app.command()
+def fix(
+    path: PathArg = Path("."),
+    interactive: Annotated[
+        bool,
+        typer.Option(
+            "--interactive", "-i", help="Review each patch and choose whether to apply it."
+        ),
+    ] = False,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write all patches to a unified diff file (apply with `git apply`).",
+        ),
+    ] = None,
+    only: Annotated[
+        list[str] | None, typer.Option("--only", help="Restrict to these finding IDs. Repeatable.")
+    ] = None,
+    deep: DeepOpt = False,
+    exclude: ExcludeOpt = None,
+    no_gitignore: NoIgnoreOpt = False,
+) -> None:
+    """Show, export or (with --interactive) apply suggested fixes. Files are never modified without your confirmation."""
+    result = _do_scan(path, deep, exclude, no_gitignore)
+    wanted = {o.upper() for o in only or []}
+    candidates = [
+        f
+        for f in result.findings
+        if f.fix.edits and (not wanted or any(f.id.upper().startswith(w) for w in wanted))
+    ]
+    manual = [
+        f
+        for f in result.findings
+        if not f.fix.edits and (not wanted or any(f.id.upper().startswith(w) for w in wanted))
+    ]
+    root = Path(result.root)
+    if not candidates:
+        out.print(
+            "[yellow]No automatic fixes available.[/]"
+            + (
+                f" {len(manual)} finding(s) need a manual fix; see `truthlint explain <ID>`."
+                if manual
+                else ""
+            )
+        )
+        return
+
+    if output is not None:
+        patches, errors = build_patches(root, candidates)
+        _write(write_patch(patches), output)
+        for e in errors:
+            err.print(Text(f"skipped: {e}", style="yellow"))
+        out.print(f"Review it, then apply with: [bold]git apply {escape(str(output))}[/]")
+        return
+
+    if not interactive:
+        out.print(
+            f"[bold]{len(candidates)}[/] finding(s) have proposed patches (dry run — nothing was changed):\n"
+        )
+        for f in candidates:
+            render_finding(out, f, verbose=True, root=root)
+        out.print(
+            Text(
+                "To apply: truthlint fix --interactive   ·   To export: truthlint fix -o truthlint-fixes.patch",
+                style="bold",
+            )
+        )
+        if manual:
+            out.print(
+                Text(
+                    f"{len(manual)} other finding(s) need a manual fix (see `truthlint explain <ID>`).",
+                    style="dim",
+                )
+            )
+        return
+
+    if not _stdin_is_tty():
+        err.print("[red]--interactive needs a terminal.[/] Use --output to export a patch instead.")
+        raise typer.Exit(2)
+    applied, skipped = [], []
+    for i, f in enumerate(candidates, 1):
+        out.rule(f"[bold]{i}/{len(candidates)}[/]")
+        render_finding(out, f, verbose=False, root=root)
+        patches, errors = finding_patches(root, f)
+        if errors:
+            out.print(Text(f"Cannot build patch: {'; '.join(errors)}", style="yellow"))
+            skipped.append(f.id)
+            continue
+        out.print(
+            Syntax(
+                "".join(p.diff for p in patches),
+                "diff",
+                theme="ansi_dark",
+                background_color="default",
+            )
+        )
+        choice = Prompt.ask("Apply this change?", choices=["y", "n", "q"], default="n")
+        if choice == "q":
+            break
+        if choice != "y":
+            skipped.append(f.id)
+            continue
+        try:
+            changed = apply_finding(root, f)
+            applied.append(f.id)
+            out.print(Text("✔ applied → " + ", ".join(changed), style="green"))
+        except (EditConflict, OSError, ValueError) as exc:
+            out.print(Text(f"✘ not applied: {exc}", style="red"))
+            skipped.append(f.id)
+    out.print()
+    out.print(
+        f"[bold]{len(applied)}[/] applied, {len(skipped)} skipped. Re-run [bold]truthlint scan[/] to see the updated score."
+    )
+
+
+@app.command()
+def rules() -> None:
+    """List every rule truthlint checks."""
+    table = Table(box=box.SIMPLE_HEAD, show_lines=False)
+    table.add_column("Rule", style="bold cyan", no_wrap=True)
+    table.add_column("Title")
+    table.add_column("Category", style="dim")
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("Mode", style="dim")
+    for r in sorted(RULES.values(), key=lambda r: r.id):
+        table.add_row(
+            r.id,
+            r.title,
+            r.category.value,
+            r.default_severity.value,
+            "deep" if r.id in DEEP_ONLY else "default",
+        )
+    out.print(table)
+    out.print("[dim]Run `truthlint explain TL201` for details on any rule.[/]")
+
+
+@app.command()
+def inspect(
+    path: PathArg = Path("."),
+    exclude: ExcludeOpt = None,
+    no_gitignore: NoIgnoreOpt = False,
+) -> None:
+    """Show what truthlint understands about a repository (languages, tooling, key files)."""
+    result = _do_scan(path, False, exclude, no_gitignore)
+    render_profile(out, result)
+    table = Table(box=box.SIMPLE_HEAD)
+    table.add_column("Group", style="bold")
+    table.add_column("Files")
+    for group, files in result.profile.key_files.items():
+        table.add_row(
+            group,
+            "\n".join(files[:12]) + (f"\n… {len(files) - 12} more" if len(files) > 12 else ""),
+        )
+    out.print(table)
+
+
+def _stdin_is_tty() -> bool:
+    return sys.stdin.isatty()
+
+
+def _utf8_stdio() -> None:
+    """Legacy Windows consoles default to cp1252, which cannot print the UI glyphs."""
+    for stream in (sys.stdout, sys.stderr):
+        enc = (getattr(stream, "encoding", None) or "").lower().replace("-", "")
+        if enc != "utf8" and hasattr(stream, "reconfigure"):
+            with contextlib.suppress(ValueError, OSError):
+                stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def main() -> None:
+    _utf8_stdio()
+    app()

truthlint/config.py

@@ -0,0 +1,57 @@
+"""User configuration: ``.truthlint.toml`` or ``[tool.truthlint]`` in ``pyproject.toml``.
+
+Example::
+
+    [tool.truthlint]
+    exclude = ["examples/**", "vendor/"]
+    disable = ["TL402"]
+    ignore_env = ["MY_CI_ONLY_VAR"]
+    min_severity = "low"
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+from .models import Severity
+
+
+class TraceConfig(BaseModel):
+    exclude: list[str] = Field(default_factory=list)
+    disable: list[str] = Field(default_factory=list)
+    ignore_env: list[str] = Field(default_factory=list)
+    min_severity: Severity = Severity.INFO
+    max_file_size: int = 1_000_000
+    max_files: int = 50_000
+
+    @field_validator("disable")
+    @classmethod
+    def _upper(cls, v: list[str]) -> list[str]:
+        return [x.strip().upper() for x in v]
+
+
+def load_config(root: Path) -> tuple[TraceConfig, str | None, str | None]:
+    """Return (config, source_path, error_message)."""
+    candidates = [root / ".truthlint.toml", root / "pyproject.toml"]
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8", errors="replace"))
+        except tomllib.TOMLDecodeError as exc:
+            if path.name == ".truthlint.toml":
+                return TraceConfig(), path.name, f"invalid TOML: {exc}"
+            continue  # malformed pyproject is reported by the TL001 rule instead
+        section = data if path.name == ".truthlint.toml" else data.get("tool", {}).get("truthlint")
+        if section is None:
+            continue
+        if path.name == ".truthlint.toml" and "tool" in section and "truthlint" in section["tool"]:
+            section = section["tool"]["truthlint"]
+        try:
+            return TraceConfig.model_validate(section), path.name, None
+        except ValidationError as exc:
+            return TraceConfig(), path.name, f"invalid configuration: {exc.errors()[0]['msg']}"
+    return TraceConfig(), None, None