Skip to content

Commit 7294f6f

Browse files
kabraham13Kevin Abrahamclaude
authored
fix(pipeline): resolve gap paths to real files (#479)
detect_gaps.py copied docs.json page IDs, which have no extension, into the path of thin_page, missing_description and apiref_narrative_page gaps. The later steps expect a file: - generate.py read REPO_ROOT / path, got FileNotFoundError (swallowed by load_file, so the model saw an empty page) or, when a folder shares the page's name, IsADirectoryError (the run crashed) - the draft was written as docs--x--y with no .mdx, so evaluate.py found no .mdx files and the run failed Add util.page_file() to resolve a page ID to its .mdx/.md file and use it where the detector emits those three gap types. Detection is unchanged; only the path value differs. Add a stdlib test for the helper. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Kevin Abraham <kevin.abraham@deepl.com> Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2225892 commit 7294f6f

3 files changed

Lines changed: 79 additions & 3 deletions

File tree

‎pipeline/detect_gaps.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@
3030

3131
import yaml
3232

33+
from util import page_file
34+
3335

3436
REPO_ROOT = Path(__file__).resolve().parent.parent
3537
STANDARDS_PATH = REPO_ROOT / "standards" / "ia.yaml"
@@ -318,7 +320,7 @@ def detect_gaps(docs_json, endpoints, families, section=None, force=False):
318320
if fm is None:
319321
continue # file missing; separate concern
320322
if not is_openapi_page(fm):
321-
gaps.append(gap("apiref_narrative_page", "medium", None, path=p,
323+
gaps.append(gap("apiref_narrative_page", "medium", None, path=page_file(p) or p,
322324
desc=f"{p} sits in the API Reference tab but is not an endpoint page (narrative belongs in a product tab or Home)"))
323325

324326
# --- Ungrouped OpenAPI tags ------------------------------------------- #
@@ -334,10 +336,10 @@ def detect_gaps(docs_json, endpoints, families, section=None, force=False):
334336
if fm is None:
335337
continue
336338
if not fm.get("description"):
337-
gaps.append(gap("missing_description", "low", None, path=p,
339+
gaps.append(gap("missing_description", "low", None, path=page_file(p) or p,
338340
desc=f"{p} has no frontmatter description"))
339341
if len(strip_frontmatter(content).split()) < 100:
340-
gaps.append(gap("thin_page", "medium", None, path=p,
342+
gaps.append(gap("thin_page", "medium", None, path=page_file(p) or p,
341343
desc=f"{p} has under 100 words"))
342344

343345
return gaps

‎pipeline/test_page_file.py‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
#!/usr/bin/env python3
2+
"""Tests for resolving a docs.json page ID to its file.
3+
4+
python pipeline/test_page_file.py
5+
6+
Stdlib only: each test builds a throwaway docs tree in a temp directory.
7+
"""
8+
9+
import sys
10+
import tempfile
11+
import unittest
12+
from pathlib import Path
13+
14+
sys.path.insert(0, str(Path(__file__).resolve().parent))
15+
16+
from util import page_file # noqa: E402
17+
18+
19+
class PageFileTest(unittest.TestCase):
20+
def setUp(self):
21+
self._tmp = tempfile.TemporaryDirectory()
22+
self.addCleanup(self._tmp.cleanup)
23+
self.root = Path(self._tmp.name)
24+
25+
def touch(self, rel):
26+
path = self.root / rel
27+
path.parent.mkdir(parents=True, exist_ok=True)
28+
path.write_text("---\ntitle: t\n---\n", encoding="utf-8")
29+
30+
def test_resolves_an_mdx_page(self):
31+
self.touch("docs/a.mdx")
32+
self.assertEqual(page_file("docs/a", self.root), "docs/a.mdx")
33+
34+
def test_falls_back_to_md(self):
35+
self.touch("docs/a.md")
36+
self.assertEqual(page_file("docs/a", self.root), "docs/a.md")
37+
38+
def test_prefers_mdx_over_md(self):
39+
self.touch("docs/a.mdx")
40+
self.touch("docs/a.md")
41+
self.assertEqual(page_file("docs/a", self.root), "docs/a.mdx")
42+
43+
def test_a_page_and_a_folder_with_the_same_name_resolve_to_the_page(self):
44+
# docs/resources/breaking-changes-change-notices.mdx sits next to a folder of
45+
# the same name; the folder must never be mistaken for the page.
46+
self.touch("docs/a.mdx")
47+
self.touch("docs/a/child.mdx")
48+
self.assertEqual(page_file("docs/a", self.root), "docs/a.mdx")
49+
50+
def test_a_folder_without_a_page_resolves_to_nothing(self):
51+
self.touch("docs/a/child.mdx")
52+
self.assertIsNone(page_file("docs/a", self.root))
53+
54+
def test_a_missing_page_resolves_to_nothing(self):
55+
self.assertIsNone(page_file("docs/missing", self.root))
56+
57+
58+
if __name__ == "__main__":
59+
unittest.main()

‎pipeline/util.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,21 @@ def load_text(path):
3838
return ""
3939

4040

41+
def page_file(page_id, repo_root=REPO_ROOT):
42+
"""Repo-relative path of the file behind a docs.json page ID, or None.
43+
44+
docs.json lists pages without an extension (docs/resources/foo). A gap that
45+
carries that ID points at no file, or at a folder that happens to share the
46+
page's name, so resolve it to the real .mdx/.md file before any step reads or
47+
writes it.
48+
"""
49+
for ext in (".mdx", ".md"):
50+
candidate = f"{page_id}{ext}"
51+
if (Path(repo_root) / candidate).is_file():
52+
return candidate
53+
return None
54+
55+
4156
OUTPUT_RULES = """## Output Format
4257
4358
- Output ONLY the .mdx file content. No commentary, no explanation, no markdown fences.

0 commit comments

Comments
 (0)