Polyglot Test Discovery, Engine Registry & Cache Subsystem Operational Architecture Guide
1. Architectural Overview
The Polyglot Test Discovery, Engine Registry & Cache Subsystem (pkg/testdiscovery) provides high-performance, deterministic static test extraction across multi-language codebases without code execution or subprocess overhead.
In complex polyglot repositories containing Go, Python, TypeScript, and Rust components, naive dynamic test discovery methods (such as invoking external runtimes pytest --collect-only, cargo test --list, or spinning up Node runtimes) introduce severe security vulnerabilities, heavy subprocess latency, and flakiness from unbuilt dependencies or uninitialized runtime states.
Under the core architecture invariants (POL-DEFAULT-142277d3):
- Zero-Subprocess Static Analysis: Test discovery occurs entirely in-memory using AST parsing (
go/ast) and compiled regular expression tokenization for Python, TypeScript, and Rust. - Incremental SHA-256 Memoization: Discovery results are cached with dual-coordinate fast-path checking (mtime fast path + SHA-256 content hash fallback), eliminating redundant parsing on untouched source files.
- Unified Kernel Object Projection: Discovered targets across all supported languages are projected into standard
test_caseobjects compatible with the ZQK Knowledge Kernel relational graph and test verification runners. - Fail-Closed Jail Containment: Strict path lexical normalization and symlink evaluation prevent directory traversal escapes outside the canonical project boundary.
2. Component Topology & Architecture
The subsystem consists of five primary architectural primitives:
flowchart TD
subgraph ClientPlane["Callers & Tooling"]
CLI["zqk test discover"]
Runner["Test Execution Harness"]
Agent["Autonomous Worker Swarm"]
end
subgraph TestDiscoverySubsystem["pkg/testdiscovery Subsystem"]
Engine["Engine (Discovery Coordinator)"]
Options["DiscoveryOptions"]
Cache["DiscoveryCache (JSON Storage)"]
subgraph DiscovererRegistry["Discoverer Registry (Discoverer Interface)"]
GoDisc["GoDiscoverer (AST Parser)"]
PyDisc["PythonDiscoverer (Token Scanner)"]
TSDisc["TypeScriptDiscoverer (Regex Scanner)"]
CargoDisc["CargoDiscoverer (Rust Scanner)"]
CustomDisc["Custom Discoverers (Plugin / Mock)"]
end
WorkerPool["Goroutine Worker Pool (goroutinelabels)"]
Aggregator["Target Aggregator & TestCase Generator"]
end
ClientPlane -->|"Discover(ctx, opts)"| Engine
Engine --> Options
Engine --> Cache
Engine --> WorkerPool
WorkerPool --> DiscovererRegistry
WorkerPool --> Aggregator
Aggregator -->|"[]DiscoveredTarget"| ClientPlane
Subsystem Components
Engine(engine.go): The central discovery coordinator. Orchestrates candidate file collection, path containment verification, worker pool distribution viagoroutinelabels.NewGoroutine, and result synthesis.DiscoveryOptions(types.go): Declarative configuration struct specifyingProjectRoot, targetPaths,Languagesfilters,ExcludePaths,Workersconcurrency ceilings, andIncrementalcaching flags.DiscoveryCache(cache.go): Thread-safe (sync.RWMutex) memoization store holding file modification timestamps, SHA-256 content hashes, and extracted targets with atomic serialized JSON persistence.DiscovererInterface (types.go): Pluggable language abstraction definingLanguage() string,CanHandle(relPath string) bool, andDiscover(ctx, projectRoot, relPath, content) ([]DiscoveredTarget, error).- Language Discoverers:
-
GoDiscoverer(go_discoverer.go): Go standard AST parsing (go/parser,go/token), extractingTest*,Benchmark*, andExample*declarations, build tags, and doc comment metadata (criteria,requirement,scenario). -PythonDiscoverer(python_discoverer.go): Static line scanning detectingdef test_*,class Test*,@pytest.mark.*decorators, and comment metadata. -TypeScriptDiscoverer(ts_discoverer.go): Static scanning for.test.ts,.spec.ts,.test.tsx,.spec.tsx,.test.js, and.spec.js, extractingdescribe,suite,it, andtestblocks. -CargoDiscoverer(cargo_discoverer.go): Rust source scanning detecting#[test],#[tokio::test],#[ignore],mod tests, and function signatures (fn,pub fn,async fn).
3. Polyglot Test Discovery & Caching Lifecycle
The discovery lifecycle combines directory walk filtering, worker distribution, and incremental cache lookups:
sequenceDiagram
autonumber
actor Caller as Client (CLI / Harness)
participant Engine as Engine
participant Walker as Candidate Walker
participant Cache as DiscoveryCache
participant Workers as Worker Pool
participant Discoverer as Language Discoverer
Caller->>Engine: Discover(ctx, opts)
Engine->>Walker: collectCandidateFiles(cleanRoot, canonicalRoot, opts)
Note over Walker: Jail containment check & symlink evaluation
Walker-->>Engine: []fileCandidate (relPath, absPath, info)
alt opts.Incremental == true
Engine->>Cache: LoadCache(cachePath)
end
loop For each file candidate in parallel
Engine->>Workers: Dispatch candidate to worker channel
Workers->>Cache: Get(relPath, modTime, content)
alt Cache Hit (mtime or SHA-256 match)
Cache-->>Workers: Cached []DiscoveredTarget
else Cache Miss
Workers->>Discoverer: CanHandle(relPath)
Discoverer-->>Workers: true
Workers->>Discoverer: Discover(ctx, root, relPath, content)
Discoverer-->>Workers: []DiscoveredTarget
Workers->>Cache: Set(relPath, modTime, content, targets)
end
end
alt opts.Incremental == true
Engine->>Cache: Save()
end
Engine-->>Caller: []DiscoveredTarget
Cache Resolution Logic
- Index Lookup: Evaluates whether
relPathexists in the cache map. - mtime Fast Path: If
entry.ModTimeUnix == modTime.Unix(), returns cached targets immediately without computing content hashes or reading file buffers. - SHA-256 Fallback: If modification times differ (such as after
git checkoutor touch operations) and file content is provided, computes SHA-256 hash. IfhStr == entry.Hash, updates mtime and returns cached targets. - Miss & Re-parse: If hashes differ or key is unknown, delegates to the matching
Discoverer, updating cache entries with newly parsed targets.
4. Engine Registry & Lifecycle State Machine
The Engine transition lifecycle guarantees thread-safe initialization, discovery coordination, and clean cache eviction:
stateDiagram-v2
[*] --> Initialized: NewEngine()
Initialized --> Configured: RegisterDiscoverer(custom)
Initialized --> Scanning: Discover(ctx, opts)
Configured --> Scanning: Discover(ctx, opts)
state Scanning {
[*] --> WalkFiles
WalkFiles --> FilterCandidates: Symlink & Ignore Gates
FilterCandidates --> Dispatched: Populate Worker Channel
}
Scanning --> Parsing: Workers Active
state Parsing {
[*] --> CacheQuery
CacheQuery --> FastReturn: Cache Hit
CacheQuery --> StaticParse: Cache Miss
StaticParse --> CacheStore: Update Dirty Entry
FastReturn --> MergedResults
CacheStore --> MergedResults
}
Parsing --> Serializing: Workers Complete
Serializing --> Flushed: cache.Save()
Flushed --> [*]: Return []DiscoveredTarget
5. Security & Isolation Boundaries
-
Jail Containment (Zero Symlink Traversal):
collectCandidateFilesstrictly resolves symlinks on the project root (canonicalRoot) and on each candidate path (canonicalPath). Any directory or file whose canonical target escapescanonicalRootis rejected or skipped viafilepath.SkipDir. -
Zero Code Execution: No child processes (
os/exec) or external interpreters (python,node,cargo) are invoked. Discovery is purely in-process and static, guaranteeing resilience against arbitrary code execution vulnerabilities in untrusted repositories. -
Automated Directory Pruning: Hardcoded exclusion lists automatically prune VCS directories (
.git), dependency folders (node_modules,vendor), build outputs (dist,build,target), and internal runtime trees (.zqk), preventing CPU exhaustion and memory bloat.
6. Concurrency & Thread-Safety Guarantees
- Concurrent Cache Invariants:
DiscoveryCacheguards internal map reads withsync.RWMutex.RLockand updates withsync.RWMutex.Lock. Multiple worker goroutines can safely read and populate cache entries simultaneously. - Worker Pool Supervision: Worker goroutines are dispatched under
goroutinelabels.NewGoroutine("testdiscovery.worker", "discover test targets in files"), guaranteeing structured goroutine naming and leak prevention in diagnostic telemetry. - Context-Bound Lifetime: Worker loops monitor
select { case <-ctx.Done(): ... }to honor caller-directed timeouts and cancellations immediately.
7. Verification & Three-Fold Proof
The subsystem adheres strictly to the Three-Fold Proof model:
| Dimension | Proof Mechanism | Verification Gate |
|---|---|---|
| Static Floor Invariant | Statement test coverage must reach \(\ge 85.0\%\) across all subsystem routines. | go test -cover ./pkg/testdiscovery (Achieved: 95.7%) |
| Operational Dynamic Proof | Multi-language test discovery across Go, Python, TypeScript, and Rust, SHA-256 incremental cache hits/misses, custom discoverer registration, and concurrent worker thread safety. | pkg/testdiscovery/testdiscovery_coverage_elevation_cycle225_test.go |
| Negative Adversarial Boundary | Corrupt JSON cache tolerance, symlink directory traversal rejection, syntax error isolation, invalid worker configurations, and graceful context cancellation. | go test -race -timeout 30s ./pkg/testdiscovery (0 failures, 0 races) |
8. Open-Core Compliance & Invariants
- Deterministic Execution: Test parsing produces identical, byte-reproducible
DiscoveredTargetoutputs across all operating platforms (Linux, macOS, Windows). - Zero Swallowed Errors: All error branches in discovery and cache operations are explicitly captured, logged, or propagated.
- Structured Goroutine Lifecycle: Concurrency operations utilize
goroutinelabelsfor leak-free, traceable background execution. - Identifier Sanitization: The public specification and implementation remain strictly decoupled from project-specific or nanosecond kernel identifiers.