truthlint

Your repository is lying. truthlint finds where: an offline CLI that cross-checks docs, configs, CI, containers and code, and reports every contradiction with file-and-line evidence.

Comment

Inspiration

Every file in a repository can be individually "fine" while the repository as a whole lies: the README says Python 3.8+, pyproject.toml says >=3.10, the Dockerfile runs 3.9, the setup guide tells newcomers to run a make target that was renamed, and the code reads an environment variable that isn't in .env.example. Linters check one file at a time, type checkers check code, link checkers check URLs — nothing checks that the files agree with each other. That gap is where onboarding breaks and deployments drift.

What it does

truthlint reads a repository the way a careful new contributor would, then cross-examines every file against every other file and reports, with evidence, where the project's claims and its reality disagree.

  • Cross-file analysis: 35 rules comparing README, docs, pyproject.toml, requirements files, package.json, lockfiles, Dockerfiles, compose files, GitHub Actions / GitLab CI, Makefiles, .env examples and source code.
  • Evidence, always: every finding cites the exact file and line on each side of the contradiction, plus a confidence level.
  • Onboarding audit: walks the setup instructions step by step and statically verifies each command — does that npm script, make target, file, compose service or pip extra actually exist?
  • Explainable scores: a 0–100 Repository Truth Score and an Onboarding Reliability Score, with every deduction itemised.
  • Reviewable fixes: a suggested fix for every finding, many with a unified-diff patch; nothing is written without explicit confirmation (truthlint fix --interactive).
  • CI-ready: truthlint scan . --fail-on high gates pull requests; Markdown and JSON reports.
pip install truthlint
truthlint scan .

How I built it

A Python 3.11+ CLI built with Typer and Rich, with Pydantic models. Parsers for each file type feed a rule engine; rules are grouped by area — runtime versions, documented commands, documentation, environment, dependencies, containers, CI, build metadata and onboarding. Environment-variable detection covers Python (AST, including pydantic-settings), JS/TS, Go, Ruby, Rust, Java, PHP, C#, Elixir, Prisma and shell. It is released to PyPI through a GitHub Actions trusted-publishing workflow.

Challenges I ran into

Being trustworthy enough to run in CI. truthlint prefers silence to guessing:

  • A finding can't be constructed without a file/line citation (enforced in code).
  • Anything that depends on the network or installed tools is reported as unverified, never as broken.
  • Monorepo and Makefile ambiguity is downgraded to unverified instead of missing.
  • Generated and gitignored paths are respected, and higher false-positive heuristics are opt-in behind --deep.

Accomplishments that I'm proud of

It's safe by construction: fully offline, no API keys, no AI service, and it never executes anything from the scanned repository — not even git, because a repository's .git/config can make git run commands. And it ships: v0.1.0 is installable from PyPI today.

Built during the event

truthlint was started on November 12, 2026, during the build window. Open-source dependencies used: Typer, Rich and Pydantic.

Built With

  • github-actions
  • pydantic
  • pypi
  • python
  • rich
  • typer
Share this project:

Updates

Submission history