Skip to content

docs: README comparison matrices + execution-tested cookbook examples - #357

Merged
helly25 merged 1 commit into
mainfrom
docs/readme-matrices-and-tested-examples
Jul 12, 2026
Merged

docs: README comparison matrices + execution-tested cookbook examples#357
helly25 merged 1 commit into
mainfrom
docs/readme-matrices-and-tested-examples

Conversation

@helly25

@helly25 helly25 commented Jul 12, 2026

Copy link
Copy Markdown
Owner

What

Expand README.md, and make the user-facing examples provably runnable.

README.md

  • Add a Tool Feature Comparison Matrix (xff vs find / fd / grep / ripgrep / shasum) and a Flavor & Behavioral Shift Matrix; all tables vertically aligned 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 Layout Templating" as GNU-printf is a GNU extension; POSIX and BSD/macOS find have no format primary — with an explanatory note.
  • Footnote strict --config=find: it stays xff's own engine, keeping RE2 as the -regex / -iregex default (verified: regex is not a per-style default in config.cc), one linear-time engine identical on Linux and macOS (where GNU find defaults to Emacs and BSD to BRE); -regextype exposes xff's grammar set, never GNU's dialect names.
  • 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 rather than only rendering it — this is what would have caught the invalid example above — plus the README "missing final newline" linter. The two git blame recipes exercise real git and degrade to a logged skip where git is absent.
  • A guard case (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

  • Document that cookbook recipes are execution-tested by //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 run on 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_test is host-incompatible locally (runs in CI); the help.cc change is comment-only and cannot alter --markdown output.

Not in this PR

The mbo 0.13.0 graduation (MODULE.bazel: drop the temporary git_override for a BCR bazel_dep) is intentionally left out and will land as its own change.

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.
@helly25
helly25 merged commit 745370d into main Jul 12, 2026
9 checks passed
@helly25
helly25 deleted the docs/readme-matrices-and-tested-examples branch July 12, 2026 14:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant