@netgreener/runtime 0.1.0

package/dist/aggregator.js

@@ -0,0 +1,270 @@
+const MAX_UNITS = 500;
+const MAX_SERVICE_UNIT_LEN = 256;
+function normalizeServiceUnit(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return 'UNKNOWN';
+    if (trimmed.length <= MAX_SERVICE_UNIT_LEN)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_SERVICE_UNIT_LEN - 1)}…`;
+}
+/** Contain NaN / ±Infinity / negatives so session_metadata numerics stay finite. */
+function nonNegativeFinite(value) {
+    return Number.isFinite(value) && value >= 0 ? value : 0;
+}
+export class ServiceRuntimeAggregator {
+    units = new Map();
+    byTenant = new Map();
+    windowStartedAt = Date.now();
+    resetWindow() {
+        this.units.clear();
+        this.byTenant.clear();
+        this.windowStartedAt = Date.now();
+    }
+    windowStartedMs() {
+        return this.windowStartedAt;
+    }
+    record(sample) {
+        const key = normalizeServiceUnit(sample.serviceUnit);
+        this.recordIntoMap(this.units, key, sample);
+        if (sample.tenantId) {
+            let tenantUnits = this.byTenant.get(sample.tenantId);
+            if (!tenantUnits) {
+                tenantUnits = new Map();
+                this.byTenant.set(sample.tenantId, tenantUnits);
+            }
+            this.recordIntoMap(tenantUnits, key, sample);
+        }
+    }
+    recordIntoMap(target, key, sample) {
+        let unit = target.get(key);
+        if (!unit) {
+            const needsOverflow = key !== '__other__' && target.size >= MAX_UNITS - 1 && !target.has(key);
+            if (needsOverflow) {
+                key = '__other__';
+                unit = target.get(key);
+            }
+            if (!unit) {
+                unit = {
+                    serviceUnit: key,
+                    unitType: sample.unitType || 'http_route',
+                    calls: 0,
+                    errors: 0,
+                    durationMsTotal: 0,
+                    durationMsMax: 0,
+                    cpuMsTotal: 0,
+                    cpuMsMeasured: false,
+                    peakRssKbMax: 0,
+                };
+                target.set(key, unit);
+            }
+        }
+        unit.calls += 1;
+        if (sample.error)
+            unit.errors += 1;
+        // Math.max(0, NaN) === NaN — must reject non-finite before accumulate.
+        const ms = nonNegativeFinite(sample.durationMs);
+        unit.durationMsTotal += ms;
+        unit.durationMsMax = Math.max(unit.durationMsMax, ms);
+        if (sample.cpuTimeMs !== undefined) {
+            unit.cpuMsTotal += nonNegativeFinite(sample.cpuTimeMs);
+            unit.cpuMsMeasured = true;
+        }
+        if (sample.peakRssKb !== undefined) {
+            const rss = nonNegativeFinite(sample.peakRssKb);
+            if (rss > 0)
+                unit.peakRssKbMax = Math.max(unit.peakRssKbMax, rss);
+        }
+    }
+    buildUnitsList(source, windowEnergyKwh, equalShare, totalDuration) {
+        const list = [...source.values()].filter((u) => u.calls > 0);
+        if (!list.length)
+            return [];
+        const energyBudget = nonNegativeFinite(windowEnergyKwh);
+        const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
+        const units = sorted.map((u) => {
+            const share = equalShare ? 1 / list.length : u.durationMsTotal / totalDuration;
+            const energy = energyBudget * share;
+            const avg = u.calls ? u.durationMsTotal / u.calls : 0;
+            const cpuSeconds = u.cpuMsMeasured
+                ? u.cpuMsTotal / 1000
+                : u.durationMsTotal / 1000;
+            const unit = {
+                service_unit: u.serviceUnit,
+                unit_type: u.unitType,
+                calls: u.calls,
+                errors: u.errors,
+                cpu_seconds_total: Math.round(cpuSeconds * 10000) / 10000,
+                energy_kwh: energy,
+                carbon_g: energy * 0.4 * 1000,
+                duration_ms: {
+                    avg: Math.round(avg * 100) / 100,
+                    max: Math.round(u.durationMsMax * 100) / 100,
+                },
+            };
+            if (u.peakRssKbMax > 0) {
+                unit.peak_rss_kb_max = Math.round(u.peakRssKbMax);
+            }
+            return unit;
+        });
+        const allocatedRaw = units.reduce((s, u) => s + u.energy_kwh, 0);
+        const drift = energyBudget - allocatedRaw;
+        if (units.length && Math.abs(drift) > 0) {
+            units[0].energy_kwh += drift;
+            units[0].carbon_g = units[0].energy_kwh * 0.4 * 1000;
+        }
+        for (const u of units) {
+            u.energy_kwh = Math.round(u.energy_kwh * 1e12) / 1e12;
+            u.carbon_g = Math.round(u.carbon_g * 1e6) / 1e6;
+        }
+        return units;
+    }
+    hasData() {
+        for (const u of this.units.values()) {
+            if (u.calls > 0)
+                return true;
+        }
+        return false;
+    }
+    totalDurationMs() {
+        let total = 0;
+        for (const u of this.units.values()) {
+            if (u.calls > 0)
+                total += u.durationMsTotal;
+        }
+        return total;
+    }
+    /** Sum of measured process CPU ms in this window (0 if none measured). */
+    totalMeasuredCpuMs() {
+        let total = 0;
+        for (const u of this.units.values()) {
+            if (u.calls > 0 && u.cpuMsMeasured)
+                total += u.cpuMsTotal;
+        }
+        return total;
+    }
+    /** True when any unit recorded measured process CPU (not duration proxy). */
+    hasMeasuredCpu() {
+        for (const u of this.units.values()) {
+            if (u.calls > 0 && u.cpuMsMeasured)
+                return true;
+        }
+        return false;
+    }
+    /** True when any unit recorded peak RSS. */
+    hasMeasuredRss() {
+        for (const u of this.units.values()) {
+            if (u.calls > 0 && u.peakRssKbMax > 0)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Build service_runtime_v0. N1 uses duration-share energy attribution (trend).
+     * CPU-accurate share can land later without changing the schema.
+     */
+    buildV0(opts) {
+        const list = [...this.units.values()].filter((u) => u.calls > 0);
+        if (!list.length)
+            return null;
+        const windowEnergyKwh = nonNegativeFinite(opts.windowEnergyKwh);
+        const windowSeconds = nonNegativeFinite(opts.windowSeconds);
+        const totalDuration = list.reduce((s, u) => s + u.durationMsTotal, 0);
+        const equalShare = totalDuration <= 0;
+        const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration);
+        const byTenant = {};
+        const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
+        for (const [tenantId, tenantMap] of this.byTenant.entries()) {
+            const tenantList = [...tenantMap.values()].filter((u) => u.calls > 0);
+            if (!tenantList.length)
+                continue;
+            const tenantBusy = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
+            const tenantEnergy = totalBusy > 0
+                ? windowEnergyKwh * (tenantBusy / totalBusy)
+                : windowEnergyKwh / Math.max(1, this.byTenant.size);
+            const tenantDuration = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
+            const tenantEqual = tenantDuration <= 0;
+            const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration);
+            if (!tenantUnits.length)
+                continue;
+            byTenant[tenantId] = {
+                tenant_id: tenantId,
+                calls: tenantUnits.reduce((s, u) => s + u.calls, 0),
+                errors: tenantUnits.reduce((s, u) => s + u.errors, 0),
+                units: tenantUnits,
+            };
+        }
+        const allocated = units.reduce((s, u) => s + u.energy_kwh, 0);
+        const residual = windowEnergyKwh - allocated;
+        const tolerance = Math.max(1e-12, Math.abs(windowEnergyKwh) * 1e-6);
+        return {
+            framework: opts.framework,
+            collector: opts.collector,
+            window_seconds: Math.round(windowSeconds * 100) / 100,
+            attribution: equalShare ? 'equal_share_no_cpu_signal' : 'duration_share',
+            accuracy: 'trend',
+            units,
+            ...(Object.keys(byTenant).length ? { by_tenant: byTenant } : {}),
+            allocation_reconciliation_v0: {
+                schema_version: 1,
+                window_energy_kwh: windowEnergyKwh,
+                allocated_energy_kwh: allocated,
+                residual_energy_kwh: residual,
+                tolerance_kwh: tolerance,
+                passed: Math.abs(residual) <= tolerance,
+                scope: 'endpoint_allocation_arithmetic_only',
+                endpoint_capture_coverage: null,
+                capture_completeness: 'unknown',
+            },
+        };
+    }
+    /** Take a snapshot and reset live window (Python take_snapshot analogue). */
+    takeSnapshot() {
+        const snap = new ServiceRuntimeAggregator();
+        snap.units = this.units;
+        snap.byTenant = this.byTenant;
+        snap.windowStartedAt = this.windowStartedAt;
+        this.units = new Map();
+        this.byTenant = new Map();
+        this.windowStartedAt = Date.now();
+        return snap;
+    }
+    mergeSnapshot(snapshot) {
+        if (snapshot.hasData()) {
+            this.windowStartedAt = Math.min(this.windowStartedAt, snapshot.windowStartedAt);
+        }
+        this.mergeMap(this.units, snapshot.units);
+        for (const [tenantId, sourceMap] of snapshot.byTenant.entries()) {
+            let targetMap = this.byTenant.get(tenantId);
+            if (!targetMap) {
+                targetMap = new Map();
+                this.byTenant.set(tenantId, targetMap);
+            }
+            this.mergeMap(targetMap, sourceMap);
+        }
+    }
+    mergeMap(target, source) {
+        for (const [rawKey, src] of source) {
+            let key = rawKey;
+            let dst = target.get(key);
+            if (!dst) {
+                const needsOverflow = key !== '__other__' && target.size >= MAX_UNITS - 1 && !target.has(key);
+                if (needsOverflow) {
+                    key = '__other__';
+                    dst = target.get(key);
+                }
+            }
+            if (!dst) {
+                target.set(key, { ...src, serviceUnit: key });
+                continue;
+            }
+            dst.calls += src.calls;
+            dst.errors += src.errors;
+            dst.durationMsTotal += src.durationMsTotal;
+            dst.durationMsMax = Math.max(dst.durationMsMax, src.durationMsMax);
+            dst.cpuMsTotal += src.cpuMsTotal;
+            dst.cpuMsMeasured = dst.cpuMsMeasured || src.cpuMsMeasured;
+            dst.peakRssKbMax = Math.max(dst.peakRssKbMax, src.peakRssKbMax);
+        }
+    }
+}

package/dist/analyze/analyzeGate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CI gate helpers for Analyze resource candidates (Node twin of Python
+ * ``findings_bridge`` fail-on, adapted to ``resource_finding_v1``).
+ *
+ * Resource candidates have no severity rank — gates match ``mechanism_id``
+ * or the aliases ``any`` / ``candidate``.
+ */
+import type { ResourceFindingCandidateV1 } from './resourceFindingCandidate.js';
+export type AnalyzeGateLimit = number | null;
+/** Effective count cap when ``--fail-on`` is set (default 0 = any match fails). */
+export declare function resolveAnalyzeGateLimit(failOn: string | null | undefined, maxAtOrAbove: number | null | undefined): AnalyzeGateLimit;
+/**
+ * Count candidates that match ``failOn``.
+ * - ``any`` / ``candidate`` → all findings
+ * - comma-separated mechanism IDs → exact mechanism_id match
+ */
+export declare function countGateFindings(findings: Iterable<ResourceFindingCandidateV1>, failOn: string): number;
+export declare function findingsExceedFailThreshold(findings: Iterable<ResourceFindingCandidateV1>, failOn: string, maxAtOrAbove?: number): boolean;
+export declare function formatAnalyzeGateFailureMessage(findings: Iterable<ResourceFindingCandidateV1>, failOn: string, maxAtOrAbove?: number): string;
+export type AnalyzeGateSummaryV0 = {
+    schema: 'netgreener_analyze_gate_summary_v0';
+    upload: 'never';
+    ok: boolean;
+    exit_code: 0 | 1;
+    project_id: string;
+    files_scanned: number;
+    findings_total: number;
+    by_mechanism: Record<string, number>;
+    gate: null | {
+        fail_on: string;
+        max_at_or_above: number;
+        matching: number;
+        exceeded: boolean;
+        message: string | null;
+    };
+};
+/** Machine-readable CI annotation payload (no upload). */
+export declare function buildAnalyzeGateSummary(input: {
+    projectId: string;
+    filesScanned: number;
+    findings: ResourceFindingCandidateV1[];
+    failOn?: string | null;
+    maxAtOrAbove?: number | null;
+}): AnalyzeGateSummaryV0;

package/dist/analyze/analyzeGate.js

@@ -0,0 +1,114 @@
+/**
+ * CI gate helpers for Analyze resource candidates (Node twin of Python
+ * ``findings_bridge`` fail-on, adapted to ``resource_finding_v1``).
+ *
+ * Resource candidates have no severity rank — gates match ``mechanism_id``
+ * or the aliases ``any`` / ``candidate``.
+ */
+/** Effective count cap when ``--fail-on`` is set (default 0 = any match fails). */
+export function resolveAnalyzeGateLimit(failOn, maxAtOrAbove) {
+    if (!failOn)
+        return null;
+    return maxAtOrAbove == null ? 0 : maxAtOrAbove;
+}
+function normalizeFailOn(failOn) {
+    return String(failOn || '')
+        .trim()
+        .toLowerCase();
+}
+/**
+ * Count candidates that match ``failOn``.
+ * - ``any`` / ``candidate`` → all findings
+ * - comma-separated mechanism IDs → exact mechanism_id match
+ */
+export function countGateFindings(findings, failOn) {
+    const key = normalizeFailOn(failOn);
+    if (!key || key === 'none' || key === 'off')
+        return 0;
+    const list = [...findings];
+    if (key === 'any' || key === 'candidate')
+        return list.length;
+    const wanted = new Set(key
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean));
+    if (wanted.size === 0)
+        return 0;
+    return list.filter((f) => wanted.has(String(f.mechanism_id || '').toLowerCase())).length;
+}
+export function findingsExceedFailThreshold(findings, failOn, maxAtOrAbove = 0) {
+    return countGateFindings(findings, failOn) > maxAtOrAbove;
+}
+export function formatAnalyzeGateFailureMessage(findings, failOn, maxAtOrAbove = 0) {
+    const list = [...findings];
+    const bad = countGateFindings(list, failOn);
+    const matching = listMatchingFindings(list, failOn);
+    const top = new Map();
+    for (const f of matching) {
+        const id = f.mechanism_id || 'unknown';
+        top.set(id, (top.get(id) || 0) + 1);
+    }
+    const topStr = [...top.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 4)
+        .map(([name, count]) => `${name} x${count}`)
+        .join(', ') || 'n/a';
+    const limit = maxAtOrAbove > 0 ? ` (max ${maxAtOrAbove})` : '';
+    return (`NetGreener gate failed: ${bad} candidate(s) matching '${failOn}'${limit} ` +
+        `(${list.length} total). Top: ${topStr}`);
+}
+function listMatchingFindings(findings, failOn) {
+    const key = normalizeFailOn(failOn);
+    if (!key || key === 'none' || key === 'off')
+        return [];
+    if (key === 'any' || key === 'candidate')
+        return findings;
+    const wanted = new Set(key
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean));
+    return findings.filter((f) => wanted.has(String(f.mechanism_id || '').toLowerCase()));
+}
+/** Machine-readable CI annotation payload (no upload). */
+export function buildAnalyzeGateSummary(input) {
+    const findings = [...input.findings];
+    const by_mechanism = {};
+    for (const f of findings) {
+        by_mechanism[f.mechanism_id] = (by_mechanism[f.mechanism_id] || 0) + 1;
+    }
+    const limit = resolveAnalyzeGateLimit(input.failOn, input.maxAtOrAbove);
+    if (!input.failOn || limit == null) {
+        return {
+            schema: 'netgreener_analyze_gate_summary_v0',
+            upload: 'never',
+            ok: true,
+            exit_code: 0,
+            project_id: input.projectId,
+            files_scanned: input.filesScanned,
+            findings_total: findings.length,
+            by_mechanism,
+            gate: null,
+        };
+    }
+    const matching = countGateFindings(findings, input.failOn);
+    const exceeded = matching > limit;
+    return {
+        schema: 'netgreener_analyze_gate_summary_v0',
+        upload: 'never',
+        ok: !exceeded,
+        exit_code: exceeded ? 1 : 0,
+        project_id: input.projectId,
+        files_scanned: input.filesScanned,
+        findings_total: findings.length,
+        by_mechanism,
+        gate: {
+            fail_on: input.failOn,
+            max_at_or_above: limit,
+            matching,
+            exceeded,
+            message: exceeded
+                ? formatAnalyzeGateFailureMessage(findings, input.failOn, limit)
+                : null,
+        },
+    };
+}

package/dist/analyze/apiOverconsumptionDetector.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Heuristic JS/TS twins of Python API overconsumption rules:
+ *   - api_call_in_comprehension
+ *   - network_call_in_loop / paid_api_in_loop (non-retry loops)
+ *
+ * RD0 disposition → mechanism ``external_api_overconsumption`` / ``external_api``.
+ * Skips retry loops (owned by retry_amplification detector).
+ */
+import { type ResourceCandidateHit } from './resourceFindingCandidate.js';
+/**
+ * Detect API calls inside array comprehensions (.map / .flatMap / …) or plain loops.
+ */
+export declare function detectApiOverconsumptionHits(source: string, relPath: string): ResourceCandidateHit[];

package/dist/analyze/apiOverconsumptionDetector.js

@@ -0,0 +1,75 @@
+/**
+ * Heuristic JS/TS twins of Python API overconsumption rules:
+ *   - api_call_in_comprehension
+ *   - network_call_in_loop / paid_api_in_loop (non-retry loops)
+ *
+ * RD0 disposition → mechanism ``external_api_overconsumption`` / ``external_api``.
+ * Skips retry loops (owned by retry_amplification detector).
+ */
+import { advanceBraceDepth, COMPREHENSION_RE, hasApiCall, LOOP_HEADER_RE, PROMISE_ALL_RE, RETRY_HEADER_RE, stripLineComment, } from './heuristicScan.js';
+import { languageForPath, } from './resourceFindingCandidate.js';
+const DETECTOR_VERSION = '0.1.0';
+const MECHANISM = 'external_api_overconsumption';
+const TITLE_COMP = 'API call inside map/filter may multiply billed attempts';
+const TITLE_LOOP = 'API call inside loop may multiply billed attempts';
+function hitBase(relPath, lineNo, language, legacy, detectorId, title) {
+    return {
+        mechanism_id: MECHANISM,
+        primary_domain: 'external_api',
+        admission_domain: 'external_api',
+        title,
+        rel_path: relPath,
+        start_line: lineNo,
+        end_line: lineNo,
+        language,
+        detector_id: detectorId,
+        detector_version: DETECTOR_VERSION,
+        legacy_issue_type: legacy,
+    };
+}
+/**
+ * Detect API calls inside array comprehensions (.map / .flatMap / …) or plain loops.
+ */
+export function detectApiOverconsumptionHits(source, relPath) {
+    const lines = source.split(/\r?\n/);
+    const hits = [];
+    let braceDepth = 0;
+    let loopAtDepth = null;
+    let inRetryLoop = false;
+    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 isLoopHeader = LOOP_HEADER_RE.test(line);
+        const before = braceDepth;
+        const { braceDepth: next, openedBrace } = advanceBraceDepth(line, braceDepth);
+        braceDepth = next;
+        if (isRetryHeader) {
+            inRetryLoop = true;
+            loopAtDepth = openedBrace ? before : braceDepth;
+        }
+        else if (isLoopHeader && loopAtDepth === null) {
+            inRetryLoop = false;
+            loopAtDepth = openedBrace ? before : braceDepth;
+        }
+        if (loopAtDepth !== null && braceDepth <= loopAtDepth) {
+            loopAtDepth = null;
+            inRetryLoop = false;
+        }
+        // Same-line comprehension + API — skip Promise.all (owned by unbounded detector)
+        if (COMPREHENSION_RE.test(line) && hasApiCall(line) && !PROMISE_ALL_RE.test(line)) {
+            hits.push(hitBase(path, lineNo, language, 'api_call_in_comprehension', 'js.static.api_in_comprehension', TITLE_COMP));
+            continue;
+        }
+        // Nested body of a non-retry loop
+        if (loopAtDepth !== null &&
+            !inRetryLoop &&
+            braceDepth > loopAtDepth &&
+            hasApiCall(line)) {
+            hits.push(hitBase(path, lineNo, language, 'network_call_in_loop', 'js.static.api_in_loop', TITLE_LOOP));
+        }
+    }
+    return hits;
+}

package/dist/analyze/astDetectors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * TypeScript AST detectors for Analyze (Python AST parity path).
+ *
+ * Returns ``null`` when typescript is unavailable or the file cannot be parsed —
+ * callers must fall back to heuristic detectors.
+ */
+import { type ResourceCandidateHit } from './resourceFindingCandidate.js';
+export type AstHitBundle = {
+    retry: ResourceCandidateHit[];
+    fileReads: ResourceCandidateHit[];
+    overconsumption: ResourceCandidateHit[];
+    unbounded: ResourceCandidateHit[];
+    polling: ResourceCandidateHit[];
+    repeatedWork: ResourceCandidateHit[];
+    processChurn: ResourceCandidateHit[];
+    fullDataset: ResourceCandidateHit[];
+    perItem: ResourceCandidateHit[];
+    modelLoad: ResourceCandidateHit[];
+    inference: ResourceCandidateHit[];
+};
+/** Full AST hit bundle, or ``null`` to signal heuristic fallback. */
+export declare function detectAllHitsAst(source: string, relPath: string): AstHitBundle | null;
+/** @deprecated Prefer detectAllHitsAst — kept for callers. */
+export declare function detectHotPathHitsAst(source: string, relPath: string): {
+    retry: ResourceCandidateHit[];
+    fileReads: ResourceCandidateHit[];
+} | null;
+export declare function detectRetryAmplificationHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectRepeatedFileReadHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectApiOverconsumptionHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectUnboundedParallelismHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectPollingIdleHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectRepeatedWorkHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectProcessChurnHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectFullDatasetInMemoryHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectPerItemInsteadOfBatchHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectModelLoadInLoopHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;
+export declare function detectInferenceInsideLoopHitsAst(source: string, relPath: string): ResourceCandidateHit[] | null;