From 826cef0c3eb9f164e8b6378c571432a5caa0a92a Mon Sep 17 00:00:00 2001 From: Andriy Oblivantsev Date: Fri, 10 Jul 2026 11:02:55 +0100 Subject: [PATCH] fix: drop PyYAML dep so verify job pytest passes Store doc rules in bin/docs_rules.json (stdlib json). test_check_docs no longer fails in the simulator job that only installs simulator/requirements.txt. --- .github/workflows/release.yaml | 3 -- bin/check_docs.py | 13 ++------- bin/docs_rules.json | 42 ++++++++++++++++++++++++++ bin/docs_rules.yaml | 47 ------------------------------ docs/improvement/README.md | 2 +- docs/improvement/ci-rules.md | 4 +-- simulator/tests/test_check_docs.py | 22 ++++++++------ 7 files changed, 61 insertions(+), 72 deletions(-) create mode 100644 bin/docs_rules.json delete mode 100644 bin/docs_rules.yaml diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 39f7444..060406d 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -33,9 +33,6 @@ jobs: - name: Fetch base branch for ADR immutability run: git fetch --depth=1 origin main - - name: Install checker dependencies - run: pip install --quiet pyyaml - - name: ADR immutability (no edits to accepted records) run: python bin/check_adrs.py --base origin/main diff --git a/bin/check_docs.py b/bin/check_docs.py index 90daf29..1cb64b0 100644 --- a/bin/check_docs.py +++ b/bin/check_docs.py @@ -4,17 +4,13 @@ from __future__ import annotations import argparse +import json import re import sys from pathlib import Path -try: - import yaml -except ImportError: # pragma: no cover - stdlib fallback for minimal envs - yaml = None # type: ignore[assignment] - ROOT = Path(__file__).resolve().parents[1] -RULES_PATH = Path(__file__).with_name("docs_rules.yaml") +RULES_PATH = Path(__file__).with_name("docs_rules.json") LINK_RE = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)") BARE_SEE_RE = re.compile(r"(? dict: - text = path.read_text(encoding="utf-8") - if yaml is not None: - return yaml.safe_load(text) - raise RuntimeError("PyYAML is required to load docs_rules.yaml") + return json.loads(path.read_text(encoding="utf-8")) def slug_heading(text: str) -> str: diff --git a/bin/docs_rules.json b/bin/docs_rules.json new file mode 100644 index 0000000..38aa906 --- /dev/null +++ b/bin/docs_rules.json @@ -0,0 +1,42 @@ +{ + "markdown_paths": [ + "docs/**/*.md", + "README.md", + "CONTRIBUTING.md", + "AGENTS.md", + "simulator/README.md", + "prototype/README.md", + "infra/**/README.md" + ], + "glossary": { + "file": "docs/00-glossary.md" + }, + "banned_link_targets": [ + "03-storage-design.md" + ], + "glossary_section_anchors": [ + "data--storage", + "swarm--robotics", + "infrastructure--delivery" + ], + "preferred_term_anchors": [ + "t0--hot", + "t1--warm", + "t2--shared", + "t3--warehouse", + "t4--dev", + "source-of-truth", + "architecture-layer-1--ingestion", + "architecture-layer-2--storage-and-transform", + "architecture-layer-3--serving-and-sync", + "pipeline-stage", + "bulk-sync", + "offload", + "rclone", + "adr", + "asr" + ], + "readability": { + "forbid_bare_see_refs": true + } +} diff --git a/bin/docs_rules.yaml b/bin/docs_rules.yaml deleted file mode 100644 index 938376b..0000000 --- a/bin/docs_rules.yaml +++ /dev/null @@ -1,47 +0,0 @@ -# Documentation rules enforced by CI (bin/check_docs.py). -# See docs/improvement/ci-rules.md for rationale and PR workflow. - -markdown_paths: - - docs/**/*.md - - README.md - - CONTRIBUTING.md - - AGENTS.md - - simulator/README.md - - prototype/README.md - - infra/**/README.md - -glossary: - file: docs/00-glossary.md - -# Relative link targets that must never reappear (known regressions). -banned_link_targets: - - 03-storage-design.md - -# Glossary links to these section headers are allowed but reported as warnings -# when a term-specific ### anchor exists (see preferred_term_anchors). -glossary_section_anchors: - - data--storage - - swarm--robotics - - infrastructure--delivery - -# First-use vocabulary should link to these ### anchors, not section headers. -preferred_term_anchors: - - t0--hot - - t1--warm - - t2--shared - - t3--warehouse - - t4--dev - - source-of-truth - - architecture-layer-1--ingestion - - architecture-layer-2--storage-and-transform - - architecture-layer-3--serving-and-sync - - pipeline-stage - - bulk-sync - - offload - - rclone - - adr - - asr - -readability: - # Fail when prose uses bare "see 05" instead of a markdown link. - forbid_bare_see_refs: true diff --git a/docs/improvement/README.md b/docs/improvement/README.md index 162ba80..3ccac0b 100644 --- a/docs/improvement/README.md +++ b/docs/improvement/README.md @@ -15,7 +15,7 @@ Issues, PRs, and reviews default to **caveman-full** ([`CONTRIBUTING.md`](../../ ## CI automation -Enforced in Gitea Actions (`docs-verify` job). Rules live in [`bin/docs_rules.yaml`](../../bin/docs_rules.yaml); see [ci-rules.md](ci-rules.md). +Enforced in Gitea Actions (`docs-verify` job). Rules live in [`bin/docs_rules.json`](../../bin/docs_rules.json); see [ci-rules.md](ci-rules.md). Originally tracked in [issue #1](https://git.produktor.io/eSlider/swarm-house/issues/1). diff --git a/docs/improvement/ci-rules.md b/docs/improvement/ci-rules.md index 8887be6..d472712 100644 --- a/docs/improvement/ci-rules.md +++ b/docs/improvement/ci-rules.md @@ -2,7 +2,7 @@ Automated checks for markdown in this repository. Enforced on every **pull request** and on **push to `main`** (including docs-only pushes that skip the simulator gate). -Implementation: [`bin/check_docs.py`](../../bin/check_docs.py) reads [`bin/docs_rules.yaml`](../../bin/docs_rules.yaml). +Implementation: [`bin/check_docs.py`](../../bin/check_docs.py) reads [`bin/docs_rules.json`](../../bin/docs_rules.json). Workflow: [`.github/workflows/release.yaml`](../../.github/workflows/release.yaml) job **`Verify documentation`**. @@ -53,6 +53,6 @@ python bin/check_docs.py --warnings-as-errors # treat section-link warnings as ## Changing rules -1. Edit `bin/docs_rules.yaml` (paths, banned targets, preferred anchors). +1. Edit `bin/docs_rules.json` (paths, banned targets, preferred anchors). 2. Adjust `bin/check_docs.py` only when adding a new rule *type*. 3. Add a row to the table above and mention it in the audit/improvement record if the change is significant. diff --git a/simulator/tests/test_check_docs.py b/simulator/tests/test_check_docs.py index 540f5bd..4460667 100644 --- a/simulator/tests/test_check_docs.py +++ b/simulator/tests/test_check_docs.py @@ -2,6 +2,7 @@ from __future__ import annotations +import json import sys from pathlib import Path @@ -59,15 +60,18 @@ def test_broken_link_detected(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) - (docs / "bad.md").write_text("See [missing](missing.md).\n") rules = tmp_path / "bin" rules.mkdir() - (rules / "docs_rules.yaml").write_text( - "markdown_paths:\n - docs/**/*.md\n" - "glossary:\n file: docs/00-glossary.md\n" - "banned_link_targets: []\n" - "glossary_section_anchors: []\n" - "preferred_term_anchors: []\n" - "readability:\n forbid_bare_see_refs: false\n" + (rules / "docs_rules.json").write_text( + json.dumps( + { + "markdown_paths": ["docs/**/*.md"], + "glossary": {"file": "docs/00-glossary.md"}, + "banned_link_targets": [], + "glossary_section_anchors": [], + "preferred_term_anchors": [], + "readability": {"forbid_bare_see_refs": False}, + } + ) ) - checker = SCRIPTS / "check_docs.py" monkeypatch.setattr("check_docs.ROOT", tmp_path) - monkeypatch.setattr("check_docs.RULES_PATH", rules / "docs_rules.yaml") + monkeypatch.setattr("check_docs.RULES_PATH", rules / "docs_rules.json") assert run_checks() == 1