docs: Adrien review — hierarchy, counts, consistency, gaps by FlorianBruniaux · Pull Request #1304 · rtk-ai/rtk

FlorianBruniaux · 2026-04-14T12:21:57Z

Summary

Full doc review pass based on Adrien's feedback.

Hierarchy

Move troubleshooting.md and what-rtk-covers.md to guide/resources/ (new folder alongside existing getting-started/ and analytics/)
Add guide/resources/telemetry.md — user-facing page (consent, opt-out, GDPR rights) adapted from docs/TELEMETRY.md

Content fixes

Remove all hardcoded counts (9 ecosystems, 12 agents, 60+, 7 more) — qualitative language only
Unify DB filename: tracking.db → history.db everywhere (canonical: src/core/constants.rs)
installation.md: replace bare cargo install rtk with warning callout + explicit git URL (Rust Type Kit name collision)
supported-agents.md / quick-start.md: counts and hardcoded lists removed

New content

gain.md: --quota section explaining pro/5x/20x tier meanings
gain.md: callout linking to discover.md (find missed savings)
index.md: "Analyze your usage" section (mentions rtk discover + rtk session)
configuration.md: ignore_dirs/ignore_files scope clarified + prose link to telemetry
what-rtk-covers.md: note that --ultra-compact long form should be preferred over -u with git commands (conflict with git's own -u)

Cross-references

All internal links updated for new resources/ paths
Landing repo (rtk-landing) already has astro.config.mjs redirects so old URLs (/guide/troubleshooting/, /guide/what-rtk-covers/) 301 to new paths

README

Core team section added (Patrick Szymkowiak — Founder, Florian Bruniaux — Core contributor, Adrien Eppling — Core contributor)

Test plan

pnpm build in rtk-landing with RTK_REPO_PATH pointing to this branch — 0 Starlight broken-link warnings
/guide/ sidebar shows 3 groups: Getting Started, Analytics, Resources
/guide/troubleshooting/ redirects to /guide/resources/troubleshooting/ (301)
/guide/what-rtk-covers/ redirects to /guide/resources/what-rtk-covers/ (301)
rtk-landing Cmd+K search — docs results navigate to /guide/… (not 404)
rg -nE '\b(9 ecosystems|12 agents|60\+|7 more)\b' docs/guide/ → 0 results
rg -n 'tracking\.db' docs/guide/ → 0 results

🤖 Generated with Claude Code

- handle npm exec|run and their aliases - handle pnpm exec|run and their aliases like npm - handle pnpx and its alias like npx - handle all forms of js script/package execution Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

…npm test` commands as we don't know which test framework is used under the hood Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

…jest Also remove duration computation as there's no endTime attribute in json output Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

This reverts commit 94a3532. Build is no longer a pnpm command with specific handling. Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

feat(discover): handle more npm/npx/pnpm/pnpx patterns

…percent B6 — report.rs:already_rtk integer division truncated small ratios to 0% (e.g. 3/1000 showed "0%" instead of "0.3%"). Now uses f64 division with one decimal place. Three regression tests added. B7 — mod.rs:SupportedBucket.savings_pct was set once from the first-seen sub-command and never updated. For buckets containing multiple sub-commands (e.g. git add + git diff + git log all under "rtk git"), the displayed estimated_savings_pct reflected only the first classification. Fix: track total_raw_output_tokens alongside total_output_tokens (savings). Compute effective_savings_pct = saved / raw * 100 at entry construction, giving a weighted average across all sub-commands in the bucket. This rate is exposed in rtk discover --format json via estimated_savings_pct. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Florian BRUNIAUX <florian@bruniaux.com>

Hierarchy: - Move troubleshooting.md and what-rtk-covers.md to guide/resources/ - Add guide/resources/telemetry.md (adapted from docs/TELEMETRY.md, user-facing: consent, opt-out, GDPR rights — without internal sections) Content fixes: - Remove all hardcoded counts (9 ecosystems, 12 agents, 60+, 7 more) replaced with qualitative language throughout - Unify DB filename: tracking.db → history.db everywhere (canonical: src/core/constants.rs HISTORY_DB) - installation.md: replace bare `cargo install rtk` with warning + explicit git URL to avoid Rust Type Kit name collision - supported-agents.md: remove hardcoded agent count - quick-start.md: remove hardcoded ecosystem list, link to what-rtk-covers New content: - gain.md: add --quota section explaining pro/5x/20x tier meanings - gain.md: add callout linking to discover.md (find missed savings) - index.md: add "Analyze your usage" section (rtk discover, rtk session) - configuration.md: clarify ignore_dirs/ignore_files scope, add prose link to telemetry.md - what-rtk-covers.md: clarify --ultra-compact vs git -u short flag conflict Cross-references: - All internal links updated for new resources/ paths - index.md: link to troubleshooting, telemetry, what-rtk-covers, analytics - discover.md: updated relative link to troubleshooting README: - Add Core team section (Patrick Szymkowiak, Florian Bruniaux, Adrien Eppling) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR refreshes and reorganizes user-facing documentation (hierarchy, wording, cross-links, telemetry/privacy) while also expanding RTK’s JS/test tooling support (notably adding rtk jest and broadening rewrite/discover rules).

Changes:

Docs: move key pages into docs/guide/resources/, add a new Telemetry & Privacy page, and remove hardcoded “counts” in favor of qualitative language.
CLI/runtime: add rtk jest, simplify rtk vitest invocation, and adjust benchmarks + hook rewrite tests accordingly.
Discover/rewrite: expand JS/TS command pattern coverage and improve reporting precision (decimal percentages + weighted savings rate), with new/expanded tests.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/main.rs	Adds `Jest` command, changes `Vitest` to accept args directly, and routes both through a shared test runner path.
src/hooks/init.rs	Updates init help examples for the new `rtk jest` / simplified `rtk vitest` usage.
src/discover/rules.rs	Expands rewrite patterns/prefixes for JS/TS tooling (pnpm/npm wrappers, jest/vitest, etc.).
src/discover/report.rs	Improves “Already using RTK” percentage formatting (decimal precision) and adds regression tests.
src/discover/registry.rs	Updates rewrite/classification tests for the expanded JS/TS patterns and new command forms.
src/discover/mod.rs	Changes supported-command aggregation to compute weighted effective savings percent.
src/cmds/js/vitest_cmd.rs	Introduces shared runner for Vitest + Jest with forced JSON output and argument filtering.
scripts/benchmark.sh	Updates vitest benchmark invocation to align with `rtk vitest` (no explicit `run` in the RTK command).
hooks/claude/test-rtk-rewrite.sh	Updates rewrite expectations (vitest/jest changes, npm run handling, plus additional rewritten commands).
docs/usage/FEATURES.md	Updates usage docs to reflect `rtk jest` / `rtk vitest` (no `vitest run`).
docs/usage/AUDIT_GUIDE.md	Updates audit examples to list Jest/Vitest separately under the new command forms.
docs/guide/resources/what-rtk-covers.md	Moves page into `resources/`, removes hardcoded counts, updates tables/flags guidance, adds `--ultra-compact` note.
docs/guide/resources/troubleshooting.md	Moves page into `resources/` and updates sidebar order.
docs/guide/resources/telemetry.md	New user-facing Telemetry & Privacy page describing consent, opt-out, GDPR rights, and collected fields.
docs/guide/index.md	Updates links for new `resources/` layout, removes hardcoded counts, and adds “Analyze your usage” section.
docs/guide/getting-started/supported-agents.md	Removes hardcoded agent count; uses qualitative wording.
docs/guide/getting-started/quick-start.md	Removes hardcoded ecosystem list and updates links to `resources/what-rtk-covers.md`.
docs/guide/getting-started/installation.md	Adds Cargo name-collision caution and uses explicit `--git` install URL.
docs/guide/getting-started/configuration.md	Updates DB filename to `history.db`, clarifies ignore scope, and links to telemetry docs.
docs/guide/analytics/gain.md	Updates examples/tables for jest/vitest naming and adds `--quota` documentation + cross-link to discover.
docs/guide/analytics/discover.md	Updates troubleshooting link to new `resources/` path.
README_zh.md	Updates test-runner examples to mention `rtk jest` / `rtk vitest` and generic `rtk test <cmd>`.
README_ko.md	Same as above for Korean README.
README_ja.md	Same as above for Japanese README.
README_fr.md	Same as above for French README.
README_es.md	Same as above for Spanish README.
README.md	Updates test-runner examples and adds “Core team” section.
INSTALL.md	Updates install verification examples and test-runner section for the new jest/vitest command forms.
.claude/hooks/rtk-suggest.sh	Updates vitest suggestion to `rtk vitest` (no `run`).

Copilot · 2026-04-14T12:28:44Z

 };
+use crate::Commands;

 /// Vitest JSON output structures (tool-specific format)


This module now handles both Vitest and Jest (use crate::Commands; + Commands::Jest match below), but the docs/naming are still Vitest-specific (file name vitest_cmd.rs, VitestParser). Please update the docs to mention Jest support and consider renaming/splitting to avoid future confusion.

Copilot · 2026-04-14T12:28:44Z

+        if arg == "run"
+            || arg.starts_with("--json")
+            || arg.starts_with("--reporter")
+            || arg.starts_with("--watch")
+        {
+            continue;
+        }


run_test silently drops user-provided args like --reporter=*, --json*, and --watch*. Since the CLI help advertises “Additional vitest/jest arguments”, this can be surprising (e.g., rtk vitest --reporter=verbose is accepted but ignored). Consider either (a) emitting a verbose warning when stripping these flags, or (b) failing fast with a clear message explaining RTK must force JSON/non-watch mode.

Suggested change

if arg == "run"

|| arg.starts_with("--json")

|| arg.starts_with("--reporter")

|| arg.starts_with("--watch")

{

continue;

}

if arg == "run" {

continue;

}

if arg.starts_with("--json")

|| arg.starts_with("--reporter")

|| arg.starts_with("--watch")

{

anyhow::bail!(

"Unsupported {} argument '{}': rtk {} must force JSON output and disable watch mode, so --json*, --reporter*, and --watch* cannot be passed through.",

framework,

arg,

framework

);

}

Copilot · 2026-04-14T12:28:44Z

+        Commands::Jest { .. } => {
+            let framework = "jest";
+            let mut cmd = package_manager_exec(framework);
+            cmd
+                // Force non-watch mode
+                .arg("--no-watch")
+                // Enable JSON structured output
+                .arg("--json");
+            (framework, cmd)
+        }


Jest support is new here, but the unit tests only cover parsing Vitest-shaped JSON. Since run_test reuses VitestParser for Jest output, please add a regression test with a representative Jest --json payload (including failures) to ensure the parser continues to work for Jest as well.

Copilot · 2026-04-14T12:28:45Z

    },
    RtkRule {
-        pattern: r"^npm\s+(run|exec)",
+        pattern: r"^npm\s+(exec|run|run-script|rum|urn|x)\s+",


The npm rewrite rule includes rum and urn as accepted subcommands (npm\s+(...|rum|urn|...)). These are not valid npm subcommands, so RTK will treat invalid commands as “supported” and rewrite them. If these are typos, remove them; if intentional, it would be better to normalize them to run rather than preserving the invalid token.

Suggested change

pattern: r"^npm\s+(exec|run|run-script|rum|urn|x)\s+",

pattern: r"^npm\s+(exec|run|run-script|x)\s+",

Copilot · 2026-04-14T12:28:45Z

+    /// Total estimated tokens *saved* (post-filter). Used for the "Est. Savings" column.
    total_output_tokens: usize,
-    savings_pct: f64,
+    /// Total estimated tokens *before* filtering (raw output). Accumulated alongside
+    /// `total_output_tokens` so the bucket's effective savings rate can be derived as
+    /// `total_output_tokens / total_raw_output_tokens` — a weighted average across
+    /// all sub-commands, regardless of which sub-command was seen first.
+    total_raw_output_tokens: usize,


total_output_tokens is now documented/used as “tokens saved”, not “output tokens” (it accumulates savings, not filtered output). Renaming this field to something like total_saved_tokens (and updating related comments) would make the aggregation logic much easier to follow and reduce the risk of misusing it later.

Copilot · 2026-04-14T12:28:45Z


 [telemetry]
-enabled = true              # anonymous daily ping (opt-out below)
+enabled = true              # anonymous daily ping — see Telemetry & Privacy for full details


This config example sets [telemetry] enabled = true, but RTK’s defaults are telemetry-disabled and consent-gated (see Config::default() / test_telemetry_default_disabled). To avoid contradicting “disabled by default” messaging, consider showing enabled = false here (or explicitly label this as an example of an opt-in configuration rather than the default).

Suggested change

enabled = true # anonymous daily ping — see Telemetry & Privacy for full details

enabled = false # anonymous daily ping — see Telemetry & Privacy for full details

Copilot · 2026-04-14T12:28:46Z

+                // Force non-watch mode
+                .arg("--no-watch")


run_test adds --no-watch for Jest. Jest CLI does not support a --no-watch flag (watch mode is enabled via --watch / --watchAll), so this will cause Jest runs to fail with an unknown option. Drop this flag and rely on stripping --watch* args instead (or translate watch args to --watch=false if you want an explicit override).

Suggested change

// Force non-watch mode

.arg("--no-watch")

Copilot · 2026-04-14T12:28:46Z

@@ -53,7 +53,7 @@ pub const RULES: &[RtkRule] = &[
        subcmd_status: &[],


The pnpm rewrite rule now matches exec/run/run-script, but rtk pnpm only filters a few subcommands (list/outdated/install/typecheck); everything else goes through passthrough. As written, discover will overestimate savings for these passthrough pnpm commands. Either restrict the pattern back to the filtered subcommands, or add subcmd_status/subcmd_savings overrides (e.g., 0% + Passthrough) for the passthrough subcommands.

Copilot · 2026-04-14T12:28:46Z

+    /// Jest commands with compact output
+    Jest {
+        /// Additional jest arguments
+        #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
+        args: Vec<String>,
+    },


The PR title/description describe a docs-only review pass, but this change adds a new rtk jest CLI command and changes runtime routing (Commands::Jest/Commands::Vitest now share a new execution path). Please update the PR description and test plan to explicitly cover these functional changes (CLI help, rewrite rules, and at least one end-to-end Jest run).

aeppling · 2026-04-14T18:58:31Z

Ok

Follow-up : search bar seems not finding any docs related content (/docs).

Just need target develop

pull_request_target doesn't inherit write permissions by default. Adding explicit permissions block so the workflow can add labels and post comments on wrong-base PRs. Fixes: 403 Resource not accessible by integration error on issue #1304 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

KuSh and others added 10 commits April 12, 2026 22:03

feat(discover): handle more npm/npx/pnpm/pnpx patterns

bab3a53

- handle npm exec|run and their aliases - handle pnpm exec|run and their aliases like npm - handle pnpx and its alias like npx - handle all forms of js script/package execution Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

fix: remove pnpx -> rtk pnpx rule as rtk pnpx command doesn't exist

325a42e

Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

feat(pnpm): handle pnpm build rewrite

f936138

Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

chore: fix clippy warning

c47edac

feat(js): distinguish between jest and vitest and don't rewrite `…

45938b2

…npm test` commands as we don't know which test framework is used under the hood Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

fix(vitest): rework command to handle differences between vitest and …

70610da

…jest Also remove duration computation as there's no endTime attribute in json output Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

Revert "feat(pnpm): handle pnpm build rewrite"

010596c

This reverts commit 94a3532. Build is no longer a pnpm command with specific handling. Signed-off-by: Nicolas Le Cam <niko.lecam@gmail.com>

Merge pull request #355 from KuSh/pnpx+dlx

9e96caa

feat(discover): handle more npm/npx/pnpm/pnpx patterns

Copilot AI review requested due to automatic review settings April 14, 2026 12:21

Copilot started reviewing on behalf of FlorianBruniaux April 14, 2026 12:22 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

aeppling added the wrong-base PR targets master instead of develop label Apr 14, 2026

FlorianBruniaux mentioned this pull request Apr 14, 2026

fix(ci): add write permissions to pr-target-check workflow #1312

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Adrien review — hierarchy, counts, consistency, gaps#1304

docs: Adrien review — hierarchy, counts, consistency, gaps#1304
FlorianBruniaux wants to merge 10 commits intomasterfrom
docs/adrien-review

FlorianBruniaux commented Apr 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

aeppling commented Apr 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	pattern: r"^npm\s+(exec\|run\|run-script\|rum\|urn\|x)\s+",
	pattern: r"^npm\s+(exec\|run\|run-script\|x)\s+",

	enabled = true # anonymous daily ping — see Telemetry & Privacy for full details
	enabled = false # anonymous daily ping — see Telemetry & Privacy for full details

		@@ -53,7 +53,7 @@ pub const RULES: &[RtkRule] = &[
		subcmd_status: &[],

Conversation

FlorianBruniaux commented Apr 14, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

aeppling commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aeppling commented Apr 14, 2026 •

edited

Loading