firchecks

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 11, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source
const FirCacheVersion = 1

FirCacheVersion is bumped when the entry layout changes incompatibly.

Variables

This section is empty.

Functions

func CacheDir

func CacheDir(repoDir string) (string, error)

CacheDir returns (and creates) {repoDir}/.krit/fir-cache.

func ClasspathFingerprint

func ClasspathFingerprint(classpath []string) string

ClasspathFingerprint returns a stable fingerprint for classpath entries. Existing files are fingerprinted by content so replacing a JAR invalidates cached FIR findings even when source files are unchanged.

func CollectFirKtFiles

func CollectFirKtFiles(scanPaths []string) ([]string, error)

CollectFirKtFiles walks the given scan paths and returns all .kt files, skipping standard build/hidden directories. Used to build the file list for InvokeCached when no explicit list is provided.

func ContentHash

func ContentHash(path string) (string, error)

ContentHash returns the hex content hash for the file at path.

func FindFirJar

func FindFirJar(scanPaths []string) string

FindFirJar locates krit-fir.jar by checking standard locations relative to the krit binary and the project being scanned.

func MergeFindings

func MergeFindings(allFindings []scanner.Finding, firFindings []scanner.Finding) []scanner.Finding

MergeFindings merges FIR findings into the existing allFindings slice, deduplicating on (file, line, col, rule). Pilot FIR rules also dedupe on (file, line, rule) because compiler source ranges can point at a callee token while the tree-sitter rule points at the containing call expression. Go tree-sitter findings win on collision (they're already in allFindings).

func SetReporter

func SetReporter(r *diag.Reporter)

SetReporter installs r as the package-level Reporter for firchecks. Passing nil restores a default warnings-only Reporter.

func ToScannerFinding

func ToScannerFinding(f FirFinding) scanner.Finding

ToScannerFinding converts a FirFinding to a scanner.Finding. Known FIR diagnostics are normalized back to Krit catalog rule IDs so --fir findings deduplicate with the Go implementations while Track B runs both versions side by side.

func WriteCacheEntry

func WriteCacheEntry(cacheDir string, entry *FirCacheEntry) error

WriteCacheEntry writes a cache entry to disk.

func WriteFreshEntries

func WriteFreshEntries(cacheDir string, files []string, resp *CheckResponse) int

WriteFreshEntries writes cache entries for each file analyzed in a CheckResponse. Crash markers from resp.Crashed are written as poison entries.

func WriteFreshEntriesForFingerprint

func WriteFreshEntriesForFingerprint(cacheDir string, files []string, resp *CheckResponse, fingerprint string) int

WriteFreshEntriesForFingerprint writes fresh cache entries and records the dependency/classpath fingerprint used to validate future hits.

Types

type CheckResponse

type CheckResponse struct {
	ID        int64             `json:"id"`
	Succeeded int               `json:"succeeded"`
	Skipped   int               `json:"skipped"`
	Findings  []FirFinding      `json:"findings"`
	Crashed   map[string]string `json:"crashed"`
}

CheckResponse is the JSON envelope returned by krit-fir for a "check" request.

func InvokeOneShot

func InvokeOneShot(jarPath string, files []string, sourceDirs, classpath, rules []string, verbose bool) (*CheckResponse, error)

InvokeOneShot starts a fresh krit-fir daemon, sends a single check request for the given files, and returns the response. The daemon is shut down after the request. Used when the persistent daemon is unavailable.

type FakeFirChecker

type FakeFirChecker struct {
	Findings []scanner.Finding
	Crashed  map[string]string
	Err      error
	// Called is the list of file slices passed to Check.
	Called [][]string
}

FakeFirChecker is a configurable test double for FirChecker. Set Findings and Crashed before use.

func NewFakeFirChecker

func NewFakeFirChecker() *FakeFirChecker

NewFakeFirChecker returns a FakeFirChecker with all maps initialized.

func (*FakeFirChecker) Check

func (f *FakeFirChecker) Check(files []string, _, _, _ []string) (*Result, error)

Check records the call and returns the configured findings.

type FirActiveRules

type FirActiveRules struct {
	Filters []FirFilterRule
	Names   []string
}

func ActiveFirRules

func ActiveFirRules(enabledRuleIDs []string) FirActiveRules

ActiveFirRules returns the FIR check names and coarse file filters that correspond to enabled Krit catalog rule IDs.

type FirCacheEntry

type FirCacheEntry struct {
	V                  int          `json:"v"`
	ContentHash        string       `json:"content_hash"`
	FilePath           string       `json:"file_path"`
	Findings           []FirFinding `json:"findings"`
	ClosureFingerprint string       `json:"closure_fingerprint,omitempty"`
	// Crashed marks a poison entry: the file deterministically crashes the FIR checker.
	Crashed    bool   `json:"crashed,omitempty"`
	CrashError string `json:"crash_error,omitempty"`
}

FirCacheEntry is one file's cached FIR findings.

func ClassifyFiles

func ClassifyFiles(cacheDir string, files []string) (hits []*FirCacheEntry, misses []string)

ClassifyFiles partitions files into cache hits and misses. Hits carry their CacheEntry; misses need JVM analysis.

func ClassifyFilesForFingerprint

func ClassifyFilesForFingerprint(cacheDir string, files []string, fingerprint string) (hits []*FirCacheEntry, misses []string)

ClassifyFilesForFingerprint is ClassifyFiles plus dependency/classpath fingerprint validation. A non-matching cache entry is treated as a miss.

func LoadCacheEntry

func LoadCacheEntry(cacheDir, hash string) (*FirCacheEntry, error)

LoadCacheEntry reads a cache entry for the given content hash. Returns (nil, nil) on miss.

type FirCacheStats

type FirCacheStats struct {
	Hits   int64
	Misses int64
	Writes int64
}

FirCacheStats holds snapshot counters.

func Stats

func Stats() FirCacheStats

Stats returns a snapshot of the cache hit/miss/write counters.

type FirChecker

type FirChecker interface {
	Check(files []string, sourceDirs, classpath, rules []string) (*Result, error)
}

FirChecker is the interface for running FIR checks. The production implementation calls InvokeCached; tests use FakeFirChecker.

type FirDaemon

type FirDaemon struct {
	// contains filtered or unexported fields
}

FirDaemon manages a long-lived krit-fir JVM process.

func ConnectOrStartFirDaemon

func ConnectOrStartFirDaemon(jarPath string, sourceDirs []string, verbose bool) (*FirDaemon, error)

ConnectOrStartFirDaemon tries to reuse an existing daemon for the given sourceDirs (via PID file), or starts a new one.

func StartFirDaemonWithPort

func StartFirDaemonWithPort(jarPath string, verbose bool) (*FirDaemon, error)

StartFirDaemonWithPort launches krit-fir.jar in TCP daemon mode.

func (*FirDaemon) Check

func (d *FirDaemon) Check(files []fileRef, sourceDirs, classpath, rules []string) (*CheckResponse, error)

Check sends a check request to the daemon and returns the response.

func (*FirDaemon) Close

func (d *FirDaemon) Close() error

Close shuts the daemon down completely.

func (*FirDaemon) MatchesRepo

func (d *FirDaemon) MatchesRepo(sourceDirs []string) bool

MatchesRepo returns true if this daemon was started for the given sourceDirs.

func (*FirDaemon) Ping

func (d *FirDaemon) Ping() error

Ping verifies the daemon is responsive.

func (*FirDaemon) Release

func (d *FirDaemon) Release() error

Release drops this Go-side handle but leaves the daemon process alive.

type FirFilterRule

type FirFilterRule struct {
	Name   string
	Filter *FirFilterSpec
}

FirFilterRule is the minimal rule view used by CollectFirCheckFiles.

type FirFilterSpec

type FirFilterSpec struct {
	// Identifiers is a list of substrings; any file whose content contains
	// at least one is forwarded to the FIR checker. Conservative: false
	// positives waste JVM work but never lose findings.
	Identifiers []string
	// AllFiles: true means the checker needs every file (no reduction).
	AllFiles bool
}

FirFilterSpec is the per-rule declaration of which files a FIR checker needs to see. Mirrors oracle.FilterSpec.

type FirFilterSummary

type FirFilterSummary struct {
	TotalFiles  int
	MarkedFiles int
	AllFiles    bool
	// Paths is the sorted list of absolute paths any rule marked for FIR analysis.
	// Nil when AllFiles is true.
	Paths []string
}

FirFilterSummary describes the outcome of a filter evaluation.

func CollectFirCheckFiles

func CollectFirCheckFiles(rules []FirFilterRule, files []*scanner.File) FirFilterSummary

CollectFirCheckFiles returns the subset of files any enabled FIR rule wants to see. Matches oracle.CollectOracleFiles semantics exactly.

type FirFinding

type FirFinding struct {
	Path       string  `json:"path"`
	Line       int     `json:"line"`
	Col        int     `json:"col"`
	StartByte  int     `json:"startByte,omitempty"`
	EndByte    int     `json:"endByte,omitempty"`
	Rule       string  `json:"rule"`
	Severity   string  `json:"severity"`
	Message    string  `json:"message"`
	Confidence float64 `json:"confidence"`
}

FirFinding is the per-finding JSON shape emitted by krit-fir.

type ProductionFirChecker

type ProductionFirChecker struct {
	JarPath    string
	SourceDirs []string
	Classpath  []string
	RepoDir    string
	UseDaemon  bool
	Verbose    bool
}

ProductionFirChecker wraps InvokeCached to satisfy FirChecker.

func (*ProductionFirChecker) Check

func (p *ProductionFirChecker) Check(files []string, sourceDirs, classpath, rules []string) (*Result, error)

Check runs InvokeCached with the configured parameters.

type Result

type Result struct {
	Findings []scanner.Finding
	// Crashed maps file path → error message for files that crashed the FIR checker.
	Crashed map[string]string
}

Result carries the findings and per-file crash markers from InvokeCached.

func InvokeCached

func InvokeCached(
	jarPath string,
	files []string,
	sourceDirs []string,
	classpath []string,
	rules []string,
	repoDir string,
	useDaemon bool,
	verbose bool,
) (*Result, error)

InvokeCached is the cache-aware entry point for running FIR checks.

jarPath is the krit-fir.jar (required when misses need JVM analysis). files is the set of .kt file paths to check (pre-filtered by CollectFirCheckFiles). sourceDirs / classpath / rules are forwarded to the daemon's check request. repoDir is used to locate the cache; empty disables caching. useDaemon controls whether to prefer the persistent daemon (vs one-shot). verbose enables progress logging to stderr.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL