-
Notifications
You must be signed in to change notification settings - Fork 0
Add DocC documentation sync gate #478
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| from __future__ import annotations | ||
|
|
||
| import importlib.util | ||
| import json | ||
| from pathlib import Path | ||
|
|
||
| ROOT = Path(__file__).resolve().parents[1] | ||
|
|
||
|
|
||
| def _load_docc_sync_module(): | ||
| module_path = ROOT / "tools" / "validate_docc_sync.py" | ||
| spec = importlib.util.spec_from_file_location("_validate_docc_sync_under_test", module_path) | ||
| assert spec and spec.loader | ||
| module = importlib.util.module_from_spec(spec) | ||
| spec.loader.exec_module(module) | ||
| return module | ||
|
|
||
|
|
||
| def test_docc_sync_contract_passes() -> None: | ||
| module = _load_docc_sync_module() | ||
|
|
||
| assert module.validate(ROOT / "tools" / "docc_sync_contract.json") == [] | ||
|
|
||
|
|
||
| def test_docc_sync_rejects_empty_synchronized_documents(tmp_path) -> None: | ||
| module = _load_docc_sync_module() | ||
| source = tmp_path / "empty.md" | ||
| source.write_text("", encoding="utf-8") | ||
| mirror = tmp_path / "mirror.md" | ||
| mirror.write_text("anchor\n", encoding="utf-8") | ||
| contract = tmp_path / "contract.json" | ||
| contract.write_text( | ||
| json.dumps( | ||
| { | ||
| "groups": [ | ||
| { | ||
| "id": "empty-source", | ||
| "docs": [str(source)], | ||
| "docc": [str(mirror)], | ||
| "required_terms": ["anchor"], | ||
| } | ||
| ] | ||
| } | ||
| ), | ||
| encoding="utf-8", | ||
| ) | ||
|
|
||
| assert module.validate(contract) == [ | ||
| f"empty-source: {source} is empty", | ||
| f"empty-source: {source} is missing required term 'anchor'", | ||
| ] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| { | ||
| "groups": [ | ||
| { | ||
| "id": "static-artifact-publishing", | ||
| "description": "Static artifact and GitHub Pages publication rules must stay aligned between repository docs and DocC.", | ||
| "docs": [ | ||
| "docs/static_artifact_publish.md" | ||
| ], | ||
| "docc": [ | ||
| "Sources/SpecGraph/Documentation.docc/ArtifactPublishing.md" | ||
| ], | ||
| "required_terms": [ | ||
| "GitHub Pages", | ||
| "documentation/SpecGraph/", | ||
| "documentation/specgraph/", | ||
| "landing/" | ||
| ], | ||
| "docs_required_terms": [ | ||
| "artifact_manifest.json", | ||
| "checksums.sha256", | ||
| "make publish-bundle" | ||
| ], | ||
| "docc_required_terms": [ | ||
| "Static Host", | ||
| "product-facing surfaces" | ||
| ] | ||
| }, | ||
| { | ||
| "id": "proposal-runtime-evidence", | ||
| "description": "Proposal tracking and runtime evidence rules must stay visible in both contributor docs and DocC.", | ||
| "docs": [ | ||
| "CONTRIBUTING.md" | ||
| ], | ||
| "docc": [ | ||
| "Sources/SpecGraph/Documentation.docc/ProposalsAndRuntime.md" | ||
| ], | ||
| "required_terms": [ | ||
| "proposal", | ||
| "runtime evidence", | ||
| "docs/proposals/", | ||
| "make proposal-tracking-gate" | ||
| ], | ||
| "docs_required_terms": [ | ||
| "Proposal tracking" | ||
| ], | ||
| "docc_required_terms": [ | ||
| "proposal tracking" | ||
| ] | ||
| }, | ||
| { | ||
| "id": "operator-source-map", | ||
| "description": "The DocC root must keep pointing operators back to canonical repository documentation sources.", | ||
| "docs": [ | ||
| "README.md", | ||
| "AGENTS.md", | ||
| "tools/README.md" | ||
| ], | ||
|
SoundBlaster marked this conversation as resolved.
|
||
| "docc": [ | ||
| "Sources/SpecGraph/Documentation.docc/SpecGraph.md" | ||
| ], | ||
| "docs_required_terms": [ | ||
| "SpecGraph" | ||
| ], | ||
| "docc_required_terms": [ | ||
| "README.md", | ||
| "CONTRIBUTING.md", | ||
| "AGENTS.md", | ||
| "tools/README.md" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,123 @@ | ||
| #!/usr/bin/env python3 | ||
| """Validate that repository docs and DocC mirror pages stay synchronized.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import argparse | ||
| import json | ||
| import sys | ||
| from pathlib import Path | ||
| from typing import Any | ||
|
|
||
| ROOT = Path(__file__).resolve().parents[1] | ||
| DEFAULT_CONTRACT = ROOT / "tools" / "docc_sync_contract.json" | ||
|
|
||
|
|
||
| def _load_contract(path: Path) -> dict[str, Any]: | ||
| try: | ||
| data = json.loads(path.read_text(encoding="utf-8")) | ||
| except FileNotFoundError: | ||
| raise SystemExit(f"DocC sync contract not found: {path}") from None | ||
| except json.JSONDecodeError as exc: | ||
| raise SystemExit(f"Invalid DocC sync contract JSON at {path}: {exc}") from exc | ||
|
|
||
| if not isinstance(data, dict) or not isinstance(data.get("groups"), list): | ||
| raise SystemExit("DocC sync contract must contain a top-level 'groups' list") | ||
| return data | ||
|
|
||
|
|
||
| def _read_text(relative_path: str, errors: list[str]) -> str: | ||
| path = Path(relative_path) | ||
| if not path.is_absolute(): | ||
| path = ROOT / path | ||
| if not path.is_file(): | ||
| errors.append(f"missing file: {relative_path}") | ||
| return "" | ||
| return path.read_text(encoding="utf-8") | ||
|
|
||
|
|
||
| def _validate_group(group: dict[str, Any], errors: list[str]) -> None: | ||
| group_id = str(group.get("id", "<missing-id>")) | ||
| docs = group.get("docs") | ||
| docc = group.get("docc") | ||
| required_terms = group.get("required_terms", []) | ||
| docs_required_terms = group.get("docs_required_terms", []) | ||
| docc_required_terms = group.get("docc_required_terms", []) | ||
|
|
||
| if not isinstance(docs, list) or not docs: | ||
| errors.append(f"{group_id}: 'docs' must be a non-empty list") | ||
| return | ||
| if not isinstance(docc, list) or not docc: | ||
| errors.append(f"{group_id}: 'docc' must be a non-empty list") | ||
| return | ||
| for field_name, value in ( | ||
| ("required_terms", required_terms), | ||
| ("docs_required_terms", docs_required_terms), | ||
| ("docc_required_terms", docc_required_terms), | ||
| ): | ||
| if not isinstance(value, list): | ||
| errors.append(f"{group_id}: '{field_name}' must be a list") | ||
| return | ||
|
|
||
| if not required_terms and not docs_required_terms and not docc_required_terms: | ||
| errors.append( | ||
| f"{group_id}: at least one of 'required_terms', " | ||
| "'docs_required_terms', or 'docc_required_terms' must be non-empty" | ||
| ) | ||
| return | ||
|
|
||
| texts = {str(path): _read_text(str(path), errors) for path in [*docs, *docc]} | ||
|
|
||
| term_sets: dict[str, list[Any]] = {} | ||
| for path in docs: | ||
| term_sets[str(path)] = [*required_terms, *docs_required_terms] | ||
| for path in docc: | ||
| term_sets[str(path)] = [*required_terms, *docc_required_terms] | ||
|
|
||
| for path, text in texts.items(): | ||
| if not text.strip(): | ||
| errors.append(f"{group_id}: {path} is empty") | ||
| for term in term_sets[path]: | ||
|
SoundBlaster marked this conversation as resolved.
|
||
| if not isinstance(term, str) or not term: | ||
| errors.append(f"{group_id}: required term must be a non-empty string") | ||
| continue | ||
| if term not in text: | ||
| errors.append(f"{group_id}: {path} is missing required term {term!r}") | ||
|
|
||
|
|
||
| def validate(contract_path: Path) -> list[str]: | ||
| contract = _load_contract(contract_path) | ||
| errors: list[str] = [] | ||
| for raw_group in contract["groups"]: | ||
| if not isinstance(raw_group, dict): | ||
| errors.append("DocC sync contract group must be an object") | ||
| continue | ||
| _validate_group(raw_group, errors) | ||
| return errors | ||
|
|
||
|
|
||
| def main(argv: list[str] | None = None) -> int: | ||
| parser = argparse.ArgumentParser( | ||
| description="Validate synchronized coverage between repository docs and DocC pages." | ||
| ) | ||
| parser.add_argument( | ||
| "--contract", | ||
| type=Path, | ||
| default=DEFAULT_CONTRACT, | ||
| help="Path to the DocC sync contract JSON.", | ||
| ) | ||
| args = parser.parse_args(argv) | ||
|
|
||
| errors = validate(args.contract) | ||
| if errors: | ||
| print("DocC sync validation failed:", file=sys.stderr) | ||
| for error in errors: | ||
| print(f"- {error}", file=sys.stderr) | ||
| return 1 | ||
|
|
||
| print("DocC sync validation passed.") | ||
| return 0 | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| raise SystemExit(main()) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.