Conversation
- `core/src/compact_cache_builder.rs` -> `core/src/compact.rs`, renamed in a0d2957 ("refactor(core): rename compact_cache_builder -> compact"). Five references across text-pipeline, compact-cache and css-parser. - `layout/src/paged.rs` -> `core/src/paged.rs`, moved in c94d0f5 ("cleanup(core): move paged-media primitives from layout to core"). - `core/src/hit_test_tag.rs` -> `core/src/hit_test.rs`, merged in 15d61ef ("cleanup(core): merge hit_test_tag into hit_test"). - `dll/src/web/cb_gen.rs` -> `dll/src/web/mod.rs`, merged in edb8ee4 ("refactor: merge cb_gen.rs stub into web/mod.rs"). Each target verified present on master; each source verified absent.
|
Yeah I'll have to redo the docs anyway (I'll probably remove the "internal" docs because there's just so much doc drift). |
|
Hello @melbinjp - thank you for your tool and PR, but the docs that you're fixing are gone now on master, because I deleted all the "Internal Documents" because the code vs docs drift is way too heavy. The guide now only leaves the "public API docs" in place, so I am closing this PR because it can't be merged anymore (the docs are gone, intentionally). However, I will install your tool in the CI, I checked it for security problems and the only small problem is that the Readme should use something like I now added both an |
Twelve pointers in the documentation named a file, a page, or a heading that is not there. PR fschutt#434 found four of them from outside the project and sent them as a patch; the tree those four lived in had been deleted the day before, so the patch cannot merge and the class of defect it found is still here. This is the gate instead of the patch. TWO CHECKERS, because they prove different things and neither subsumes the other: azul-doc check links resolution against the worktree. A `[text](../dom.md)` whose page is not there, an image that is not on disk, a `#anchor` with no heading behind it, a backticked `core/src/foo.rs` that moved. No history needed, so it runs offline in `azul-doc check` and in `cargo test -p azul-doc` - which is where a contributor meets it, before pushing. Anchors are checked by rendering the target page through comrak with the same `header_ids` the generator uses and reading the ids back out of the emitted anchor tags, so this cannot drift from what the site serves the way a reimplemented slug function would. docproof drift from git history. It says *"moved to `core/src/compact.rs` in a0d2957"* rather than "not found", which is the difference between a finding you can act on and one you have to investigate. That needs full history, so it is a CI job. The overlap is deliberate and the edges are the point: a path that never existed is not a finding for docproof (no deletion to point at), and a broken intra-guide link is invisible to it (verified by injecting one). THE THIRD-PARTY JOB IS PINNED AND PENNED IN. docproof is ~3.3k lines of Python from another repository, read before adoption: no network, no filesystem writes, no eval/exec, subprocess is `git` only with list-argv and a timeout, and a claimed path is resolved then `relative_to(root)` before use. On top of that the job: - pins a COMMIT, not a tag. `@v1` is a mutable pointer someone else owns; a SHA is the content. The rev-parse assertion after checkout is there because `ref:` accepts a branch name too. - takes `permissions: contents: read`. The workflow grants `pages: write` and `id-token: write` at the top, and a job-level block replaces the default rather than adding to it. - sets `persist-credentials: false` on both checkouts, so the run's GITHUB_TOKEN is not sitting in `.git/config` while another repository's code runs. - runs from source over PYTHONPATH rather than `pip install`, which would resolve the build backend and its dependencies from PyPI unpinned - a far larger surface than the thing being pinned. On 3.12 the tool needs no packages at all. - fails when it judged NOTHING. A shallow clone cannot tell a deleted path from one that never existed, so every judgement degrades to a skip and the run goes green having checked nothing; the shallow guard and the `^(ok|BROKEN) paths:` assertion turn both routes into a failure. The status is captured rather than piped through `tee`, which would have returned 0 and swallowed every finding. - asserts the tree is unmodified afterwards. The tool is read-only today; if a future pin writes, this run is where we find out. THE TWELVE, each verified against the commit that moved the thing: doc/README.md the autoreview pipeline still routed through `doc/guide/en/reference.md`, deleted by b87ba47 - our own commit, two days ago. Stage removed, the rest renumbered. NAVIGATION.md `cpurender.rs` became a directory in 16104b1; now names the directory and its four modules. SUPER_PLAN / webtransport-plan three UDP paths removed in 1f5cbd4. The deferred item they belonged to is marked done, with the commit. headless/pdf.md `examples/azul-doc` -> `azul-writer`, 8564dc2. headless/rendering.md `scripts/screenshot.sh` was removed in 9c0d709; the harness is `autoreview autodoc-screenshots`. five anchors three headings on dom.md no longer exist under the names four pages linked to; the sizing link on layout.md was one dash short of the slug comrak actually emits. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
You reimplemented two guards the action already has: it refuses to run without Your workflow asserts the tool is read-only on the grounds that it "is documented as read-only". It was not documented, and nothing checked it. It was just true. Now it is both: |
2 participants
The internals guide points at four source files that have moved or merged. Each target verified present on
master, each source verified absent.rendering/text-pipeline.md:83,styling/compact-cache.md(x3),styling/css-parser.md:298core/src/compact_cache_builder.rscore/src/compact.rs, renamed ina0d295796layout/fragmentation.md:52layout/src/paged.rscore/src/paged.rs, moved inc94d0f5faevents/hit-testing.md:88core/src/hit_test_tag.rscore/src/hit_test.rs, merged in15d61efdcstyling/css-parser.md:106dll/src/web/cb_gen.rsdll/src/web/mod.rs, merged inedb8ee4e7Each commit message says what happened in its own words: "rename compact_cache_builder -> compact", "move paged-media primitives from layout to core", "merge hit_test_tag into hit_test", "merge cb_gen.rs stub into web/mod.rs". Ten lines across five files, no prose changes.
What is deliberately not in this
Six more stale paths remain and each needs a judgement I should not make from outside:
layout/fragmentation.md:49nameslayout/src/fragmentation.rs, gone inf3151a0e4. There is acss/src/props/layout/fragmentation.rs, but that is a CSS property module and may not be what the sentence means.pdf.md:62namesexamples/azul-doc, gone in8564dc2f4. No obvious successor among the current examples.internals/web.md:1110and:1112name two dated session logs removed by9b55eeea2("remove 58 dated session-log/handoff/sprint s"). Deleting the references is probably right and it is an editorial call.SUPER_PLAN_0.2.0.md:175names two UDP transport paths removed in1f5cbd437. A plan document describing what was planned is not obviously wrong for naming them.Happy to send any of those as a follow-up if you say which way they should go.
Found by docproof, a documentation checker that resolves documented paths against the repository and its git history. Verified against
masteratd60e0e5d4before opening.