circle-ir 3.8.4 → 3.9.8

package/dist/analyzer.d.ts

@@ -3,10 +3,40 @@
  *
  * Main entry point for analyzing source code and producing Circle-IR output.
  * This is the core static analyzer. LLM-based verification and discovery are out of scope for this library.
+ *
+ * The analysis pipeline runs twenty-seven sequential passes over a shared CodeGraph:
+ *   1. TaintMatcherPass        — config-based source/sink extraction
+ *   2. ConstantPropagationPass — dead-code detection, symbol table, field taint
+ *   3. LanguageSourcesPass     — language-specific sources/sinks (JS, Python, getters)
+ *   4. SinkFilterPass          — four-stage false-positive elimination
+ *   5. TaintPropagationPass    — DFG-based flow verification
+ *   6. InterproceduralPass     — cross-method taint propagation
+ *   7. DeadCodePass            — CFG blocks unreachable from entry (CWE-561)
+ *   8. MissingAwaitPass        — unawaited async calls in JS/TS (CWE-252)
+ *   9. NPlusOnePass            — DB/HTTP calls inside loop bodies (CWE-1049)
+ *  10. MissingPublicDocPass    — public methods/types without doc comments
+ *  11. TodoInProdPass          — TODO/FIXME/HACK markers in production code
+ *  12. StringConcatLoopPass    — string += inside loops, O(n²) allocations (CWE-1046)
+ *  13. SyncIoAsyncPass         — blocking *Sync calls inside async functions (CWE-1050)
+ *  14. UncheckedReturnPass     — ignored boolean return from File.delete etc. (CWE-252)
+ *  15. NullDerefPass           — null-assigned var dereferenced without guard (CWE-476)
+ *  16. ResourceLeakPass        — stream/connection opened but never closed (CWE-772)
+ *  17. VariableShadowingPass   — inner scope re-declares outer name (CWE-1109)
+ *  18. LeakedGlobalPass        — assignment without declaration in JS/TS (CWE-1109)
+ *  19. UnusedVariablePass      — local variable declared but value never read (CWE-561)
+ *  20. DependencyFanOutPass    — module imports 20+ other modules (architecture smell)
+ *  21. StaleDocRefPass         — doc comment references unknown symbol (CWE: none)
+ *  22. InfiniteLoopPass        — loops with no reachable exit edge (CWE-835)
+ *  23. DeepInheritancePass     — class inheritance depth > 5 (CWE-1086)
+ *  24. RedundantLoopPass       — loop-invariant .length/.size()/Math.* (CWE-1050)
+ *  25. UnboundedCollectionPass — collection grows in loop with no size limit (CWE-770)
+ *  26. SerialAwaitPass         — independent sequential awaits in JS/TS (performance)
+ *  27. ReactInlineJsxPass      — inline objects/functions in JSX props (performance)
  */
-import type { CircleIR, AnalysisResponse } from './types/index.js';
+import type { CircleIR, AnalysisResponse, ProjectAnalysis } from './types/index.js';
 import type { TaintConfig } from './types/config.js';
 import { type SupportedLanguage } from './core/index.js';
+import { isFalsePositive } from './analysis/index.js';
 export interface AnalyzerOptions {
     /**
      * Path to tree-sitter.wasm for parser initialization.
@@ -51,3 +81,20 @@ export declare function isAnalyzerInitialized(): boolean;
  * Reset the analyzer (mainly for testing).
  */
 export declare function resetAnalyzer(): void;
+/**
+ * Analyze a set of files as a project, finding cross-file taint flows.
+ *
+ * Runs single-file `analyze()` on each file in order, then uses
+ * `ProjectGraph` + `CrossFileResolver` to surface flows that cross file
+ * boundaries.  The per-file `CircleIR` outputs are preserved unchanged in
+ * `ProjectAnalysis.files`.
+ *
+ * `findings` is always empty — it requires LLM enrichment which is out of
+ * scope for this library (see CLAUDE.md and SPEC.md section 11).
+ */
+export declare function analyzeProject(files: Array<{
+    code: string;
+    filePath: string;
+    language: SupportedLanguage;
+}>, options?: AnalyzerOptions): Promise<ProjectAnalysis>;
+export { isFalsePositive };