Struct SuggestService 

pub struct SuggestService { /* private fields */ }

Thread-safe service for accessing suggestions

Provides read-only queries for LLM and UI consumers. Write operations go through SuggestEngine (not this service).

Implementations

impl SuggestService

pub fn new(registry: SuggestRegistry) -> Self

Create a new service with the given registry

pub fn with_strategy( registry: SuggestRegistry, strategy: SuggestStrategy, ) -> Self

Create a service with custom strategy

pub fn with_gc_config(registry: SuggestRegistry, gc_config: GcConfig) -> Self

Create a service with custom GC configuration

pub fn get( &self, id: SuggestId, ) -> Option<MappedRwLockReadGuard<'_, StoredSuggestion>>

Get a suggestion by ID

Returns a mapped guard that holds the read lock while providing access to the stored suggestion.

pub fn is_valid(&self, id: SuggestId) -> bool

Check if a suggestion ID is still valid

pub fn query( &self, query: &SuggestQuery, ) -> Vec<(SuggestId, SuggestCategory, SafetyLevel)>

Query suggestions with filter

pub fn auto_applicable(&self) -> Vec<SuggestId>

Get all suggestions for auto-application (safety=Auto)

pub fn by_category(&self, category: SuggestCategory) -> Vec<SuggestId>

Get suggestions by category

pub fn count(&self) -> usize

Get suggestion count

pub fn is_empty(&self) -> bool

Check if there are any suggestions

pub fn pattern_name(&self, id: SuggestId) -> Option<&'static str>

Get pattern names for a suggestion

pub fn rule_id(&self, id: SuggestId) -> Option<&str>

Get rule ID for a suggestion (e.g., “RL021”). Returns None for non-pattern-based suggestions.

pub fn registry(&self) -> &SuggestRegistry

Get registry access (for pattern lookup)

pub fn to_mutation_specs( &self, id: SuggestId, ctx: &AnalysisContext, ) -> Option<Vec<MutationSpec>>

Generate MutationSpecs for a suggestion

Takes AnalysisContext to resolve types and generate accurate specs.

pub fn generate_with_params( &self, ctx: &AnalysisContext, rule_id: &str, params: &SuggestParams, ) -> Option<Vec<SuggestOpportunity>>

Generate suggestions with external parameters.

This method enables code generation from patterns with user-provided parameters. For example, generating OrderAPI from an API pattern with { "name": "Order" }.

Arguments

• ctx - Analysis context for code graph queries
• rule_id - Rule ID of the parameterized suggestion (e.g., “api-pattern”)
• params - User-provided parameters (e.g., { "name": "Order" })

Returns

• Some(opportunities) - Generated opportunities if rule exists and accepts params
• None - If rule not found or doesn’t accept params

Example

let params = [("name".to_string(), "Order".to_string())].into_iter().collect();
let opps = service.generate_with_params(&ctx, "api-pattern", &params);

pub fn generate_and_store( &self, ctx: &AnalysisContext, rule_id: &str, params: &SuggestParams, ) -> usize

Generate suggestions and store them.

Like generate_with_params, but also stores the generated opportunities in the service for later retrieval and application.

Returns the number of suggestions stored.

pub fn list_parameterized(&self) -> Vec<ParameterizedSuggestInfo>

List all parameterized suggestions with their schemas.

Returns suggestions that accept external parameters, along with their parameter schemas. Useful for LLMs to discover available generation patterns.

pub fn record_changes(&self, trigger: SuggestTrigger) -> bool

Record changes and check if evaluation should trigger

pub fn take_pending(&self) -> (usize, AcChanges)

Take pending changes (for evaluation)

pub fn insert(&self, suggestion: StoredSuggestion) -> Option<SuggestId>

Insert a new suggestion (write operation).

Returns None if an active suggestion with the same identity (pattern + opportunity_id) already exists.

pub fn close(&self, id: SuggestId, reason: impl Into<String>) -> bool

Close a suggestion (write operation)

pub fn invalidate_for_symbol(&self, symbol: &SymbolId)

Invalidate suggestions for a modified symbol

pub fn remove_for_symbol(&self, symbol: &SymbolId)

Remove suggestions for a deleted symbol

pub fn gc(&self, valid_symbols: impl Fn(&SymbolId) -> bool)

Run garbage collection

pub fn clear(&self)

Clear all suggestions

pub fn detect(&self, ctx: &AnalysisContext, symbols: &[SymbolId]) -> usize

Detect suggestions for given symbols using registered patterns.

This is the main entry point for suggestion detection. Automatically filters out suggestions for symbols with @spec:allow(...) directives.

Returns the number of new suggestions found.

pub fn detect_with_allow( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, ) -> usize

Detect suggestions with custom AllowStore.

Use this when you want to reuse an AllowStore across multiple detect calls or when you have a pre-built AllowStore.

pub fn detect_with_rule_filter<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], is_rule_enabled: F, ) -> usize

where F: Fn(&str, &str) -> bool,

Detect suggestions with rule filter.

The is_rule_enabled closure takes (rule_id, file_path) to check if a rule should be processed. Rules returning false are skipped. This enables project and module-level rule configuration.

pub fn detect_with_allow_and_rule_filter<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, is_rule_enabled: F, ) -> usize

where F: Fn(&str, &str) -> bool,

Detect suggestions with custom AllowStore and rule filter.

Combines symbol-level allow directives with project/module-level rule filtering. The is_rule_enabled closure takes (rule_id, file_path) to support module configs.

pub fn detect_with_config<F, S>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, is_rule_enabled: F, severity_override: S, ) -> usize

where F: Fn(&str, &str) -> bool, S: Fn(&str) -> Option<LintSeverity>,

Detect suggestions with full configuration support.

This is the most complete variant that supports:

• Custom AllowStore for symbol-level @spec:allow directives
• Rule filter closure for project-level rule configuration
• Severity override closure for per-rule severity changes

The severity_override closure takes a rule_id and returns an optional new severity. If None, the default severity is used.

The is_rule_enabled closure takes (rule_id, file_path) to support module-level rule configuration.

pub fn detect_with_config_and_scope<F, S>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, is_rule_enabled: F, severity_override: S, scope_filter: &[SymbolScope], ) -> usize

where F: Fn(&str, &str) -> bool, S: Fn(&str) -> Option<LintSeverity>,

Detect suggestions with full configuration and scope filtering.

Extends detect_with_config with scope-based filtering. Each opportunity is tagged with its SymbolScope (Lib/Bin/Test) based on symbol context. If scope_filter is non-empty, only opportunities matching one of the specified scopes are stored.

pub fn detect_patterns( &self, ctx: &AnalysisContext, symbols: &[SymbolId], pattern_names: &[&str], ) -> usize

Detect suggestions for specific patterns only.

Automatically filters out suggestions for symbols with @spec:allow(...) directives.

pub fn detect_patterns_with_allow( &self, ctx: &AnalysisContext, symbols: &[SymbolId], pattern_names: &[&str], allow_store: &AllowStore, ) -> usize

Detect suggestions for specific patterns with custom AllowStore.

pub fn detect_with_precheck<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool,

Detect suggestions with pre-check filter.

The precheck callback is called for each opportunity with:

• The opportunity itself
• The generated MutationSpecs

Only opportunities where precheck returns true are stored. This enables scan-time verification to ensure Apply will succeed.

Example

let count = service.detect_with_precheck(ctx, symbols, |opp, specs, ctx| {
    // Run GraphVerifier on specs
    verify_specs(specs, ctx)
});

pub fn detect_with_precheck_and_allow<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool,

Detect suggestions with pre-check filter and custom AllowStore.

pub fn detect_with_parallel_precheck<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool + Sync,

Detect suggestions with parallel pre-check execution.

This method parallelizes the expensive precheck phase using rayon:

1. Phase 1 (sequential): Detect all opportunities and generate specs
2. Phase 2 (parallel): Run precheck on each candidate
3. Phase 3 (sequential): Insert passed suggestions

This significantly reduces wall-clock time when precheck involves expensive operations like fork_clone() (~100ms each).

Example

let result = service.detect_with_parallel_precheck(ctx, symbols, |opp, specs, ctx| {
    // This closure runs in parallel - must be Sync
    let mut forked = ctx.fork_clone();
    executor.execute_v2(&blueprint, &mut forked).success
});

pub fn detect_with_parallel_precheck_limited<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], limit: Option<usize>, precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool + Sync,

Detect suggestions with parallel pre-check and optional limit.

When limit is Some(N), only the top N candidates by priority are checked. Candidates are sorted by priority (confidence * safety_weight) before precheck.

pub fn detect_with_parallel_precheck_and_allow<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool + Sync,

Detect suggestions with parallel pre-check, custom AllowStore, and optional limit.

pub fn detect_with_parallel_precheck_and_allow_limited<F>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, limit: Option<usize>, precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool + Sync,

Detect suggestions with parallel pre-check, custom AllowStore, and optional limit.

pub fn detect_with_parallel_precheck_and_rule_filter<F, R>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], limit: Option<usize>, is_rule_enabled: R, precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool + Sync, R: Fn(&str) -> bool,

Detect suggestions with parallel pre-check, rule filter, and optional limit.

This is the most complete variant that supports:

• Custom AllowStore for symbol-level @spec:allow directives
• Rule filter closure for project-level rule configuration
• Optional limit on candidates to check
• Parallel precheck execution

pub fn detect_with_parallel_precheck_full<F, R>( &self, ctx: &AnalysisContext, symbols: &[SymbolId], allow_store: &AllowStore, limit: Option<usize>, is_rule_enabled: R, precheck: F, ) -> DetectWithPrecheckResult

where F: Fn(&SuggestOpportunity, &[MutationSpec], &AnalysisContext) -> bool + Sync, R: Fn(&str) -> bool,

Full-featured parallel precheck detection with all options.

This is the internal implementation that other parallel precheck methods delegate to.

impl SuggestService

pub fn stats(&self) -> SuggestStats

Get statistics about current state

pub fn take_store(&self) -> SuggestStore

Take the store contents, leaving an empty store.

Used for preserving suggestions across API reload.

pub fn restore_store(&self, store: SuggestStore)

Restore store contents from a previous backup.

Used for preserving suggestions across API reload.