| #!/usr/bin/env python3 | |
| # *************************************************************************************************************************** | |
| # * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * | |
| # * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * | |
| # * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * | |
| # * with the License. You may obtain a copy of the License at * | |
| # * * | |
| # * http://www.apache.org/licenses/LICENSE-2.0 * | |
| # * * | |
| # * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * | |
| # * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * | |
| # * specific language governing permissions and limitations under the License. * | |
| # *************************************************************************************************************************** | |
| """ | |
| Check that the AI artifacts (including static/llms.txt) are fresh and report source drift signals. | |
| Full docs: check-ai-artifacts.md | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import json | |
| import re | |
| import subprocess | |
| import sys | |
| from pathlib import Path | |
| def run(cmd: list[str], cwd: Path) -> subprocess.CompletedProcess[str]: | |
| return subprocess.run(cmd, cwd=cwd, text=True, capture_output=True) | |
| def check_ai_artifact_freshness(docs_root: Path, juneau_root: Path) -> list[str]: | |
| result = run( | |
| [ | |
| sys.executable, "scripts/generate-ai-artifacts.py", "--check", | |
| "--docs-root", str(docs_root), "--juneau-root", str(juneau_root), | |
| ], | |
| docs_root, | |
| ) | |
| if result.returncode == 0: | |
| return [] | |
| errors = ["AI artifact freshness check failed."] | |
| if result.stdout: | |
| errors.append(result.stdout.strip()) | |
| if result.stderr: | |
| errors.append(result.stderr.strip()) | |
| return errors | |
| def check_llms_txt_shape(docs_root: Path) -> list[str]: | |
| path = docs_root / "static" / "llms.txt" | |
| if not path.exists(): | |
| return [f"Missing llms.txt: {path}"] | |
| text = path.read_text(encoding="utf-8") | |
| if not text.startswith("# Apache Juneau\n"): | |
| return ["llms.txt must start with the '# Apache Juneau' H1."] | |
| return [] | |
| def check_readme_version(docs_root: Path, release: str) -> list[str]: | |
| readme = (docs_root / "README.md").read_text(encoding="utf-8") | |
| m = re.search(r"<version>([^<]+)</version>", readme) | |
| if not m: | |
| return ["Could not find Maven <version> in juneau-docs README.md quickstart section."] | |
| found = m.group(1).strip() | |
| if found != release: | |
| return [f"README quickstart version mismatch: expected {release}, found {found}."] | |
| return [] | |
| def check_javadocs_link_consistency(docs_root: Path) -> list[str]: | |
| config = (docs_root / "docusaurus.config.ts").read_text(encoding="utf-8") | |
| matches = re.findall(r"href:\s*'pathname:///([^']+)'", config) | |
| javadocs_links = {link for link in matches if "javadocs" in link or "apidocs" in link} | |
| unique = sorted(javadocs_links) | |
| if len(unique) <= 1: | |
| return [] | |
| return [f"Javadocs links are inconsistent in docusaurus.config.ts: {', '.join(unique)}."] | |
| def check_release_note_source_presence(docs_root: Path, juneau_root: Path, release: str) -> list[str]: | |
| errors = [] | |
| docs_release = docs_root / "pages" / "release-notes" / f"{release}.md" | |
| if not docs_release.exists(): | |
| errors.append(f"Missing canonical release note page: {docs_release}") | |
| root_release = juneau_root / "RELEASE-NOTES.txt" | |
| if not root_release.exists(): | |
| errors.append(f"Missing legacy release-notes file: {root_release}") | |
| return errors | |
| def check_manifest_shape(docs_root: Path) -> list[str]: | |
| manifest_path = docs_root / "static" / "ai" / "manifest.json" | |
| if not manifest_path.exists(): | |
| return [f"Missing manifest: {manifest_path}"] | |
| manifest = json.loads(manifest_path.read_text(encoding="utf-8")) | |
| required = {"schema_version", "version", "generated_at", "source_commit", "record_count"} | |
| missing = sorted(required.difference(manifest.keys())) | |
| if missing: | |
| return [f"Manifest missing required fields: {', '.join(missing)}"] | |
| return [] | |
| def resolve_current_release(juneau_root: Path) -> str: | |
| script = juneau_root / "scripts" / "current-release.py" | |
| result = run([sys.executable, str(script)], juneau_root) | |
| if result.returncode != 0: | |
| raise RuntimeError(result.stderr or "unable to resolve current release") | |
| return result.stdout.strip() | |
| def parse_args() -> argparse.Namespace: | |
| script_dir = Path(__file__).resolve().parent | |
| parser = argparse.ArgumentParser(description="Check Juneau docs AI artifacts.") | |
| parser.add_argument("--docs-root", type=Path, default=script_dir.parent, | |
| help="juneau-docs checkout root (default: parent of this script's folder)") | |
| parser.add_argument("--juneau-root", type=Path, default=None, | |
| help="Juneau source checkout (default: sibling ../juneau)") | |
| return parser.parse_args() | |
| def main() -> int: | |
| args = parse_args() | |
| docs_root = args.docs_root.resolve() | |
| juneau_root = (args.juneau_root or docs_root.parent / "juneau").resolve() | |
| if not (juneau_root / "scripts" / "current-release.py").is_file(): | |
| print(f"ERROR: Juneau checkout not found at {juneau_root} (missing scripts/current-release.py).") | |
| print("Pass --juneau-root /path/to/juneau to specify it explicitly.") | |
| return 1 | |
| release = resolve_current_release(juneau_root) | |
| errors: list[str] = [] | |
| errors.extend(check_ai_artifact_freshness(docs_root, juneau_root)) | |
| errors.extend(check_manifest_shape(docs_root)) | |
| errors.extend(check_llms_txt_shape(docs_root)) | |
| errors.extend(check_readme_version(docs_root, release)) | |
| errors.extend(check_javadocs_link_consistency(docs_root)) | |
| errors.extend(check_release_note_source_presence(docs_root, juneau_root, release)) | |
| if errors: | |
| print("AI documentation checks failed:") | |
| for err in errors: | |
| print(f"- {err}") | |
| return 1 | |
| print("All AI documentation checks passed.") | |
| return 0 | |
| if __name__ == "__main__": | |
| raise SystemExit(main()) |