@netgreener/runtime 0.1.10 → 0.1.12
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/CHANGELOG.md +8 -0
- package/dist/aggregator.d.ts +3 -0
- package/dist/aggregator.js +36 -13
- package/dist/analyze/buildResourceFindings.d.ts +1 -1
- package/dist/analyze/buildResourceFindings.js +4 -2
- package/dist/analyze/findingGuidance.d.ts +14 -0
- package/dist/analyze/findingGuidance.js +52 -0
- package/dist/analyze/index.d.ts +3 -2
- package/dist/analyze/index.js +3 -2
- package/dist/analyze/projectScan.d.ts +3 -1
- package/dist/analyze/projectScan.js +29 -6
- package/dist/analyze/resourceFindingCandidate.d.ts +6 -0
- package/dist/analyze/resourceFindingCandidate.js +11 -0
- package/dist/analyze/serviceDiscovery.d.ts +23 -1
- package/dist/analyze/serviceDiscovery.js +164 -4
- package/dist/cli/helpText.js +1 -0
- package/dist/cli/netgreener.js +8 -0
- package/dist/cli/runtimeCli.d.ts +2 -0
- package/dist/cli/runtimeCli.js +35 -0
- package/dist/config.js +3 -1
- package/dist/exporter.js +9 -0
- package/dist/externalApiMeter.js +12 -7
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/managedCollectorLauncher.d.ts +2 -1
- package/dist/managedCollectorLauncher.js +2 -1
- package/dist/mcpToolMeter.js +6 -1
- package/dist/processResources.js +5 -2
- package/dist/runtime.d.ts +4 -5
- package/dist/runtime.js +86 -50
- package/dist/runtimeControls.d.ts +5 -0
- package/dist/runtimeControls.js +69 -0
- package/dist/runtimeHealth.d.ts +15 -0
- package/dist/runtimeHealth.js +47 -1
- package/dist/tenantContext.d.ts +4 -0
- package/dist/tenantContext.js +36 -10
- package/dist/uploader.js +45 -1
- package/fixtures/git/canonical_git_key_vectors.v1.json +66 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog — @netgreener/runtime
|
|
2
2
|
|
|
3
|
+
## [0.1.11] — 2026-10-21
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
- Preserve exact retry payloads and isolate newly arriving observations.
|
|
7
|
+
- Allocate process CPU and memory consistently across routes and tenants.
|
|
8
|
+
- Bound tenant buckets and improve tenant inference and diagnostics.
|
|
9
|
+
- Improve service discovery and resource-finding guidance for Node projects.
|
|
10
|
+
|
|
3
11
|
## [0.1.10] — 2026-10-19
|
|
4
12
|
|
|
5
13
|
### Added
|
package/dist/aggregator.d.ts
CHANGED
|
@@ -4,6 +4,7 @@ export declare class ServiceRuntimeAggregator {
|
|
|
4
4
|
private byTenant;
|
|
5
5
|
private windowStartedAt;
|
|
6
6
|
resetWindow(): void;
|
|
7
|
+
excludePausedTime(milliseconds: number): void;
|
|
7
8
|
windowStartedMs(): number;
|
|
8
9
|
record(sample: {
|
|
9
10
|
serviceUnit: string;
|
|
@@ -40,6 +41,8 @@ export declare class ServiceRuntimeAggregator {
|
|
|
40
41
|
windowSeconds: number;
|
|
41
42
|
/** Crude window RAM (GiB·h); split by occupancy share when present. */
|
|
42
43
|
windowRamGbHours?: number | null;
|
|
44
|
+
/** One process-wide CPU delta; per-route values are allocated estimates. */
|
|
45
|
+
windowCpuSeconds?: number | null;
|
|
43
46
|
occupancy?: {
|
|
44
47
|
by_unit: Record<string, number>;
|
|
45
48
|
in_flight_seconds: number;
|
package/dist/aggregator.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { energyKwhToCarbonG } from './carbonLedger.js';
|
|
2
|
+
import { tenantBucketId } from './tenantContext.js';
|
|
2
3
|
const MAX_UNITS = 500;
|
|
3
4
|
const MAX_SERVICE_UNIT_LEN = 256;
|
|
4
5
|
function normalizeServiceUnit(raw) {
|
|
@@ -22,6 +23,9 @@ export class ServiceRuntimeAggregator {
|
|
|
22
23
|
this.byTenant.clear();
|
|
23
24
|
this.windowStartedAt = Date.now();
|
|
24
25
|
}
|
|
26
|
+
excludePausedTime(milliseconds) {
|
|
27
|
+
this.windowStartedAt += Math.max(0, milliseconds);
|
|
28
|
+
}
|
|
25
29
|
windowStartedMs() {
|
|
26
30
|
return this.windowStartedAt;
|
|
27
31
|
}
|
|
@@ -29,10 +33,11 @@ export class ServiceRuntimeAggregator {
|
|
|
29
33
|
const key = normalizeServiceUnit(sample.serviceUnit);
|
|
30
34
|
this.recordIntoMap(this.units, key, sample);
|
|
31
35
|
if (sample.tenantId) {
|
|
32
|
-
|
|
36
|
+
const tenantId = tenantBucketId(sample.tenantId, this.byTenant);
|
|
37
|
+
let tenantUnits = this.byTenant.get(tenantId);
|
|
33
38
|
if (!tenantUnits) {
|
|
34
39
|
tenantUnits = new Map();
|
|
35
|
-
this.byTenant.set(
|
|
40
|
+
this.byTenant.set(tenantId, tenantUnits);
|
|
36
41
|
}
|
|
37
42
|
this.recordIntoMap(tenantUnits, key, sample);
|
|
38
43
|
}
|
|
@@ -97,13 +102,16 @@ export class ServiceRuntimeAggregator {
|
|
|
97
102
|
: null;
|
|
98
103
|
const useOccupancy = Boolean(alloc?.useOccupancy);
|
|
99
104
|
const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
|
|
105
|
+
const totalCalls = list.reduce((sum, unit) => sum + unit.calls, 0);
|
|
100
106
|
const units = sorted.map((u) => {
|
|
101
|
-
const share = equalShare ?
|
|
107
|
+
const share = equalShare ? u.calls / totalCalls : u.durationMsTotal / totalDuration;
|
|
102
108
|
const energy = energyBudget * share;
|
|
103
109
|
const avg = u.calls ? u.durationMsTotal / u.calls : 0;
|
|
104
|
-
const cpuSeconds =
|
|
105
|
-
?
|
|
106
|
-
: u.
|
|
110
|
+
const cpuSeconds = alloc?.windowCpuSeconds != null
|
|
111
|
+
? nonNegativeFinite(alloc.windowCpuSeconds) * share
|
|
112
|
+
: u.cpuMsMeasured
|
|
113
|
+
? u.cpuMsTotal / 1000
|
|
114
|
+
: u.durationMsTotal / 1000;
|
|
107
115
|
const unit = {
|
|
108
116
|
service_unit: u.serviceUnit,
|
|
109
117
|
unit_type: u.unitType,
|
|
@@ -248,21 +256,33 @@ export class ServiceRuntimeAggregator {
|
|
|
248
256
|
windowSeconds,
|
|
249
257
|
windowRamGbHours,
|
|
250
258
|
useOccupancy,
|
|
259
|
+
windowCpuSeconds: opts.windowCpuSeconds,
|
|
251
260
|
};
|
|
252
261
|
const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration, attributedOccMap, unitAlloc);
|
|
253
262
|
const byTenant = {};
|
|
254
263
|
const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
264
|
+
const totalCalls = list.reduce((s, u) => s + u.calls, 0);
|
|
255
265
|
for (const [tenantId, tenantMap] of this.byTenant.entries()) {
|
|
256
266
|
const tenantList = [...tenantMap.values()].filter((u) => u.calls > 0);
|
|
257
267
|
if (!tenantList.length)
|
|
258
268
|
continue;
|
|
259
269
|
const tenantBusy = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
270
|
+
const tenantShare = totalBusy > 0 ? tenantBusy / totalBusy
|
|
271
|
+
: tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls;
|
|
260
272
|
const tenantEnergy = totalBusy > 0
|
|
261
273
|
? windowEnergyKwh * (tenantBusy / totalBusy)
|
|
262
|
-
: windowEnergyKwh
|
|
274
|
+
: windowEnergyKwh * tenantShare;
|
|
263
275
|
const tenantDuration = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
264
276
|
const tenantEqual = tenantDuration <= 0;
|
|
265
|
-
const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap,
|
|
277
|
+
const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, {
|
|
278
|
+
...unitAlloc,
|
|
279
|
+
// Route occupancy cannot identify tenants sharing that route.
|
|
280
|
+
useOccupancy: false,
|
|
281
|
+
windowRamGbHours: windowRamGbHours == null ? null
|
|
282
|
+
: windowRamGbHours * tenantShare,
|
|
283
|
+
windowCpuSeconds: opts.windowCpuSeconds == null ? null
|
|
284
|
+
: opts.windowCpuSeconds * tenantShare,
|
|
285
|
+
});
|
|
266
286
|
if (!tenantUnits.length)
|
|
267
287
|
continue;
|
|
268
288
|
byTenant[tenantId] = {
|
|
@@ -286,9 +306,11 @@ export class ServiceRuntimeAggregator {
|
|
|
286
306
|
else
|
|
287
307
|
attribution = 'duration_share';
|
|
288
308
|
const attribution_detail = {
|
|
289
|
-
cpu:
|
|
290
|
-
? { method: '
|
|
291
|
-
:
|
|
309
|
+
cpu: opts.windowCpuSeconds != null
|
|
310
|
+
? { method: 'process_window_duration_share', kind: 'allocated_estimate' }
|
|
311
|
+
: measuredCpu
|
|
312
|
+
? { method: 'request_process_cpu_time', kind: 'proxy' }
|
|
313
|
+
: { method: 'request_duration_proxy', kind: 'proxy' },
|
|
292
314
|
ram: {
|
|
293
315
|
method: useOccupancy
|
|
294
316
|
? 'concurrency_normalized_active_occupancy'
|
|
@@ -303,7 +325,7 @@ export class ServiceRuntimeAggregator {
|
|
|
303
325
|
},
|
|
304
326
|
gpu: { method: 'none', kind: 'unavailable' },
|
|
305
327
|
energy: {
|
|
306
|
-
cpu_dynamic:
|
|
328
|
+
cpu_dynamic: 'duration_share',
|
|
307
329
|
memory: useOccupancy ? 'ram_occupancy_share' : 'unallocated',
|
|
308
330
|
gpu: 'none',
|
|
309
331
|
},
|
|
@@ -361,7 +383,8 @@ export class ServiceRuntimeAggregator {
|
|
|
361
383
|
this.windowStartedAt = Math.min(this.windowStartedAt, snapshot.windowStartedAt);
|
|
362
384
|
}
|
|
363
385
|
this.mergeMap(this.units, snapshot.units);
|
|
364
|
-
for (const [
|
|
386
|
+
for (const [sourceTenantId, sourceMap] of snapshot.byTenant.entries()) {
|
|
387
|
+
const tenantId = tenantBucketId(sourceTenantId, this.byTenant);
|
|
365
388
|
let targetMap = this.byTenant.get(tenantId);
|
|
366
389
|
if (!targetMap) {
|
|
367
390
|
targetMap = new Map();
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
import { type DeclaredExternalApiEntry } from './declaredExternalApis.js';
|
|
7
7
|
import { type ListCandidateSourceFilesOptions } from './projectScan.js';
|
|
8
8
|
import { type ResourceFindingCandidateV1 } from './resourceFindingCandidate.js';
|
|
9
|
-
import type
|
|
9
|
+
import { type ServiceManifestV0 } from './serviceDiscovery.js';
|
|
10
10
|
export type BuildResourceFindingsOptions = ListCandidateSourceFilesOptions & {
|
|
11
11
|
projectId?: string;
|
|
12
12
|
/** Max candidate findings to return (default 50). */
|
|
@@ -9,6 +9,7 @@ import { collectDeclaredExternalApis, dependencyMapFromPackageJson, } from './de
|
|
|
9
9
|
import { collectPreferAstHits } from './preferAstDetectors.js';
|
|
10
10
|
import { buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
|
|
11
11
|
import { toResourceFindingCandidate, } from './resourceFindingCandidate.js';
|
|
12
|
+
import { attachServiceUnitsToFindings } from './serviceDiscovery.js';
|
|
12
13
|
import { filterValidResourceFindings } from './validateResourceFinding.js';
|
|
13
14
|
import { isTypescriptAnalyzeAvailable } from './loadTypescript.js';
|
|
14
15
|
function readProjectDependencyMap(projectDir) {
|
|
@@ -66,7 +67,8 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
|
|
|
66
67
|
continue;
|
|
67
68
|
}
|
|
68
69
|
}
|
|
69
|
-
const
|
|
70
|
+
const manifest = buildServiceManifestFromPaths(projectDir, Object.keys(sources), opts);
|
|
71
|
+
const findings = attachServiceUnitsToFindings(buildResourceFindingsFromSources(sources, opts), manifest);
|
|
70
72
|
const by_mechanism = {};
|
|
71
73
|
for (const f of findings) {
|
|
72
74
|
by_mechanism[f.mechanism_id] = (by_mechanism[f.mechanism_id] || 0) + 1;
|
|
@@ -75,7 +77,6 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
|
|
|
75
77
|
sources,
|
|
76
78
|
packageDependencies: readProjectDependencyMap(projectDir),
|
|
77
79
|
});
|
|
78
|
-
const manifest = buildServiceManifestFromPaths(projectDir, Object.keys(sources), opts);
|
|
79
80
|
return {
|
|
80
81
|
schema: 'resource_analyze_result_v0',
|
|
81
82
|
contract_status: 'mp4_scaffold',
|
|
@@ -97,6 +98,7 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
|
|
|
97
98
|
'Detectors: retry_amplification, external_api_overconsumption, unbounded_parallelism, polling_or_idle_work, repeated_work, process_or_runtime_churn (subprocess + model_load), memory_retention_or_materialization, per_item_instead_of_batch (nested lookup + inference_inside_loop)',
|
|
98
99
|
`typescript AST available=${isTypescriptAnalyzeAvailable()}`,
|
|
99
100
|
'Candidates are fail-closed filtered through vendored resource_finding_v1 JSON Schema (Ajv)',
|
|
101
|
+
'Guidance is optimization.summary (schema-legal); Next App Router / Pages API fill service_manifest endpoints',
|
|
100
102
|
'Skipped RD0 context-only: http_call_without_timeout; skipped low-energy print_in_loop; skipped ML-only excess_training_work / accelerator_underutilization',
|
|
101
103
|
],
|
|
102
104
|
};
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Candidate-safe guidance for Node Analyze findings.
|
|
3
|
+
*
|
|
4
|
+
* resource_finding_v1 forbids extra top-level fields. Guidance belongs on
|
|
5
|
+
* optional ``optimization.{hypothesis_id,summary,risk}`` — never a new property.
|
|
6
|
+
* Does not upload, verify, or claim measured savings.
|
|
7
|
+
*/
|
|
8
|
+
export type MechanismGuidance = {
|
|
9
|
+
hypothesis_id: string;
|
|
10
|
+
summary: string;
|
|
11
|
+
risk: 'low' | 'medium' | 'high';
|
|
12
|
+
};
|
|
13
|
+
export declare const MECHANISM_GUIDANCE: Record<string, MechanismGuidance>;
|
|
14
|
+
export declare function optimizationForMechanism(mechanismId: string): MechanismGuidance | null;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Candidate-safe guidance for Node Analyze findings.
|
|
3
|
+
*
|
|
4
|
+
* resource_finding_v1 forbids extra top-level fields. Guidance belongs on
|
|
5
|
+
* optional ``optimization.{hypothesis_id,summary,risk}`` — never a new property.
|
|
6
|
+
* Does not upload, verify, or claim measured savings.
|
|
7
|
+
*/
|
|
8
|
+
export const MECHANISM_GUIDANCE = {
|
|
9
|
+
retry_amplification: {
|
|
10
|
+
hypothesis_id: 'cap_retries_jitter',
|
|
11
|
+
summary: 'Cap retry attempts and add exponential backoff with jitter so failed calls do not multiply paid traffic.',
|
|
12
|
+
risk: 'medium',
|
|
13
|
+
},
|
|
14
|
+
external_api_overconsumption: {
|
|
15
|
+
hypothesis_id: 'batch_or_cache_api',
|
|
16
|
+
summary: 'Batch requests, cache stable responses, or move the call outside the hot path so cost does not scale with every item.',
|
|
17
|
+
risk: 'medium',
|
|
18
|
+
},
|
|
19
|
+
unbounded_parallelism: {
|
|
20
|
+
hypothesis_id: 'limit_concurrency',
|
|
21
|
+
summary: 'Bound concurrency with a pool or semaphore so fan-out cannot exhaust sockets, workers, or provider rate limits.',
|
|
22
|
+
risk: 'high',
|
|
23
|
+
},
|
|
24
|
+
polling_or_idle_work: {
|
|
25
|
+
hypothesis_id: 'replace_poll_sleep',
|
|
26
|
+
summary: 'Replace tight poll/sleep loops with a webhook, queue, or backoff so idle wait does not burn CPU and outbound calls.',
|
|
27
|
+
risk: 'medium',
|
|
28
|
+
},
|
|
29
|
+
repeated_work: {
|
|
30
|
+
hypothesis_id: 'reuse_computed_result',
|
|
31
|
+
summary: 'Hoist or cache repeated reads and identical work so the same payload is not fetched or recomputed every iteration.',
|
|
32
|
+
risk: 'low',
|
|
33
|
+
},
|
|
34
|
+
process_or_runtime_churn: {
|
|
35
|
+
hypothesis_id: 'reuse_runtime_process',
|
|
36
|
+
summary: 'Reuse a long-lived process or loaded model instead of spawning or reloading on every request or loop iteration.',
|
|
37
|
+
risk: 'high',
|
|
38
|
+
},
|
|
39
|
+
memory_retention_or_materialization: {
|
|
40
|
+
hypothesis_id: 'stream_or_chunk',
|
|
41
|
+
summary: 'Stream or chunk the dataset instead of materializing the full collection in memory on the hot path.',
|
|
42
|
+
risk: 'medium',
|
|
43
|
+
},
|
|
44
|
+
per_item_instead_of_batch: {
|
|
45
|
+
hypothesis_id: 'batch_per_item_work',
|
|
46
|
+
summary: 'Replace per-item lookups or inference with a batched API or join so work grows with batches, not each row.',
|
|
47
|
+
risk: 'medium',
|
|
48
|
+
},
|
|
49
|
+
};
|
|
50
|
+
export function optimizationForMechanism(mechanismId) {
|
|
51
|
+
return MECHANISM_GUIDANCE[mechanismId] ?? null;
|
|
52
|
+
}
|
package/dist/analyze/index.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
export { buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, type ServiceEndpointUnit, type ServiceFileExtraction, type ServiceManifestV0, type ServiceTaskUnit, } from './serviceDiscovery.js';
|
|
2
|
-
export { buildServiceManifestFromPaths, listCandidateSourceFiles, type ListCandidateSourceFilesOptions, } from './projectScan.js';
|
|
1
|
+
export { attachServiceUnitsToFindings, buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, nextFileRoutePath, type ServiceEndpointUnit, type ServiceFileExtraction, type ServiceManifestV0, type ServiceTaskUnit, } from './serviceDiscovery.js';
|
|
2
|
+
export { DEFAULT_MAX_SOURCE_FILES, buildServiceManifestFromPaths, listCandidateSourceFiles, type ListCandidateSourceFilesOptions, } from './projectScan.js';
|
|
3
|
+
export { MECHANISM_GUIDANCE, optimizationForMechanism, type MechanismGuidance, } from './findingGuidance.js';
|
|
3
4
|
export { NON_RESOURCE_CATEGORIES, RESOURCE_DOMAINS, admitAnalyzeCandidate, isNonResourceCategory, type AdmissionDecision, type NonResourceCategory, type ResourceDomain, } from './resourceAdmission.js';
|
|
4
5
|
export { languageForPath, toResourceFindingCandidate, type ResourceCandidateHit, type ResourceFindingCandidateV1, type ResourcePrimaryDomain, } from './resourceFindingCandidate.js';
|
|
5
6
|
export { detectRetryAmplificationHits } from './retryAmplificationDetector.js';
|
package/dist/analyze/index.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
export { buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, } from './serviceDiscovery.js';
|
|
2
|
-
export { buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
|
|
1
|
+
export { attachServiceUnitsToFindings, buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, nextFileRoutePath, } from './serviceDiscovery.js';
|
|
2
|
+
export { DEFAULT_MAX_SOURCE_FILES, buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
|
|
3
|
+
export { MECHANISM_GUIDANCE, optimizationForMechanism, } from './findingGuidance.js';
|
|
3
4
|
export { NON_RESOURCE_CATEGORIES, RESOURCE_DOMAINS, admitAnalyzeCandidate, isNonResourceCategory, } from './resourceAdmission.js';
|
|
4
5
|
export { languageForPath, toResourceFindingCandidate, } from './resourceFindingCandidate.js';
|
|
5
6
|
export { detectRetryAmplificationHits } from './retryAmplificationDetector.js';
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { type ServiceManifestV0 } from './serviceDiscovery.js';
|
|
2
|
+
/** Default Analyze walk cap — large enough for Next App Router trees. */
|
|
3
|
+
export declare const DEFAULT_MAX_SOURCE_FILES = 5000;
|
|
2
4
|
export type ListCandidateSourceFilesOptions = {
|
|
3
|
-
/** Max files to return (default
|
|
5
|
+
/** Max files to return (default 5000). */
|
|
4
6
|
maxFiles?: number;
|
|
5
7
|
/** Max bytes to read per file when building a manifest (default 512 KiB). */
|
|
6
8
|
maxFileBytes?: number;
|
|
@@ -4,7 +4,10 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { readdirSync, readFileSync, statSync } from 'node:fs';
|
|
6
6
|
import { join, relative, sep } from 'node:path';
|
|
7
|
-
import { buildServiceManifest } from './serviceDiscovery.js';
|
|
7
|
+
import { buildServiceManifest, nextFileRoutePath, } from './serviceDiscovery.js';
|
|
8
|
+
/** Default Analyze walk cap — large enough for Next App Router trees. */
|
|
9
|
+
export const DEFAULT_MAX_SOURCE_FILES = 5000;
|
|
10
|
+
const WALK_SAFETY_CAP = 20_000;
|
|
8
11
|
const DEFAULT_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
|
|
9
12
|
const DEFAULT_SKIP_DIR_NAMES = new Set([
|
|
10
13
|
'node_modules',
|
|
@@ -20,17 +23,31 @@ const DEFAULT_SKIP_DIR_NAMES = new Set([
|
|
|
20
23
|
function normalizeRel(path) {
|
|
21
24
|
return path.split(sep).join('/');
|
|
22
25
|
}
|
|
26
|
+
function scanRank(rel) {
|
|
27
|
+
const n = rel.replace(/\\/g, '/');
|
|
28
|
+
if (nextFileRoutePath(n))
|
|
29
|
+
return 0;
|
|
30
|
+
if (n.startsWith('app/') ||
|
|
31
|
+
n.startsWith('src/app/') ||
|
|
32
|
+
n.startsWith('pages/') ||
|
|
33
|
+
n.startsWith('src/pages/')) {
|
|
34
|
+
return 1;
|
|
35
|
+
}
|
|
36
|
+
if (n.startsWith('src/'))
|
|
37
|
+
return 2;
|
|
38
|
+
return 3;
|
|
39
|
+
}
|
|
23
40
|
/**
|
|
24
41
|
* List repo-relative JS/TS source paths under ``projectDir`` (bounded).
|
|
25
42
|
* Never throws — returns [] on errors.
|
|
26
43
|
*/
|
|
27
44
|
export function listCandidateSourceFiles(projectDir, opts = {}) {
|
|
28
|
-
const maxFiles = Math.max(1, opts.maxFiles ??
|
|
45
|
+
const maxFiles = Math.max(1, opts.maxFiles ?? DEFAULT_MAX_SOURCE_FILES);
|
|
29
46
|
const extensions = new Set([...(opts.extensions ?? DEFAULT_EXTENSIONS)].map((e) => e.toLowerCase()));
|
|
30
47
|
const skip = new Set([...(opts.skipDirNames ?? DEFAULT_SKIP_DIR_NAMES)].map((n) => n.toLowerCase()));
|
|
31
48
|
const out = [];
|
|
32
49
|
const walk = (absDir) => {
|
|
33
|
-
if (out.length >=
|
|
50
|
+
if (out.length >= WALK_SAFETY_CAP)
|
|
34
51
|
return;
|
|
35
52
|
let entries;
|
|
36
53
|
try {
|
|
@@ -40,7 +57,7 @@ export function listCandidateSourceFiles(projectDir, opts = {}) {
|
|
|
40
57
|
return;
|
|
41
58
|
}
|
|
42
59
|
for (const entry of entries) {
|
|
43
|
-
if (out.length >=
|
|
60
|
+
if (out.length >= WALK_SAFETY_CAP)
|
|
44
61
|
return;
|
|
45
62
|
const name = entry.name;
|
|
46
63
|
if (name.startsWith('.') && name !== '.env.example') {
|
|
@@ -76,7 +93,8 @@ export function listCandidateSourceFiles(projectDir, opts = {}) {
|
|
|
76
93
|
return [];
|
|
77
94
|
}
|
|
78
95
|
walk(projectDir);
|
|
79
|
-
|
|
96
|
+
out.sort((a, b) => scanRank(a) - scanRank(b) || a.localeCompare(b));
|
|
97
|
+
return out.slice(0, maxFiles);
|
|
80
98
|
}
|
|
81
99
|
/**
|
|
82
100
|
* Read supplied repo-relative paths (or auto-walk) and build ``service_manifest_v0``.
|
|
@@ -102,10 +120,15 @@ export function buildServiceManifestFromPaths(projectDir, relPaths, opts = {}) {
|
|
|
102
120
|
}
|
|
103
121
|
}
|
|
104
122
|
const manifest = buildServiceManifest(sources);
|
|
123
|
+
const scanned = Object.keys(sources).length;
|
|
124
|
+
const maxFiles = Math.max(1, opts.maxFiles ?? DEFAULT_MAX_SOURCE_FILES);
|
|
105
125
|
manifest.notes = [
|
|
106
126
|
...manifest.notes,
|
|
107
|
-
`scanned_files=${
|
|
127
|
+
`scanned_files=${scanned}`,
|
|
108
128
|
relPaths ? 'paths=explicit' : 'paths=auto_walk',
|
|
129
|
+
...(!relPaths && scanned >= maxFiles
|
|
130
|
+
? [`scan_truncated=true max_files=${maxFiles}`]
|
|
131
|
+
: []),
|
|
109
132
|
];
|
|
110
133
|
return manifest;
|
|
111
134
|
}
|
|
@@ -36,6 +36,12 @@ export type ResourceFindingCandidateV1 = {
|
|
|
36
36
|
observation_ids: string[];
|
|
37
37
|
benchmark_result_ids: string[];
|
|
38
38
|
};
|
|
39
|
+
/** Optional candidate guidance — schema-legal subset of resource_finding_v1.optimization. */
|
|
40
|
+
optimization?: {
|
|
41
|
+
hypothesis_id: string;
|
|
42
|
+
summary: string;
|
|
43
|
+
risk: 'low' | 'medium' | 'high';
|
|
44
|
+
};
|
|
39
45
|
};
|
|
40
46
|
export type ResourceCandidateHit = {
|
|
41
47
|
mechanism_id: string;
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* change RunSession, and does not claim Optimize / verified savings.
|
|
6
6
|
*/
|
|
7
7
|
import { createHash } from 'node:crypto';
|
|
8
|
+
import { optimizationForMechanism } from './findingGuidance.js';
|
|
8
9
|
import { admitAnalyzeCandidate } from './resourceAdmission.js';
|
|
9
10
|
const POLICY_VERSION = '0.1.0';
|
|
10
11
|
function languageFromPath(relPath) {
|
|
@@ -36,6 +37,7 @@ export function toResourceFindingCandidate(hit, projectId = 'local') {
|
|
|
36
37
|
return null;
|
|
37
38
|
const language = hit.language || languageFromPath(hit.rel_path);
|
|
38
39
|
const scopeId = (hit.symbol || hit.rel_path).slice(0, 200);
|
|
40
|
+
const guidance = optimizationForMechanism(hit.mechanism_id);
|
|
39
41
|
return {
|
|
40
42
|
schema_version: 'resource_finding_v1',
|
|
41
43
|
finding_id: stableFindingId(hit, projectId).slice(0, 128),
|
|
@@ -68,6 +70,15 @@ export function toResourceFindingCandidate(hit, projectId = 'local') {
|
|
|
68
70
|
observation_ids: [],
|
|
69
71
|
benchmark_result_ids: [],
|
|
70
72
|
},
|
|
73
|
+
...(guidance
|
|
74
|
+
? {
|
|
75
|
+
optimization: {
|
|
76
|
+
hypothesis_id: guidance.hypothesis_id.slice(0, 64),
|
|
77
|
+
summary: guidance.summary.slice(0, 400),
|
|
78
|
+
risk: guidance.risk,
|
|
79
|
+
},
|
|
80
|
+
}
|
|
81
|
+
: {}),
|
|
71
82
|
};
|
|
72
83
|
}
|
|
73
84
|
export function languageForPath(relPath) {
|
|
@@ -54,8 +54,13 @@ export type ServiceManifestV0 = {
|
|
|
54
54
|
};
|
|
55
55
|
notes: string[];
|
|
56
56
|
};
|
|
57
|
+
/**
|
|
58
|
+
* HTTP path implied by a Next.js App Router ``route`` file or Pages ``pages/api`` file.
|
|
59
|
+
* Route groups ``(marketing)`` and parallel slots ``@modal`` are dropped.
|
|
60
|
+
*/
|
|
61
|
+
export declare function nextFileRoutePath(relPath: string): string | null;
|
|
57
62
|
/** Frameworks whose imports / requires appear in ``source``. */
|
|
58
|
-
export declare function detectFrameworks(source: string): string[];
|
|
63
|
+
export declare function detectFrameworks(source: string, relPath?: string): string[];
|
|
59
64
|
/**
|
|
60
65
|
* Extract service units from one JS/TS source string.
|
|
61
66
|
* Never throws on bad source — returns empty collections.
|
|
@@ -64,3 +69,20 @@ export declare function extractServiceUnits(sourceCode: string, relPath?: string
|
|
|
64
69
|
/** Project-level ``service_manifest_v0`` from ``{relPath: source}``. */
|
|
65
70
|
export declare function buildServiceManifest(fileSources: Record<string, string>): ServiceManifestV0;
|
|
66
71
|
export declare function isServiceProject(manifest: ServiceManifestV0): boolean;
|
|
72
|
+
type FindingScope = {
|
|
73
|
+
kind: 'function' | 'service_unit' | 'task' | 'script';
|
|
74
|
+
id: string;
|
|
75
|
+
source_locations: Array<{
|
|
76
|
+
path: string;
|
|
77
|
+
start_line: number;
|
|
78
|
+
end_line: number;
|
|
79
|
+
}>;
|
|
80
|
+
};
|
|
81
|
+
/**
|
|
82
|
+
* Attribute a finding to the owning endpoint/task when the file+line is unambiguous.
|
|
83
|
+
* Same rule as Python ``attach_service_units``: innermost span, else sole unit on the file.
|
|
84
|
+
*/
|
|
85
|
+
export declare function attachServiceUnitsToFindings<T extends {
|
|
86
|
+
scope: FindingScope;
|
|
87
|
+
}>(findings: T[], manifest: ServiceManifestV0): T[];
|
|
88
|
+
export {};
|