morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #2776] [CLOSED] docs: link the README guide table to repository guides #5385

New issue

Closed

opened 2026-10-31 01:06:13 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:06:13 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2776
Author: @YunzhouLi-hub
Created: 10/13/2026
Status: ❌ Closed

Base: main ← Head: docs/2679-relative-guide-links

📝 Commits (3)

c5b892d docs: link the README guide table to repository guides
89239c1 test(docs): preserve translated guide-link boundary coverage
ca00d3e chore: sync captured review base for PR 2776

📊 Changes

20 files changed (+60 additions, -69 deletions)

View changed files

📝 README.md (+3 -3)
📝 docs/readme/README_ar.md (+3 -3)
📝 docs/readme/README_de.md (+3 -3)
📝 docs/readme/README_es.md (+3 -3)
📝 docs/readme/README_fa.md (+3 -3)
📝 docs/readme/README_fr.md (+3 -3)
📝 docs/readme/README_id.md (+3 -3)
📝 docs/readme/README_it.md (+3 -3)
📝 docs/readme/README_ja.md (+3 -3)
📝 docs/readme/README_ko.md (+3 -3)
📝 docs/readme/README_pl.md (+3 -3)
📝 docs/readme/README_pt-BR.md (+3 -3)
📝 docs/readme/README_ru.md (+3 -3)
📝 docs/readme/README_th.md (+3 -3)
📝 docs/readme/README_tr.md (+3 -3)
📝 docs/readme/README_uk.md (+3 -3)
📝 docs/readme/README_vi.md (+3 -3)
📝 docs/readme/README_zh-TW.md (+3 -3)
📝 docs/readme/README_zh.md (+3 -3)
📝 tests/boundary/filesystem/productCatalog.test.ts (+3 -12)

📄 Description

Summary

Fixes #2679. The "What you can analyze" table in README.md pointed three cells at absolute rea.tools guide URLs while every other row used a relative docs/ link. Those three cells now use relative paths, matching CONTRIBUTING.md's rule that guide links stay relative so they work on GitHub and on the website.

Draft deliberately — the localisation question below is open and needs a maintainer decision.

Problem and expected behavior

README.md:155, :162 and :163 used https://rea.tools/guides/{native,javascript,browser}/ while the surrounding rows used docs/<file>.md. Absolute URLs take GitHub readers off-repo and bypass the link checker, so a typo would only surface as a 404 on the published site after a user hit it.

Targets are not guessed. docs/.vitepress/config.ts — the navigation authority CONTRIBUTING.md names — defines the mapping in its "Investigation guides" sidebar:

Cell	Old	`config.ts` entry	New
Native binaries	`https://rea.tools/guides/native/`	`:29` `/native-investigation`	`docs/native-investigation.md`
JavaScript / Electron	`https://rea.tools/guides/javascript/`	`:31-34` `/javascript-artifact-reconstruction`	`docs/javascript-artifact-reconstruction.md`
Websites	`https://rea.tools/guides/browser/`	`:39` `/browser-observation`	`docs/browser-observation.md`

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

Change and scope

19 files, 57 insertions, 57 deletions — three cells each, plus the padding needed to keep each table cell's width unchanged so column alignment survives.

README.md alone would not pass CI. scripts/lib/docs-facts.mjs:104-110 requires every README_*.md to carry the same link set as README.md, and :13-23 strips the locale prefix from https://rea.tools/<locale>/guides/... so the two sides compare equal. That 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. Changing only English measured 18 failures of documentation links differ from README.md, so the 18 translated files change in the same commit.

Deliberately unchanged: README.md:20 and :311 (https://rea.tools/guides/) and website/README.md:465. Those are top-level site navigation, not table cells, and are outside what this issue reports.

Contract and boundary impact

Markdown link targets only. No tool contract, no provider behaviour, no Evidence semantics, no output shape.

Evidence and regression coverage

No new tests — this is a documentation link change, and the existing checks are the coverage:

Check	What it proves
`node scripts/check-doc-facts.mjs`	All 19 READMEs carry an identical link set; was 18 failures before the translation changes, now clean
`tests/conformance/readmeConsistency.test.ts`	Translated README `bash` examples still match English
`npx oxfmt --check README*.md`	34 files formatted

Padding is asserted by construction: each replacement computes its new pad from the byte delta of the link, so every rewritten cell keeps its original width. Verified visually against the four untouched rows of the same table.

Validation performed

Command	Result
`node scripts/check-doc-facts.mjs`	exit 0
`npm run test:local -- tests/conformance/readmeConsistency.test.ts`	2/2 pass
`npm run verify:test-discovery`	all 1055 test files discovered exactly once
`npm run check:fast`	2/2 tasks successful
`npx oxfmt --check README*.md`	correct format

Node 24.15.0, Windows x64.

Not verified, and the reason this is a draft: I did not run a website build, so I am not claiming the relative links resolve correctly under a locale route prefix on the VitePress site. On GitHub they certainly do.

Compatibility, safety, and release

The localisation cost is the substance of this PR and should be reviewed as such:

A translated reader clicking "原生分析" on GitHub now reaches the English docs/native-investigation.md rather than https://rea.tools/zh-CN/guides/native/.
Whether the localized site still serves those cells depends on how docs/*.md resolves under a locale prefix — unverified here.
No execution, no filesystem writes, no network, no provider process.

Docs-only, so patch-level at most.

Before merge

Decide the localisation direction. Either accept that translated GitHub readers get the English guide, or keep the translations absolute and extend readmeLinkTargets in scripts/lib/docs-facts.mjs to treat a relative target as equivalent to the locale-prefixed URL. The second is a check-logic change and a bigger call than a docs fix, which is why I did not make it unilaterally.
Confirm the relative links resolve correctly on the localized website (needs a website build I could not run).
If the localisation direction is "keep absolute", this PR should be reduced to README.md only plus the checker change.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2776 **Author:** [@YunzhouLi-hub](https://github.com/YunzhouLi-hub) **Created:** 10/13/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/2679-relative-guide-links` --- ### 📝 Commits (3) - [`c5b892d`](https://github.com/morluto/rea/commit/c5b892dc6fd908b5994630c00fcfef46b4b9fa18) docs: link the README guide table to repository guides - [`89239c1`](https://github.com/morluto/rea/commit/89239c1985d1f63c4e3a96b71dc279be7ea7f4fb) test(docs): preserve translated guide-link boundary coverage - [`ca00d3e`](https://github.com/morluto/rea/commit/ca00d3e37281e10b30e3845a122921cf24083249) chore: sync captured review base for PR 2776 ### 📊 Changes **20 files changed** (+60 additions, -69 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+3 -3) 📝 `docs/readme/README_ar.md` (+3 -3) 📝 `docs/readme/README_de.md` (+3 -3) 📝 `docs/readme/README_es.md` (+3 -3) 📝 `docs/readme/README_fa.md` (+3 -3) 📝 `docs/readme/README_fr.md` (+3 -3) 📝 `docs/readme/README_id.md` (+3 -3) 📝 `docs/readme/README_it.md` (+3 -3) 📝 `docs/readme/README_ja.md` (+3 -3) 📝 `docs/readme/README_ko.md` (+3 -3) 📝 `docs/readme/README_pl.md` (+3 -3) 📝 `docs/readme/README_pt-BR.md` (+3 -3) 📝 `docs/readme/README_ru.md` (+3 -3) 📝 `docs/readme/README_th.md` (+3 -3) 📝 `docs/readme/README_tr.md` (+3 -3) 📝 `docs/readme/README_uk.md` (+3 -3) 📝 `docs/readme/README_vi.md` (+3 -3) 📝 `docs/readme/README_zh-TW.md` (+3 -3) 📝 `docs/readme/README_zh.md` (+3 -3) 📝 `tests/boundary/filesystem/productCatalog.test.ts` (+3 -12) </details> ### 📄 Description ## Summary Fixes #2679. The "What you can analyze" table in `README.md` pointed three cells at absolute `rea.tools` guide URLs while every other row used a relative `docs/` link. Those three cells now use relative paths, matching CONTRIBUTING.md's rule that guide links stay relative so they work on GitHub and on the website. **Draft deliberately — the localisation question below is open and needs a maintainer decision.** ## Problem and expected behavior `README.md:155`, `:162` and `:163` used `https://rea.tools/guides/{native,javascript,browser}/` while the surrounding rows used `docs/<file>.md`. Absolute URLs take GitHub readers off-repo and bypass the link checker, so a typo would only surface as a 404 on the published site after a user hit it. Targets are not guessed. `docs/.vitepress/config.ts` — the navigation authority CONTRIBUTING.md names — defines the mapping in its "Investigation guides" sidebar: | Cell | Old | `config.ts` entry | New | | --- | --- | --- | --- | | Native binaries | `https://rea.tools/guides/native/` | `:29` `/native-investigation` | `docs/native-investigation.md` | | JavaScript / Electron | `https://rea.tools/guides/javascript/` | `:31-34` `/javascript-artifact-reconstruction` | `docs/javascript-artifact-reconstruction.md` | | Websites | `https://rea.tools/guides/browser/` | `:39` `/browser-observation` | `docs/browser-observation.md` | All three files exist; `docs/native.md`, `docs/javascript.md` and `docs/browser.md` do not. ## Change and scope 19 files, 57 insertions, 57 deletions — three cells each, plus the padding needed to keep each table cell's width unchanged so column alignment survives. `README.md` alone would not pass CI. `scripts/lib/docs-facts.mjs:104-110` requires every `README_*.md` to carry the same link set as `README.md`, and `:13-23` strips the locale prefix from `https://rea.tools/<locale>/guides/...` so the two sides compare equal. That 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. Changing only English measured 18 failures of `documentation links differ from README.md`, so the 18 translated files change in the same commit. Deliberately unchanged: `README.md:20` and `:311` (`https://rea.tools/guides/`) and `website/README.md:465`. Those are top-level site navigation, not table cells, and are outside what this issue reports. ## Contract and boundary impact Markdown link targets only. No tool contract, no provider behaviour, no Evidence semantics, no output shape. ## Evidence and regression coverage No new tests — this is a documentation link change, and the existing checks are the coverage: | Check | What it proves | | --- | --- | | `node scripts/check-doc-facts.mjs` | All 19 READMEs carry an identical link set; was 18 failures before the translation changes, now clean | | `tests/conformance/readmeConsistency.test.ts` | Translated README `bash` examples still match English | | `npx oxfmt --check README*.md` | 34 files formatted | Padding is asserted by construction: each replacement computes its new pad from the byte delta of the link, so every rewritten cell keeps its original width. Verified visually against the four untouched rows of the same table. ## Validation performed | Command | Result | | --- | --- | | `node scripts/check-doc-facts.mjs` | exit 0 | | `npm run test:local -- tests/conformance/readmeConsistency.test.ts` | 2/2 pass | | `npm run verify:test-discovery` | all 1055 test files discovered exactly once | | `npm run check:fast` | 2/2 tasks successful | | `npx oxfmt --check README*.md` | correct format | Node 24.15.0, Windows x64. **Not verified, and the reason this is a draft:** I did not run a website build, so I am not claiming the relative links resolve correctly under a locale route prefix on the VitePress site. On GitHub they certainly do. ## Compatibility, safety, and release The localisation cost is the substance of this PR and should be reviewed as such: - A translated reader clicking "原生分析" on GitHub now reaches the **English** `docs/native-investigation.md` rather than `https://rea.tools/zh-CN/guides/native/`. - Whether the localized site still serves those cells depends on how `docs/*.md` resolves under a locale prefix — unverified here. - No execution, no filesystem writes, no network, no provider process. Docs-only, so patch-level at most. ## Before merge - [ ] **Decide the localisation direction.** Either accept that translated GitHub readers get the English guide, or keep the translations absolute and extend `readmeLinkTargets` in `scripts/lib/docs-facts.mjs` to treat a relative target as equivalent to the locale-prefixed URL. The second is a check-logic change and a bigger call than a docs fix, which is why I did not make it unilaterally. - [ ] Confirm the relative links resolve correctly on the localized website (needs a website build I could not run). - [ ] If the localisation direction is "keep absolute", this PR should be reduced to `README.md` only plus the checker change. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:06:13 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-03 13:39:23 +00:00

[PR #7111] [MERGED] fix(lldb): keep the bridge's no-target proof through interruption #7649

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#5385

No description provided.

Rows
Columns