Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

Mechanically check the tool count wording against the real tool list (#50) (#57)

Shogo Kajiyamabbfe941be9bd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72fa3be..f4dd5d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
## Unreleased
+- **Test: the prose tool count in README/`docs/contract.md`/`package.json` is now checked against the real tool list.** 0.11.0 was cut to fix exactly this drift (README said 28 twice and 22 once; `package.json` said 21) by hand, with nothing to stop it recurring. `tests/test_contract.py`'s `test_docs_tool_count_matches_the_real_tool_list` scans all three for `"<N> tools"` wording and fails if any number doesn't match `scripts/`'s actual public-tool count, so the next tool added/removed without updating every mention fails CI instead of drifting silently. `contract_version`/`skill.version` were already split (0.9.0) and already documented as "additive keeps `contract_version`, breaking bumps it" — `docs/contract.md` now also repeats the tagged-version pin guidance next to that table, since `capability_map` makes this the most cross-repo-facing part of the contract. Closes [#50](https://github.com/kajisho5/ffmpeg-skill/issues/50).
- **Tests: `overlay.py --image` on an audio-less video is now covered.** Every existing overlay test used a
source with audio; investigating a downstream report of `overlay.py` "hanging" on audio-less input (the
historical 0.9.x defect this tool's own `-t <duration>` fix, added in 0.10.0, was meant to close) found the
diff --git a/docs/contract.md b/docs/contract.md
index f111516..3aab1de 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -25,7 +25,14 @@ The contract is derived from the code that runs, not maintained beside it:
A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
-for provenance.
+for provenance. Consumers should also pin `ffmpeg-skill` itself by npm version or git
+tag, not by tracking `main` — see README, "Development", "Releasing".
+
+The prose tool count in this file, README and `package.json`'s description is not
+generated (it reads naturally in a sentence), so `tests/test_contract.py`'s
+`test_docs_tool_count_matches_the_real_tool_list` checks all three against the real
+count from `scripts/` on every CI run instead — a stale count fails a test rather than
+drifting silently.
## Skill
diff --git a/tests/test_contract.py b/tests/test_contract.py
index e9e0356..2252426 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -105,6 +105,26 @@ class ContractTests(unittest.TestCase):
self.assertTrue(c["invocation"]["structured"]["canonical"])
self.assertFalse(c["invocation"]["raw_argv"]["canonical"])
+ def test_docs_tool_count_matches_the_real_tool_list(self):
+ """README/SKILL.md/docs/contract.md each state the tool count in prose (not generated,
+ since it reads naturally in a sentence); this pins every stated count against the real
+ one so a new/removed tool that forgets to update one of them fails CI instead of
+ drifting silently -- see #50, filed after README said 28 twice, 22 once (stale), and
+ package.json's description said 21, all at the same time."""
+ real_count = len(self.contract["tools"])
+ checks = [
+ (ROOT / "README.md", re.compile(r"\b(\d+)\s+(?:public )?tools\b")),
+ (ROOT / "docs" / "contract.md", re.compile(r"\b(\d+)\s+tools\b")),
+ (ROOT / "package.json", re.compile(r"(\d+)\s+FFmpeg tools\b")),
+ ]
+ for path, pattern in checks:
+ text = path.read_text(encoding="utf-8")
+ counts = {int(m.group(1)) for m in pattern.finditer(text)}
+ self.assertTrue(counts, f"{path.relative_to(ROOT)}: no '<N> tools' wording found to check")
+ self.assertEqual(counts, {real_count},
+ f"{path.relative_to(ROOT)}: states tool count(s) {sorted(counts)}, "
+ f"but scripts/ actually has {real_count} public tools -- update the stale wording")
+
def test_skill_metadata_and_version_separation(self):
pkg = json.loads((ROOT / "package.json").read_text())
self.assertEqual(self.contract["skill"]["version"], pkg["version"])