Implement import-based search for nodejs.referenced capability

[tsanders-rh]

Overview

This PR implements a new import-based search algorithm for the nodejs.referenced capability, replacing the previous workspace/symbol approach which had significant limitations with TypeScript LSP servers.

Problem Statement

The nodejs.referenced capability was not working reliably for the following reasons:

1. LSP Limitation: TypeScript LSP's workspace/symbol only returns top-level declarations in each file
2. Export Structure: Exported components like PatternFly's Card, Button, etc. are not top-level declarations in their source packages - they're exported from re-export barrel files
3. False Negatives: This caused imported symbols to not be detected, resulting in rules failing to match
4. Inefficient Workaround: Previous solution used combo rules combining nodejs.referenced AND builtin.filecontent, which was:
   • Semantically incorrect (text pattern matching instead of semantic analysis)
   • Slower (required both LSP calls and regex scans)
   • Fragile (required maintaining regex patterns for each symbol)

Solution: Import-Based Search

This PR implements a three-step algorithm that leverages the fact that developers must import symbols before using them:

Algorithm

1. FAST SCAN (no LSP required)

   • Scan all TypeScript/JavaScript files for import statements containing the pattern
   • Uses regex matching on normalized content
   • Handles multiline imports via preprocessing
   • Supports:
     • Named imports: import { Card } from "package"
     • Default imports: import Card from "package"
     • Multiple symbols: import { Card, CardBody } from "package"
   • Correctly identifies word boundaries to avoid false matches

2. GET DEFINITIONS (LSP textDocument/definition)

   • For each import location found, use LSP to locate where the symbol is actually defined
   • Opens files in LSP as needed
   • Tracks processed definitions to avoid duplicates

3. GET REFERENCES (LSP textDocument/references)

   • For each definition, use LSP to find all usage locations in the workspace
   • Filters results to workspace folders only
   • Excludes dependency folders
   • Deduplicates incidents

Why This Works Better

• Accurate: Finds actual semantic usage, not just text patterns
• Faster: Avoids expensive workspace/symbol calls; regex scan is much faster
• Comprehensive: Correctly handles all import patterns including multiline
• Maintainable: No need for per-symbol regex patterns

Implementation Details

New Code (nodejs/service_client.go)

Type Definitions:

// ImportLocation tracks where a symbol is imported
type ImportLocation struct {
    fileURI  string
    langID   string
    position protocol.Position
    line     string
}

// fileInfo tracks a source file
type fileInfo struct {
    path   string
    langID string
}

Key Methods:

1. EvaluateReferenced() - Main entry point (~200 lines)

   • Comprehensive docstring explaining the algorithm
   • Scans for imports
   • Opens files in LSP
   • Gets definitions and references
   • Filters and deduplicates results

2. findImportStatements() - Import detection (~95 lines)

   • Regex-based search for import statements
   • Handles both named and default imports
   • Correctly identifies word boundaries
   • Returns positions for LSP definition lookup

3. normalizeMultilineImports() - Preprocessing (~90 lines)

   • Converts multiline imports to single lines
   • Preserves string literals
   • Handles brace depth tracking
   • Enables regex matching on formatted code

4. Helper Functions:

   • isIdentifierChar() - Validates JavaScript identifier characters
   • min() - Utility function

5. Method Overrides:

   • GetDependencies() - Returns empty map (nodejs doesn't use external dependency providers)
   • GetDependenciesDAG() - Returns empty map

Enhanced Logging (base_service_client.go)

• Added structured logging for workspace/symbol calls
• Logs query, result count, and error states
• Removed debug fmt.Printf statements
• Helps diagnose fallback behavior

Testing

Tested with PatternFly v5→v6 migration ruleset on tackle2-ui codebase:

• 56 rules for React component migrations
• Successfully detects imports and references for all PatternFly components
• No longer requires builtin.filecontent workarounds
• Verified with components: Card, Button, Chip, Badge, Label, etc.

Example Rule (Before vs After)

Before (Combo Rule):

when:
  and:
  - nodejs.referenced:
      pattern: Card
  - builtin.filecontent:
      pattern: import.*\{[^}]*\bCard\b[^}]*\}.*from ['"]@patternfly/react-core['"]
      filePattern: \.(j|t)sx?$

After (Clean):

when:
  nodejs.referenced:
    pattern: Card

Benefits

1. ✅ Accurate Detection - Finds actual semantic usage regardless of export structure
2. ✅ Faster Execution - Avoids expensive workspace/symbol calls
3. ✅ Eliminates Workarounds - No need for combo rules with builtin.filecontent
4. ✅ Better Semantics - True semantic analysis instead of text pattern matching
5. ✅ Comprehensive Docs - Detailed docstrings for all major methods
6. ✅ Maintainable - Clear algorithm, well-structured code

Files Changed

• external-providers/generic-external-provider/pkg/server_configurations/nodejs/service_client.go - Main implementation (~480 lines added)
• lsp/base_service_client/base_service_client.go - Enhanced logging
• lsp/base_service_client/cmd_dialer.go - Minor updates
• external-providers/dotnet-external-provider/go.mod - Dependency updates
• external-providers/dotnet-external-provider/go.sum - Dependency updates
• external-providers/golang-dependency-provider/go.mod - Dependency updates
• external-providers/golang-dependency-provider/go.sum - Dependency updates

Total: 7 files changed, 538 insertions(+), 104 deletions(-)

Impact on Existing Rules

This change enables existing nodejs.referenced rules to work correctly. Rules that were using combo patterns with builtin.filecontent can be simplified to use only nodejs.referenced.

No breaking changes - existing rules continue to work, but can now be simplified.

Next Steps

After this PR is merged:

1. Update analyzer-rule-generator to stop creating combo rules (guide available)
2. Simplify existing rulesets to remove builtin.filecontent workarounds
3. Consider applying similar import-based approach to other language providers if needed

Related Issues

Fixes issues with PatternFly v5→v6 migration rules where components were not being detected.

---

Signed-off-by: Todd Sanders [email protected]