@netgreener/runtime 0.1.0

package/dist/analyze/memoryIoDetectors.js

@@ -0,0 +1,68 @@
+/**
+ * Heuristic JS/TS twins for memory / storage RD0 candidate_map rules:
+ *   - repeated_file_reads → repeated_work / storage.io
+ *   - full_dataset_in_memory → memory_retention_or_materialization / memory.host
+ */
+import { FILE_READ_RE, forEachSourceLine, stripLineComment, } from './heuristicScan.js';
+import { languageForPath, } from './resourceFindingCandidate.js';
+const DETECTOR_VERSION = '0.1.0';
+const JSON_PARSE_RE = /\bJSON\.parse\s*\(/;
+/**
+ * Python ``repeated_file_reads`` twin — fs read inside a loop.
+ */
+export function detectRepeatedFileReadHits(source, relPath) {
+    const hits = [];
+    const language = languageForPath(relPath);
+    const path = relPath.replace(/\\/g, '/');
+    forEachSourceLine(source, ({ line, lineNo, inLoop }) => {
+        if (!inLoop || !FILE_READ_RE.test(line))
+            return;
+        hits.push({
+            mechanism_id: 'repeated_work',
+            primary_domain: 'storage.io',
+            admission_domain: 'storage.io',
+            title: 'File read inside loop may repeat avoidable I/O work',
+            rel_path: path,
+            start_line: lineNo,
+            end_line: lineNo,
+            language,
+            detector_id: 'js.static.repeated_file_reads',
+            detector_version: DETECTOR_VERSION,
+            legacy_issue_type: 'repeated_file_reads',
+        });
+    });
+    return hits;
+}
+/**
+ * Python ``full_dataset_in_memory`` twin — load+parse entire file payload.
+ * Flags JSON.parse(readFile…) on one line, or readFile then JSON.parse within 2 lines.
+ */
+export function detectFullDatasetInMemoryHits(source, relPath) {
+    const hits = [];
+    const language = languageForPath(relPath);
+    const path = relPath.replace(/\\/g, '/');
+    const lines = source.split(/\r?\n/).map((l) => stripLineComment(l));
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const lineNo = i + 1;
+        const sameLine = JSON_PARSE_RE.test(line) && FILE_READ_RE.test(line);
+        const window = [lines[i + 1] ?? '', lines[i + 2] ?? ''].join('\n');
+        const readThenParse = FILE_READ_RE.test(line) && JSON_PARSE_RE.test(window);
+        if (!sameLine && !readThenParse)
+            continue;
+        hits.push({
+            mechanism_id: 'memory_retention_or_materialization',
+            primary_domain: 'memory.host',
+            admission_domain: 'memory.host',
+            title: 'Loading and parsing an entire file may retain a full dataset in memory',
+            rel_path: path,
+            start_line: lineNo,
+            end_line: lineNo,
+            language,
+            detector_id: 'js.static.full_dataset_in_memory',
+            detector_version: DETECTOR_VERSION,
+            legacy_issue_type: 'full_dataset_in_memory',
+        });
+    }
+    return hits;
+}

package/dist/analyze/preferAstDetectors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Prefer TypeScript AST for Analyze detectors; fall back to heuristics.
+ * Parses each source at most once via ``detectAllHitsAst``.
+ */
+import type { ResourceCandidateHit } from './resourceFindingCandidate.js';
+/** Collect all prefer-AST hits for one source file (single parse when TS available). */
+export declare function collectPreferAstHits(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectRetryAmplificationHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectRepeatedFileReadHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectApiOverconsumptionHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectUnboundedParallelismHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectPollingIdleHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectRepeatedWorkHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectProcessChurnHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectFullDatasetInMemoryHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectPerItemInsteadOfBatchHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectModelLoadInLoopHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];
+export declare function detectInferenceInsideLoopHitsPreferAst(source: string, relPath: string): ResourceCandidateHit[];

package/dist/analyze/preferAstDetectors.js

@@ -0,0 +1,91 @@
+/**
+ * Prefer TypeScript AST for Analyze detectors; fall back to heuristics.
+ * Parses each source at most once via ``detectAllHitsAst``.
+ */
+import { detectApiOverconsumptionHits } from './apiOverconsumptionDetector.js';
+import { detectAllHitsAst, } from './astDetectors.js';
+import { detectInferenceInsideLoopHits, detectModelLoadInLoopHits, detectPollingIdleHits, detectPerItemInsteadOfBatchHits, detectProcessChurnHits, detectRepeatedWorkHits, } from './cpuResourceDetectors.js';
+import { detectFullDatasetInMemoryHits, detectRepeatedFileReadHits, } from './memoryIoDetectors.js';
+import { detectRetryAmplificationHits } from './retryAmplificationDetector.js';
+import { detectUnboundedParallelismHits } from './unboundedParallelismDetector.js';
+function prefer(astHits, fallback) {
+    if (astHits !== null && astHits !== undefined)
+        return astHits;
+    return fallback();
+}
+/** Collect all prefer-AST hits for one source file (single parse when TS available). */
+export function collectPreferAstHits(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    if (bundle) {
+        return [
+            ...bundle.retry,
+            ...bundle.overconsumption,
+            ...bundle.unbounded,
+            ...bundle.polling,
+            ...bundle.repeatedWork,
+            ...bundle.processChurn,
+            ...bundle.modelLoad,
+            ...bundle.inference,
+            ...bundle.fileReads,
+            ...bundle.fullDataset,
+            ...bundle.perItem,
+        ];
+    }
+    return [
+        ...detectRetryAmplificationHits(source, relPath),
+        ...detectApiOverconsumptionHits(source, relPath),
+        ...detectUnboundedParallelismHits(source, relPath),
+        ...detectPollingIdleHits(source, relPath),
+        ...detectRepeatedWorkHits(source, relPath),
+        ...detectProcessChurnHits(source, relPath),
+        ...detectModelLoadInLoopHits(source, relPath),
+        ...detectInferenceInsideLoopHits(source, relPath),
+        ...detectRepeatedFileReadHits(source, relPath),
+        ...detectFullDatasetInMemoryHits(source, relPath),
+        ...detectPerItemInsteadOfBatchHits(source, relPath),
+    ];
+}
+export function detectRetryAmplificationHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.retry ?? null, () => detectRetryAmplificationHits(source, relPath));
+}
+export function detectRepeatedFileReadHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.fileReads ?? null, () => detectRepeatedFileReadHits(source, relPath));
+}
+export function detectApiOverconsumptionHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.overconsumption ?? null, () => detectApiOverconsumptionHits(source, relPath));
+}
+export function detectUnboundedParallelismHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.unbounded ?? null, () => detectUnboundedParallelismHits(source, relPath));
+}
+export function detectPollingIdleHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.polling ?? null, () => detectPollingIdleHits(source, relPath));
+}
+export function detectRepeatedWorkHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.repeatedWork ?? null, () => detectRepeatedWorkHits(source, relPath));
+}
+export function detectProcessChurnHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.processChurn ?? null, () => detectProcessChurnHits(source, relPath));
+}
+export function detectFullDatasetInMemoryHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.fullDataset ?? null, () => detectFullDatasetInMemoryHits(source, relPath));
+}
+export function detectPerItemInsteadOfBatchHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.perItem ?? null, () => detectPerItemInsteadOfBatchHits(source, relPath));
+}
+export function detectModelLoadInLoopHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.modelLoad ?? null, () => detectModelLoadInLoopHits(source, relPath));
+}
+export function detectInferenceInsideLoopHitsPreferAst(source, relPath) {
+    const bundle = detectAllHitsAst(source, relPath);
+    return prefer(bundle?.inference ?? null, () => detectInferenceInsideLoopHits(source, relPath));
+}

package/dist/analyze/projectScan.d.ts

@@ -0,0 +1,19 @@
+import { type ServiceManifestV0 } from './serviceDiscovery.js';
+export type ListCandidateSourceFilesOptions = {
+    /** Max files to return (default 200). */
+    maxFiles?: number;
+    /** Max bytes to read per file when building a manifest (default 512 KiB). */
+    maxFileBytes?: number;
+    extensions?: Iterable<string>;
+    skipDirNames?: Iterable<string>;
+};
+/**
+ * List repo-relative JS/TS source paths under ``projectDir`` (bounded).
+ * Never throws — returns [] on errors.
+ */
+export declare function listCandidateSourceFiles(projectDir: string, opts?: ListCandidateSourceFilesOptions): string[];
+/**
+ * Read supplied repo-relative paths (or auto-walk) and build ``service_manifest_v0``.
+ * Never throws — empty-but-shaped manifest on any error.
+ */
+export declare function buildServiceManifestFromPaths(projectDir: string, relPaths?: Iterable<string> | null, opts?: ListCandidateSourceFilesOptions): ServiceManifestV0;

package/dist/analyze/projectScan.js

@@ -0,0 +1,115 @@
+/**
+ * Bounded project walk for MP4 Analyze scaffold.
+ * Never touches RunSession upload. Skips node_modules / dist / .git by default.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { buildServiceManifest } from './serviceDiscovery.js';
+const DEFAULT_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
+const DEFAULT_SKIP_DIR_NAMES = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.git',
+    '.next',
+    '.turbo',
+    '.cache',
+    'out',
+]);
+function normalizeRel(path) {
+    return path.split(sep).join('/');
+}
+/**
+ * List repo-relative JS/TS source paths under ``projectDir`` (bounded).
+ * Never throws — returns [] on errors.
+ */
+export function listCandidateSourceFiles(projectDir, opts = {}) {
+    const maxFiles = Math.max(1, opts.maxFiles ?? 200);
+    const extensions = new Set([...(opts.extensions ?? DEFAULT_EXTENSIONS)].map((e) => e.toLowerCase()));
+    const skip = new Set([...(opts.skipDirNames ?? DEFAULT_SKIP_DIR_NAMES)].map((n) => n.toLowerCase()));
+    const out = [];
+    const walk = (absDir) => {
+        if (out.length >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= maxFiles)
+                return;
+            const name = entry.name;
+            if (name.startsWith('.') && name !== '.env.example') {
+                // skip hidden dirs/files except harmless examples
+                if (entry.isDirectory())
+                    continue;
+            }
+            const abs = join(absDir, name);
+            if (entry.isDirectory()) {
+                if (skip.has(name.toLowerCase()))
+                    continue;
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const lower = name.toLowerCase();
+            const dot = lower.lastIndexOf('.');
+            if (dot < 0)
+                continue;
+            const ext = lower.slice(dot);
+            if (!extensions.has(ext))
+                continue;
+            out.push(normalizeRel(relative(projectDir, abs)));
+        }
+    };
+    try {
+        const st = statSync(projectDir);
+        if (!st.isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    walk(projectDir);
+    return out.sort();
+}
+/**
+ * Read supplied repo-relative paths (or auto-walk) and build ``service_manifest_v0``.
+ * Never throws — empty-but-shaped manifest on any error.
+ */
+export function buildServiceManifestFromPaths(projectDir, relPaths, opts = {}) {
+    try {
+        const maxFileBytes = Math.max(1024, opts.maxFileBytes ?? 512 * 1024);
+        const paths = relPaths
+            ? [...relPaths].filter(Boolean).map((p) => normalizeRel(String(p)))
+            : listCandidateSourceFiles(projectDir, opts);
+        const sources = {};
+        for (const rel of paths) {
+            try {
+                const abs = join(projectDir, rel);
+                const st = statSync(abs);
+                if (!st.isFile() || st.size > maxFileBytes)
+                    continue;
+                sources[rel] = readFileSync(abs, { encoding: 'utf8' });
+            }
+            catch {
+                continue;
+            }
+        }
+        const manifest = buildServiceManifest(sources);
+        manifest.notes = [
+            ...manifest.notes,
+            `scanned_files=${Object.keys(sources).length}`,
+            relPaths ? 'paths=explicit' : 'paths=auto_walk',
+        ];
+        return manifest;
+    }
+    catch {
+        return buildServiceManifest({});
+    }
+}

package/dist/analyze/resourceAdmission.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MP4 default-deny admission stub for Analyze candidates.
+ *
+ * Used by ``toResourceFindingCandidate`` before emitting ``resource_finding_v1``.
+ * Rejects clearly non-resource categories so Node cannot silently copy Python
+ * legacy finding types into the resource path. Shared policy / TCK remain
+ * authoritative when fully wired.
+ */
+/** Categories that must never enter the resource Analyze/Optimize path. */
+export declare const NON_RESOURCE_CATEGORIES: readonly ["hardcoded_secret", "security", "sql_injection", "architecture", "style", "maintainability", "missing_test", "generic_complexity", "generic_reliability", "generic_correctness"];
+export type NonResourceCategory = (typeof NON_RESOURCE_CATEGORIES)[number];
+/** Domains allowed to become resource candidates (scaffold allow-list). */
+export declare const RESOURCE_DOMAINS: readonly ["cpu", "gpu", "memory", "io", "network", "energy", "external_api", "quality_outcome", "compute.cpu", "compute.gpu", "memory.host", "memory.gpu", "storage.io", "network.io"];
+export type ResourceDomain = (typeof RESOURCE_DOMAINS)[number];
+export type AdmissionDecision = {
+    admitted: true;
+    domain: ResourceDomain;
+    reason: 'resource_domain_allowlisted';
+} | {
+    admitted: false;
+    reason: 'non_resource_category' | 'unknown_or_missing_domain' | 'explicit_deny';
+    category?: string;
+    detail?: string;
+};
+/**
+ * Default-deny: admit only when ``domain`` is a known resource domain and
+ * ``category`` (if present) is not a forbidden non-resource class.
+ */
+export declare function admitAnalyzeCandidate(input: {
+    domain?: string | null;
+    category?: string | null;
+}): AdmissionDecision;
+export declare function isNonResourceCategory(category: string): boolean;

package/dist/analyze/resourceAdmission.js

@@ -0,0 +1,91 @@
+/**
+ * MP4 default-deny admission stub for Analyze candidates.
+ *
+ * Used by ``toResourceFindingCandidate`` before emitting ``resource_finding_v1``.
+ * Rejects clearly non-resource categories so Node cannot silently copy Python
+ * legacy finding types into the resource path. Shared policy / TCK remain
+ * authoritative when fully wired.
+ */
+/** Categories that must never enter the resource Analyze/Optimize path. */
+export const NON_RESOURCE_CATEGORIES = [
+    'hardcoded_secret',
+    'security',
+    'sql_injection',
+    'architecture',
+    'style',
+    'maintainability',
+    'missing_test',
+    'generic_complexity',
+    'generic_reliability',
+    'generic_correctness',
+];
+/** Domains allowed to become resource candidates (scaffold allow-list). */
+export const RESOURCE_DOMAINS = [
+    'cpu',
+    'gpu',
+    'memory',
+    'io',
+    'network',
+    'energy',
+    'external_api',
+    'quality_outcome',
+    // Contract primary_domain aliases (resource_finding_v1)
+    'compute.cpu',
+    'compute.gpu',
+    'memory.host',
+    'memory.gpu',
+    'storage.io',
+    'network.io',
+];
+/** Map contract primary_domain → short admission key when needed. */
+const DOMAIN_ALIASES = {
+    'compute.cpu': 'cpu',
+    'compute.gpu': 'gpu',
+    'memory.host': 'memory',
+    'memory.gpu': 'memory',
+    'storage.io': 'io',
+    'network.io': 'network',
+};
+const NON_RESOURCE_SET = new Set(NON_RESOURCE_CATEGORIES);
+const RESOURCE_SET = new Set(RESOURCE_DOMAINS);
+function normalizeDomain(domain) {
+    const d = domain.trim().toLowerCase();
+    return DOMAIN_ALIASES[d] || d;
+}
+/**
+ * Default-deny: admit only when ``domain`` is a known resource domain and
+ * ``category`` (if present) is not a forbidden non-resource class.
+ */
+export function admitAnalyzeCandidate(input) {
+    const category = String(input.category || '')
+        .trim()
+        .toLowerCase();
+    if (category && NON_RESOURCE_SET.has(category)) {
+        return {
+            admitted: false,
+            reason: 'non_resource_category',
+            category,
+            detail: 'legacy/non-resource finding classes are rejected by default-deny',
+        };
+    }
+    const raw = String(input.domain || '')
+        .trim()
+        .toLowerCase();
+    const domain = normalizeDomain(raw);
+    if (!domain || (!RESOURCE_SET.has(domain) && !RESOURCE_SET.has(raw))) {
+        return {
+            admitted: false,
+            reason: 'unknown_or_missing_domain',
+            detail: 'resource Analyze requires an allowlisted primary domain',
+        };
+    }
+    const admittedDomain = (RESOURCE_SET.has(raw) ? raw : domain);
+    return {
+        admitted: true,
+        domain: admittedDomain,
+        reason: 'resource_domain_allowlisted',
+    };
+}
+export function isNonResourceCategory(category) {
+    return NON_RESOURCE_SET.has(String(category || '').trim().toLowerCase());
+}

package/dist/analyze/resourceFindingCandidate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MP4 Node twin of Python resource-candidate IR (``resource_finding_v1``).
+ *
+ * Emits **candidates** only (evidence_state=candidate). Does not upload, does not
+ * change RunSession, and does not claim Optimize / verified savings.
+ */
+/** Contract primary_domain values used by Node Analyze candidates. */
+export type ResourcePrimaryDomain = 'compute.cpu' | 'compute.gpu' | 'memory.host' | 'memory.gpu' | 'storage.io' | 'network.io' | 'external_api';
+export type ResourceFindingCandidateV1 = {
+    schema_version: 'resource_finding_v1';
+    finding_id: string;
+    project_id: string;
+    evidence_state: 'candidate';
+    comparison_origin: 'none';
+    lifecycle_status: 'pending_admission';
+    verification_outcome: 'not_run';
+    primary_domain: ResourcePrimaryDomain;
+    mechanism_id: string;
+    title: string;
+    scope: {
+        kind: 'function' | 'service_unit' | 'task' | 'script';
+        id: string;
+        language: 'javascript' | 'typescript';
+        runtime: 'nodejs';
+        source_locations: Array<{
+            path: string;
+            start_line: number;
+            end_line: number;
+            symbol?: string;
+        }>;
+    };
+    lineage: {
+        detector_id: string;
+        detector_version: string;
+        policy_version: string;
+        observation_ids: string[];
+        benchmark_result_ids: string[];
+    };
+};
+export type ResourceCandidateHit = {
+    mechanism_id: string;
+    primary_domain: ResourcePrimaryDomain;
+    /** Short domain key for local admission stub (e.g. external_api). */
+    admission_domain: string;
+    title: string;
+    rel_path: string;
+    start_line: number;
+    end_line: number;
+    symbol?: string;
+    language: 'javascript' | 'typescript';
+    detector_id: string;
+    detector_version: string;
+    legacy_issue_type?: string;
+    /** Optional reject category — when set, must pass default-deny. */
+    category?: string;
+};
+/**
+ * Shape a detector hit into ``resource_finding_v1`` candidate, or null if denied.
+ */
+export declare function toResourceFindingCandidate(hit: ResourceCandidateHit, projectId?: string): ResourceFindingCandidateV1 | null;
+export declare function languageForPath(relPath: string): 'javascript' | 'typescript';

package/dist/analyze/resourceFindingCandidate.js

@@ -0,0 +1,75 @@
+/**
+ * MP4 Node twin of Python resource-candidate IR (``resource_finding_v1``).
+ *
+ * Emits **candidates** only (evidence_state=candidate). Does not upload, does not
+ * change RunSession, and does not claim Optimize / verified savings.
+ */
+import { createHash } from 'node:crypto';
+import { admitAnalyzeCandidate } from './resourceAdmission.js';
+const POLICY_VERSION = '0.1.0';
+function languageFromPath(relPath) {
+    const lower = relPath.toLowerCase();
+    if (lower.endsWith('.ts') || lower.endsWith('.tsx'))
+        return 'typescript';
+    return 'javascript';
+}
+function stableFindingId(hit, projectId) {
+    const preimage = [
+        projectId,
+        hit.mechanism_id,
+        hit.rel_path,
+        String(hit.start_line),
+        hit.detector_id,
+    ].join('|');
+    const digest = createHash('sha256').update(preimage).digest('hex').slice(0, 12);
+    return `rf_${hit.mechanism_id.slice(0, 24)}_${digest}`;
+}
+/**
+ * Shape a detector hit into ``resource_finding_v1`` candidate, or null if denied.
+ */
+export function toResourceFindingCandidate(hit, projectId = 'local') {
+    const decision = admitAnalyzeCandidate({
+        domain: hit.admission_domain,
+        category: hit.category,
+    });
+    if (!decision.admitted)
+        return null;
+    const language = hit.language || languageFromPath(hit.rel_path);
+    const scopeId = (hit.symbol || hit.rel_path).slice(0, 200);
+    return {
+        schema_version: 'resource_finding_v1',
+        finding_id: stableFindingId(hit, projectId).slice(0, 128),
+        project_id: String(projectId || 'local').slice(0, 64),
+        evidence_state: 'candidate',
+        comparison_origin: 'none',
+        lifecycle_status: 'pending_admission',
+        verification_outcome: 'not_run',
+        primary_domain: hit.primary_domain,
+        mechanism_id: hit.mechanism_id,
+        title: hit.title.slice(0, 200),
+        scope: {
+            kind: hit.symbol ? 'function' : 'script',
+            id: scopeId,
+            language,
+            runtime: 'nodejs',
+            source_locations: [
+                {
+                    path: hit.rel_path.replace(/\\/g, '/').slice(0, 512),
+                    start_line: Math.max(1, hit.start_line),
+                    end_line: Math.max(hit.start_line, hit.end_line),
+                    ...(hit.symbol ? { symbol: hit.symbol.slice(0, 120) } : {}),
+                },
+            ],
+        },
+        lineage: {
+            detector_id: hit.detector_id,
+            detector_version: hit.detector_version,
+            policy_version: POLICY_VERSION,
+            observation_ids: [],
+            benchmark_result_ids: [],
+        },
+    };
+}
+export function languageForPath(relPath) {
+    return languageFromPath(relPath);
+}

package/dist/analyze/retryAmplificationDetector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Heuristic JS/TS twin of Python ``api_usage_audit.api_call_in_retry_loop``.
+ *
+ * Maps via RD0 disposition → mechanism ``retry_amplification`` / domain ``external_api``.
+ * Not a TypeScript AST yet — brace-depth + line heuristics only.
+ */
+import { type ResourceCandidateHit } from './resourceFindingCandidate.js';
+/**
+ * Detect API calls nested in retry-ish loops in one source file.
+ */
+export declare function detectRetryAmplificationHits(source: string, relPath: string): ResourceCandidateHit[];

package/dist/analyze/retryAmplificationDetector.js

@@ -0,0 +1,55 @@
+/**
+ * Heuristic JS/TS twin of Python ``api_usage_audit.api_call_in_retry_loop``.
+ *
+ * Maps via RD0 disposition → mechanism ``retry_amplification`` / domain ``external_api``.
+ * Not a TypeScript AST yet — brace-depth + line heuristics only.
+ */
+import { advanceBraceDepth, hasApiCall, RETRY_HEADER_RE, stripLineComment, } from './heuristicScan.js';
+import { languageForPath, } from './resourceFindingCandidate.js';
+const DETECTOR_ID = 'js.static.retry_loop';
+const DETECTOR_VERSION = '0.1.0';
+const LEGACY_ISSUE = 'api_call_in_retry_loop';
+const MECHANISM = 'retry_amplification';
+const TITLE = 'Retry loop may amplify billed API attempts';
+/**
+ * Detect API calls nested in retry-ish loops in one source file.
+ */
+export function detectRetryAmplificationHits(source, relPath) {
+    const lines = source.split(/\r?\n/);
+    const hits = [];
+    let braceDepth = 0;
+    /** Brace depth of the retry loop header line (body is deeper). */
+    let retryAtDepth = null;
+    const language = languageForPath(relPath);
+    const path = relPath.replace(/\\/g, '/');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = stripLineComment(lines[i] ?? '');
+        const lineNo = i + 1;
+        const isRetryHeader = RETRY_HEADER_RE.test(line);
+        const before = braceDepth;
+        const { braceDepth: next, openedBrace } = advanceBraceDepth(line, braceDepth);
+        braceDepth = next;
+        if (isRetryHeader && retryAtDepth === null) {
+            retryAtDepth = openedBrace ? before : braceDepth;
+        }
+        if (retryAtDepth !== null && braceDepth <= retryAtDepth) {
+            retryAtDepth = null;
+        }
+        if (retryAtDepth !== null && braceDepth > retryAtDepth && hasApiCall(line)) {
+            hits.push({
+                mechanism_id: MECHANISM,
+                primary_domain: 'external_api',
+                admission_domain: 'external_api',
+                title: TITLE,
+                rel_path: path,
+                start_line: lineNo,
+                end_line: lineNo,
+                language,
+                detector_id: DETECTOR_ID,
+                detector_version: DETECTOR_VERSION,
+                legacy_issue_type: LEGACY_ISSUE,
+            });
+        }
+    }
+    return hits;
+}