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:
- Deterministic checks (
shiplock check) — fast, exact, no model. Missing docs, banned words, internal references in public docs, absolute README links, version alignment, the architecture module list, object coverage, the per-file manifest, versioned-file markers. - 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.
Print the audit prompt with:
shiplock prompt
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 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
Metadata
Release files for shiplock 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shiplock-0.1.0.tar.gz | 23.7 kB | With provenance | Details for shiplock-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shiplock-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for shiplock-0.1.0-py3-none-any.whl |
Total release size: 48.6 kB
Release files / shiplock-0.1.0.tar.gz
| Download URL | shiplock-0.1.0.tar.gz |
|---|---|
| Size | 23.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b0647fe2d1219c57b6fa2e6f4bb0bfb1167429a7f7646ed995c4d4aed0b5274e
|
|
BLAKE2b-256 checksum How to use checksums |
c12d77bd1340eec72c44fa7f9fb550756443bc660a1e29c9f3208f518959bf9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.
Transparency logRelease files / shiplock-0.1.0-py3-none-any.whl
| Download URL | shiplock-0.1.0-py3-none-any.whl |
|---|---|
| Size | 24.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
958d6d5d1b80d8f4f535abc5f275720a1afd5c3830396858da0a5d5760b879f3
|
|
BLAKE2b-256 checksum How to use checksums |
f80fc21af58f1c8dd0b442320e179c7fc963e39f71c1c700a0c6185391debdd4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.
Transparency logSecurity for shiplock 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for shiplock-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.