derive.py repos (the public repo list, from repos.json)
-derive.py readme (README.md's derive blocks, from data.json and chock's install and witness data)
+derive.py readme (README.md's derive blocks, from data.json and chock's install and witness data, and agents.json)
"""
from __future__ import annotations
@@ -237,6 +237,9 @@ def main(argv: list[str]) -> None:
data.update(derive_agentseam(Path(argv[1]), argv[2]))
elif argv[0] == "readme":
README.write_text(render_readme(README.read_text(encoding="utf-8"), data), encoding="utf-8")
+ import agents_data # noqa: PLC0415 -- the picture's data, refreshed by the same command
+
+ agents_data.write()
return
else:
data.update(derive_repos())
diff --git a/docs/assets/readme/render.mjs b/docs/assets/readme/render.mjs
index 29702131..e45dc4b4 100644
--- a/docs/assets/readme/render.mjs
+++ b/docs/assets/readme/render.mjs
@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
import path from 'node:path';
import { where, SITE_PALETTE } from './where-chock-sits.mjs';
import { where as sessionPath } from './session-path.mjs';
+import { where as agentsPicture } from './agents.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const OUT = process.env.OUT_DIR || HERE;
@@ -219,10 +220,11 @@ ${grid(3, 16, [[A.grades.enforced, 'matrix cells graded “enforced”:
const FIGURE = JSON.parse(readFileSync(path.join(HERE, 'where-chock-sits.json'), 'utf8'));
const WHERE = where(page, FIGURE), WHERE_SITE = where(page, FIGURE, SITE_PALETTE), SESSION_PATH = sessionPath(page, FIGURE);
+const AGENTS = JSON.parse(readFileSync(path.join(HERE, 'agents.json'), 'utf8')), AGENTS_PNG = agentsPicture(page, AGENTS);
const ALL_NEW = { layers: LAYERS, quickstart: QUICKSTART, matrix: MATRIX, catalog: CATALOG, family: FAMILY, honest: HONEST };
// README v2 panels go under v2/; the titled refusal, roles and contribute PNGs at the old paths stay frozen until RW-7b.
-const V2 = { 'v2/refusal': REFUSAL, 'v2/roles': ROLES, 'v2/contribute': CONTRIBUTE, 'v2/where-chock-sits': WHERE, 'v2/where-chock-sits-site': WHERE_SITE, 'v2/session-path': SESSION_PATH };
+const V2 = { 'v2/refusal': REFUSAL, 'v2/roles': ROLES, 'v2/contribute': CONTRIBUTE, 'v2/where-chock-sits': WHERE, 'v2/where-chock-sits-site': WHERE_SITE, 'v2/session-path': SESSION_PATH, 'v2/agents': AGENTS_PNG };
// 1280x640 social preview banners: the same specs as the covers, laid out for the fixed canvas.
const social = ({ repo, title, sub, chips, right }) => `
diff --git a/docs/assets/readme/v2/agents.png b/docs/assets/readme/v2/agents.png
new file mode 100644
index 00000000..a69b39fc
Binary files /dev/null and b/docs/assets/readme/v2/agents.png differ
diff --git a/tests/test_readme_agents.py b/tests/test_readme_agents.py
new file mode 100644
index 00000000..20bc65db
--- /dev/null
+++ b/tests/test_readme_agents.py
@@ -0,0 +1,119 @@
+"""The "Which agents, and how strongly Chock holds in each" picture is derived from the code, never typed."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import shutil
+import struct
+import subprocess
+
+import pytest
+from readme_figure_support import ASSETS, ROOT
+
+JSON = ASSETS / "agents.json"
+
+
+def _derive():
+ spec = importlib.util.spec_from_file_location("agents_data", ASSETS / "agents_data.py")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _committed() -> dict:
+ return json.loads(JSON.read_text(encoding="utf-8"))
+
+
+def test_agents_json_equals_what_the_code_derives_now() -> None:
+ committed = _committed()
+ assert committed == _derive().derive(), (
+ "agents.json is behind the code; run: python docs/assets/readme/derive.py readme"
+ )
+
+
+def test_one_row_per_surface_agent_in_the_documented_order() -> None:
+ from chock.compile.surfaces import SURFACE_AGENTS
+
+ rows = _committed()["rows"]
+ assert {r["id"] for r in rows} == set(SURFACE_AGENTS) and len(rows) == len(SURFACE_AGENTS)
+ order = {"tested live": 0, "untested": 1, "": 2}
+ keys = [(order[r["plugin"]], r["name"].lower()) for r in rows]
+ assert keys == sorted(keys)
+
+
+def test_cells_match_surfaces_grades_and_the_readme_summary() -> None:
+ from chock.compile.surfaces import SURFACE_AGENTS, Surface
+
+ derive = _derive()
+ data = _committed()
+ for row in data["rows"]:
+ surfaces = SURFACE_AGENTS[row["id"]]
+ assert row["ci"] is (Surface.CI_GATE in surfaces) and row["git"] is True and row["rule"] is True
+ has_hook = bool({Surface.PRE_TOOL_USE, Surface.AGENT_HOOKS} & surfaces)
+ assert (row["hook_grade"] != "none") == has_hook == bool(row["hook"])
+ assert row["hook"] == derive.GRADE_WORDS[row["hook_grade"]]
+ assert row["matrix_pre_tool"] in derive.GRADE_WORDS
+ readme = (ROOT / "README.md").read_text(encoding="utf-8")
+ counts = data["counts"]
+ assert sum(1 for r in data["rows"] if r["plugin"] == "tested live") == counts["plugin_tested"]
+ assert f"All {counts['agents']} above get" in readme and f"{counts['own_hook']} also get a native hook" in readme
+ assert f"{counts['plugin_tested']} tested, {counts['plugin_untested']} untested" in readme
+
+
+def test_display_names_are_the_ones_the_readme_table_uses() -> None:
+ readme = (ROOT / "README.md").read_text(encoding="utf-8")
+ table = readme.split("### Supported agents", 1)[1]
+ for name in _derive().NAMES.values():
+ assert f"| **{name}** |" in table, name
+
+
+def test_no_text_is_typed_into_the_layout() -> None:
+ layout = (ASSETS / "agents.mjs").read_text(encoding="utf-8")
+ for word in ("refuses", "advice", "tested", "fails open", "Which agents"):
+ assert word not in layout, word
+
+
+def _node(script: str) -> object:
+ node = shutil.which("node")
+ if not node:
+ pytest.skip("node is not installed")
+ done = subprocess.run(
+ [node, "--input-type=module", "-e", script], cwd=ROOT, capture_output=True, text=True, check=False
+ )
+ assert done.returncode == 0, done.stderr
+ return json.loads(done.stdout)
+
+
+def test_no_text_overflows_a_card() -> None:
+ script = (
+ "import {layout, crowded} from './docs/assets/readme/agents.mjs';"
+ "import {readFileSync} from 'node:fs';"
+ "const W = JSON.parse(readFileSync('docs/assets/readme/agents.json', 'utf8'));"
+ "console.log(JSON.stringify(crowded(layout(W))));"
+ )
+ assert _node(script) == []
+
+
+def test_title_is_the_teaching_one_and_chock_is_named_only_in_the_footer() -> None:
+ data = _committed()
+ assert data["title"] == "Where each coding agent can be stopped"
+ text = json.dumps({k: v for k, v in data.items() if k not in ("footer", "source")}).lower()
+ assert "chock" not in text and "chock" in data["footer"].lower()
+ assert f"Chock {data['source']['chock']} with agentseam" in data["footer"]
+ assert list(data["groups"].values()) == ["One plugin, tested live", "One plugin, untested", "Git hook and CI"]
+
+
+def test_png_exists_is_two_x_wide_and_is_registered_and_no_site_render_exists() -> None:
+ png = ASSETS / "v2" / "agents.png"
+ assert png.stat().st_size > 10_000
+ assert struct.unpack(">II", png.read_bytes()[16:24])[0] == 1760
+ assert not (ASSETS / "v2" / "agents-site.png").exists()
+ render = (ASSETS / "render.mjs").read_text(encoding="utf-8")
+ assert "'v2/agents': AGENTS_PNG" in render and "agents-site" not in render
+
+
+def test_adapters_page_links_the_picture_and_the_readme_stays_untouched() -> None:
+ page = (ROOT / "docs" / "adapters" / "README.md").read_text(encoding="utf-8")
+ assert "../assets/readme/v2/agents.png" in page
+ assert "agents.png" not in (ROOT / "README.md").read_text(encoding="utf-8")