Structural pattern search is a standalone local CLI capability backed by GoCPG. It is not Scenario 21: the current Scenario 21 is interface documentation sync. Use this guide for AST-pattern search, YAML-rule scanning, result inspection, rule generation, and explicitly approved rewrites against a known CPG database.
Prerequisites and scope
Every scan, search, list, stats, or fix command requires an explicit --db PATH; the CLI does not borrow a hidden active project. Record the source revision used to build that CPG, the database identity, selected rule directories, rule ID, language, file filters and GoCPG version.
The maintained built-in rule source is gocpg/configs/rules/. Do not freeze a rule or language count in evergreen prose: both change with the checked-out revision. Pass an explicit --rules directory when the exact rule pack matters.
Search and scan without changing source
Run an ad hoc AST-pattern search:
python -m src.cli patterns search "malloc($SIZE)" --lang c --db PATH
Run a reviewed rule pack and save a SARIF artifact:
python -m src.cli patterns scan --db PATH --rules gocpg/configs/rules/c --format sarif --output results.sarif
search returns bounded matches up to --max-results. scan evaluates YAML rules and may update pattern-result tables in the selected CPG as part of analysis. Neither command edits source files. Preserve findings, diagnostics, rule digests and the CPG/source revision relationship.
Preview a rewrite first
patterns fix is a mutating command unless --dry-run is supplied. Always begin with the same database, source root, rule directory, rule ID and file scope you intend to approve:
python -m src.cli patterns fix --db PATH --rules gocpg/configs/rules/autofix --input SOURCE_ROOT --dry-run
The preview prints affected files, lines, diagnostics and diffs where the backend provides them. The CLI also calculates a preview_digest over the reviewed scope. Stop if the source revision moved, a path escapes SOURCE_ROOT, the rule pack changed, or the preview lacks enough detail to assess the rewrite.
Approve, apply, and verify
After recording the preview and exact scope, rerun the same command without --dry-run:
python -m src.cli patterns fix --db PATH --rules gocpg/configs/rules/autofix --input SOURCE_ROOT
The CLI requests authorization through ApprovalEngine; when that route is unavailable in an interactive terminal, it falls back to an explicit prompt. Rejection, EOF, or an approval error must not be converted into implicit consent.
Backups are enabled by default and use .bak files where the GoCPG rewrite backend supports them. --no-backup deliberately weakens recovery and should be used only under separately accepted version-control and rollback evidence. A successful command requires every returned rewrite to report fix_applied; unconfirmed results fail closed.
After application, inspect the version-control diff, run focused tests and static checks, and compare each changed file with the approved preview. A backup stores a copy; transactional rollback uses reviewed version-control state or a verified backup after resolving the exact target paths.
Other CLI operations
python -m src.cli patterns list --db PATH
python -m src.cli patterns stats --db PATH
python -m src.cli patterns generate "find unchecked return values" --lang c --output rule.yaml
Review and test generated rules before use. generate can invoke an LLM and may require configured
model access; syntax, precision, and rewrite safety come from that review and testing.
Runtime surface boundary
The former structural-pattern REST and MCP surfaces are removed. Use the CLI above. Do not publish examples for retired /api/v1/patterns/... routes or infer an MCP mutation tool from pattern findings exposed by other features.
Source contract
src/cli/analysis_commands/patterns_command.py— CLI registration, explicit DB scope, preview, approval, backup and apply confirmation;src/services/cpg/query_mixins/pattern_queries.py— reads persisted pattern rules, findings and statistics;src/services/gocpg/core/models.py— current scan request and result models;gocpg/configs/rules/— maintained checked-in rule packs;gocpg/pkg/storage/duckdb/schema.go— pattern-result and rule tables.