feat(report): add --type filter to report search (swamp-club#498)

[keeb]

Summary

Adds a --type <report-name> filter to swamp report search so users can
narrow stored reports to an exact report type name across all models and
workflows (e.g. swamp report search --type @webframp/cost-audit-report).

The report type name is already stored on every report artifact as the
reportName tag and is already shown in search results, so this is a pure
filter addition — no schema or data-model changes.

--type is an exact match, deliberately distinct from the positional
[query] substring match. This provides the precise type matching that the
existing --label workaround cannot. The filter runs after --scope and
before the --label filter so it shrinks the candidate set ahead of the
per-candidate definition lookups the label filter performs.

Also documents the previously-undocumented report search browse command and
all its flags in the swamp-report skill.

Resolves swamp-club#498.

Changes

• src/libswamp/reports/search.ts — type?: string on ReportSearchInput; exact-match filter block
• src/cli/commands/report_search.ts — --type <name> CLI option, passed into the search input
• src/libswamp/reports/search_test.ts — 3 tests: exact match, exact-not-substring, composes with --scope
• .claude/skills/swamp-report/SKILL.md — documents the report search browse command and flags

Test Plan

• deno fmt --check, deno check, deno lint — all pass
• deno run test src/libswamp/reports/search_test.ts — 12 passed
• End-to-end against a compiled binary: --type "@swamp/method-summary" returns the report; --type "method-summary" (substring) returns nothing, confirming exact matching through the full stack

🤖 Generated with Claude Code

[github-actions]

CLI UX Review

Blocking

None.

Suggestions

1. CLI help example uses a contributor-specific org name (@webframp/cost-audit-report). A generic placeholder like @myorg/cost-audit-report (as used in the skill docs) would be more neutral. Minor and subjective.

2. JSON output omits active filter parameters. The JSON shape { query, results } doesn't echo back applied filters (type, scope, model, etc.), so a script can't confirm what filter was used from the response alone. This is pre-existing for all other flags — not a regression from this PR, but worth noting as a future improvement.

Verdict

PASS — --type is correctly named, clearly described, and consistent with the existing --scope/--model/--workflow/--label filter pattern. Flag placement in help text matches the filter application order. Skill documentation accurately covers the new flag and the previously-undocumented report search command. JSON and log modes both work correctly with the server-side filter.

[github-actions]

Adversarial Review

Critical / High

None found.

Medium

None found.

Low

1. src/libswamp/reports/search.ts:202-205 — --type filter is case-sensitive while --scope is also case-sensitive, but [query] is case-insensitive. If a user passes --type "@Webframp/Cost-Audit-Report" they get zero results silently (no error, just empty). This is documented as "exact match" so it's by design, but the asymmetry with [query]'s case-insensitive behavior could surprise users. Not a bug — the PR body explicitly calls out this distinction and the test at line 170 validates it. Mentioning for visibility only.

Verdict

PASS — This is a clean, well-scoped addition. The filter logic is a straightforward === comparison on Record<string, string> tags, so there are no type coercion surprises. The filter is correctly positioned after --scope and before --label (which does per-candidate async lookups). The CLI option is correctly wired through the Cliffy command definition and passed into ReportSearchInput. The ReportSearchInput type is properly exported from the libswamp barrel. Tests cover the three important cases: exact match works, substring does not match, and composition with --scope. No security, concurrency, resource management, or API contract concerns.

[github-actions]

CLI UX Review

Blocking

None.

Suggestions

1. The --scope option lists its valid enum values in the description: (method, model, workflow). The new --type flag is intentionally free-form, but a brief qualifier like "Filter by exact report type name (e.g. @webframp/cost-audit-report); case-sensitive" would help users understand case sensitivity without having to test it.

Verdict

PASS — --type follows the existing flag naming convention (consistent with data search, data list, vault get), the exact-match semantics are clearly signalled both in the description and in SKILL.md, JSON and log output shapes are unchanged (pure filter), and the new flag is placed logically between --scope and --label in both the command definition and the help documentation.

[github-actions]

Code Review

Clean, well-scoped PR. Adds an exact-match --type filter to report search that follows the existing filter patterns (scope, label, query) precisely.

Blocking Issues

None.

Suggestions

1. The 4-line comment block at src/libswamp/reports/search.ts:197-201 is more verbose than the project's "default to no comments" convention calls for. The filter's behavior is clear from c.data.tags.reportName === input.type. A single line noting the placement rationale (before label filter for performance) would suffice, or it could be omitted entirely.

What looks good

• libswamp boundary: CLI command imports exclusively from src/libswamp/mod.ts — no internal path leaks.
• DDD: type added to the ReportSearchInput application-service input (value object); filter logic stays in the reportSearch application service where search/query orchestration belongs. No domain model changes needed since reportName is an existing tag.
• Test coverage: 3 new tests cover exact match, non-substring rejection, and composition with --scope. Tests follow project conventions (naming, assertions, co-located with source).
• No security concerns: Pure string equality against stored tags — no injection surface.
• Skill docs: Documents the previously-undocumented report search subcommand and its flags.