Package com.tnsai.quality.security.harness

Interface MatcherSpi

All Known Implementing Classes:
RegexMatcher
public interface MatcherSpi
SPI for static vulnerability matchers — regex / AST / dependency-version checks that pre-filter files for the agent stage (TNS-291).

Matchers are cheap; they run on every file. A hit doesn't directly become a ReviewFinding — it marks the file as a candidate so a ReviewAgentSpi can do the deeper analysis. The agent gets the matcher's hits as part of its prompt context.

Implementations should be deterministic + side-effect-free; the scan(java.nio.file.Path, java.lang.String) method may be called concurrently from different threads over different files.

Since:
0.10.0 (TNS-291)

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    MatcherSpi.Hit
    One location matched by a MatcherSpi.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    cwe()
    CWE id this matcher targets, e.g.
    Severity
    defaultSeverity()
    Default severity assigned when this matcher fires alone (no agent).
    String
    description()
    Human-readable description of what this matcher looks for.
    String
    id()
    Stable id, e.g.
    List<MatcherSpi.Hit>
    scan(Path file, String content)
    Scan content and return the locations where the matcher found a candidate.

  • Method Details

    • id

      String id()
      Stable id, e.g. "sql-injection".

    • cwe

      String cwe()
      CWE id this matcher targets, e.g. "CWE-89".

    • defaultSeverity

      Severity defaultSeverity()
      Default severity assigned when this matcher fires alone (no agent).

    • description

      String description()
      Human-readable description of what this matcher looks for.

    • scan

      List<MatcherSpi.Hit> scan(Path file, String content)
      Scan content and return the locations where the matcher found a candidate. Returning an empty list means the file is clean w.r.t. this matcher.
      Parameters:
      file - relative path inside the project — only used for language gating (e.g. skip non-Java files)
      content - full file content as UTF-8