Skip to content

docs(guide): long-form GUIDE.md with scrut-tested examples#23

Open
srnnkls wants to merge 3 commits into
feat/stdlib-didyoumean-suggestionsfrom
docs/guide
Open

docs(guide): long-form GUIDE.md with scrut-tested examples#23
srnnkls wants to merge 3 commits into
feat/stdlib-didyoumean-suggestionsfrom
docs/guide

Conversation

@srnnkls

@srnnkls srnnkls commented Jun 27, 2026

Copy link
Copy Markdown
Owner

What

Adds GUIDE.md, the long-form companion to the README, plus a scrut suite that keeps its worked examples honest.

The guide is ordered features-and-DX first, internals-and-design last:

  • Front half (authoring DX): how fas works (patterns-not-predicates mental model), your first rule end to end, the stdlib vocabulary table, writing when (subsumption, the parsed view, structural negation, what when can't express), the five then verbs, how decisions combine, global/project layering, package organization, and the explain/vet/diagnostics loop.
  • Back half (internals): an "Under the hood" section (subsumption engine, preprocessor bridge, closed-world matching, embedded stdlib module overlay, two-phase pipeline, synthesis, localize→render diagnostics, fail-open) and a "Design motivations" section.

Tests

tests/guide.md is a scrut suite (mirroring tests/policies.md / tests/diagnostics.md) asserting every worked example byte-for-byte, with fixtures under tests/guide_rules/ (project layer) and tests/guide_rules_global/ (global layer, for the layering examples). It's picked up automatically by mise run test-integration (glob tests/*.md).

Every output in the guide was captured from a real build, not written from memory.

  • scrut test -w . tests/*.md88/88 pass (12 new, no regressions)
  • go test ./tests/ → pass (the coverage/drift Go tests scan only tests/policies/, so the new fixture dirs don't perturb them)

Notes

  • The guide describes the diagnostic surface accurately rather than over-promising: composed-matcher misses (tool.#Bash & list.MatchN(...)) don't emit a caret frame — only the leaf/kind/disjunction shapes in tests/diagnostics.md do — so the guide's explain test asserts exit codes (0 fired / 1 missed), which are deterministic.
  • "Wiring into Claude Code" describes hook registration in prose but omits a concrete settings.json snippet, since that schema is Claude Code's, not fas's. Easy to add if wanted.

srnnkls added 2 commits June 27, 2026 20:58
Add GUIDE.md as the long-form companion to the README: features and
authoring DX up front (mental model, first rule, stdlib vocabulary,
writing when, the then verbs, synthesis, layering, packages, debugging),
implementation and design motivations under a closing under-the-hood
section.

Back every worked example with tests/guide.md, a scrut suite over
tests/guide_rules/ and tests/guide_rules_global/ fixtures, so the guide
cannot drift from the binary.
Rewrite "What when cannot express" so every inert shape (sibling refs,
let-over-input, input-dependent if, computed counts, close) is paired
with the concrete, loadable pattern to use instead. Fix the count
example: bare string/_ in a when matcher is rejected (E0501), so use a
regex element.

Back the alternatives with tests/guide_rules_alts/ and a scrut section
proving each one compiles and fires.
@srnnkls
srnnkls changed the base branch from main to feat/stdlib-didyoumean-suggestions June 27, 2026 18:59
@srnnkls

srnnkls commented Jun 27, 2026

Copy link
Copy Markdown
Owner Author

Updated: rebased onto feat/stdlib-didyoumean-suggestions (was main) — main predates fas vet, FAS_LOG, and the additive-injects fix that the guide documents, so the scrut suite only passes against the feature binary. Will retarget to main once the feature branch lands.

Also added: each subsumption footgun in the guide now names a loadable alternative, backed by tests/guide_rules_alts/ and a new scrut section (93/93 pass).

Incorporates the parser change that groups each invocation with its own
command, subcommand, action, targets, and flags. Documents the flat-list
over-match (cat README && rm .env) and the calls join that matches only a
single call that both runs a read verb and targets a secret.
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