sourceverity 1.0.2 → 1.0.4

package/README.md

@@ -65,8 +65,56 @@ npx sourceverity scan . --format agent
 npx sourceverity scan . --format sarif
 ```
 
+
+### Confidence and CI Policy
+
+Severity describes the impact if a finding is real. Confidence describes how strongly SourceVerity can establish the condition from source and type information.
+
+| Confidence | Meaning |
+| ---------- | ------- |
+| High | A resolved API, type, or local control-flow proof establishes the condition. |
+| Medium | The operation is unconsumed or potentially risky, but an implementation or rejection path cannot be proven. |
+| Low | Evidence is incomplete. Use this level for review, not as a CI gate. |
+
+`--min-confidence` filters findings before output and baseline comparison. Its default is `medium`. `--fail-on` controls the process result independently: `error` is the default, `warning` fails on either warnings or errors, and `never` always exits successfully.
+
+For CI, begin with high-confidence findings:
+
+```bash
+npx sourceverity scan . --min-confidence high --fail-on error
+```
+
+### Configuration
+
+`--config` accepts a JSON file for `scan` and `baseline` commands. The path is resolved from the current working directory. Configuration is data-only; unknown fields and invalid values are rejected.
+
+```json
+{
+  "ignore": [
+    "generated/**",
+    "vendor/**"
+  ]
+}
+```
+
+`ignore` contains repository-relative ignore patterns. These patterns are applied in addition to SourceVerity's built-in ignores and the target repository's root `.gitignore`.
+
+```bash
+npx sourceverity scan . --config sourceverity.json
+npx sourceverity baseline create . --config sourceverity.json
+```
+
+### Diagnostic Compatibility
+
+Rule IDs are stable baseline and suppression keys. A rule ID changes only for an intentional breaking change.
+
+Finding fingerprints are stability-sensitive. A behavior-preserving refactor must not change them; a semantic change may change them when the reported source identity or proof changes. Severity and confidence changes require regression coverage because they can alter CI behavior.
+
+JSON, agent, and SARIF outputs are machine interfaces. New fields may be added, but existing schema fields retain their meaning within a major version.
+
 ---
 
+
 ## Using SourceVerity with Coding Agents
 
 SourceVerity's `agent` format provides structured, deterministic diagnostics optimized for coding assistants like Codex.
@@ -122,8 +170,8 @@ When adopting SourceVerity on an existing codebase with existing findings, gener
 # Create or update baseline
 npx sourceverity baseline create
 
-# Run scan checking only new findings against baseline
-npx sourceverity scan . --baseline
+# Run a scan checking only findings absent from the baseline
+npx sourceverity baseline check .
 ```
 
 ---
@@ -139,7 +187,7 @@ const user = JSON.parse(payload) as User;
 
 ---
 
-## Initial Production Rule Set
+## Built-in Rule Set
 
 | Rule ID | Category | Default Severity | Confidence | Description |
 | ------- | -------- | ---------------- | ---------- | ----------- |
@@ -173,8 +221,48 @@ const result = await scanRepository({
 console.log(`Found ${result.findings.length} findings across ${result.summary.filesAnalyzed} files.`);
 ```
 
+
+## Limits and Safety
+
+SourceVerity is a static analyzer. It does not execute analyzed source, import target modules, run package scripts, or install dependencies. It uses the TypeScript installation supplied by the repository when one is available.
+
+Dynamic dispatch, external callbacks, reflection, runtime-generated values, and unavailable package implementations remain unknown. SourceVerity reports these paths as advisories when useful; it does not present them as compiler errors or proven runtime failures.
+
+Workspace discovery stays within the requested repository root, including after canonical path resolution. A workspace declaration cannot expand the scan into a parent or symlinked external directory.
+
+## CI, Verification, and Benchmarks
+
+The repository verification gate is:
+
+```bash
+npm run verify
+```
+
+It runs the strict typecheck, build, test suite, package validation, and clean-consumer smoke test.
+
+Measure semantic-audit scaling with:
+
+```bash
+npm run benchmark
+```
+
+The benchmark creates 100-, 1,000-, and 10,000-file TypeScript fixtures, performs one warmup scan, then reports five raw latency and RSS-delta samples per size with median and p95 latency. Override the workload when investigating a specific scale:
+
+```bash
+SOURCEVERITY_BENCHMARK_FILES=500,5000 SOURCEVERITY_BENCHMARK_SAMPLES=3 npm run benchmark
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup and the verification gate. Changes to semantic rules require representative true-positive, true-negative, and adversarial coverage.
+
+## Security
+
+Analyzed repositories are untrusted input. SourceVerity keeps scans read-only, validates data-only configuration strictly, sanitizes terminal-facing output, and avoids expanding workspace paths outside the requested root.
+
 ---
 
+
 ## Requirements & Engines
 
 - Node.js >= 20.12.0

package/dist/analysis/arrayBounds.d.ts

@@ -0,0 +1,4 @@
+export { isCompleteBoundsExitGuard, isFixedLengthGuardedIndex, isNodeDescendantOf, isParamBoundedCondition, isPositiveBoundsEntryGuard, isStaticArrayLiteralBoundedIndex, normalizeArrayTarget, normalizeIndexExpression, resolveStaticConstArrayLiteral, } from "./arrayBoundsCore.js";
+export { isFindIndexBoundedIndex, isLoopOrCallbackBoundedIndex, } from "./arrayIterationBounds.js";
+export { isConstructedArrayCardinalityBoundedIndex, isSearchProvenanceBoundedIndex, } from "./arrayConstructionBounds.js";
+//# sourceMappingURL=arrayBounds.d.ts.map

package/dist/analysis/arrayBounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayBounds.d.ts","sourceRoot":"","sources":["../../src/analysis/arrayBounds.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,gCAAgC,EAChC,oBAAoB,EACpB,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yCAAyC,EACzC,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC"}

package/dist/analysis/arrayBounds.js

@@ -0,0 +1,4 @@
+export { isCompleteBoundsExitGuard, isFixedLengthGuardedIndex, isNodeDescendantOf, isParamBoundedCondition, isPositiveBoundsEntryGuard, isStaticArrayLiteralBoundedIndex, normalizeArrayTarget, normalizeIndexExpression, resolveStaticConstArrayLiteral, } from "./arrayBoundsCore.js";
+export { isFindIndexBoundedIndex, isLoopOrCallbackBoundedIndex, } from "./arrayIterationBounds.js";
+export { isConstructedArrayCardinalityBoundedIndex, isSearchProvenanceBoundedIndex, } from "./arrayConstructionBounds.js";
+//# sourceMappingURL=arrayBounds.js.map

package/dist/analysis/arrayBounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayBounds.js","sourceRoot":"","sources":["../../src/analysis/arrayBounds.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,gCAAgC,EAChC,oBAAoB,EACpB,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yCAAyC,EACzC,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC"}

package/dist/analysis/arrayBoundsCore.d.ts

@@ -0,0 +1,69 @@
+import type * as tsType from "typescript";
+import type { GuardCheckResult } from "./controlFlowTypes.js";
+declare function isParamBoundedCondition(cond: tsType.Expression, paramName: string, arrayLength: number, ts: typeof tsType, isExitGuard: boolean): boolean;
+/**
+ * Normalizes an index expression to an identifier base + integer offset.
+ * e.g. `idx` -> { baseText: "idx", offset: 0 }
+ * e.g. `idx + 1` -> { baseText: "idx", offset: 1 }
+ * e.g. `idx - 1` -> { baseText: "idx", offset: -1 }
+ */
+interface NormalizedIndex {
+    readonly baseText: string;
+    readonly baseSymbol?: tsType.Symbol | undefined;
+    readonly offset: number;
+}
+declare function normalizeIndexExpression(expr: tsType.Expression, ts: typeof tsType, checker?: tsType.TypeChecker | undefined): NormalizedIndex | undefined;
+/**
+ * Normalizes an array target expression (identifier or property access).
+ */
+interface NormalizedArray {
+    readonly text: string;
+    readonly symbol?: tsType.Symbol | undefined;
+}
+declare function arraysMatch(a: NormalizedArray | undefined, b: NormalizedArray | undefined): boolean;
+declare function isNodeDescendantOf(child: tsType.Node, parent: tsType.Node): boolean;
+declare function normalizeArrayTarget(expr: tsType.Expression, ts: typeof tsType, checker?: tsType.TypeChecker | undefined): NormalizedArray | undefined;
+/**
+ * Checks if a binary condition expression guards an index lower bound (e.g. index === -1 or index < 0).
+ */
+declare function isLowerBoundNegativeGuard(cond: tsType.Expression, indexInfo: NormalizedIndex, ts: typeof tsType): boolean;
+/**
+ * Checks if an expression represents `array.length` or `array.length - K`.
+ */
+declare function parseArrayLengthOffset(expr: tsType.Expression, arrayInfo: NormalizedArray | readonly NormalizedArray[], ts: typeof tsType, checker?: tsType.TypeChecker | undefined): number | undefined;
+/**
+ * Checks if an exit condition contains both a lower-bound check and an upper-bound check.
+ */
+declare function isCompleteBoundsExitGuard(cond: tsType.Expression, indexInfo: NormalizedIndex, arrayInfo: NormalizedArray, ts: typeof tsType): boolean;
+/**
+ * Checks if an entry condition contains both a lower-bound non-negative check and an upper-bound check against array.length.
+ * e.g. `if (i >= 0 && i < array.length - 1)`
+ */
+declare function isPositiveBoundsEntryGuard(cond: tsType.Expression, indexInfo: NormalizedIndex, arrayInfo: NormalizedArray, ts: typeof tsType): boolean;
+/**
+ * Checks if an array target is a static, non-empty const array initialized with an array literal.
+ */
+declare function resolveStaticConstArrayLiteral(arrayExpr: tsType.Expression, ts: typeof tsType, checker?: tsType.TypeChecker | undefined): {
+    elements: readonly tsType.Expression[];
+    length: number;
+    name: string;
+} | undefined;
+/**
+ * Checks if a static array access has a literal integer index guaranteed to be in-bounds.
+ */
+declare function isStaticArrayLiteralBoundedIndex(operand: tsType.ElementAccessExpression, ts: typeof tsType, checker?: tsType.TypeChecker | undefined): GuardCheckResult | undefined;
+/**
+ * Checks if a literal index access is proven in-bounds by a dominating fixed-length equality or comparison guard.
+ * e.g. `if (arr.length === 2) arr[0]!` or `if (arr.length >= 2) arr[1]!`
+ */
+declare function isFixedLengthGuardedIndex(node: tsType.NonNullExpression, operand: tsType.ElementAccessExpression, ts: typeof tsType, checker?: tsType.TypeChecker | undefined): GuardCheckResult | undefined;
+export { containsControlFlowExit, countUnconditionalPushes, hasArrayMutation, hasMutationBeforeNode, isLowerBoundNegativeGuard, arraysMatch, isCompleteBoundsExitGuard, isFixedLengthGuardedIndex, isNodeDescendantOf, isParamBoundedCondition, isPositiveBoundsEntryGuard, isStaticArrayLiteralBoundedIndex, normalizeArrayTarget, normalizeIndexExpression, resolveStaticConstArrayLiteral, parseArrayLengthOffset, };
+export type { NormalizedArray };
+/**
+ * Checks if a node or its subtrees contain mutating operations on the given array text/symbol.
+ */
+declare function hasArrayMutation(node: tsType.Node, arrayText: string, ts: typeof tsType, checker?: tsType.TypeChecker | undefined, arraySymbol?: tsType.Symbol | undefined): boolean;
+declare function containsControlFlowExit(body: tsType.Node, ts: typeof tsType): boolean;
+declare function countUnconditionalPushes(body: tsType.Node, arrayText: string, ts: typeof tsType, checker?: tsType.TypeChecker | undefined, arraySymbol?: tsType.Symbol | undefined): number;
+declare function hasMutationBeforeNode(statementNode: tsType.Node, targetNode: tsType.Node, arrayText: string, ts: typeof tsType, checker?: tsType.TypeChecker | undefined, arraySymbol?: tsType.Symbol | undefined): boolean;
+//# sourceMappingURL=arrayBoundsCore.d.ts.map

package/dist/analysis/arrayBoundsCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrayBoundsCore.d.ts","sourceRoot":"","sources":["../../src/analysis/arrayBoundsCore.ts"],"names":[],"mappings":"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"}