xploitscan-shared-rules 2.4.20 → 2.4.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,9 @@
1
+ export { IgnoreEntry, MAX_IGNORE_BYTES, MAX_IGNORE_LINES, MAX_SUPPRESSED_LIST, MAX_WARNING_CAP, NESTED_IGNORE_WARNING, RULE_ID_PATTERN, SUPPRESSION_REGEXES, ScanSuppressionMeta, SuppressionInfo, SuppressionWarning, applySuppressions, attachInlineSuppressed, attachScanSuppression, buildMarkerIndex, capWarnings, clampCount, countPass, isRootIgnorePath, isRuleScopedIgnoreLine, isUnscopedOverBroadLine, isWellFormedRuleId, markerCoversLine, maskStringLiterals, matchIgnore, parseIgnoreFile, parseIgnoreSources, parseMarkers, publicSuppressedRecord, readInlineSuppressed, readScanSuppression, suppressionSummary, warningForUpload, warningLine } from './suppression.cjs';
1
2
  import { ParseResult } from '@babel/parser';
2
3
  import { File, Node, CallExpression, ObjectExpression, BinaryExpression } from '@babel/types';
4
+ import { AiStatus, AiReason, AiSurface, PlanCause } from './ai-status-constants.cjs';
5
+ export { AI_REASONS, AI_STATUSES, AI_SURFACES, PLAN_CAUSES, WEBHOOK_EVENT_TYPES, WEBHOOK_REASONS } from './ai-status-constants.cjs';
6
+ import 'ignore';
3
7
 
4
8
  /**
5
9
  * Cross-file facts a rule cannot learn from the file it is scanning.
@@ -165,7 +169,7 @@ interface CustomRule {
165
169
  * before a scan can be saved without enough provenance to explain a changed
166
170
  * grade.
167
171
  */
168
- declare const SCANNER_VERSION = "2.4.20";
172
+ declare const SCANNER_VERSION = "2.4.22";
169
173
 
170
174
  /**
171
175
  * Line-oriented helpers shared by every rule. Pure string manipulation — no fs
@@ -242,7 +246,7 @@ declare function deduplicateFindings<T extends Finding>(findings: readonly T[]):
242
246
  * calling this directly from their match loop or by passing their results
243
247
  * through filterSilenced().
244
248
  */
245
- declare function isInlineSilenced(content: string, matchIndex: number, ruleId: string): boolean;
249
+ declare function isInlineSilenced(_content: string, _matchIndex: number, _ruleId: string): boolean;
246
250
  /**
247
251
  * Line-indexed variant. The entropy scanner walks the file line by line and
248
252
  * never computes character offsets, so making it reconstruct one just to call
@@ -1084,7 +1088,7 @@ declare function isInsideFixMessage(content: string, matchIndex: number): boolea
1084
1088
  * high/critical rules a per-site escape valve so users don't disable a whole
1085
1089
  * rule to suppress one reviewed-and-accepted finding.
1086
1090
  */
1087
- declare function filterSilenced(matches: RuleMatch[], content: string, ruleId: string): RuleMatch[];
1091
+ declare function filterSilenced(matches: RuleMatch[], _content: string, _ruleId: string): RuleMatch[];
1088
1092
  declare function findMatches(content: string, pattern: RegExp, rule: Omit<CustomRule, "check">, filePath: string, fixTemplate?: (match: RegExpExecArray) => string): RuleMatch[];
1089
1093
  /**
1090
1094
  * findMatches for a matcher that is not a single RegExp — one a regex can
@@ -1287,6 +1291,84 @@ declare const PRO_RULE_COUNT = 193;
1287
1291
  /** The full catalog. FREE_RULE_COUNT + PRO_RULE_COUNT, asserted in the test. */
1288
1292
  declare const TOTAL_RULE_COUNT = 223;
1289
1293
 
1294
+ /**
1295
+ * One AiDegraded value for every scan surface.
1296
+ * Surfaces import toAiDegraded / aiStatusLine / bucketFiles. They do not
1297
+ * write their own status sentence.
1298
+ *
1299
+ * CLI default budget (stated for the PR): 30_000 ms. The API keeps the
1300
+ * serverless default of 8_000 ms. Per-call timeout is
1301
+ * min(PER_CALL_TIMEOUT_MS, floor(budget * 0.6)) and is always strictly
1302
+ * below the budget (see ai-fp-filter.ts).
1303
+ *
1304
+ * Migration 0064 is forward-only: migrate.ts has no down step. Re-adding
1305
+ * the column is a no-op via the existing duplicate-column tolerance.
1306
+ * NULL ai_status_json reads as { status: "unknown", reason: null }.
1307
+ */
1308
+
1309
+ interface AiDegraded {
1310
+ status: AiStatus;
1311
+ reason: AiReason | null;
1312
+ surface: AiSurface;
1313
+ total: number;
1314
+ reviewed: number;
1315
+ unreviewed: number;
1316
+ capped: number;
1317
+ /** Set only for reason model_error, so 429 / 529 / 500 stay distinct. */
1318
+ modelStatus: number | null;
1319
+ }
1320
+ /** Visible copy when a paid plan was expected and could not be verified. */
1321
+ declare const PLAN_UNVERIFIED_NOTICE = "Couldn't verify your plan, scanned with free rules only.";
1322
+ declare const FILE_BUCKETS: readonly ["0", "1-4", "5-19", "20+"];
1323
+ type FileBucket = (typeof FILE_BUCKETS)[number];
1324
+ declare function bucketFiles(n: unknown): FileBucket;
1325
+ /**
1326
+ * Collapse a specific verifier/download failure onto the stored cause enum.
1327
+ * The specific name stays on rulesStatus.specific for the per-cause tests.
1328
+ */
1329
+ declare function planCause(specific: string): PlanCause;
1330
+ interface ToAiDegradedInput {
1331
+ status?: unknown;
1332
+ reason?: unknown;
1333
+ surface?: unknown;
1334
+ total?: unknown;
1335
+ reviewed?: unknown;
1336
+ unreviewed?: unknown;
1337
+ capped?: unknown;
1338
+ modelStatus?: unknown;
1339
+ }
1340
+ /** Build a status object. reviewed + unreviewed + capped === total always. */
1341
+ declare function toAiDegraded(input?: ToAiDegradedInput): AiDegraded;
1342
+ /** NULL stored JSON and a missing field both read as unknown. */
1343
+ declare function unknownAiStatus(surface?: AiSurface): AiDegraded;
1344
+ /** The one plain sentence every surface prints. */
1345
+ declare function aiStatusLine(d: AiDegraded): string;
1346
+ /** Event props for scan_ai_degraded. Exact key set, nothing else. */
1347
+ declare const SCAN_AI_DEGRADED_KEYS: readonly ["status", "reason", "surface", "total", "reviewed", "capped", "files_received_bucket"];
1348
+ declare function scanAiDegradedProps(d: AiDegraded, filesReceived: unknown): Record<(typeof SCAN_AI_DEGRADED_KEYS)[number], string | number | null>;
1349
+ declare const SCAN_TOKEN_NULL_KEYS: readonly ["cause", "surface", "tier_expected"];
1350
+ declare function scanTokenNullProps(cause: PlanCause, surface: string): {
1351
+ cause: PlanCause;
1352
+ surface: string;
1353
+ tier_expected: "paid";
1354
+ };
1355
+ declare const BILLING_WEBHOOK_UNMATCHED_KEYS: readonly ["type", "reason", "final"];
1356
+ declare function billingWebhookUnmatchedProps(input: {
1357
+ type?: unknown;
1358
+ reason?: unknown;
1359
+ final?: unknown;
1360
+ }): {
1361
+ type: string;
1362
+ reason: string;
1363
+ final: boolean;
1364
+ };
1365
+
1366
+ /**
1367
+ * Per-call timeout is strictly below the overall budget for the default
1368
+ * (8000) and every legal clamp (1..60000). floor(budget * 0.6) is at most
1369
+ * budget - 1 when budget >= 1, and the 8000 cap is below any budget above it.
1370
+ */
1371
+ declare function perCallTimeoutMs(budgetMs: number): number;
1290
1372
  interface FilteredFinding {
1291
1373
  finding: Finding;
1292
1374
  reason: string;
@@ -1328,6 +1410,8 @@ interface AIFilterResult {
1328
1410
  timedOut: boolean;
1329
1411
  /** #945 proof. Logged by the API as the fixed-shape ai_fp_mask line only. */
1330
1412
  maskStats: MaskStats;
1413
+ /** Present on every return, including the early exits. */
1414
+ aiDegraded: AiDegraded;
1331
1415
  }
1332
1416
  /**
1333
1417
  * Findings the AI must never delete. Criticals and live/Secrets stay reported
@@ -1355,7 +1439,9 @@ declare function packReviewBatches(fileFindings: Finding[], content: string): Fi
1355
1439
  * @param budgetMs - Overall deadline (milliseconds). When expired, return
1356
1440
  * unreviewed findings with aiReviewed: false. Defaults to AI_FILTER_BUDGET_MS.
1357
1441
  */
1358
- declare function filterFalsePositives(findings: Finding[], fileContents: Map<string, string>, budgetMs?: number): Promise<AIFilterResult>;
1442
+ declare function filterFalsePositives(findings: Finding[], fileContents: Map<string, string>, budgetMs?: number, options?: {
1443
+ surface?: AiSurface;
1444
+ }): Promise<AIFilterResult>;
1359
1445
 
1360
1446
  /**
1361
1447
  * Shannon-entropy based secret detection.
@@ -1738,4 +1824,4 @@ input: {
1738
1824
  content: string;
1739
1825
  }[] | QualityContext, rules?: QualityRule[]): Finding[];
1740
1826
 
1741
- export { type AIFilterResult, type AppRoute, type BuilderFingerprint, CHECKABLE_CLAIMS, type Confidence, type CustomRule, DOTENV_ASSIGN_RE, type DetectedFramework, type ExposedConfig, type Exposure, FREE_RULE_COUNT, type FilteredFinding, type Finding, GRADE_FINDINGS_PER_RULE, type GradeOptions, type GradeResult, type HeaderFinding, INTENT_EXPECTATIONS, type IntentExpectation, type IntentMismatch, type IntentOrigin, type IntentReport, type IntentStatement, MODEL_ANALYSIS, MODEL_POLICY_REVIEWED, MODEL_REVIEW_INTERVAL_DAYS, MODEL_TEMPERATURE, MODEL_TRIAGE, NON_APP_PATH_PATTERNS, PRO_RULE_COUNT, PUBLIC_ENV_PREFIX_RE, type ParsedFile, type ProjectContext, QUALITY_EXAMPLES, type QualityContext, type QualityExample, type QualityFile, type QualityHit, type QualityRule, RULE_IMPACTS, type RouteFramework, type RouteTable, type RuleMatch, SCANNER_VERSION, SERVER_ACTION_WRITE_RE, type SecurityGrade, type Severity, TEST_FILE_PATTERN, TOTAL_RULE_COUNT, type TaintMap, type TargetCheck, type VibePlatform, allRules, assessHeaders, astMatch, buildProjectContext, buildQualityContext, buildReviewPrompt, buildTaintMap, calculateGrade, callSpreads, checkIntent, classifyExposure, classifyPublicEnvVar, classifyStatement, clientSideAuth, complianceMap, consoleLogProduction, corsWildcard, dangerousInnerHTML, deduplicateFindings, detectBuilder, detectExposedConfig, detectFramework, detectPlatform, disabledTLSVerification, dotenvValue, emptyCatchBlock, enclosingHandler, envNotGitignored, evalUsage, exposedAuthSecret, exposedDebugMode, exposedEnvFile, exposedStackTraces, extractRoutes, extractScriptUrls, filterFalsePositives, filterSilenced, findMatches, findMatchesAt, findSourceMapRefs, freeRules, getObjectProperty, getSnippet, gradeRuleFamily, hardcodedJWTSecret, hardcodedSecretValues, hardcodedSecrets, harvestIntent, insecureCookies, insecureRandomness, isCalleeNamed, isClientTarget, isCommentLine, isDotenvPath, isInlineSilenced, isInsideFixMessage, isLineSilenced, isLive, isMethodCall, isPrivateAddress, isProtectedFromAiRemoval, isSbomPath, isServerSideFile, isServerTarget, isTestFile, isTestPath, isUngradedFinding, isVendoredFinding, isVendoredPath, lineNumberAt, lineTextAt, maskComments, maskOutboundAuthNoise, maskSecretValue, missingAuthMiddleware, missingCSP, missingErrorBoundary, missingHTTPS, missingLockFile, newDataFence, nextPublicSecret, noRateLimiting, normalizeScanPath, packReviewBatches, parseFile, parseScanTarget, parseSupabaseConfig, qualityRules, replaceBlockComments, routeForFile, runCustomRules, scanConfigs, scanDependencies, scanEntropy, scanMultiFile, scanQuality, sqlInjection, stripeWebhookUnprotected, supabaseFunctionName, supabaseNoRLS, todoLeftInCode, tryParse, unmeasuredQualityRules, unvalidatedRedirect, vc001TestFixtureSeverity, vendoredReason, visitBinary, visitCalls, weakHashing, xssVulnerability };
1827
+ export { type AIFilterResult, type AiDegraded, AiReason, AiStatus, AiSurface, type AppRoute, BILLING_WEBHOOK_UNMATCHED_KEYS, type BuilderFingerprint, CHECKABLE_CLAIMS, type Confidence, type CustomRule, DOTENV_ASSIGN_RE, type DetectedFramework, type ExposedConfig, type Exposure, FREE_RULE_COUNT, type FilteredFinding, type Finding, GRADE_FINDINGS_PER_RULE, type GradeOptions, type GradeResult, type HeaderFinding, INTENT_EXPECTATIONS, type IntentExpectation, type IntentMismatch, type IntentOrigin, type IntentReport, type IntentStatement, MODEL_ANALYSIS, MODEL_POLICY_REVIEWED, MODEL_REVIEW_INTERVAL_DAYS, MODEL_TEMPERATURE, MODEL_TRIAGE, NON_APP_PATH_PATTERNS, PLAN_UNVERIFIED_NOTICE, PRO_RULE_COUNT, PUBLIC_ENV_PREFIX_RE, type ParsedFile, PlanCause, type ProjectContext, QUALITY_EXAMPLES, type QualityContext, type QualityExample, type QualityFile, type QualityHit, type QualityRule, RULE_IMPACTS, type RouteFramework, type RouteTable, type RuleMatch, SCANNER_VERSION, SCAN_AI_DEGRADED_KEYS, SCAN_TOKEN_NULL_KEYS, SERVER_ACTION_WRITE_RE, type SecurityGrade, type Severity, TEST_FILE_PATTERN, TOTAL_RULE_COUNT, type TaintMap, type TargetCheck, type VibePlatform, aiStatusLine, allRules, assessHeaders, astMatch, billingWebhookUnmatchedProps, bucketFiles, buildProjectContext, buildQualityContext, buildReviewPrompt, buildTaintMap, calculateGrade, callSpreads, checkIntent, classifyExposure, classifyPublicEnvVar, classifyStatement, clientSideAuth, complianceMap, consoleLogProduction, corsWildcard, dangerousInnerHTML, deduplicateFindings, detectBuilder, detectExposedConfig, detectFramework, detectPlatform, disabledTLSVerification, dotenvValue, emptyCatchBlock, enclosingHandler, envNotGitignored, evalUsage, exposedAuthSecret, exposedDebugMode, exposedEnvFile, exposedStackTraces, extractRoutes, extractScriptUrls, filterFalsePositives, filterSilenced, findMatches, findMatchesAt, findSourceMapRefs, freeRules, getObjectProperty, getSnippet, gradeRuleFamily, hardcodedJWTSecret, hardcodedSecretValues, hardcodedSecrets, harvestIntent, insecureCookies, insecureRandomness, isCalleeNamed, isClientTarget, isCommentLine, isDotenvPath, isInlineSilenced, isInsideFixMessage, isLineSilenced, isLive, isMethodCall, isPrivateAddress, isProtectedFromAiRemoval, isSbomPath, isServerSideFile, isServerTarget, isTestFile, isTestPath, isUngradedFinding, isVendoredFinding, isVendoredPath, lineNumberAt, lineTextAt, maskComments, maskOutboundAuthNoise, maskSecretValue, missingAuthMiddleware, missingCSP, missingErrorBoundary, missingHTTPS, missingLockFile, newDataFence, nextPublicSecret, noRateLimiting, normalizeScanPath, packReviewBatches, parseFile, parseScanTarget, parseSupabaseConfig, perCallTimeoutMs, planCause, qualityRules, replaceBlockComments, routeForFile, runCustomRules, scanAiDegradedProps, scanConfigs, scanDependencies, scanEntropy, scanMultiFile, scanQuality, scanTokenNullProps, sqlInjection, stripeWebhookUnprotected, supabaseFunctionName, supabaseNoRLS, toAiDegraded, todoLeftInCode, tryParse, unknownAiStatus, unmeasuredQualityRules, unvalidatedRedirect, vc001TestFixtureSeverity, vendoredReason, visitBinary, visitCalls, weakHashing, xssVulnerability };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,9 @@
1
+ export { IgnoreEntry, MAX_IGNORE_BYTES, MAX_IGNORE_LINES, MAX_SUPPRESSED_LIST, MAX_WARNING_CAP, NESTED_IGNORE_WARNING, RULE_ID_PATTERN, SUPPRESSION_REGEXES, ScanSuppressionMeta, SuppressionInfo, SuppressionWarning, applySuppressions, attachInlineSuppressed, attachScanSuppression, buildMarkerIndex, capWarnings, clampCount, countPass, isRootIgnorePath, isRuleScopedIgnoreLine, isUnscopedOverBroadLine, isWellFormedRuleId, markerCoversLine, maskStringLiterals, matchIgnore, parseIgnoreFile, parseIgnoreSources, parseMarkers, publicSuppressedRecord, readInlineSuppressed, readScanSuppression, suppressionSummary, warningForUpload, warningLine } from './suppression.js';
1
2
  import { ParseResult } from '@babel/parser';
2
3
  import { File, Node, CallExpression, ObjectExpression, BinaryExpression } from '@babel/types';
4
+ import { AiStatus, AiReason, AiSurface, PlanCause } from './ai-status-constants.js';
5
+ export { AI_REASONS, AI_STATUSES, AI_SURFACES, PLAN_CAUSES, WEBHOOK_EVENT_TYPES, WEBHOOK_REASONS } from './ai-status-constants.js';
6
+ import 'ignore';
3
7
 
4
8
  /**
5
9
  * Cross-file facts a rule cannot learn from the file it is scanning.
@@ -165,7 +169,7 @@ interface CustomRule {
165
169
  * before a scan can be saved without enough provenance to explain a changed
166
170
  * grade.
167
171
  */
168
- declare const SCANNER_VERSION = "2.4.20";
172
+ declare const SCANNER_VERSION = "2.4.22";
169
173
 
170
174
  /**
171
175
  * Line-oriented helpers shared by every rule. Pure string manipulation — no fs
@@ -242,7 +246,7 @@ declare function deduplicateFindings<T extends Finding>(findings: readonly T[]):
242
246
  * calling this directly from their match loop or by passing their results
243
247
  * through filterSilenced().
244
248
  */
245
- declare function isInlineSilenced(content: string, matchIndex: number, ruleId: string): boolean;
249
+ declare function isInlineSilenced(_content: string, _matchIndex: number, _ruleId: string): boolean;
246
250
  /**
247
251
  * Line-indexed variant. The entropy scanner walks the file line by line and
248
252
  * never computes character offsets, so making it reconstruct one just to call
@@ -1084,7 +1088,7 @@ declare function isInsideFixMessage(content: string, matchIndex: number): boolea
1084
1088
  * high/critical rules a per-site escape valve so users don't disable a whole
1085
1089
  * rule to suppress one reviewed-and-accepted finding.
1086
1090
  */
1087
- declare function filterSilenced(matches: RuleMatch[], content: string, ruleId: string): RuleMatch[];
1091
+ declare function filterSilenced(matches: RuleMatch[], _content: string, _ruleId: string): RuleMatch[];
1088
1092
  declare function findMatches(content: string, pattern: RegExp, rule: Omit<CustomRule, "check">, filePath: string, fixTemplate?: (match: RegExpExecArray) => string): RuleMatch[];
1089
1093
  /**
1090
1094
  * findMatches for a matcher that is not a single RegExp — one a regex can
@@ -1287,6 +1291,84 @@ declare const PRO_RULE_COUNT = 193;
1287
1291
  /** The full catalog. FREE_RULE_COUNT + PRO_RULE_COUNT, asserted in the test. */
1288
1292
  declare const TOTAL_RULE_COUNT = 223;
1289
1293
 
1294
+ /**
1295
+ * One AiDegraded value for every scan surface.
1296
+ * Surfaces import toAiDegraded / aiStatusLine / bucketFiles. They do not
1297
+ * write their own status sentence.
1298
+ *
1299
+ * CLI default budget (stated for the PR): 30_000 ms. The API keeps the
1300
+ * serverless default of 8_000 ms. Per-call timeout is
1301
+ * min(PER_CALL_TIMEOUT_MS, floor(budget * 0.6)) and is always strictly
1302
+ * below the budget (see ai-fp-filter.ts).
1303
+ *
1304
+ * Migration 0064 is forward-only: migrate.ts has no down step. Re-adding
1305
+ * the column is a no-op via the existing duplicate-column tolerance.
1306
+ * NULL ai_status_json reads as { status: "unknown", reason: null }.
1307
+ */
1308
+
1309
+ interface AiDegraded {
1310
+ status: AiStatus;
1311
+ reason: AiReason | null;
1312
+ surface: AiSurface;
1313
+ total: number;
1314
+ reviewed: number;
1315
+ unreviewed: number;
1316
+ capped: number;
1317
+ /** Set only for reason model_error, so 429 / 529 / 500 stay distinct. */
1318
+ modelStatus: number | null;
1319
+ }
1320
+ /** Visible copy when a paid plan was expected and could not be verified. */
1321
+ declare const PLAN_UNVERIFIED_NOTICE = "Couldn't verify your plan, scanned with free rules only.";
1322
+ declare const FILE_BUCKETS: readonly ["0", "1-4", "5-19", "20+"];
1323
+ type FileBucket = (typeof FILE_BUCKETS)[number];
1324
+ declare function bucketFiles(n: unknown): FileBucket;
1325
+ /**
1326
+ * Collapse a specific verifier/download failure onto the stored cause enum.
1327
+ * The specific name stays on rulesStatus.specific for the per-cause tests.
1328
+ */
1329
+ declare function planCause(specific: string): PlanCause;
1330
+ interface ToAiDegradedInput {
1331
+ status?: unknown;
1332
+ reason?: unknown;
1333
+ surface?: unknown;
1334
+ total?: unknown;
1335
+ reviewed?: unknown;
1336
+ unreviewed?: unknown;
1337
+ capped?: unknown;
1338
+ modelStatus?: unknown;
1339
+ }
1340
+ /** Build a status object. reviewed + unreviewed + capped === total always. */
1341
+ declare function toAiDegraded(input?: ToAiDegradedInput): AiDegraded;
1342
+ /** NULL stored JSON and a missing field both read as unknown. */
1343
+ declare function unknownAiStatus(surface?: AiSurface): AiDegraded;
1344
+ /** The one plain sentence every surface prints. */
1345
+ declare function aiStatusLine(d: AiDegraded): string;
1346
+ /** Event props for scan_ai_degraded. Exact key set, nothing else. */
1347
+ declare const SCAN_AI_DEGRADED_KEYS: readonly ["status", "reason", "surface", "total", "reviewed", "capped", "files_received_bucket"];
1348
+ declare function scanAiDegradedProps(d: AiDegraded, filesReceived: unknown): Record<(typeof SCAN_AI_DEGRADED_KEYS)[number], string | number | null>;
1349
+ declare const SCAN_TOKEN_NULL_KEYS: readonly ["cause", "surface", "tier_expected"];
1350
+ declare function scanTokenNullProps(cause: PlanCause, surface: string): {
1351
+ cause: PlanCause;
1352
+ surface: string;
1353
+ tier_expected: "paid";
1354
+ };
1355
+ declare const BILLING_WEBHOOK_UNMATCHED_KEYS: readonly ["type", "reason", "final"];
1356
+ declare function billingWebhookUnmatchedProps(input: {
1357
+ type?: unknown;
1358
+ reason?: unknown;
1359
+ final?: unknown;
1360
+ }): {
1361
+ type: string;
1362
+ reason: string;
1363
+ final: boolean;
1364
+ };
1365
+
1366
+ /**
1367
+ * Per-call timeout is strictly below the overall budget for the default
1368
+ * (8000) and every legal clamp (1..60000). floor(budget * 0.6) is at most
1369
+ * budget - 1 when budget >= 1, and the 8000 cap is below any budget above it.
1370
+ */
1371
+ declare function perCallTimeoutMs(budgetMs: number): number;
1290
1372
  interface FilteredFinding {
1291
1373
  finding: Finding;
1292
1374
  reason: string;
@@ -1328,6 +1410,8 @@ interface AIFilterResult {
1328
1410
  timedOut: boolean;
1329
1411
  /** #945 proof. Logged by the API as the fixed-shape ai_fp_mask line only. */
1330
1412
  maskStats: MaskStats;
1413
+ /** Present on every return, including the early exits. */
1414
+ aiDegraded: AiDegraded;
1331
1415
  }
1332
1416
  /**
1333
1417
  * Findings the AI must never delete. Criticals and live/Secrets stay reported
@@ -1355,7 +1439,9 @@ declare function packReviewBatches(fileFindings: Finding[], content: string): Fi
1355
1439
  * @param budgetMs - Overall deadline (milliseconds). When expired, return
1356
1440
  * unreviewed findings with aiReviewed: false. Defaults to AI_FILTER_BUDGET_MS.
1357
1441
  */
1358
- declare function filterFalsePositives(findings: Finding[], fileContents: Map<string, string>, budgetMs?: number): Promise<AIFilterResult>;
1442
+ declare function filterFalsePositives(findings: Finding[], fileContents: Map<string, string>, budgetMs?: number, options?: {
1443
+ surface?: AiSurface;
1444
+ }): Promise<AIFilterResult>;
1359
1445
 
1360
1446
  /**
1361
1447
  * Shannon-entropy based secret detection.
@@ -1738,4 +1824,4 @@ input: {
1738
1824
  content: string;
1739
1825
  }[] | QualityContext, rules?: QualityRule[]): Finding[];
1740
1826
 
1741
- export { type AIFilterResult, type AppRoute, type BuilderFingerprint, CHECKABLE_CLAIMS, type Confidence, type CustomRule, DOTENV_ASSIGN_RE, type DetectedFramework, type ExposedConfig, type Exposure, FREE_RULE_COUNT, type FilteredFinding, type Finding, GRADE_FINDINGS_PER_RULE, type GradeOptions, type GradeResult, type HeaderFinding, INTENT_EXPECTATIONS, type IntentExpectation, type IntentMismatch, type IntentOrigin, type IntentReport, type IntentStatement, MODEL_ANALYSIS, MODEL_POLICY_REVIEWED, MODEL_REVIEW_INTERVAL_DAYS, MODEL_TEMPERATURE, MODEL_TRIAGE, NON_APP_PATH_PATTERNS, PRO_RULE_COUNT, PUBLIC_ENV_PREFIX_RE, type ParsedFile, type ProjectContext, QUALITY_EXAMPLES, type QualityContext, type QualityExample, type QualityFile, type QualityHit, type QualityRule, RULE_IMPACTS, type RouteFramework, type RouteTable, type RuleMatch, SCANNER_VERSION, SERVER_ACTION_WRITE_RE, type SecurityGrade, type Severity, TEST_FILE_PATTERN, TOTAL_RULE_COUNT, type TaintMap, type TargetCheck, type VibePlatform, allRules, assessHeaders, astMatch, buildProjectContext, buildQualityContext, buildReviewPrompt, buildTaintMap, calculateGrade, callSpreads, checkIntent, classifyExposure, classifyPublicEnvVar, classifyStatement, clientSideAuth, complianceMap, consoleLogProduction, corsWildcard, dangerousInnerHTML, deduplicateFindings, detectBuilder, detectExposedConfig, detectFramework, detectPlatform, disabledTLSVerification, dotenvValue, emptyCatchBlock, enclosingHandler, envNotGitignored, evalUsage, exposedAuthSecret, exposedDebugMode, exposedEnvFile, exposedStackTraces, extractRoutes, extractScriptUrls, filterFalsePositives, filterSilenced, findMatches, findMatchesAt, findSourceMapRefs, freeRules, getObjectProperty, getSnippet, gradeRuleFamily, hardcodedJWTSecret, hardcodedSecretValues, hardcodedSecrets, harvestIntent, insecureCookies, insecureRandomness, isCalleeNamed, isClientTarget, isCommentLine, isDotenvPath, isInlineSilenced, isInsideFixMessage, isLineSilenced, isLive, isMethodCall, isPrivateAddress, isProtectedFromAiRemoval, isSbomPath, isServerSideFile, isServerTarget, isTestFile, isTestPath, isUngradedFinding, isVendoredFinding, isVendoredPath, lineNumberAt, lineTextAt, maskComments, maskOutboundAuthNoise, maskSecretValue, missingAuthMiddleware, missingCSP, missingErrorBoundary, missingHTTPS, missingLockFile, newDataFence, nextPublicSecret, noRateLimiting, normalizeScanPath, packReviewBatches, parseFile, parseScanTarget, parseSupabaseConfig, qualityRules, replaceBlockComments, routeForFile, runCustomRules, scanConfigs, scanDependencies, scanEntropy, scanMultiFile, scanQuality, sqlInjection, stripeWebhookUnprotected, supabaseFunctionName, supabaseNoRLS, todoLeftInCode, tryParse, unmeasuredQualityRules, unvalidatedRedirect, vc001TestFixtureSeverity, vendoredReason, visitBinary, visitCalls, weakHashing, xssVulnerability };
1827
+ export { type AIFilterResult, type AiDegraded, AiReason, AiStatus, AiSurface, type AppRoute, BILLING_WEBHOOK_UNMATCHED_KEYS, type BuilderFingerprint, CHECKABLE_CLAIMS, type Confidence, type CustomRule, DOTENV_ASSIGN_RE, type DetectedFramework, type ExposedConfig, type Exposure, FREE_RULE_COUNT, type FilteredFinding, type Finding, GRADE_FINDINGS_PER_RULE, type GradeOptions, type GradeResult, type HeaderFinding, INTENT_EXPECTATIONS, type IntentExpectation, type IntentMismatch, type IntentOrigin, type IntentReport, type IntentStatement, MODEL_ANALYSIS, MODEL_POLICY_REVIEWED, MODEL_REVIEW_INTERVAL_DAYS, MODEL_TEMPERATURE, MODEL_TRIAGE, NON_APP_PATH_PATTERNS, PLAN_UNVERIFIED_NOTICE, PRO_RULE_COUNT, PUBLIC_ENV_PREFIX_RE, type ParsedFile, PlanCause, type ProjectContext, QUALITY_EXAMPLES, type QualityContext, type QualityExample, type QualityFile, type QualityHit, type QualityRule, RULE_IMPACTS, type RouteFramework, type RouteTable, type RuleMatch, SCANNER_VERSION, SCAN_AI_DEGRADED_KEYS, SCAN_TOKEN_NULL_KEYS, SERVER_ACTION_WRITE_RE, type SecurityGrade, type Severity, TEST_FILE_PATTERN, TOTAL_RULE_COUNT, type TaintMap, type TargetCheck, type VibePlatform, aiStatusLine, allRules, assessHeaders, astMatch, billingWebhookUnmatchedProps, bucketFiles, buildProjectContext, buildQualityContext, buildReviewPrompt, buildTaintMap, calculateGrade, callSpreads, checkIntent, classifyExposure, classifyPublicEnvVar, classifyStatement, clientSideAuth, complianceMap, consoleLogProduction, corsWildcard, dangerousInnerHTML, deduplicateFindings, detectBuilder, detectExposedConfig, detectFramework, detectPlatform, disabledTLSVerification, dotenvValue, emptyCatchBlock, enclosingHandler, envNotGitignored, evalUsage, exposedAuthSecret, exposedDebugMode, exposedEnvFile, exposedStackTraces, extractRoutes, extractScriptUrls, filterFalsePositives, filterSilenced, findMatches, findMatchesAt, findSourceMapRefs, freeRules, getObjectProperty, getSnippet, gradeRuleFamily, hardcodedJWTSecret, hardcodedSecretValues, hardcodedSecrets, harvestIntent, insecureCookies, insecureRandomness, isCalleeNamed, isClientTarget, isCommentLine, isDotenvPath, isInlineSilenced, isInsideFixMessage, isLineSilenced, isLive, isMethodCall, isPrivateAddress, isProtectedFromAiRemoval, isSbomPath, isServerSideFile, isServerTarget, isTestFile, isTestPath, isUngradedFinding, isVendoredFinding, isVendoredPath, lineNumberAt, lineTextAt, maskComments, maskOutboundAuthNoise, maskSecretValue, missingAuthMiddleware, missingCSP, missingErrorBoundary, missingHTTPS, missingLockFile, newDataFence, nextPublicSecret, noRateLimiting, normalizeScanPath, packReviewBatches, parseFile, parseScanTarget, parseSupabaseConfig, perCallTimeoutMs, planCause, qualityRules, replaceBlockComments, routeForFile, runCustomRules, scanAiDegradedProps, scanConfigs, scanDependencies, scanEntropy, scanMultiFile, scanQuality, scanTokenNullProps, sqlInjection, stripeWebhookUnprotected, supabaseFunctionName, supabaseNoRLS, toAiDegraded, todoLeftInCode, tryParse, unknownAiStatus, unmeasuredQualityRules, unvalidatedRedirect, vc001TestFixtureSeverity, vendoredReason, visitBinary, visitCalls, weakHashing, xssVulnerability };