shiplock 0.0.1__tar.gz

shiplock-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mo Shehu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shiplock-0.0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# The test suite runs from the repo, where its conftest and the repo's own
+# shiplock.toml exist; setuptools' default template would ship tests/test*.py
+# without either, a suite that can't run. Ship the package alone.
+prune tests

shiplock-0.0.1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: shiplock
+Version: 0.0.1
+Summary: Deterministic docs-vs-code release checks, config-driven per repo, runnable locally, in pytest, and in CI.
+Author: Mo Shehu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shehuphd/shiplock
+Keywords: documentation,release,ci,docs-vs-code,linter
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-randomly>=3.15; extra == "test"
+Requires-Dist: pyyaml>=6; extra == "test"
+Requires-Dist: rates; extra == "test"
+Dynamic: license-file
+
+# 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:
+
+```bash
+python3 --version
+```
+
+If that fails, install Python from [python.org/downloads](https://www.python.org/downloads/)
+(or your platform package manager: `apt install python3-pip`, `dnf install python3-pip`).
+
+## Install
+
+```bash
+pip install shiplock
+```
+
+## See it work
+
+Point it at any repo — no config file, no setup:
+
+```bash
+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](https://github.com/shehuphd/shiplock/blob/main/USAGE.md).
+
+## Two layers
+
+Shiplock checks in two layers:
+
+1. **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.
+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.
+
+Print the audit prompt with:
+
+```bash
+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:
+
+```python
+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](https://github.com/shehuphd/shiplock/blob/main/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:
+
+```yaml
+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](https://github.com/shehuphd/shiplock/blob/main/USAGE.md).
+
+## Documentation
+
+- [USAGE.md](https://github.com/shehuphd/shiplock/blob/main/USAGE.md) — the full manual: config schema, every check, exit codes.
+- [ARCHITECTURE.md](https://github.com/shehuphd/shiplock/blob/main/ARCHITECTURE.md) — how the package is put together.
+- [MANIFEST.md](https://github.com/shehuphd/shiplock/blob/main/MANIFEST.md) — a per-file map of the codebase.
+- [CHANGELOG.md](https://github.com/shehuphd/shiplock/blob/main/CHANGELOG.md) — dated release notes.
+
+## License
+
+MIT. See [LICENSE](https://github.com/shehuphd/shiplock/blob/main/LICENSE).
+
+By [Mo Shehu](https://mohammedshehu.com)

shiplock-0.0.1/README.md

@@ -0,0 +1,123 @@
+# 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:
+
+```bash
+python3 --version
+```
+
+If that fails, install Python from [python.org/downloads](https://www.python.org/downloads/)
+(or your platform package manager: `apt install python3-pip`, `dnf install python3-pip`).
+
+## Install
+
+```bash
+pip install shiplock
+```
+
+## See it work
+
+Point it at any repo — no config file, no setup:
+
+```bash
+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](https://github.com/shehuphd/shiplock/blob/main/USAGE.md).
+
+## Two layers
+
+Shiplock checks in two layers:
+
+1. **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.
+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.
+
+Print the audit prompt with:
+
+```bash
+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:
+
+```python
+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](https://github.com/shehuphd/shiplock/blob/main/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:
+
+```yaml
+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](https://github.com/shehuphd/shiplock/blob/main/USAGE.md).
+
+## Documentation
+
+- [USAGE.md](https://github.com/shehuphd/shiplock/blob/main/USAGE.md) — the full manual: config schema, every check, exit codes.
+- [ARCHITECTURE.md](https://github.com/shehuphd/shiplock/blob/main/ARCHITECTURE.md) — how the package is put together.
+- [MANIFEST.md](https://github.com/shehuphd/shiplock/blob/main/MANIFEST.md) — a per-file map of the codebase.
+- [CHANGELOG.md](https://github.com/shehuphd/shiplock/blob/main/CHANGELOG.md) — dated release notes.
+
+## License
+
+MIT. See [LICENSE](https://github.com/shehuphd/shiplock/blob/main/LICENSE).
+
+By [Mo Shehu](https://mohammedshehu.com)

shiplock-0.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+# SPDX license expressions (license = "MIT") need setuptools 77.0.3 or newer.
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shiplock"
+version = "0.0.1"
+description = "Deterministic docs-vs-code release checks, config-driven per repo, runnable locally, in pytest, and in CI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Mo Shehu" }]
+keywords = ["documentation", "release", "ci", "docs-vs-code", "linter"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    # tomllib is stdlib from 3.11; the tomli backport covers 3.10 only.
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-randomly>=3.15", "pyyaml>=6", "rates"]
+
+[project.urls]
+Homepage = "https://github.com/shehuphd/shiplock"
+
+[project.scripts]
+shiplock = "shiplock.cli:main"
+
+[tool.pytest.ini_options]
+# Fail loudly if the randomizer isn't installed, rather than silently running
+# tests in a fixed order.
+required_plugins = ["pytest-randomly"]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+shiplock = ["py.typed", "prompts/*.md"]

shiplock-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shiplock-0.0.1/src/shiplock/__init__.py

@@ -0,0 +1,23 @@
+"""Shiplock: deterministic docs-vs-code release checks.
+
+The public surface is small on purpose. Most callers want either the CLI
+(``shiplock check`` / ``shiplock prompt``) or the two entry points re-exported
+here: load a repo's config, then run the checks over it.
+"""
+
+from shiplock._config import Config, ConfigError, load_config
+from shiplock._report import Finding, Notice, Report
+from shiplock._checks import run_checks
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Config",
+    "ConfigError",
+    "Finding",
+    "Notice",
+    "Report",
+    "load_config",
+    "run_checks",
+    "__version__",
+]