feat: generalize new-class advisory into config-driven advice block (#347)

[fdaviddpt]

Context

#347 asked for a hint when an edit/paste adds a component class or a public component attribute (XSD/cache regen reminder), gated behind a config flag like the existing adviseForNewTest. Rather than bolt on a second hardcoded advisory, this generalizes the mechanism: adviseForNewTest (a single-purpose bool) becomes a config-driven advice block of named rules, so projects add nudges as data instead of code.

What changed

• advice block — top-level map of named rules. Each rule gates (all optional) on:
  • hooks_into — ops that trigger it (default: all mutating)
  • match — path glob
  • when — new-file | existing-file | always
  • contains — regex over the content the op added (lines after but not before), so it fires only when the op introduces the pattern, not when the file already held it
  • resolve / resolveFromValidator — a subprocess emitting a would-be target via the exit-3 + stderr contract
  • message — {target}/{path}/{op} interpolate; a {target}-less message gets — consider <target> appended when a resolver produced one
• resolveFromValidator accepts a validator name, not just true. true grabs the first validator declaring a resolver — in a multi-resolver config that's the wrong one (DVSI: phpstan-component's resolver precedes phpunit's, so the old adviseForNewTest was almost certainly resolving against the wrong script).
• Threaded pre_content into both _run_with_validators call sites so contains matches added-content.
• Docs (validators.md + configuration.md), .supertool.example.json, CHANGELOG.

Breaking

adviseForNewTest: true removed. Express it as an advice.newTest rule:

"advice": { "newTest": { "hooks_into": ["paste"], "match": "*.php", "when": "new-file", "resolveFromValidator": "phpunit", "message": "new class without test" } }

Tests

Rewrote the advice test block for the new API: newTest parity (7), contains-on-added-content (3), when gate, default ops, multi-rule, interpolation, named-validator disambiguation, and a regression test asserting the [advice] block uses real newlines (a literal-\n bug slipped past substring asserts and was caught in self-review). Full suite: 3479 passed.

Closes #347

🤖 Generated by Max

[fdaviddpt]

Addressed review in 0d601f1:

• feat: between op — extract function bodies and line slices #1 _advice_added_text now does a multiset (count-based) diff — a duplicated line counts as added even when an identical line pre-existed.
• feat(gl-mr): list conflicting files + hunks + resolve commands #2 added _advice_wants_pre + wired both call sites to snapshot pre-edit bytes whenever a contains rule applies, so the added-content gate is exact regardless of rollback_on_fail/notifier config (no more whole-file over-fire on existing-file edits).
• Improve supertool hook-stdout cap handling #3/Per-tool exclude-paths for traversal ops (glob, grep, ls, tree, map) #4 interpolate {path}/{op} before inserting a resolver target (no re-scan), and strip the leading space on empty-message + target.
• Skipped feat: per-tool exclude-paths for traversal ops #5 (silent skip on mis-named resolveFromValidator) — advice is non-blocking by design; a warning in every receipt is noisier than the footgun.

Tests added for the multiset case and _advice_wants_pre. Full suite: 3481 passed.