docs: README comparison matrices + execution-tested cookbook examples - #357
Merged
Conversation
Expand README.md and guarantee the user-facing examples actually run.
README.md
- Add a Tool Feature Comparison Matrix (xff vs find/fd/grep/ripgrep/shasum) and a
Flavor & Behavioral Shift Matrix; vertically align every table via
tools/align_markdown_tables.py.
- Fix an invalid example (`-print "{path} {sha256}"` -> `xff -type f -hash=sha256`),
a broken table row, and mangled `\t`/`\n` escapes.
- Mark find's custom templating as GNU-only (`-printf` is a GNU extension; POSIX and
BSD/macOS find have none), and footnote strict `--config=find`: it keeps RE2 as the
`-regex` default (verified - regex is not a per-style default in config.cc), one
linear-time engine identical across platforms.
- Drop the em-dash in the title (repo no-em-dashes rule).
xff/examples (new package)
- cookbook_test.sh RUNS every `--help=cookbook` recipe (SOT: cli/help.cc
RenderCookbook) against a fixture tree instead of only rendering it, plus the README
"missing final newline" linter. The two git-blame recipes exercise real git and
degrade to a skip where git is absent.
- A guard case fails if a recipe is added or reworded without a matching test, so
examples ship tested, not just shown.
cli/help.cc, AGENTS.md
- Document that cookbook recipes are execution-tested by //xff/examples:cookbook_test,
and add the "a new/changed recipe carries a test" rule to self-documenting features.
Test: bazel test //xff/examples:cookbook_test //xff/cli:help_topic_test (all pass);
pre-commit (clang-format, shfmt, shellcheck, no-shell-grep, align-markdown-tables,
module-versions, ...) green on every changed file.
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
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.
What
Expand
README.md, and make the user-facing examples provably runnable.README.md
find/fd/grep/ripgrep/shasum) and a Flavor & Behavioral Shift Matrix; all tables vertically aligned viatools/align_markdown_tables.py.-print "{path} {sha256}"→xff -type f -hash=sha256), a broken table row, and mangled\t/\nescapes.GNU—-printfis a GNU extension; POSIX and BSD/macOSfindhave no format primary — with an explanatory note.--config=find: it stays xff's own engine, keeping RE2 as the-regex/-iregexdefault (verified: regex is not a per-style default inconfig.cc), one linear-time engine identical on Linux and macOS (where GNU find defaults to Emacs and BSD to BRE);-regextypeexposes xff's grammar set, never GNU's dialect names.no-em-dashesrule).xff/examples (new package)
cookbook_test.shruns every--help=cookbookrecipe (SOT:cli/help.ccRenderCookbook) against a fixture tree rather than only rendering it — this is what would have caught the invalid example above — plus the README "missing final newline" linter. The twogit blamerecipes exercise realgitand degrade to a logged skip wheregitis absent.cookbook_recipes_are_all_tested) fails if a recipe is added or reworded without a matching execution case, so examples ship tested, not just shown.cli/help.cc, AGENTS.md
//xff/examples:cookbook_test, and add "a new/changed cookbook recipe carries a test" to the self-documenting-features rules.Testing
bazel test //xff/examples:cookbook_test //xff/cli:help_topic_test→ pass (10/10 in the new suite, both git recipes ran).pre-commit runon every changed file → green: clang-format, shfmt, shellcheck,no-shell-grep-in-bashtests,no-em-dashes,align-markdown-tables, module-versions, whitespace/EOF.//xff/cli:xff_markdown_testis host-incompatible locally (runs in CI); thehelp.ccchange is comment-only and cannot alter--markdownoutput.Not in this PR
The
mbo0.13.0 graduation (MODULE.bazel: drop the temporarygit_overridefor a BCRbazel_dep) is intentionally left out and will land as its own change.