Shiplock

Shiplock is a release gate that checks a repository's documentation against its own code. It catches the drift that shows up at ship time: a doc describing a provider set the code no longer has, a README missing a shipped feature, a version string that moved in one file and not another, an example file that fell behind the API it demonstrates.

It runs the same way in three places — your terminal, your test suite, and CI — off one config file per repo, so the check that blocks a release is the check you ran locally a minute earlier.

Before you start

Shiplock needs Python 3.10 or newer. Check with:

python3 --version

If that fails, install Python from python.org/downloads (or your platform package manager: apt install python3-pip, dnf install python3-pip).

Install

pip install shiplock

See it work

Point it at any repo — no config file, no setup:

shiplock check path/to/your/repo

(or shiplock check from inside one). Shiplock sweeps whichever docs it recognizes and reports what it finds, one finding per problem:

docs-exist  USAGE.md
    declared public doc is missing: USAGE.md
readme-links  README.md:31
    relative link 'USAGE.md' (PyPI resolves it against pypi.org, not the repo)

Findings print to stdout; notices for the checks that need configuration, and the run summary, print to stderr — so stdout stays clean for a pipe. Exit code 0 means clean, 1 means a check found a problem, 2 means a config or usage error. That makes shiplock check a drop-in CI step and a pytest assertion alike. --json swaps the human output for one machine-readable object. On a terminal, findings render red and a clean run green (NO_COLOR turns that off); piped output stays plain.

When you want the rest of the checks — version alignment, architecture and manifest coverage, object documentation, versioned-file markers — add a shiplock.toml declaring your repo's surfaces. The full schema, section by section, is in USAGE.md.

Two layers

Shiplock checks in two layers:

1. Deterministic checks (shiplock check) — fast, exact, no model. Missing docs, the words you ban, internal references in public docs, absolute README links, a leak scan of the git-tracked files, version alignment, the architecture module list, object coverage, the per-file manifest, versioned-file markers, dependency declarations duplicated between pyproject and requirements files, tests that carry no assertion.
2. A semantic audit (shiplock prompt) — the prompt for a fresh agent to read the code and hold every doc claim against it, from state rather than from what changed. Centrally versioned inside the package, so every repo gets prompt updates on the next install.

The leak scan also runs on its own, as a git pre-push gate:

shiplock scan

It reads the git-tracked files, not only the declared docs, and flags the internal-reference patterns, project code-names, home paths, and personal emails you declare. shiplock ships no rules of its own: rules about you live in one file per machine (~/.config/shiplock/rules.toml), read in every repo; a repo's own rules in a gitignored shiplock.local.toml; and patterns that name nothing private in shiplock.toml. shiplock scan --staged and shiplock scan --range run the same rules over the staged diff and a commit range, for pre-commit and pre-push hooks. Private labels and matched values are masked in the output, so a code-name never echoes into a CI log.

Print the audit prompt with:

shiplock prompt

There's also a second, advisory prompt, outside the gate: shiplock prompt ablation prints a prompt for an agent to report what the repo could remove, merge, or make cheaper, with findings split into mechanical folds and decisions for the owner. It renders a report, never a verdict.

In Python

Everything the CLI does is callable — load_config and run_checks return a typed report, so the gate can run inside a test suite:

from pathlib import Path
from shiplock import load_config, run_checks

def test_docs_match_code():
    report = run_checks(load_config(Path(__file__).parent.parent))
    assert report.ok, [f.message for f in report.findings]

The full API surface is in USAGE.md.

In CI

Shiplock ships a reusable GitHub Actions workflow that runs both layers on every push and pull request, and opens an issue when the audit fails:

jobs:
  gate:
    uses: shehuphd/shiplock/.github/workflows/gate.yml@main

The gate installs the checked-out repo only when its config uses a check that imports the package (version or coverage), which it decides by running shiplock needs-import. An app repo that configures neither runs the gate without being an installable package.

The full wiring — inputs, the audit's API key, the dormant-first rollout — is in USAGE.md.

Documentation

• USAGE.md — the full manual: config schema, every check, exit codes.
• ARCHITECTURE.md — how the package is put together.
• MANIFEST.md — a per-file map of the codebase.
• CHANGELOG.md — dated release notes.

License

MIT. See LICENSE.

By Mo Shehu