Promote integration to main: fix the 44 dead fork links - #66
Merged
Conversation
Fixes 44 dead links in published specification prose, and adds the guard that would have caught them. ## The defect Every link of the form `https://github.com/afogel/ACS_official/blob/dev/specification/v0.1.0/...` returns **HTTP 404**. The fork is public, but it has no `dev` branch. 25 of the 44 are live on the published hooks page right now. They all arrived in one commit, `f46d260 "Integrate canonical v0.1.0 (#2)"`, the donation import. The links were self-referential when the spec lived in that repo, the content moved to `GenAI-Security-Project`, and the links did not. The `dev` branch was later removed, turning stale links into broken ones. Affected: `hooks.md` (25), `specification.md` (8), `inspect/README.md` (3), `trace/events.md` (2), and one each in `extend_cyclonedx.md`, `extend_spdx.md`, `extend_swid.md`, `extend_ocsf.md`, `extend_opentelemetry.md`. ## The fix Each file link now points at that schema's own `$id`. The mapping was verified programmatically against `specification/v0.1.0/**/*.json` before anything was rewritten: every linked path exists, and its `$id` equals the replacement URL exactly. Those URLs return 200 and are already re-checked every six hours by `monitor-pages.yml`. That location is also durable in a way the old one was not. A `blob/<branch>` URL rots when a branch is renamed. A schema `$id` is the identity the specification already commits to. One of the 44 is a directory browse link with no `$id`. It points at the canonical repository tree instead. ## Why this was invisible Three things, each individually reasonable: - No link checker exists anywhere in CI. - `mkdocs build --strict` validates internal references only, never external URLs. - `tests/conftest.py` deliberately exempts `("a", "href")` as non-fetching, which is correct, because that guard protects against resources a browser fetches rather than links a human clicks. So the repository had strong guards against third-party asset injection and none against dead links in its own normative prose. ## The guard `tests/test_doc_links.py`, committed before the fix so the failure is in the history. - **Foreign repositories.** No file under `docs/` may link to a `github.com` repository outside a three-entry allowlist: this repository, plus `prowler-cloud/py-ocsf-models` and `ocsf/examples`, which are legitimate OCSF references already present. Positive allowlist, so a new foreign repository fails until someone adds it deliberately. - **Schema links stay canonical.** Every docs link into the published schema namespace must resolve to a schema that exists under `specification/` and whose `$id` equals that exact URL. This catches drift in both directions, including a schema that gets moved or renamed. ## Verification - Guard finds 44 violations before the fix, 0 after - `uv run pytest`: 204 passed, 1 skipped - `uv run mkdocs build --strict`: clean - Five rewritten URLs fetched live: all 200 - No `afogel` reference remains anywhere in the repository --------- Signed-off-by: rocklambros <rock@rockcyber.com>
rocklambros
requested review from
GangGreenTemperTatum,
afogel,
almogbhl,
bar-capsule,
fewdisc,
mamicidal,
sclintonowasp and
stefanoamorelli
as code owners
September 10, 2026 01:41
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Carries #65 to the publishing branch. 44 links in published spec prose currently return HTTP 404, and 25 of them are live on the hooks page right now. Merging this republishes the site with them pointing at each schema's own $id.
Merge with a merge commit, not a squash.