morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 07:47:29 +00:00

[GH-ISSUE #2679] Inconsistent absolute URLs in "What you can analyze" table violate CONTRIBUTING.md guidance #980

New issue

Closed

opened 2026-10-15 18:30:04 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

2026-10-15 18:30:04 +00:00

Owner

Originally created by @rollroyces on GitHub (Oct 13, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2679

What I observed

CONTRIBUTING.md states verbatim:

"Site navigation lives in docs/.vitepress/config.ts. Keep links to guides relative so they work on GitHub and the website; link to repository files outside docs/ using their full GitHub URLs."

The English README.md "What you can analyze" table mostly links to guide pages with relative paths such as docs/binary-diagnostics.md, docs/evm-bytecode.md, and docs/android-analysis.md. Three cells deviate from that rule and instead point at https://rea.tools/guides/<topic>/.

Note: I did not find a fourth violating cell in the badge row. The badges point at shields.io, npmjs.com, skills.sh, discord.gg, and trendshift.io — none match the https://rea.tools/guides/<topic>/ shape. If a fourth cell exists that I missed, please point me to it and I will re-check.

The 3 inconsistent cells

Row label	Current absolute URL	Candidate relative target
Native binaries	`https://rea.tools/guides/native/`	`docs/native-investigation.md` is the closest match; `docs/native.md` does not exist — needs maintainer confirmation
JavaScript / Electron	`https://rea.tools/guides/javascript/`	No obvious 1:1. Candidates: `docs/javascript-application-workflows.md`, `docs/javascript-application-graph.md`, `docs/javascript-recovery.md`, `docs/javascript-runtime-observation.md`, `docs/javascript-runtime-reconciliation.md`, `docs/javascript-artifact-reconstruction.md` — needs maintainer confirmation
Websites	`https://rea.tools/guides/browser/`	`docs/browser-observation.md` is the closest match; `docs/browser.md` does not exist — needs maintainer confirmation

docs/native.md, docs/javascript.md, and docs/browser.md are all absent from the listing, so an automated guess risks pointing the table at the wrong guide.

Why this is more than cosmetic

Relative links are what lets the same Markdown render sensibly on github.com and the VitePress site. Absolute URLs in those three rows always take the reader off-repo on GitHub, and they bypass the link checker: a typo like https://rea.tools/guides/nativ/ would fail-fast on a relative-path lint but silently 404 on the published site until a user notices. Aligning the three outliers with the rest of the table restores the property CONTRIBUTING.md asks for.

What I'm NOT proposing

I will not open a PR until the maintainer confirms the three target paths. Two of the three rows have no obvious 1:1 candidate in docs/, so an automated edit would risk pointing the table at the wrong guide.

Verification I can run

npm run docs:check (mentioned in CONTRIBUTING.md) would catch broken relative paths introduced by the edit, but it cannot tell us whether the chosen docs/<file>.md is the right guide for that table row — that judgement belongs to a maintainer who knows the docs taxonomy. I have not yet run the check myself, because I don't want to converge on a target path before confirmation.

Offer

Happy to turn this into a focused PR once the 3 target paths are confirmed.

Originally created by @rollroyces on GitHub (Oct 13, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2679 ## What I observed `CONTRIBUTING.md` states verbatim: > "Site navigation lives in `docs/.vitepress/config.ts`. Keep links to guides relative so they work on GitHub and the website; link to repository files outside `docs/` using their full GitHub URLs." The English `README.md` "What you can analyze" table mostly links to guide pages with relative paths such as `docs/binary-diagnostics.md`, `docs/evm-bytecode.md`, and `docs/android-analysis.md`. **Three cells** deviate from that rule and instead point at `https://rea.tools/guides/<topic>/`. Note: I did not find a fourth violating cell in the badge row. The badges point at shields.io, npmjs.com, skills.sh, discord.gg, and trendshift.io — none match the `https://rea.tools/guides/<topic>/` shape. If a fourth cell exists that I missed, please point me to it and I will re-check. ## The 3 inconsistent cells | Row label | Current absolute URL | Candidate relative target | | --- | --- | --- | | Native binaries | `https://rea.tools/guides/native/` | `docs/native-investigation.md` is the closest match; `docs/native.md` does not exist — needs maintainer confirmation | | JavaScript / Electron | `https://rea.tools/guides/javascript/` | No obvious 1:1. Candidates: `docs/javascript-application-workflows.md`, `docs/javascript-application-graph.md`, `docs/javascript-recovery.md`, `docs/javascript-runtime-observation.md`, `docs/javascript-runtime-reconciliation.md`, `docs/javascript-artifact-reconstruction.md` — needs maintainer confirmation | | Websites | `https://rea.tools/guides/browser/` | `docs/browser-observation.md` is the closest match; `docs/browser.md` does not exist — needs maintainer confirmation | `docs/native.md`, `docs/javascript.md`, and `docs/browser.md` are all absent from the listing, so an automated guess risks pointing the table at the wrong guide. ## Why this is more than cosmetic Relative links are what lets the same Markdown render sensibly on github.com and the VitePress site. Absolute URLs in those three rows always take the reader off-repo on GitHub, and they bypass the link checker: a typo like `https://rea.tools/guides/nativ/` would fail-fast on a relative-path lint but silently 404 on the published site until a user notices. Aligning the three outliers with the rest of the table restores the property CONTRIBUTING.md asks for. ## What I'm NOT proposing I will not open a PR until the maintainer confirms the three target paths. Two of the three rows have no obvious 1:1 candidate in `docs/`, so an automated edit would risk pointing the table at the wrong guide. ## Verification I can run `npm run docs:check` (mentioned in CONTRIBUTING.md) would catch broken relative paths introduced by the edit, but it cannot tell us whether the chosen `docs/<file>.md` is the *right* guide for that table row — that judgement belongs to a maintainer who knows the docs taxonomy. I have not yet run the check myself, because I don't want to converge on a target path before confirmation. ## Offer Happy to turn this into a focused PR once the 3 target paths are confirmed.

bsakaguchi

2026-10-15 18:30:04 +00:00

closed this issue
added the
area: domain

enhancement
labels

bsakaguchi commented

2026-10-15 18:30:06 +00:00

Author

Owner

@YunzhouLi-hub commented on GitHub (Oct 13, 2026):

Hi, I'd like to take this one. The three target paths are not actually ambiguous — docs/.vitepress/config.ts is the navigation authority CONTRIBUTING.md points at, and its "Investigation guides" sidebar group names all three exactly:

README cell	absolute URL	`docs/.vitepress/config.ts` entry	resolved guide
Native binaries	`https://rea.tools/guides/native/`	`:29` `{ text: "Native binaries", link: "/native-investigation" }`	`docs/native-investigation.md`
JavaScript / Electron	`https://rea.tools/guides/javascript/`	`:31-34` `{ text: "JavaScript and Electron", link: "/javascript-artifact-reconstruction" }`	`docs/javascript-artifact-reconstruction.md`
Websites	`https://rea.tools/guides/browser/`	`:39` `{ text: "Browser observation", link: "/browser-observation" }`	`docs/browser-observation.md`

All three files exist; docs/native.md, docs/javascript.md and docs/browser.md do not.

While working it I hit a scope question this issue does not cover, and it needs a maintainer decision rather than my guess.

docs:check requires all 18 translated READMEs to carry the same link set as README.md. scripts/lib/docs-facts.mjs:104-110 compares the sorted link targets of every README_*.md against README.md, and :13-23 strips the locale prefix from https://rea.tools/<locale>/guides/... so the two sides line up. That prefix-stripping is why the current state passes: English uses the bare URL, translations use the locale-prefixed one, and the checker treats them as the same logical target.

So fixing only README.md turns docs:check red — I measured 18 failures of documentation links differ from README.md. The translations have to change in the same commit, and that is where the real question sits:

Should the translated files also become relative docs/*.md links?

I went with yes in #2786, for three reasons: CONTRIBUTING.md's rule is stated without a language carve-out, relative links certainly work on GitHub, and keeping the absolute form leaves the checker unsatisfiable. But the tradeoff is real and I cannot verify the second half of it locally:

On GitHub, a translated reader clicking "原生分析" now lands on the English docs/native-investigation.md instead of the localized https://rea.tools/zh-CN/guides/native/. That is a genuine localisation regression.
Whether the VitePress site still serves these cells for a non-English locale depends on how docs/*.md resolves under a locale route prefix. I did not run a website build, so I am not claiming the website half works — only that the GitHub half does.

If the localized behaviour matters more than the link checker, the alternative is to leave the translations absolute and teach readmeLinkTargets about the relative form instead. That is a check-logic change, which is a bigger call than a docs fix, so I did not make it unilaterally.

Happy to rework #2786 in whichever direction you prefer. I drafted it as a draft PR deliberately, since the localisation question is open.

@YunzhouLi-hub commented on GitHub (Oct 13, 2026): Hi, I'd like to take this one. The three target paths are not actually ambiguous — `docs/.vitepress/config.ts` is the navigation authority CONTRIBUTING.md points at, and its "Investigation guides" sidebar group names all three exactly: | README cell | absolute URL | `docs/.vitepress/config.ts` entry | resolved guide | | --- | --- | --- | --- | | Native binaries | `https://rea.tools/guides/native/` | `:29` `{ text: "Native binaries", link: "/native-investigation" }` | `docs/native-investigation.md` | | JavaScript / Electron | `https://rea.tools/guides/javascript/` | `:31-34` `{ text: "JavaScript and Electron", link: "/javascript-artifact-reconstruction" }` | `docs/javascript-artifact-reconstruction.md` | | Websites | `https://rea.tools/guides/browser/` | `:39` `{ text: "Browser observation", link: "/browser-observation" }` | `docs/browser-observation.md` | All three files exist; `docs/native.md`, `docs/javascript.md` and `docs/browser.md` do not. While working it I hit a scope question this issue does not cover, and it needs a maintainer decision rather than my guess. **`docs:check` requires all 18 translated READMEs to carry the same link set as `README.md`.** `scripts/lib/docs-facts.mjs:104-110` compares the sorted link targets of every `README_*.md` against `README.md`, and `:13-23` strips the locale prefix from `https://rea.tools/<locale>/guides/...` so the two sides line up. That prefix-stripping is why the current state passes: English uses the bare URL, translations use the locale-prefixed one, and the checker treats them as the same logical target. So fixing only `README.md` turns `docs:check` red — I measured 18 failures of `documentation links differ from README.md`. The translations have to change in the same commit, and that is where the real question sits: **Should the translated files also become relative `docs/*.md` links?** I went with yes in #2786, for three reasons: CONTRIBUTING.md's rule is stated without a language carve-out, relative links certainly work on GitHub, and keeping the absolute form leaves the checker unsatisfiable. But the tradeoff is real and I cannot verify the second half of it locally: - On GitHub, a translated reader clicking "原生分析" now lands on the **English** `docs/native-investigation.md` instead of the localized `https://rea.tools/zh-CN/guides/native/`. That is a genuine localisation regression. - Whether the VitePress site still serves these cells for a non-English locale depends on how `docs/*.md` resolves under a locale route prefix. I did not run a website build, so **I am not claiming the website half works** — only that the GitHub half does. If the localized behaviour matters more than the link checker, the alternative is to leave the translations absolute and teach `readmeLinkTargets` about the relative form instead. That is a check-logic change, which is a bigger call than a docs fix, so I did not make it unilaterally. Happy to rework #2786 in whichever direction you prefer. I drafted it as a draft PR deliberately, since the localisation question is open.

bsakaguchi commented

2026-10-15 18:30:06 +00:00

Author

Owner

@morluto commented on GitHub (Oct 14, 2026):

Addressed on main in e572c38dcf6ae72176319baef000784ff7d15e2f.

The three analysis-table guide links use existing repository Markdown targets, including every translated README.

Validation: Affected suites passed in the merged 65-file run (1169 passed, 2 explicit skips), with full static/architecture checks and documentation checks passing. Final installed-package verification is recorded separately in the audit.

Verification scope: Controlled source and production-boundary verification on macOS with pinned Node 24.18.0; real external engines and Windows hosts were not independently rerun. Closure covers the described source defect, not broader provider conformance or performance.

@morluto commented on GitHub (Oct 14, 2026): Addressed on main in [e572c38dcf6ae72176319baef000784ff7d15e2f](https://github.com/morluto/rea/commit/e572c38dcf6ae72176319baef000784ff7d15e2f). The three analysis-table guide links use existing repository Markdown targets, including every translated README. Validation: Affected suites passed in the merged 65-file run (1169 passed, 2 explicit skips), with full static/architecture checks and documentation checks passing. Final installed-package verification is recorded separately in the audit. Verification scope: Controlled source and production-boundary verification on macOS with pinned Node 24.18.0; real external engines and Windows hosts were not independently rerun. Closure covers the described source defect, not broader provider conformance or performance.

bsakaguchi referenced this issue

2026-10-17 21:07:28 +00:00

[PR #980] [MERGED] fix(evaluation): canonicalize Unicode argument keys #2550

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:29:45 +00:00