cs-survival-kit 0.1.0__tar.gz

cs_survival_kit-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+.venv/
+__pycache__/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+
+# Build output
+dist/
+
+# Agent scratch space
+.superpowers/
+
+# OS
+.DS_Store

cs_survival_kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2026-10-04)
+
+
+### Features
+
+* **bench:** add benchmark toolkit ([#2](https://github.com/jwallace145/cs-survival-kit/issues/2)) ([3f28939](https://github.com/jwallace145/cs-survival-kit/commit/3f28939626bf68b0e3523a14b8fda053e2221612))
+
+
+### Miscellaneous
+
+* **repo:** scaffold library, tooling, and CI ([#1](https://github.com/jwallace145/cs-survival-kit/issues/1)) ([3b9d319](https://github.com/jwallace145/cs-survival-kit/commit/3b9d319859145a92ff7a4aa02f548ce4e0ad7dbe))

cs_survival_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jimmy Wallace
+
+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.

cs_survival_kit-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: cs-survival-kit
+Version: 0.1.0
+Summary: Hand-written data structures and algorithms, plus a benchmarking toolkit.
+Project-URL: Repository, https://github.com/jwallace145/cs-survival-kit
+Project-URL: Documentation, https://jwallace145.github.io/cs-survival-guide/
+Project-URL: Changelog, https://github.com/jwallace145/cs-survival-kit/blob/main/CHANGELOG.md
+Author: Jimmy Wallace
+License-Expression: MIT
+License-File: LICENSE
+Keywords: algorithms,benchmarking,data-structures,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: bench
+Description-Content-Type: text/markdown
+
+# cs-survival-kit
+
+Hand-written data structures and algorithms in Python, plus a small toolkit
+for benchmarking them.
+
+This library is the companion to the
+[CS Survival Guide](https://jwallace145.github.io/cs-survival-guide/)
+([source](https://github.com/jwallace145/cs-survival-guide)). The guide
+explains the ideas; this package is the code. The guide's Reference section
+is rendered directly from this package's docstrings and source.
+
+Every data structure and algorithm here is written by hand, for study. The
+goal is clarity over cleverness: read the source alongside the guide.
+
+## Install
+
+```bash
+pip install cs-survival-kit
+```
+
+Requires Python 3.12 or newer. The core package has no runtime dependencies.
+
+```python
+from cs_survival_kit.data_structures import DynamicArray
+```
+
+Structures land one at a time. A module whose functions still raise
+`NotImplementedError` is a stub waiting for its implementation.
+
+## Benchmarks
+
+`cs_survival_kit.bench` is a small, stdlib-only toolkit for measuring how code
+scales with input size, and for checking the result against the complexity a
+docstring claims.
+
+### Write a benchmark
+
+A benchmark is a set of cases to compare across a range of sizes. Each case
+has a `setup(n)` that builds the inputs (not timed) and a `run(inputs)` that
+is timed:
+
+```python
+# benchmarks/bench_sorting.py
+from cs_survival_kit.bench import Benchmark
+
+
+def bubble_sort(items: list[int]) -> None:
+    for end in range(len(items) - 1, 0, -1):
+        for i in range(end):
+            if items[i] > items[i + 1]:
+                items[i], items[i + 1] = items[i + 1], items[i]
+
+
+sorting = Benchmark("sorting", sizes=[100, 200, 400, 800])
+sorting.case("bubble sort", setup=lambda n: list(range(n, 0, -1)), run=bubble_sort)
+sorting.case("list.sort", setup=lambda n: list(range(n, 0, -1)), run=list.sort)
+
+BENCHMARKS = [sorting]
+```
+
+`setup` is called again before every timed call, so `run` may mutate its
+inputs. A case can pass its own `sizes=` to cap a slow implementation at
+smaller inputs. A case that raises `NotImplementedError` is reported as
+`not implemented` and skipped, so a benchmark can be written before the code
+it measures.
+
+### Run it
+
+```bash
+python -m cs_survival_kit.bench                               # every benchmarks/bench_*.py
+python -m cs_survival_kit.bench benchmarks/bench_sorting.py   # just one file
+python -m cs_survival_kit.bench --smoke                       # check they execute; write nothing
+```
+
+```text
+sorting
+     n  bubble sort  list.sort
+   100  140 µs       256 ns
+   200  546 µs       472 ns
+   400  2.28 ms      905 ns
+   800  10.4 ms      1.74 µs
+ slope  2.07         0.92
+growth  ~ quadratic  ~ linear
+```
+
+Each time is per call: the minimum of 5 measurements, with garbage collection
+disabled, looping fast calls until a measurement lasts about 0.1 seconds.
+
+`slope` is the least-squares slope of time against size on a log-log scale,
+which approximates the exponent `k` in `O(n^k)`: about 0 is constant, about 1
+is linear, about 2 is quadratic. `O(n log n)` reads as slightly above 1. It is
+an empirical sanity check, not a proof.
+
+A benchmark can also be driven from Python: `results = sorting.run(repeat=5)`,
+then `results.table()`, `results.fit()` or `results.to_dict()`.
+
+### Stored results
+
+A full run merges its results into
+`src/cs_survival_kit/_data/benchmarks.json` (or `--output FILE`), keyed by
+benchmark name, so re-running one file updates only its own entries. That file
+ships inside the package.
+
+Published numbers come from a single development machine, never from CI:
+shared runners are too noisy. CI only runs `--smoke`.
+
+## Local development
+
+```bash
+uv sync                          # create .venv and install dev tools
+
+uv run ruff check                # lint
+uv run ruff format --check       # formatting
+uv run pyright                   # type check
+uv run python scripts/check_docs.py   # docs-completeness check
+uv run pytest                    # tests and doctests
+uv run python -m cs_survival_kit.bench --smoke   # benchmarks execute
+uv build                         # sdist and wheel into dist/
+```
+
+All of these run in CI and must pass before a PR can merge.
+
+## Releases
+
+cs-survival-kit uses [Conventional Commits](https://www.conventionalcommits.org)
+and [Semantic Versioning](https://semver.org), starting in the `0.x`
+development lifecycle.
+
+```text
+feat:                      -> minor release (0.1.0 -> 0.2.0)
+fix:                       -> patch release (0.2.0 -> 0.2.1)
+BREAKING CHANGE / feat!:   -> while in 0.x, also bumps the minor version
+```
+
+[Release Please](https://github.com/googleapis/release-please) watches `main`
+and maintains a release PR that accumulates changes. Merging that PR:
+
+- updates the version in `pyproject.toml` (the version source of truth)
+- updates `CHANGELOG.md`
+- creates the SemVer git tag (e.g. `v0.4.0`) and the GitHub Release
+- publishes the release to [PyPI](https://pypi.org/project/cs-survival-kit/)
+- notifies the guide, which opens a PR to document the new version
+
+The version and changelog are never edited by hand.
+
+The publishing pipeline can be rehearsed without releasing anything: running
+the **Publish to TestPyPI** workflow from the Actions tab builds `main` as a
+throwaway `0.0.0.devN` version, publishes it to
+[TestPyPI](https://test.pypi.org/project/cs-survival-kit/), and installs it
+back.
+
+### Commit examples
+
+```text
+feat(ds): add dynamic array
+feat(algo): add binary search
+fix(ds): correct dynamic array shrink threshold
+feat(bench): add memory benchmarks
+chore(deps): update ruff
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full convention.
+
+## License
+
+[MIT](LICENSE)

cs_survival_kit-0.1.0/README.md

@@ -0,0 +1,166 @@
+# cs-survival-kit
+
+Hand-written data structures and algorithms in Python, plus a small toolkit
+for benchmarking them.
+
+This library is the companion to the
+[CS Survival Guide](https://jwallace145.github.io/cs-survival-guide/)
+([source](https://github.com/jwallace145/cs-survival-guide)). The guide
+explains the ideas; this package is the code. The guide's Reference section
+is rendered directly from this package's docstrings and source.
+
+Every data structure and algorithm here is written by hand, for study. The
+goal is clarity over cleverness: read the source alongside the guide.
+
+## Install
+
+```bash
+pip install cs-survival-kit
+```
+
+Requires Python 3.12 or newer. The core package has no runtime dependencies.
+
+```python
+from cs_survival_kit.data_structures import DynamicArray
+```
+
+Structures land one at a time. A module whose functions still raise
+`NotImplementedError` is a stub waiting for its implementation.
+
+## Benchmarks
+
+`cs_survival_kit.bench` is a small, stdlib-only toolkit for measuring how code
+scales with input size, and for checking the result against the complexity a
+docstring claims.
+
+### Write a benchmark
+
+A benchmark is a set of cases to compare across a range of sizes. Each case
+has a `setup(n)` that builds the inputs (not timed) and a `run(inputs)` that
+is timed:
+
+```python
+# benchmarks/bench_sorting.py
+from cs_survival_kit.bench import Benchmark
+
+
+def bubble_sort(items: list[int]) -> None:
+    for end in range(len(items) - 1, 0, -1):
+        for i in range(end):
+            if items[i] > items[i + 1]:
+                items[i], items[i + 1] = items[i + 1], items[i]
+
+
+sorting = Benchmark("sorting", sizes=[100, 200, 400, 800])
+sorting.case("bubble sort", setup=lambda n: list(range(n, 0, -1)), run=bubble_sort)
+sorting.case("list.sort", setup=lambda n: list(range(n, 0, -1)), run=list.sort)
+
+BENCHMARKS = [sorting]
+```
+
+`setup` is called again before every timed call, so `run` may mutate its
+inputs. A case can pass its own `sizes=` to cap a slow implementation at
+smaller inputs. A case that raises `NotImplementedError` is reported as
+`not implemented` and skipped, so a benchmark can be written before the code
+it measures.
+
+### Run it
+
+```bash
+python -m cs_survival_kit.bench                               # every benchmarks/bench_*.py
+python -m cs_survival_kit.bench benchmarks/bench_sorting.py   # just one file
+python -m cs_survival_kit.bench --smoke                       # check they execute; write nothing
+```
+
+```text
+sorting
+     n  bubble sort  list.sort
+   100  140 µs       256 ns
+   200  546 µs       472 ns
+   400  2.28 ms      905 ns
+   800  10.4 ms      1.74 µs
+ slope  2.07         0.92
+growth  ~ quadratic  ~ linear
+```
+
+Each time is per call: the minimum of 5 measurements, with garbage collection
+disabled, looping fast calls until a measurement lasts about 0.1 seconds.
+
+`slope` is the least-squares slope of time against size on a log-log scale,
+which approximates the exponent `k` in `O(n^k)`: about 0 is constant, about 1
+is linear, about 2 is quadratic. `O(n log n)` reads as slightly above 1. It is
+an empirical sanity check, not a proof.
+
+A benchmark can also be driven from Python: `results = sorting.run(repeat=5)`,
+then `results.table()`, `results.fit()` or `results.to_dict()`.
+
+### Stored results
+
+A full run merges its results into
+`src/cs_survival_kit/_data/benchmarks.json` (or `--output FILE`), keyed by
+benchmark name, so re-running one file updates only its own entries. That file
+ships inside the package.
+
+Published numbers come from a single development machine, never from CI:
+shared runners are too noisy. CI only runs `--smoke`.
+
+## Local development
+
+```bash
+uv sync                          # create .venv and install dev tools
+
+uv run ruff check                # lint
+uv run ruff format --check       # formatting
+uv run pyright                   # type check
+uv run python scripts/check_docs.py   # docs-completeness check
+uv run pytest                    # tests and doctests
+uv run python -m cs_survival_kit.bench --smoke   # benchmarks execute
+uv build                         # sdist and wheel into dist/
+```
+
+All of these run in CI and must pass before a PR can merge.
+
+## Releases
+
+cs-survival-kit uses [Conventional Commits](https://www.conventionalcommits.org)
+and [Semantic Versioning](https://semver.org), starting in the `0.x`
+development lifecycle.
+
+```text
+feat:                      -> minor release (0.1.0 -> 0.2.0)
+fix:                       -> patch release (0.2.0 -> 0.2.1)
+BREAKING CHANGE / feat!:   -> while in 0.x, also bumps the minor version
+```
+
+[Release Please](https://github.com/googleapis/release-please) watches `main`
+and maintains a release PR that accumulates changes. Merging that PR:
+
+- updates the version in `pyproject.toml` (the version source of truth)
+- updates `CHANGELOG.md`
+- creates the SemVer git tag (e.g. `v0.4.0`) and the GitHub Release
+- publishes the release to [PyPI](https://pypi.org/project/cs-survival-kit/)
+- notifies the guide, which opens a PR to document the new version
+
+The version and changelog are never edited by hand.
+
+The publishing pipeline can be rehearsed without releasing anything: running
+the **Publish to TestPyPI** workflow from the Actions tab builds `main` as a
+throwaway `0.0.0.devN` version, publishes it to
+[TestPyPI](https://test.pypi.org/project/cs-survival-kit/), and installs it
+back.
+
+### Commit examples
+
+```text
+feat(ds): add dynamic array
+feat(algo): add binary search
+fix(ds): correct dynamic array shrink threshold
+feat(bench): add memory benchmarks
+chore(deps): update ruff
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full convention.
+
+## License
+
+[MIT](LICENSE)

cs_survival_kit-0.1.0/benchmarks/bench_dynamic_array.py

@@ -0,0 +1,55 @@
+"""Benchmarks for DynamicArray: the cost of n appends under each growth policy.
+
+Expected story: geometric growth (doubling, or any factor above 1) makes
+append amortized O(1), so n appends are linear in n (slope about 1), the same
+as the built-in list. Additive growth copies the whole array every `step`
+appends, so n appends are quadratic (slope about 2).
+"""
+
+from typing import Protocol
+
+from cs_survival_kit.bench import Benchmark
+from cs_survival_kit.data_structures.dynamic_array import (
+    DynamicArray,
+    additive,
+    doubling,
+    geometric,
+)
+
+
+class Appendable(Protocol):
+    """Anything with a list-style `append`."""
+
+    def append(self, value: int, /) -> None:
+        """Add a value at the end."""
+        ...
+
+
+def append_n(inputs: tuple[Appendable, int]) -> None:
+    """Append n integers to a fresh container."""
+    container, n = inputs
+    for i in range(n):
+        container.append(i)
+
+
+append = Benchmark("dynamic_array.append", sizes=[10**k for k in range(2, 7)])
+append.case(
+    "DynamicArray(doubling)",
+    setup=lambda n: (DynamicArray[int](growth=doubling), n),
+    run=append_n,
+)
+append.case(
+    "DynamicArray(geometric(1.5))",
+    setup=lambda n: (DynamicArray[int](growth=geometric(1.5)), n),
+    run=append_n,
+)
+append.case(
+    "DynamicArray(additive(16))",
+    setup=lambda n: (DynamicArray[int](growth=additive(16)), n),
+    run=append_n,
+    # Quadratic: capped well below the other cases so a full run stays short.
+    sizes=[1_000, 2_000, 5_000, 10_000, 20_000, 50_000],
+)
+append.case("list", setup=lambda n: (list[int](), n), run=append_n)
+
+BENCHMARKS = [append]

cs_survival_kit-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cs-survival-kit"
+# Managed by Release Please. Do not edit by hand.
+version = "0.1.0"
+description = "Hand-written data structures and algorithms, plus a benchmarking toolkit."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jimmy Wallace" }]
+keywords = ["algorithms", "data-structures", "benchmarking", "education"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Education",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Education",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+# The core package has zero runtime dependencies. Keep it that way.
+dependencies = []
+
+[project.optional-dependencies]
+bench = []
+
+[project.urls]
+Repository = "https://github.com/jwallace145/cs-survival-kit"
+Documentation = "https://jwallace145.github.io/cs-survival-guide/"
+Changelog = "https://github.com/jwallace145/cs-survival-kit/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["hypothesis", "pyright", "pytest", "ruff"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cs_survival_kit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/benchmarks", "/scripts", "/README.md", "/LICENSE", "/CHANGELOG.md"]
+
+[tool.ruff]
+src = ["src", "scripts"]
+
+[tool.ruff.format]
+# Only format Python sources; leave code blocks in markdown as written.
+exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "D"]
+# Constructor args are documented on the class, not on __init__.
+ignore = ["D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.pyright]
+include = ["src", "scripts", "tests", "benchmarks"]
+strict = ["src"]
+extraPaths = ["scripts"]
+pythonVersion = "3.12"
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+testpaths = ["src", "tests"]
+pythonpath = ["scripts"]

cs_survival_kit-0.1.0/scripts/check_docs.py

@@ -0,0 +1,140 @@
+"""Docs-completeness check for the study modules.
+
+Enforces two rules over ``data_structures/`` and ``algorithms/``:
+
+1. Every public class has a ``Complexity:`` section in its docstring.
+2. An implemented function or method (its body is no longer just
+   ``raise NotImplementedError``) must not have ``TODO`` in its own docstring,
+   its class docstring, or its module docstring.
+
+Stubs may keep their placeholders; nothing ships implemented and undocumented.
+
+Usage:
+    python scripts/check_docs.py [PATH ...]
+"""
+
+import ast
+import sys
+from collections.abc import Iterator, Sequence
+from pathlib import Path
+
+DEFAULT_PATHS = (
+    "src/cs_survival_kit/data_structures",
+    "src/cs_survival_kit/algorithms",
+)
+PLACEHOLDER = "TODO"
+COMPLEXITY_HEADER = "Complexity:"
+
+type FunctionNode = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+def _has_placeholder(node: ast.Module | ast.ClassDef | FunctionNode) -> bool:
+    return PLACEHOLDER in (ast.get_docstring(node) or "")
+
+
+def _is_stub(function: FunctionNode) -> bool:
+    """Return whether the body is only ``raise NotImplementedError``."""
+    body = function.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        body = body[1:]
+    if len(body) != 1 or not isinstance(body[0], ast.Raise):
+        return False
+    raised = body[0].exc
+    if isinstance(raised, ast.Call):
+        raised = raised.func
+    return isinstance(raised, ast.Name) and raised.id == "NotImplementedError"
+
+
+def _walk(
+    body: Sequence[ast.stmt], classes: tuple[ast.ClassDef, ...] = ()
+) -> Iterator[tuple[ast.ClassDef | FunctionNode, tuple[ast.ClassDef, ...]]]:
+    """Yield each class, function and method with its enclosing classes.
+
+    Functions nested inside other functions are implementation details and
+    are not visited.
+    """
+    for node in body:
+        if isinstance(node, ast.ClassDef):
+            yield node, classes
+            yield from _walk(node.body, (*classes, node))
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            yield node, classes
+
+
+def check_source(source: str, filename: str) -> list[str]:
+    """Check one module's source and return its violations.
+
+    Args:
+        source: The module's source code.
+        filename: Name used to prefix each violation.
+
+    Returns:
+        One ``file:line: message`` string per violation, in source order.
+    """
+    module = ast.parse(source, filename=filename)
+    errors: list[str] = []
+
+    def report(node: ast.ClassDef | FunctionNode, message: str) -> None:
+        errors.append(f"{filename}:{node.lineno}: {message}")
+
+    for node, classes in _walk(module.body):
+        name = ".".join([*(cls.name for cls in classes), node.name])
+        if isinstance(node, ast.ClassDef):
+            public = not any(part.startswith("_") for part in name.split("."))
+            if public and COMPLEXITY_HEADER not in (ast.get_docstring(node) or ""):
+                report(node, f"class {name} has no '{COMPLEXITY_HEADER}' section")
+            continue
+        if _is_stub(node):
+            continue
+        scopes = [("its", node), ("its module", module)]
+        if classes:
+            scopes.insert(1, ("its class", classes[-1]))
+        for owner, scope in scopes:
+            if _has_placeholder(scope):
+                report(
+                    node,
+                    f"{name} is implemented but {owner} docstring "
+                    f"contains {PLACEHOLDER}",
+                )
+    return errors
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the check over the given paths (default: the study modules).
+
+    Returns:
+        0 if clean, 1 if there are violations, 2 if a path does not exist.
+    """
+    args = sys.argv[1:] if argv is None else argv
+    roots = [Path(arg) for arg in (args or DEFAULT_PATHS)]
+
+    files: list[Path] = []
+    for root in roots:
+        if root.is_file():
+            files.append(root)
+        elif root.is_dir():
+            files.extend(sorted(root.rglob("*.py")))
+        else:
+            print(f"check_docs: path does not exist: {root}", file=sys.stderr)
+            return 2
+
+    errors: list[str] = []
+    for file in files:
+        errors.extend(check_source(file.read_text(encoding="utf-8"), str(file)))
+
+    for error in errors:
+        print(error)
+    if errors:
+        print(f"\ncheck_docs: {len(errors)} problem(s) in {len(files)} file(s)")
+        return 1
+    print(f"check_docs: {len(files)} file(s) OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())