feat(commands): did-you-mean hint for unknown @gittensory verbs (#2170)

[rust-toml]

Fixes #2170

Summary

• Add a pure command-suggest module (Levenshtein distance + catalog lookup) for unrecognized @gittensory verbs.
• Preserve the existing help fallback for unknown verbs, but attach unknownVerb on the parsed command so the help card can show a did-you-mean line when a close match exists (distance ≤ 2).
• Cover parser, help-card integration, and suggester branches with unit tests aimed at full patch coverage.

Test plan

• npm run test:ci (local, Node 22.18)
• Targeted coverage on changed src/github/** lines via command-suggest.test.ts + github-commands.test.ts
• Parse: @gittensory reveiw → help + unknownVerb; @gittensory preflight unchanged
• Help card: typo shows Did you mean @gittensory preflight?; far-off typo and bare @gittensory omit the hint

Made with Cursor

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-06 18:24:39 UTC}

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a small, pure did-you-mean suggester (Levenshtein distance + catalog lookup) and wires it into parseGittensoryMentionCommand/helpSections so an unrecognized @​gittensory verb still falls back to help but now surfaces a close-match hint. The refactor of parseGittensoryMentionCommand correctly separates the bare-mention, action-command, known-mention-command, and unknown-verb paths, and unknownVerb is only set on the genuinely unmatched branch (never for bare @​gittensory or recognized commands/aliases), matching the test assertions. Test coverage is thorough (parser branches, suggester branches, live-catalog suggestions, and rendered help-card output), and the PR is properly scoped to the linked issue #2170 with no unrelated changes.

Nits — 5 non-blocking

• src/github/commands.ts: commandSuggestCatalog() rebuilds mentionCommands/actionCommands/actionAliases into a new object on every call to suggestCommand/parseGittensoryMentionCommand; consider memoizing since the underlying catalogs are static.
• src/github/command-suggest.ts: rawVerb is already lowercased by the caller in commands.ts before being stored as unknownVerb, so the .trim().toLowerCase() in suggestCommand/isKnownGittensoryCommandVerb is redundant there (harmless, but worth a comment noting callers may pass raw input too).
• command-suggest.ts's targets array recomputes Object.keys(actionAliases) on every suggestCommand call inside commandSuggestTargets; fine at this catalog size but worth noting if the catalog grows.
• No JSDoc/comment on COMMAND_SUGGEST_MAX_DISTANCE explaining why 2 was chosen as the threshold (e.g., balance between usefulness and false positives) — would help future tuning.
• Consider hoisting the catalog object built in commandSuggestCatalog() (src/github/commands.ts) to a module-level constant computed once, since GITTENSORY_MENTION_COMMAND_CATALOG/GITTENSORY_ACTION_COMMANDS/GITTENSORY_ACTION_COMMAND_ALIASES appear static.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2170
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 0 registered-repo PR(s), 0 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	rust-toml; Gittensor profile; 0 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: rust-toml
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, Rust, C++, Go, Java, JavaScript, Solidity
• Official Gittensor activity: 0 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.48%. Comparing base (bbad5c8) to head (76967dd).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3854      +/-   ##
==========================================
+ Coverage   93.47%   93.48%   +0.01%     
==========================================
  Files         332      333       +1     
  Lines       33110    33151      +41     
  Branches    12116    12127      +11     
==========================================
+ Hits        30948    30990      +42     
  Misses       1530     1530              
+ Partials      632      631       -1     

Files with missing lines	Coverage Δ
src/github/command-suggest.ts	100.00% <100.00%> (ø)
src/github/commands.ts	98.14% <100.00%> (+0.23%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.