Repository navigation
ci: list docs pages not verified for 6 months - #170
Conversation
The host answers 404 at its root, so the weekly link check failed (run 44069505306, issue #164). Name the TES API URL instead, which the service check covers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
scripts/check_verified.py lists the docs pages whose last_verified date is older than 6 months (or --months) or still null, with tests at 100% coverage. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A verified job in the Links workflow opens or comments on the issue "Docs pages to verify" with the pages due. The README says so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Read pages with a byte order mark as MkDocs does, and fail on a quoted or repeated last_verified key and on a value on the next line, which YAML reads but the script would have misread. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pages due are a reminder and stay due for weeks; failing the run would hide failures of the other checks. The README says how the issue ends. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An indented comment after last_verified: is still null, and a value after blank or comment lines is still a value. The README says which form of the key the weekly check reads; the job comment is clearer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewer's GuideImplementationAdd the dependency-free checker that parses verification dates, identifies due pages, and produces the report and CLI exit status.
ConfigurationSchedule the verification check in the weekly Links workflow and include it in the configured coverage checks.
DocumentationDocument the weekly report, local checker command, and issue lifecycle, and correct the proTES references to use its working TES API endpoint.
TestsCover date parsing, due-page selection, reporting, CLI behavior, and error handling for the new checker.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Documentation build overview
3 files changed± researchers/index.html± operators/services/index.html± operators/services/protes/index.html |
Linked issuesChecked at commit 321db7f #164 Dead links in the docs · 1 of 1 met
#168 ci: list docs pages not verified for 6 months · 4 of 4 met
|
There was a problem hiding this comment.
Hey - I've found 8 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="scripts/check_verified.py" line_range="54" />
<code_context>
+FRONT_MATTER = re.compile(r"^-{3}[ \t]*\n(.*?\n)(?:\.{3}|-{3})[ \t]*\n", re.DOTALL)
+# The key at the top level, its value up to a comment
+KEY = re.compile(
+ r"^last_verified[ \t]*:(?P<value>[^\n#]*?)[ \t]*(?:#[^\n]*)?$", re.MULTILINE
+)
+# Forms of the key that YAML reads but this script doesn't: a quoted key, and
</code_context>
<issue_to_address>
**Malformed dates disappear from reports**
When a `last_verified` value has `#` immediately after the date, without separating whitespace, `KEY` treats the adjacent `#` as a comment, so `read_page` accepts the malformed value as a fresh date and omits the page from the due report.
Treat `#` as a comment only when YAML whitespace separates it from the value, and reject values with an adjacent `#`.
</issue_to_address>
### Comment 2
<location path="scripts/check_verified.py" line_range="51" />
<code_context>
+)
+
+# As MkDocs reads front matter (`mkdocs.utils.meta.YAML_RE`)
+FRONT_MATTER = re.compile(r"^-{3}[ \t]*\n(.*?\n)(?:\.{3}|-{3})[ \t]*\n", re.DOTALL)
+# The key at the top level, its value up to a comment
+KEY = re.compile(
</code_context>
<issue_to_address>
**Front matter pages disappear**
When a page has CRLF front matter, or valid metadata before `last_verified` contains `---` or `...` followed by whitespace and a newline, `FRONT_MATTER` requires LF line endings and accepts a closing delimiter without requiring it to start a line. `read_page` therefore returns `None` for CRLF front matter or for valid metadata containing `---` or `...` mid-line before `last_verified`, so due pages are omitted from the report.
Match front-matter delimiters as complete lines while accepting CRLF line endings.
</issue_to_address>
### Comment 3
<location path="scripts/check_verified.py" line_range="54" />
<code_context>
+FRONT_MATTER = re.compile(r"^-{3}[ \t]*\n(.*?\n)(?:\.{3}|-{3})[ \t]*\n", re.DOTALL)
+# The key at the top level, its value up to a comment
+KEY = re.compile(
+ r"^last_verified[ \t]*:(?P<value>[^\n#]*?)[ \t]*(?:#[^\n]*)?$", re.MULTILINE
+)
+# Forms of the key that YAML reads but this script doesn't: a quoted key, and
</code_context>
<issue_to_address>
**Indented metadata is omitted**
When a page uses valid front matter with an indented root-level `last_verified` key, `KEY` only matches at column zero, so `read_page` returns `None` and stale or unverified pages are omitted from the weekly report.
Make `KEY` recognize valid indented root-level `last_verified` keys.
</issue_to_address>
### Comment 4
<location path="scripts/check_verified.py" line_range="52" />
<code_context>
+
+# As MkDocs reads front matter (`mkdocs.utils.meta.YAML_RE`)
+FRONT_MATTER = re.compile(r"^-{3}[ \t]*\n(.*?\n)(?:\.{3}|-{3})[ \t]*\n", re.DOTALL)
+# The key at the top level, its value up to a comment
+KEY = re.compile(
+ r"^last_verified[ \t]*:(?P<value>[^\n#]*?)[ \t]*(?:#[^\n]*)?$", re.MULTILINE
</code_context>
<issue_to_address>
**Pages without a final newline are skipped**
When a Markdown file's closing front-matter delimiter is the final bytes of the file, with no trailing newline, `FRONT_MATTER` requires a newline after the closing delimiter, so it returns no match when a Markdown file ends immediately after `---` or `...`. MkDocs' front-matter parser accepts that ending, so a stale or unverified page is omitted from the weekly report.
Allow end-of-file as well as a newline after the closing front-matter delimiter.
</issue_to_address>
### Comment 5
<location path="scripts/check_verified.py" line_range="152-153" />
<code_context>
+ not verified yet, by path.
+ """
+ stale = sorted(
+ (p for p in pages if p.verified is not None and p.verified < cutoff),
+ key=lambda p: (p.verified, p.path),
+ )
+ unverified = sorted((p for p in pages if p.verified is None), key=lambda p: p.path)
</code_context>
<issue_to_address>
**Future dates suppress reminders**
When a valid but future date is entered as `last_verified`, `due` only selects dates before the cutoff, so the page is treated as verified and omitted from the report until the cutoff passes its future date plus the configured age.
Reject dates later than the effective check date, including the `--today` value, as malformed.
</issue_to_address>
### Comment 6
<location path="scripts/check_verified.py" line_range="257" />
<code_context>
+ cutoff = months_before(today, options.months)
+ try:
+ files = find_files(options.paths or DEFAULT_PATHS, SUFFIXES)
+ pages = [page for path in files if (page := read_page(path)) is not None]
+ except CheckError as exc:
+ print(f"error: {exc}", file=sys.stderr)
</code_context>
<issue_to_address>
**Overlapping paths inflate counts**
When the caller supplies overlapping paths, such as a directory and a Markdown file inside it, `find_files` returns the same file for each matching argument, so `main` reads duplicate pages and lists them multiple times, inflating the report counts.
Deduplicate the files returned by `find_files` before reading pages.
</issue_to_address>
### Comment 7
<location path="scripts/check_verified.py" line_range="257-258" />
<code_context>
+ cutoff = months_before(today, options.months)
+ try:
+ files = find_files(options.paths or DEFAULT_PATHS, SUFFIXES)
+ pages = [page for path in files if (page := read_page(path)) is not None]
+ except CheckError as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ return 1
</code_context>
<issue_to_address>
**I/O errors escape CLI handling**
When a selected file cannot be read or decoded, or the requested output cannot be created or written, `read_page` and the output-file writes can raise `OSError` or `UnicodeDecodeError`, but `main` catches only `CheckError`; callers get an uncaught exception and traceback instead of the check’s documented error handling.
Catch `OSError` and `UnicodeDecodeError` for input reads and `OSError` for output writes, report the error, and return status 1.
Also at `scripts/check_verified.py:265-266`.
</issue_to_address>
### Comment 8
<location path="scripts/check_verified.py" line_range="173" />
<code_context>
+ Returns:
+ The report.
+ """
+ summary = f"{checked} pages have a `last_verified` date."
+ if not stale and not unverified:
+ return f"{summary} All of them were verified on or after {cutoff}.\n"
</code_context>
<issue_to_address>
**Dated page count is inflated**
When one or more pages have `last_verified` set to null, `~`, or an empty value, `main` includes pages with `verified is None` in `checked`, so the summary says they have a date even though they are listed as unverified; readers see an inflated dated-page count.
Count only pages with a non-`None` `verified` value in the dated-page summary.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 7 findings to address first, and if the date check reports pages incorrectly, the workflow may open an issue or add comments that remain after the change is reverted. Those reports are bounded and can be closed or cleaned up; reverting stops future reports.
Blocking findings: scripts/check_verified.py:54, scripts/check_verified.py:51, scripts/check_verified.py:54, scripts/check_verified.py:52, scripts/check_verified.py:153, and 2 more
Reject future dates, indented keys and a # right after the value, read each file once, turn read errors into exit 1, and count keys rather than dates in the summary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Lists the docs pages whose operational facts are due for verification, weekly, in one issue (part of #152).
scripts/check_verified.pyreads thelast_verifiedfront matter ofdocs/**/*.md(standard library only, like the other checks) and lists the pages whose date is older than 6 months (--months N) and the pages stillnull. Pages without the key are left out. Exit codes as for the other checks: 0 none due, 2 some due, 1 if it can't run. It rejects values the build rejects, and key forms it can't read without a YAML parser (quoted key, repeated key, value on the next line), so it never misreports a page; it also rejects dates in the future. Tests at 100% coverage.verified("Verified dates") in the weeklyLinksworkflow opens or comments on the issue "Docs pages to verify" via.github/actions/report-issue, labelledtype: docs.nulltoday the run would fail every week and hide real link or service failures. Say if you'd rather have the failure.Testjob inci.ymlalready reads "Tests of the scripts inscripts/and the hooks inhooks/" (updated by ci: check service URLs against the registry #167), so it needs no change.The first run will open the issue with the 25 pages that are still
null.Unrelated fixes
docs: stop linking the proTES host root: the first manual run ofLinksafter ci: flag links to archived repositories #169 (run 44069505306) failed inLink checkbecausehttps://protes.rahtiapp.fi/answers 404 (the service has no page at its root;/ga4gh/tes/v1/service-infoanswers 200). The two linked mentions now name the TES API URL as code. The other two jobs passed. This closes the dead-links issue Dead links in the docs #164.Verification
pytest: 356 passed, coverage 100%.mkdocs build --strict: passes;python scripts/check_names.py: passes.ruff checkandruff format --checkon the new files: clean;mypy --stricton the new script and its tests: clean.python scripts/check_verified.pyonmain's docs: exit 2, 28 pages with the key, 25null, none stale.Declined review findings
Two review rounds (adversarial and quality); all medium and low findings fixed except:
YAML_REand universal newlines, so it finds front matter exactly where MkDocs does (replied in the threads).? last_verified) and flow-style keys aren't recognized. Declined as unrealistic in front matter; the docstring says so.docs/researchers/federated-workflows.mdstill nameshttps://protes.rahtiapp.fias code. Not a link (lychee skips it), and the notebook there asks for the gateway address, so I left it.Closes #168
Closes #164
🤖 Generated with Claude Code