feat(reference): explained examples that run in the practice terminal - #395
Merged
Merged
Conversation
Replayed through the engine, 224 of the 464 /app/reference examples printed
an error: made-up file names, comments typed as part of the command, bash
shown to Windows learners.
- New CommandExample {command, explanation, environments?}; examples live in
commandExamples.ts and are merged into the catalogue (single source).
Every example is explained for a beginner and uses the practice terminal's
files; Windows learners get the PowerShell form.
- NOT_SIMULATED marks commands the engine does not run yet (tree, find,
less, alias, tar, zip...); the reference tells the learner so.
- commandReference.test.ts replays every shown example (git ones inside a
prepared repository) and ratchets the 32 remaining gaps, which are engine
gaps fixed next.
- Content fixes: umask is not a Windows command, find gets its PowerShell
form, a cherry-pick example used an impossible commit id, a crontab line
and .gitignore patterns were shown as commands, the curl alias note only
applies to Windows PowerShell 5.1.
- UI: the duplicated "Description" is gone; only the card header toggles
(a real Button with aria-controls), so selecting an example or following a
doc link no longer collapses the card; examples wrap instead of scrolling;
filter pills are one scrollable row until the content area is 48rem wide
(container query: the sidebar squeezes the width), reported by @Thierry.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @thierryvm, you've used your own review budget of 250,000 diff characters for the last 7 days.
You can request another review in 1 hour and 16 minutes by commenting @sourcery-ai review. Upgrade to get a review now.
Guide du reviewerRefonte de Diagramme du flux de rendu d’une carte de commande de référenceflowchart TD
Start[Select command and environment] --> Filter[Filter examples by environments]
Filter --> Status{Command simulated?}
Status -->|No| Warning[Show simulator limitation]
Status -->|Yes| Details[Show command details]
Warning --> Details
Details --> Examples[Show wrapped command and explanation]
Header[Header button] --> Toggle[Toggle details with aria-controls]
Toggle --> Details
Modifications au niveau des fichiers
Conseils et commandesInteragir avec Sourcery
Personnaliser votre expérienceAccédez à votre tableau de bord pour :
Obtenir de l’aide
Original review guide in EnglishReviewer's GuideReworks Flow diagram for rendering a reference command cardflowchart TD
Start[Select command and environment] --> Filter[Filter examples by environments]
Filter --> Status{Command simulated?}
Status -->|No| Warning[Show simulator limitation]
Status -->|Yes| Details[Show command details]
Warning --> Details
Details --> Examples[Show wrapped command and explanation]
Header[Header button] --> Toggle[Toggle details with aria-controls]
Toggle --> Details
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@Thierry asked for
/app/referenceto be checked like the lessons and made more pedagogical. Replayed through the engine, 224 of its 464 examples printed an error: made-up file names (cat notes.txt,cp a.txt b.txt), comments typed as part of the command (tree /F (Windows : …)), bash shown to Windows learners (2>/dev/null).CommandExample {command, explanation, environments?}incommandExamples.ts, merged intocommandCatalogue(the 76 inline string arrays are gone: single source). Every example says what it does, uses the practice terminal's files (documents/notes.txt,projets/script.sh…) and Windows learners get the PowerShell form.NOT_SIMULATEDmarks commands the engine does not run yet (tree,find,less,alias,tar,zip…); the card tells the learner to try them on their own machine.commandReference.test.tsreplays every shown example per OS (Git examples inside a prepared repository) and ratchets the 32 remaining failures (exact set: a new failure fails the test, a fixed one must be deleted). Proven with a mutation. The 32 are engine gaps (cat -n,grep -ron a directory,Get-Date,Get-Help,tasklist,Set-Content, and a real bug:git commit -am "msg"loses its message) — next PR.umaskis not a Windows command;findgets its PowerShell form; a cherry-pick example used an impossible commit id (e4f5g6h); a crontab line and.gitignorepatterns were shown as commands; thecurlalias note only applies to Windows PowerShell 5.1.Buttonwitharia-controls: selecting an example or following a doc link no longer collapses the card, and links are no longer nested in a button. Examples wrap instead of scrolling (the end of a long command is often the option being explained). Filter pills (reported by @Thierry: 7 rows on a narrow screen) are one scrollable row until the content area is 48rem wide — a container query, because the sidebar squeezes the width, not the viewport.Test plan
tsc --noEmit,eslint src, unit tests (2694 + new),vite buildcommandReference.test.tsfail; restored → greenui-auditor: C1 (header as real Button), W1 (aria-controls), W3 (aria-hiddenchevrons), W4 (keys) fixed; W2 (pre-existing#58a6ffliteral) out of scopefeature-dev:code-reviewer: no finding ≥ 80, explanations checked for bash / zsh / PowerShell 7 accuracy🤖 Generated with Claude Code
Résumé par Sourcery
Rendre la référence des commandes plus pédagogique et plus fiable en fournissant des exemples expliqués et exécutables, en identifiant clairement les limites du simulateur et en validant le catalogue en continu.
Nouvelles fonctionnalités :
Corrections de bugs :
Améliorations :
Documentation :
Tests :
Original summary in English
Summary by Sourcery
Make the command reference more pedagogical and trustworthy by providing explained, runnable examples, clearly identifying simulator limitations, and validating the catalogue continuously.
New Features:
Bug Fixes:
Enhancements:
Documentation:
Tests: