Add a docs validator: fragment anchors, broken paths, part-number consistency

[munzzyy]

This adds tools/validate_docs.py, a standalone script covering three things archbee validate / archbee broken-links (.github/workflows/validate.yml) don't:

1. Anchor check -- for every internal link with a #fragment, resolve the target page and confirm the fragment actually matches one of its headings (computed the same way GitHub computes heading anchors: lowercase, strip punctuation, spaces to hyphens, -1/-2 suffixes for repeated headings).
2. Path check -- for every internal link and image reference, including Archbee's ::Image[]{src="..."} / :inlineImage[]{src="..."} directives, confirm the target file exists.
3. Part-number check -- flags part-number "families" (BQ25xxx chargers, BQ28Zxxx fuel gauges, MT7921xxx Wi-Fi chips) that resolve to more than one distinct value across the docs. This one's a warning, not an error, because hardware revs do swap parts sometimes. It surfaces the disagreement for someone to adjudicate instead of assuming either side is wrong.

Archbee's checker resolves that a link's target file exists, but it doesn't parse the target's headings to confirm the fragment is real, and it has no concept of a part number at all. That's a real gap: #419 fixes 4 broken-anchor/path bugs that have been sitting on public-release through every CI run, and #420/#422 cover a part-number mismatch (BQ25792 vs BQ25798, BQ28Z610 vs BQ28Z620) that no automated check would have caught either.

Fenced code blocks are skipped by every check, since the contribution guide pages use placeholder paths like your-image.png as syntax examples inside ```markdown fences (About-Docs.md, About-Hardware.md) -- those aren't real broken links and shouldn't be flagged.

What it finds on current public-release: 8 errors, 16 warnings, all triaged by hand, zero false positives.

Errors (all genuinely broken):

• The 3 #contributing-a-third-party-module links in dev-log/4.md and dev-log/5.md -- fixed by Fix broken section anchors and an image path, add missing eSIM mention #419.
• The malformed /.#comment-on-an-open-task link on About-Testing.md -- fixed by Fix broken section anchors and an image path, add missing eSIM mention #419.
• The missing leading slash on the image path in Video-decoding.md -- fixed by Fix broken section anchors and an image path, add missing eSIM mention #419.
• Three more instances of that exact same missing-slash bug that Fix broken section anchors and an image path, add missing eSIM mention #419 doesn't touch: cpu-software/How-to-install-linux-image.md has three ::Image[]{src="files/pics/..."} directives all missing the leading /. Worth noting these each carry a githubPath="docs/files/pics/..." attribute with the correct full path right next to the broken src -- looks like whatever generated these directives got the two attributes out of sync. I didn't fix these here since this PR is about the checker, not the docs, but they're real and reproducible on HEAD.

Warnings (real disagreements, left for a human to resolve, not fixed here):

• BQ25792 (Tech-Specs.md) vs BQ25798 (Heatsink.md) and BQ28Z610 (Tech-Specs.md) vs BQ28Z620 (Power-subsystem.md) -- same mismatch as Battery, charger, and fuel gauge specs differ between Tech-Specs and the power/mechanics pages #420, being resolved in Fix charger and fuel gauge part numbers to match the shipped hardware #422.
• MT7921AUN vs MT7921AU across Tech-Specs.md, WiFi-Bluetooth.md, WiFi.md, WiFi-DBDC.md, and dev-log/4.md (12 occurrences). I looked into this one previously and couldn't find a public source that resolves which suffix is correct, so it's flagged rather than fixed -- exactly the case this check is meant to surface for a human with the datasheet, not to auto-resolve.

Won't catch: the missing "eSIM" mention on Tech-Specs.md's interfaces list, also fixed in #419. That's a plain content omission, not a link or part-number mismatch, and this kind of structural check has no way to see it.

Testing: tools/test_validate_docs.py, unittest, 35 tests covering slug computation (punctuation, emoji, duplicate headings, markdown/directive syntax inside headings), fragment resolution, the Archbee image directive parsing, code-fence skipping, and part-family divergence detection. Runs with python -m unittest or directly. All passing. mypy tools/*.py is clean under the same strict config pyproject.toml already has, run the same way test-open-tasks-generator.yml runs it.

This only touches tools/, no workflow files. Run it with python3 tools/validate_docs.py (add --strict to also fail on the part-number warnings). Happy to add a small CI job wired the same way as the existing "Test Open Tasks generator" workflow if that's wanted, but figured the workflow wiring itself should be your call.

[NickVolynkin]

Hi @munzzyy, thanks for the contribution. I see three separate checks here; let's discuss each one.

Anchor link checker
Great addition to built-in Archbee checks. I've tested it and found a few errors that you've already fixed in #419. Let's add a CI job to run this test. Would you like to do it yourself or let someone else make a contribution?

Image path checker
There are false positive results: the test resolves image paths as relative to the .md file, but it seems that Archbee resolves them as relative to the project root.

ERROR   docs/cpu-software/How-to-install-linux-image.md:14  [path] target 'files/pics/rk3576_maskrom_mode.jpg' does not resolve to an existing file (resolved: docs/cpu-software/files/pics/rk3576_maskrom_mode.jpg)
ERROR   docs/cpu-software/How-to-install-linux-image.md:26  [path] target 'files/pics/rk3576_boot_priority_logic.jpg' does not resolve to an existing file (resolved: docs/cpu-software/files/pics/rk3576_boot_priority_logic.jpg)
ERROR   docs/cpu-software/How-to-install-linux-image.md:32  [path] target 'files/pics/rk3576_boot_mode_config.jpg' does not resolve to an existing file (resolved: docs/cpu-software/files/pics/rk3576_boot_mode_config.jpg)

For example

• file path: files/pics/rk3576_maskrom_mode.jpg
• path resolved by test: docs/cpu-software/files/pics/rk3576_maskrom_mode.jpg
• actual path: docs/files/pics/rk3576_maskrom_mode.jpg
• rendered successfully in a document: https://docs.flipper.net/one/cpu-software/how-to-install-linux-image#rockchip-maskrom-mode

I've checked if Archbee can detect an actually broken image path, and it cannot. So, the test is actually useful, but needs to be fixed first.

Please also split the anchor link and image path checkers into separate scripts or different --keys of a single script. We'll need to run these tests separately in CI, so we see precisely what's broken when a test fails.

Part number checker
There is, indeed, an inconsistency. We should certainly fix it, but I don't think we should test it this way. A precise part number/model is almost like a term or a proper name (such as Flipper One). There are dedicated linters for checking terms and proper names, starting with https://vale.sh/.

So, I think it's best to exclude this check from the current PR.

---

To sum it up, please check the following points:

• Fix image path resolving
• Add separate commands or --keys to run anchor and image path checks.
• Add each check to CI as a separate job step in the validate.yml workflow
• Remove the model number check.
• (Optionally) Fix the model number in a separate PR.