@netgreener/runtime 0.1.8 → 0.1.10
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 +12 -0
- package/TUTORIAL.md +120 -29
- package/dist/aggregator.d.ts +12 -2
- package/dist/aggregator.js +135 -8
- package/dist/analyze/buildResourceFindings.d.ts +4 -0
- package/dist/analyze/buildResourceFindings.js +17 -0
- package/dist/analyze/cli.d.ts +1 -0
- package/dist/analyze/cli.js +22 -1
- package/dist/analyze/declaredExternalApis.d.ts +31 -0
- package/dist/analyze/declaredExternalApis.js +174 -0
- package/dist/analyze/index.d.ts +1 -0
- package/dist/analyze/index.js +1 -0
- package/dist/auto.d.ts +7 -0
- package/dist/auto.js +8 -0
- package/dist/bullmq.d.ts +2 -2
- package/dist/bullmq.js +28 -58
- package/dist/carbonLedger.d.ts +28 -0
- package/dist/carbonLedger.js +52 -0
- package/dist/cgroupV2.d.ts +44 -0
- package/dist/cgroupV2.js +174 -0
- package/dist/cli/helpText.d.ts +3 -3
- package/dist/cli/helpText.js +42 -35
- package/dist/cli/netgreener.d.ts +7 -7
- package/dist/cli/netgreener.js +23 -16
- package/dist/cli/runCli.d.ts +20 -0
- package/dist/cli/runCli.js +249 -0
- package/dist/cli/runPreload.d.ts +5 -0
- package/dist/cli/runPreload.js +43 -0
- package/dist/collectorMetadata.d.ts +1 -1
- package/dist/collectorMetadata.js +2 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +6 -2
- package/dist/exporter.d.ts +7 -2
- package/dist/exporter.js +12 -6
- package/dist/express.js +17 -6
- package/dist/externalApiMeter.d.ts +51 -2
- package/dist/externalApiMeter.js +379 -26
- package/dist/fastify.js +17 -6
- package/dist/index.d.ts +12 -2
- package/dist/index.js +11 -1
- package/dist/init.d.ts +30 -0
- package/dist/init.js +31 -0
- package/dist/lifecycle.d.ts +45 -0
- package/dist/lifecycle.js +112 -0
- package/dist/managedCollectorLauncher.d.ts +37 -0
- package/dist/managedCollectorLauncher.js +162 -0
- package/dist/mcpToolMeter.d.ts +101 -0
- package/dist/mcpToolMeter.js +496 -0
- package/dist/n4/deploymentMatrix.d.ts +9 -5
- package/dist/n4/deploymentMatrix.js +13 -9
- package/dist/n4/missingnessInventory.js +3 -3
- package/dist/next.d.ts +89 -0
- package/dist/next.js +328 -0
- package/dist/nextConfig.d.ts +34 -0
- package/dist/nextConfig.js +73 -0
- package/dist/nextEntryTransform.d.ts +9 -0
- package/dist/nextEntryTransform.js +181 -0
- package/dist/occupancyTracker.d.ts +27 -0
- package/dist/occupancyTracker.js +87 -0
- package/dist/optimize/apply.d.ts +38 -0
- package/dist/optimize/apply.js +173 -0
- package/dist/optimize/cli.d.ts +26 -0
- package/dist/optimize/cli.js +323 -0
- package/dist/optimize/index.d.ts +6 -0
- package/dist/optimize/index.js +5 -0
- package/dist/optimize/llmApply.d.ts +22 -0
- package/dist/optimize/llmApply.js +80 -0
- package/dist/optimize/llmSession.d.ts +88 -0
- package/dist/optimize/llmSession.js +135 -0
- package/dist/optimize/provider.d.ts +17 -0
- package/dist/optimize/provider.js +119 -0
- package/dist/optimize/safePatches.d.ts +18 -0
- package/dist/optimize/safePatches.js +247 -0
- package/dist/optimize/types.d.ts +79 -0
- package/dist/optimize/types.js +6 -0
- package/dist/optimize/verification.d.ts +16 -0
- package/dist/optimize/verification.js +165 -0
- package/dist/processResources.d.ts +5 -0
- package/dist/processResources.js +28 -4
- package/dist/processRuntime.js +7 -28
- package/dist/processTree.d.ts +47 -0
- package/dist/processTree.js +148 -0
- package/dist/runContextEnrichment.d.ts +11 -0
- package/dist/runContextEnrichment.js +92 -0
- package/dist/runtime.d.ts +36 -1
- package/dist/runtime.js +140 -17
- package/dist/sdk/client.d.ts +152 -0
- package/dist/sdk/client.js +396 -0
- package/dist/sdk/gitUrl.d.ts +6 -0
- package/dist/sdk/gitUrl.js +87 -0
- package/dist/sdk/index.d.ts +5 -0
- package/dist/sdk/index.js +5 -0
- package/dist/serverlessHints.d.ts +9 -6
- package/dist/serverlessHints.js +10 -7
- package/dist/taskMeter.d.ts +14 -0
- package/dist/taskMeter.js +53 -0
- package/dist/types.d.ts +43 -0
- package/examples/aca-container-gate/Dockerfile +20 -0
- package/examples/aca-container-gate/azure-container-app.yaml +27 -0
- package/examples/aca-container-gate/gate.env +7 -0
- package/examples/aca-container-gate/server.mjs +117 -0
- package/examples/azure-functions-gate/.funcignore +6 -0
- package/examples/azure-functions-gate/README.md +25 -0
- package/examples/azure-functions-gate/host.json +15 -0
- package/examples/azure-functions-gate/package-lock.json +161 -0
- package/examples/azure-functions-gate/package.json +14 -0
- package/examples/azure-functions-gate/src/functions/health.js +27 -0
- package/examples/express-local-live-smoke.mjs +127 -0
- package/examples/extractRunId.mjs +11 -0
- package/examples/next-pilot-dry-run.mjs +32 -0
- package/examples/serverless-thin-gate.mjs +89 -0
- package/fixtures/run-smoke/hello.mjs +4 -0
- package/loaders/next-entry-loader.cjs +14 -0
- package/package.json +25 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog — @netgreener/runtime
|
|
2
2
|
|
|
3
|
+
## [0.1.10] — 2026-10-19
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- Next.js config wrapper and `loaders/next-entry-loader.cjs` for App Router route, page, and server-action observation
|
|
7
|
+
- Ephemeral invoke flush after the response closes
|
|
8
|
+
- `calls_unknown` on external API rows when a call has no token usage
|
|
9
|
+
|
|
10
|
+
## [0.1.9] — 2026-10-12
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- Public export `@netgreener/runtime/next`
|
|
14
|
+
|
|
3
15
|
## [0.1.8] — 2026-09-27
|
|
4
16
|
|
|
5
17
|
### Fixed
|
package/TUTORIAL.md
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
**Twin of:** [`SERVICE_RUNTIME_TUTORIAL.md`](../docs/SERVICE_RUNTIME_TUTORIAL.md)
|
|
4
4
|
**§4–§6** (FastAPI / Celery / process wrap).
|
|
5
|
-
**Package:** `@netgreener/runtime` (
|
|
6
|
-
**
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
**Package:** `@netgreener/runtime` (public npm; see [`PRODUCTION_DOCS.md`](PRODUCTION_DOCS.md)).
|
|
6
|
+
**Governed label:** **Node.js Runtime production** (N10 issued 2026-10-02).
|
|
7
|
+
**Still not claimed:** default collector cutover; container/K8s; cgroup as production claim.
|
|
8
|
+
**Opt-in (DevOps):** `NETGREENER_COLLECTOR_MODE=managed` — same idea as Python Celery (§7).
|
|
9
9
|
|
|
10
10
|
| Need deeper reference | Doc |
|
|
11
11
|
|-----------------------|-----|
|
|
@@ -14,7 +14,9 @@ without your retained evidence.
|
|
|
14
14
|
| Package status / CI | [`README.md`](README.md), [`ROADMAP.md`](ROADMAP.md) |
|
|
15
15
|
| Tenant dogfood | [`NODE_TENANT_DOGFOOD.md`](../docs/NODE_TENANT_DOGFOOD.md) |
|
|
16
16
|
| Service tokens | [`CI_SERVICE_TOKEN_ONBOARDING.md`](../docs/CI_SERVICE_TOKEN_ONBOARDING.md) |
|
|
17
|
-
| Python twin | [`SERVICE_RUNTIME_TUTORIAL.md`](../docs/SERVICE_RUNTIME_TUTORIAL.md) |
|
|
17
|
+
| Python twin (Celery managed) | [`SERVICE_RUNTIME_TUTORIAL.md`](../docs/SERVICE_RUNTIME_TUTORIAL.md) · [`SERVICE_RUNTIME_INTEGRATION.md`](../docs/SERVICE_RUNTIME_INTEGRATION.md) |
|
|
18
|
+
| Optimize / LLM apply gates | [`OPTIMIZE_STUB.md`](OPTIMIZE_STUB.md) |
|
|
19
|
+
| Owner publish commands (CLI / npm / VSIX) | [`OWNER_PUBLISH_COMMANDS.md`](../docs/OWNER_PUBLISH_COMMANDS.md) |
|
|
18
20
|
|
|
19
21
|
---
|
|
20
22
|
|
|
@@ -26,18 +28,26 @@ without your retained evidence.
|
|
|
26
28
|
| **Fastify** HTTP API | Per-**route** KPIs | `netgreenerFastifyPlugin` | **Yes — one `register`** (§4) |
|
|
27
29
|
| **Nest** | Express or Fastify under the hood | `applyNetGreenerNestHooks(app)` | **Yes — one hook** (§4) |
|
|
28
30
|
| **BullMQ** worker | Per-**task** KPIs | `netgreenerBullMqProcessor` | **Yes — wrap the processor** (§5) |
|
|
29
|
-
| **Script / cron / batch** `node …` | Process window + outbound `fetch` | `startProcessRuntime` / `runWithProcessTenant` | **Yes — start helper** (§6) |
|
|
31
|
+
| **Script / cron / batch** `node …` | Process window + outbound `fetch` | `startProcessRuntime` / `runWithProcessTenant` / `netgreener run` | **Yes — start helper or CLI** (§6–§7) |
|
|
32
|
+
|
|
33
|
+
### Who should touch which env vars?
|
|
34
|
+
|
|
35
|
+
| Audience | Use | Ignore unless DevOps asks |
|
|
36
|
+
|----------|-----|---------------------------|
|
|
37
|
+
| **App developer** (Express/Fastify/Nest) | Token, project id, `SERVICE_RUNTIME=1` | `COLLECTOR_MODE`, `EXPORT_MODE=collector` |
|
|
38
|
+
| **DevOps / platform** | Workers needing durable spool | `NETGREENER_COLLECTOR_MODE=managed` (Python Celery twin; Node `netgreener run`) |
|
|
30
39
|
|
|
31
40
|
Default upload mode remains **`NETGREENER_EXPORT_MODE=direct`**. Sibling collector
|
|
32
|
-
IPC
|
|
41
|
+
IPC and managed mode are **opt-in only**; we do not cut over the default.
|
|
33
42
|
|
|
34
43
|
```text
|
|
35
|
-
HTTP: middleware/plugin → window → POST /api/v1/runsessions/ (default direct
|
|
36
|
-
BullMQ: wrapped processor → window → same
|
|
37
|
-
Process: startProcessRuntime → window →
|
|
44
|
+
HTTP: middleware/plugin → window → POST /api/v1/runsessions/ (default direct)
|
|
45
|
+
BullMQ: wrapped processor → window → same direct path (default)
|
|
46
|
+
Process: startProcessRuntime / netgreener run → window → direct (default)
|
|
38
47
|
|
|
39
|
-
Opt-in: NETGREENER_EXPORT_MODE=collector →
|
|
40
|
-
|
|
48
|
+
Opt-in: NETGREENER_EXPORT_MODE=collector → IPC → sibling collector (you start collector)
|
|
49
|
+
Opt-in: NETGREENER_COLLECTOR_MODE=managed → NetGreener starts+drains collector for you
|
|
50
|
+
(Python: Celery launcher; Node: netgreener run)
|
|
41
51
|
```
|
|
42
52
|
|
|
43
53
|
---
|
|
@@ -74,15 +84,12 @@ Find **ORG_ID** / **PROJECT_ID** in the NetGreener dashboard (project URL looks
|
|
|
74
84
|
|
|
75
85
|
## 3. Install `@netgreener/runtime` in that project
|
|
76
86
|
|
|
77
|
-
The package is **private** today (Azure DevOps / internal registry). Install from your
|
|
78
|
-
approved feed or path — there is **no** public npm publish yet.
|
|
79
|
-
|
|
80
87
|
```bash
|
|
81
|
-
# Example once the private feed is configured for your project:
|
|
82
88
|
npm install @netgreener/runtime
|
|
83
89
|
```
|
|
84
90
|
|
|
85
|
-
|
|
91
|
+
Requires Node.js **22** or **24** (see `package.json` `engines`). For install /
|
|
92
|
+
upgrade / claimed limits, see [`PRODUCTION_DOCS.md`](PRODUCTION_DOCS.md).
|
|
86
93
|
|
|
87
94
|
Verify the import resolves:
|
|
88
95
|
|
|
@@ -261,9 +268,9 @@ Worker/process twins: §5.5 / §6.1. Local proofs:
|
|
|
261
268
|
## 5. BullMQ — any worker project (Part 5 twin)
|
|
262
269
|
|
|
263
270
|
Unlike Python Celery (entrypoint wrap, often **no** task code changes), Node BullMQ
|
|
264
|
-
v0 meters by **wrapping the processor** you already pass to `Worker`.
|
|
265
|
-
|
|
266
|
-
|
|
271
|
+
v0 meters by **wrapping the processor** you already pass to `Worker`. Default remains
|
|
272
|
+
**direct** flush from the worker process. For a **managed** sibling collector (Python
|
|
273
|
+
Celery twin), see §7 — opt-in DevOps only; not required for BullMQ KPIs.
|
|
267
274
|
|
|
268
275
|
### 5.1 Wrap the processor (required for task KPIs)
|
|
269
276
|
|
|
@@ -373,13 +380,96 @@ yet; call `startProcessRuntime` from your entry file (or a thin launcher you own
|
|
|
373
380
|
### 6.1 Opt-in sibling collector (process → MP2 IPC)
|
|
374
381
|
|
|
375
382
|
Same env as §4.5 / §5.5. Flush via `flushProcessRuntime('manual')` or shutdown.
|
|
376
|
-
IPC payload uses `collector: node_process`.
|
|
377
|
-
|
|
378
|
-
|
|
383
|
+
IPC payload uses `collector: node_process`. For **NetGreener-started** collector
|
|
384
|
+
lifecycle (Python Celery twin), use §7 instead of manually starting the sibling.
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## 7. Managed collector — `NETGREENER_COLLECTOR_MODE=managed` (opt-in)
|
|
389
|
+
|
|
390
|
+
**Same idea as Python Celery** (`docs/SERVICE_RUNTIME_INTEGRATION.md`): NetGreener
|
|
391
|
+
starts and drains a sibling `python -m netgreener.collector_server`, and the Node
|
|
392
|
+
child exports with `NETGREENER_EXPORT_MODE=collector`.
|
|
393
|
+
|
|
394
|
+
### Who needs this?
|
|
395
|
+
|
|
396
|
+
| You are… | Recommendation |
|
|
397
|
+
|----------|----------------|
|
|
398
|
+
| Wiring Express / Fastify / Nest | **Skip** — leave unset; use default **direct** |
|
|
399
|
+
| Running BullMQ with default path | **Skip** unless platform asks for durable spool |
|
|
400
|
+
| DevOps wrapping `netgreener run` / workers | **Optional** — set `managed` when you want supervised collector |
|
|
401
|
+
|
|
402
|
+
### Example (`netgreener run`)
|
|
403
|
+
|
|
404
|
+
```powershell
|
|
405
|
+
$env:NETGREENER_SERVICE_RUNTIME = "1"
|
|
406
|
+
$env:NETGREENER_TOKEN = "ngs_…" # kept on collector; stripped from child by default
|
|
407
|
+
$env:NETGREENER_PROJECT_ID = "97"
|
|
408
|
+
$env:NETGREENER_COLLECTOR_MODE = "managed"
|
|
409
|
+
# optional: $env:NETGREENER_COLLECTOR_ENDPOINT = "tcp://127.0.0.1:17999"
|
|
410
|
+
netgreener run .\jobs\report.mjs .
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Requires Python with `netgreener.collector_server` importable. Windows: **`tcp://` only**.
|
|
414
|
+
|
|
415
|
+
When the Node child flushes with `EXPORT_MODE=collector`, IPC includes `emitter_pid`.
|
|
416
|
+
The collector attaches an honest **`collector_resource_sample_v0`** (process-tree via
|
|
417
|
+
psutil; cgroup v2 on Linux only) onto `session_metadata` — it does **not** erase
|
|
418
|
+
Node `node_process_*` provenance. Disable with
|
|
419
|
+
`NETGREENER_COLLECTOR_ENRICH_RESOURCES=0`.
|
|
420
|
+
|
|
421
|
+
Default package / unset mode remains **direct**. Managed does **not** change N10
|
|
422
|
+
production claim wording by itself.
|
|
423
|
+
|
|
424
|
+
### CI / dogfood (no upload)
|
|
425
|
+
|
|
426
|
+
```powershell
|
|
427
|
+
# Module honesty (Linux tree/cgroup; Windows unavailable = PASS)
|
|
428
|
+
npm run example:n5b-linux-gate
|
|
429
|
+
|
|
430
|
+
# Live flush → collector enrich (needs sibling ../netgreener_cli or NETGREENER_CLI_ROOT)
|
|
431
|
+
# Linux CI sets NETGREENER_N5B_REQUIRE_FLUSH=1
|
|
432
|
+
npm run example:n5b-flush-dogfood
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
Artifact: `artifacts/n5b-flush/latest.json`. Azure job: `n5b_flush_dogfood`.
|
|
436
|
+
|
|
437
|
+
---
|
|
438
|
+
|
|
439
|
+
## 7b. Optimize, LLM apply-verified, Investigate (parity)
|
|
440
|
+
|
|
441
|
+
Default optimize stays **local** (no LLM, no upload). Same `api_server` brain when you opt in.
|
|
442
|
+
|
|
443
|
+
### CLI
|
|
444
|
+
|
|
445
|
+
```powershell
|
|
446
|
+
# Local proposals (+ optional deterministic safe apply)
|
|
447
|
+
netgreener optimize .\my-app
|
|
448
|
+
netgreener optimize .\my-app --apply --skip-test
|
|
449
|
+
|
|
450
|
+
# Shared LLM session (review JSON)
|
|
451
|
+
$env:NETGREENER_TOKEN = "ngs_…"
|
|
452
|
+
netgreener optimize .\my-app --llm --project-id 97
|
|
453
|
+
|
|
454
|
+
# LLM splice writes — VerificationProvider before/after (NOT the same as --apply)
|
|
455
|
+
netgreener optimize .\my-app --llm --apply-verified --project-id 97 --skip-test
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
`--llm` + `--apply` is rejected on purpose. Use `--apply-verified` for LLM writes.
|
|
459
|
+
|
|
460
|
+
### VS Code (Node workspace)
|
|
461
|
+
|
|
462
|
+
| Command | Path |
|
|
463
|
+
|---------|------|
|
|
464
|
+
| **Plan Optimizations** | QuickPick: LLM plan · **LLM apply-verified (CLI)** · Local Node Optimize |
|
|
465
|
+
| **Investigate Anomaly Brief** | Claim brief → `.netgreener/anomaly-investigation.json` → scoped Analyze |
|
|
466
|
+
| URI | `vscode://netgreener.netgreener-vscode-extension/anomalyBrief?briefId=…` |
|
|
467
|
+
|
|
468
|
+
Does **not** flip `EXPORT_MODE`. Does **not** invent measured savings.
|
|
379
469
|
|
|
380
470
|
---
|
|
381
471
|
|
|
382
|
-
##
|
|
472
|
+
## 8. Common failures
|
|
383
473
|
|
|
384
474
|
| Symptom | Check |
|
|
385
475
|
|---------|--------|
|
|
@@ -390,12 +480,13 @@ sampler or CLI launcher — those remain MP3. Proof lives in
|
|
|
390
480
|
| Tenant missing after auth (Fastify) | Use `bindFastifyTenant(request, …)` |
|
|
391
481
|
| BullMQ jobs invisible | Processor must be wrapped with `netgreenerBullMqProcessor` |
|
|
392
482
|
| BullMQ tenant missing | `NETGREENER_TENANT_SOURCE=task_kwarg` + kwarg in `job.data` |
|
|
393
|
-
| Package not found on npm |
|
|
394
|
-
|
|
|
483
|
+
| Package not found on npm | Check `@netgreener/runtime` install / registry access |
|
|
484
|
+
| Managed collector fails to start | Python `netgreener.collector_server` on PATH; Windows needs `tcp://` |
|
|
485
|
+
| Serverless / Lambda freezes mid-window | Use thin-flush (§10); flush at invoke end; durability is best-effort |
|
|
395
486
|
|
|
396
487
|
---
|
|
397
488
|
|
|
398
|
-
##
|
|
489
|
+
## 9. Minimal copy-paste canaries
|
|
399
490
|
|
|
400
491
|
**Express dry-run:** middleware + `/health` + `NETGREENER_RUNTIME_DRY_RUN=1` +
|
|
401
492
|
`getExpressRuntime().flush('manual')`.
|
|
@@ -410,7 +501,7 @@ sampler or CLI launcher — those remain MP3. Proof lives in
|
|
|
410
501
|
|
|
411
502
|
---
|
|
412
503
|
|
|
413
|
-
##
|
|
504
|
+
## 10. Thin-flush / serverless mode
|
|
414
505
|
|
|
415
506
|
Long-running VM / container / K8s Node should keep default **`direct`** or opt-in
|
|
416
507
|
**`collector`** (§4.5). Serverless hosts often cannot run a durable sibling collector.
|
|
@@ -475,7 +566,7 @@ flipping the default off `direct` for long-running Node.
|
|
|
475
566
|
|
|
476
567
|
---
|
|
477
568
|
|
|
478
|
-
##
|
|
569
|
+
## 11. Stop here (honesty)
|
|
479
570
|
|
|
480
571
|
This tutorial does **not** by itself:
|
|
481
572
|
- publish `@netgreener/runtime` to npm
|
package/dist/aggregator.d.ts
CHANGED
|
@@ -17,6 +17,8 @@ export declare class ServiceRuntimeAggregator {
|
|
|
17
17
|
peakRssKb?: number;
|
|
18
18
|
}): void;
|
|
19
19
|
private recordIntoMap;
|
|
20
|
+
/** Peak RSS (KiB) across units with calls — for crude window RAM estimate. */
|
|
21
|
+
maxPeakRssKb(): number;
|
|
20
22
|
private buildUnitsList;
|
|
21
23
|
hasData(): boolean;
|
|
22
24
|
totalDurationMs(): number;
|
|
@@ -27,14 +29,22 @@ export declare class ServiceRuntimeAggregator {
|
|
|
27
29
|
/** True when any unit recorded peak RSS. */
|
|
28
30
|
hasMeasuredRss(): boolean;
|
|
29
31
|
/**
|
|
30
|
-
* Build service_runtime_v0.
|
|
31
|
-
*
|
|
32
|
+
* Build service_runtime_v0.
|
|
33
|
+
* When occupancy snapshot is present → ``cpu_and_occupancy_v1`` (anomaly evidence).
|
|
34
|
+
* Occupancy is window-scaled (Python twin) so coverage reconciles to ``window_seconds``.
|
|
32
35
|
*/
|
|
33
36
|
buildV0(opts: {
|
|
34
37
|
collector: string;
|
|
35
38
|
framework: string;
|
|
36
39
|
windowEnergyKwh: number;
|
|
37
40
|
windowSeconds: number;
|
|
41
|
+
/** Crude window RAM (GiB·h); split by occupancy share when present. */
|
|
42
|
+
windowRamGbHours?: number | null;
|
|
43
|
+
occupancy?: {
|
|
44
|
+
by_unit: Record<string, number>;
|
|
45
|
+
in_flight_seconds: number;
|
|
46
|
+
idle_seconds: number;
|
|
47
|
+
} | null;
|
|
38
48
|
}): ServiceRuntimeV0 | null;
|
|
39
49
|
/** Take a snapshot and reset live window (Python take_snapshot analogue). */
|
|
40
50
|
takeSnapshot(): ServiceRuntimeAggregator;
|
package/dist/aggregator.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { energyKwhToCarbonG } from './carbonLedger.js';
|
|
1
2
|
const MAX_UNITS = 500;
|
|
2
3
|
const MAX_SERVICE_UNIT_LEN = 256;
|
|
3
4
|
function normalizeServiceUnit(raw) {
|
|
@@ -76,11 +77,25 @@ export class ServiceRuntimeAggregator {
|
|
|
76
77
|
unit.peakRssKbMax = Math.max(unit.peakRssKbMax, rss);
|
|
77
78
|
}
|
|
78
79
|
}
|
|
79
|
-
|
|
80
|
+
/** Peak RSS (KiB) across units with calls — for crude window RAM estimate. */
|
|
81
|
+
maxPeakRssKb() {
|
|
82
|
+
let max = 0;
|
|
83
|
+
for (const u of this.units.values()) {
|
|
84
|
+
if (u.calls > 0 && u.peakRssKbMax > max)
|
|
85
|
+
max = u.peakRssKbMax;
|
|
86
|
+
}
|
|
87
|
+
return max;
|
|
88
|
+
}
|
|
89
|
+
buildUnitsList(source, windowEnergyKwh, equalShare, totalDuration, occByUnit, alloc) {
|
|
80
90
|
const list = [...source.values()].filter((u) => u.calls > 0);
|
|
81
91
|
if (!list.length)
|
|
82
92
|
return [];
|
|
83
93
|
const energyBudget = nonNegativeFinite(windowEnergyKwh);
|
|
94
|
+
const windowSeconds = nonNegativeFinite(alloc?.windowSeconds ?? 0);
|
|
95
|
+
const windowRam = alloc?.windowRamGbHours != null
|
|
96
|
+
? nonNegativeFinite(alloc.windowRamGbHours)
|
|
97
|
+
: null;
|
|
98
|
+
const useOccupancy = Boolean(alloc?.useOccupancy);
|
|
84
99
|
const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
|
|
85
100
|
const units = sorted.map((u) => {
|
|
86
101
|
const share = equalShare ? 1 / list.length : u.durationMsTotal / totalDuration;
|
|
@@ -96,7 +111,7 @@ export class ServiceRuntimeAggregator {
|
|
|
96
111
|
errors: u.errors,
|
|
97
112
|
cpu_seconds_total: Math.round(cpuSeconds * 10000) / 10000,
|
|
98
113
|
energy_kwh: energy,
|
|
99
|
-
carbon_g: energy
|
|
114
|
+
carbon_g: energyKwhToCarbonG(energy).carbonG,
|
|
100
115
|
duration_ms: {
|
|
101
116
|
avg: Math.round(avg * 100) / 100,
|
|
102
117
|
max: Math.round(u.durationMsMax * 100) / 100,
|
|
@@ -105,13 +120,22 @@ export class ServiceRuntimeAggregator {
|
|
|
105
120
|
if (u.peakRssKbMax > 0) {
|
|
106
121
|
unit.peak_rss_kb_max = Math.round(u.peakRssKbMax);
|
|
107
122
|
}
|
|
123
|
+
const occ = occByUnit?.[u.serviceUnit];
|
|
124
|
+
const occS = occ != null && occ > 0 ? occ : 0;
|
|
125
|
+
if (occS > 0) {
|
|
126
|
+
unit.occupancy_seconds = Math.round(occS * 1e6) / 1e6;
|
|
127
|
+
}
|
|
128
|
+
if (windowRam != null) {
|
|
129
|
+
const occShare = useOccupancy && windowSeconds > 0 ? occS / windowSeconds : share;
|
|
130
|
+
unit.ram_gb_hours = Math.round(windowRam * occShare * 1e6) / 1e6;
|
|
131
|
+
}
|
|
108
132
|
return unit;
|
|
109
133
|
});
|
|
110
134
|
const allocatedRaw = units.reduce((s, u) => s + u.energy_kwh, 0);
|
|
111
135
|
const drift = energyBudget - allocatedRaw;
|
|
112
136
|
if (units.length && Math.abs(drift) > 0) {
|
|
113
137
|
units[0].energy_kwh += drift;
|
|
114
|
-
units[0].carbon_g = units[0].energy_kwh
|
|
138
|
+
units[0].carbon_g = energyKwhToCarbonG(units[0].energy_kwh).carbonG;
|
|
115
139
|
}
|
|
116
140
|
for (const u of units) {
|
|
117
141
|
u.energy_kwh = Math.round(u.energy_kwh * 1e12) / 1e12;
|
|
@@ -160,8 +184,9 @@ export class ServiceRuntimeAggregator {
|
|
|
160
184
|
return false;
|
|
161
185
|
}
|
|
162
186
|
/**
|
|
163
|
-
* Build service_runtime_v0.
|
|
164
|
-
*
|
|
187
|
+
* Build service_runtime_v0.
|
|
188
|
+
* When occupancy snapshot is present → ``cpu_and_occupancy_v1`` (anomaly evidence).
|
|
189
|
+
* Occupancy is window-scaled (Python twin) so coverage reconciles to ``window_seconds``.
|
|
165
190
|
*/
|
|
166
191
|
buildV0(opts) {
|
|
167
192
|
const list = [...this.units.values()].filter((u) => u.calls > 0);
|
|
@@ -169,9 +194,62 @@ export class ServiceRuntimeAggregator {
|
|
|
169
194
|
return null;
|
|
170
195
|
const windowEnergyKwh = nonNegativeFinite(opts.windowEnergyKwh);
|
|
171
196
|
const windowSeconds = nonNegativeFinite(opts.windowSeconds);
|
|
197
|
+
const windowRamGbHours = opts.windowRamGbHours != null ? nonNegativeFinite(opts.windowRamGbHours) : null;
|
|
172
198
|
const totalDuration = list.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
173
199
|
const equalShare = totalDuration <= 0;
|
|
174
|
-
const
|
|
200
|
+
const occ = opts.occupancy;
|
|
201
|
+
const unitKeys = new Set(list.map((u) => u.serviceUnit));
|
|
202
|
+
const rawOccByUnit = occ?.by_unit || {};
|
|
203
|
+
let attributedOccMap = {};
|
|
204
|
+
let orphanOcc = 0;
|
|
205
|
+
for (const [k, v] of Object.entries(rawOccByUnit)) {
|
|
206
|
+
const n = Math.max(0, Number(v) || 0);
|
|
207
|
+
if (n <= 0)
|
|
208
|
+
continue;
|
|
209
|
+
if (unitKeys.has(k))
|
|
210
|
+
attributedOccMap[k] = n;
|
|
211
|
+
else
|
|
212
|
+
orphanOcc += n;
|
|
213
|
+
}
|
|
214
|
+
let totalOcc = Object.values(attributedOccMap).reduce((s, v) => s + v, 0);
|
|
215
|
+
const idleSecondsRaw = Math.max(0, occ?.idle_seconds || 0);
|
|
216
|
+
const inFlightSecondsRaw = Math.max(0, occ?.in_flight_seconds || 0);
|
|
217
|
+
let unattributedOcc = idleSecondsRaw + inFlightSecondsRaw + orphanOcc;
|
|
218
|
+
const hasOccupancySignal = Boolean(occ) && (totalOcc > 0 || unattributedOcc > 0);
|
|
219
|
+
// Align occupancy coverage to the meter window (Python service_runtime_v0 twin).
|
|
220
|
+
if (hasOccupancySignal && windowSeconds > 0) {
|
|
221
|
+
const coverage = totalOcc + unattributedOcc;
|
|
222
|
+
if (coverage <= 0) {
|
|
223
|
+
unattributedOcc = windowSeconds;
|
|
224
|
+
}
|
|
225
|
+
else if (Math.abs(coverage - windowSeconds) > 1e-9) {
|
|
226
|
+
const scale = windowSeconds / coverage;
|
|
227
|
+
attributedOccMap = Object.fromEntries(Object.entries(attributedOccMap).map(([k, v]) => [k, v * scale]));
|
|
228
|
+
totalOcc = Object.values(attributedOccMap).reduce((s, v) => s + v, 0);
|
|
229
|
+
unattributedOcc = windowSeconds - totalOcc;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
const useOccupancy = hasOccupancySignal && (totalOcc > 0 || unattributedOcc > 0);
|
|
233
|
+
// Keep idle / in-flight proportions after window-scale (orphan folds into unattributed).
|
|
234
|
+
let idleOut = idleSecondsRaw;
|
|
235
|
+
let inFlightOut = inFlightSecondsRaw;
|
|
236
|
+
if (useOccupancy && windowSeconds > 0) {
|
|
237
|
+
const rawUna = idleSecondsRaw + inFlightSecondsRaw + orphanOcc;
|
|
238
|
+
if (rawUna > 0) {
|
|
239
|
+
idleOut = unattributedOcc * (idleSecondsRaw / rawUna);
|
|
240
|
+
inFlightOut = unattributedOcc * (inFlightSecondsRaw / rawUna);
|
|
241
|
+
}
|
|
242
|
+
else {
|
|
243
|
+
idleOut = unattributedOcc;
|
|
244
|
+
inFlightOut = 0;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
const unitAlloc = {
|
|
248
|
+
windowSeconds,
|
|
249
|
+
windowRamGbHours,
|
|
250
|
+
useOccupancy,
|
|
251
|
+
};
|
|
252
|
+
const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration, attributedOccMap, unitAlloc);
|
|
175
253
|
const byTenant = {};
|
|
176
254
|
const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
177
255
|
for (const [tenantId, tenantMap] of this.byTenant.entries()) {
|
|
@@ -184,7 +262,7 @@ export class ServiceRuntimeAggregator {
|
|
|
184
262
|
: windowEnergyKwh / Math.max(1, this.byTenant.size);
|
|
185
263
|
const tenantDuration = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
186
264
|
const tenantEqual = tenantDuration <= 0;
|
|
187
|
-
const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration);
|
|
265
|
+
const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, unitAlloc);
|
|
188
266
|
if (!tenantUnits.length)
|
|
189
267
|
continue;
|
|
190
268
|
byTenant[tenantId] = {
|
|
@@ -197,14 +275,63 @@ export class ServiceRuntimeAggregator {
|
|
|
197
275
|
const allocated = units.reduce((s, u) => s + u.energy_kwh, 0);
|
|
198
276
|
const residual = windowEnergyKwh - allocated;
|
|
199
277
|
const tolerance = Math.max(1e-12, Math.abs(windowEnergyKwh) * 1e-6);
|
|
278
|
+
const measuredCpu = this.hasMeasuredCpu();
|
|
279
|
+
let attribution;
|
|
280
|
+
if (useOccupancy)
|
|
281
|
+
attribution = 'cpu_and_occupancy_v1';
|
|
282
|
+
else if (measuredCpu)
|
|
283
|
+
attribution = 'cpu_share';
|
|
284
|
+
else if (equalShare)
|
|
285
|
+
attribution = 'equal_share_no_cpu_signal';
|
|
286
|
+
else
|
|
287
|
+
attribution = 'duration_share';
|
|
288
|
+
const attribution_detail = {
|
|
289
|
+
cpu: measuredCpu
|
|
290
|
+
? { method: 'request_process_cpu_time', kind: 'measured' }
|
|
291
|
+
: { method: 'request_duration_proxy', kind: 'proxy' },
|
|
292
|
+
ram: {
|
|
293
|
+
method: useOccupancy
|
|
294
|
+
? 'concurrency_normalized_active_occupancy'
|
|
295
|
+
: this.hasMeasuredRss()
|
|
296
|
+
? 'process_rss_peak_observed'
|
|
297
|
+
: 'unallocated',
|
|
298
|
+
kind: useOccupancy
|
|
299
|
+
? 'allocated_estimate'
|
|
300
|
+
: this.hasMeasuredRss()
|
|
301
|
+
? 'measured'
|
|
302
|
+
: 'unavailable',
|
|
303
|
+
},
|
|
304
|
+
gpu: { method: 'none', kind: 'unavailable' },
|
|
305
|
+
energy: {
|
|
306
|
+
cpu_dynamic: measuredCpu ? 'cpu_time_share_preferred' : 'duration_share',
|
|
307
|
+
memory: useOccupancy ? 'ram_occupancy_share' : 'unallocated',
|
|
308
|
+
gpu: 'none',
|
|
309
|
+
},
|
|
310
|
+
};
|
|
311
|
+
const unattributedRam = useOccupancy && windowSeconds > 0 && windowRamGbHours != null
|
|
312
|
+
? windowRamGbHours * (unattributedOcc / windowSeconds)
|
|
313
|
+
: null;
|
|
200
314
|
return {
|
|
201
315
|
framework: opts.framework,
|
|
202
316
|
collector: opts.collector,
|
|
203
317
|
window_seconds: Math.round(windowSeconds * 100) / 100,
|
|
204
|
-
attribution
|
|
318
|
+
attribution,
|
|
319
|
+
attribution_detail,
|
|
205
320
|
accuracy: 'trend',
|
|
206
321
|
units,
|
|
207
322
|
...(Object.keys(byTenant).length ? { by_tenant: byTenant } : {}),
|
|
323
|
+
...(useOccupancy
|
|
324
|
+
? {
|
|
325
|
+
unattributed: {
|
|
326
|
+
occupancy_seconds: Math.round(unattributedOcc * 1e6) / 1e6,
|
|
327
|
+
idle_seconds: Math.round(idleOut * 1e6) / 1e6,
|
|
328
|
+
in_flight_seconds: Math.round(inFlightOut * 1e6) / 1e6,
|
|
329
|
+
...(unattributedRam != null
|
|
330
|
+
? { ram_gb_hours: Math.round(unattributedRam * 1e6) / 1e6 }
|
|
331
|
+
: {}),
|
|
332
|
+
},
|
|
333
|
+
}
|
|
334
|
+
: {}),
|
|
208
335
|
allocation_reconciliation_v0: {
|
|
209
336
|
schema_version: 1,
|
|
210
337
|
window_energy_kwh: windowEnergyKwh,
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* Prefer TypeScript AST when available; heuristics otherwise.
|
|
4
4
|
* Additive Analyze path — never touches RunSession upload.
|
|
5
5
|
*/
|
|
6
|
+
import { type DeclaredExternalApiEntry } from './declaredExternalApis.js';
|
|
6
7
|
import { type ListCandidateSourceFilesOptions } from './projectScan.js';
|
|
7
8
|
import { type ResourceFindingCandidateV1 } from './resourceFindingCandidate.js';
|
|
8
9
|
import type { ServiceManifestV0 } from './serviceDiscovery.js';
|
|
@@ -17,10 +18,13 @@ export type ResourceAnalyzeResultV0 = {
|
|
|
17
18
|
project_id: string;
|
|
18
19
|
manifest: ServiceManifestV0;
|
|
19
20
|
findings: ResourceFindingCandidateV1[];
|
|
21
|
+
/** Python analyze twin — catalog seed when uploaded via findings/batch. */
|
|
22
|
+
declared_external_apis: DeclaredExternalApiEntry[];
|
|
20
23
|
stats: {
|
|
21
24
|
files_scanned: number;
|
|
22
25
|
findings: number;
|
|
23
26
|
by_mechanism: Record<string, number>;
|
|
27
|
+
declared_external_apis: number;
|
|
24
28
|
};
|
|
25
29
|
notes: string[];
|
|
26
30
|
};
|
|
@@ -5,11 +5,21 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import { readFileSync, statSync } from 'node:fs';
|
|
7
7
|
import { join } from 'node:path';
|
|
8
|
+
import { collectDeclaredExternalApis, dependencyMapFromPackageJson, } from './declaredExternalApis.js';
|
|
8
9
|
import { collectPreferAstHits } from './preferAstDetectors.js';
|
|
9
10
|
import { buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
|
|
10
11
|
import { toResourceFindingCandidate, } from './resourceFindingCandidate.js';
|
|
11
12
|
import { filterValidResourceFindings } from './validateResourceFinding.js';
|
|
12
13
|
import { isTypescriptAnalyzeAvailable } from './loadTypescript.js';
|
|
14
|
+
function readProjectDependencyMap(projectDir) {
|
|
15
|
+
try {
|
|
16
|
+
const raw = readFileSync(join(projectDir, 'package.json'), { encoding: 'utf8' });
|
|
17
|
+
return dependencyMapFromPackageJson(JSON.parse(raw));
|
|
18
|
+
}
|
|
19
|
+
catch {
|
|
20
|
+
return null;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
13
23
|
function collectHitsFromSources(sources) {
|
|
14
24
|
const hits = [];
|
|
15
25
|
for (const [rel, source] of Object.entries(sources)) {
|
|
@@ -61,6 +71,10 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
|
|
|
61
71
|
for (const f of findings) {
|
|
62
72
|
by_mechanism[f.mechanism_id] = (by_mechanism[f.mechanism_id] || 0) + 1;
|
|
63
73
|
}
|
|
74
|
+
const declared_external_apis = collectDeclaredExternalApis({
|
|
75
|
+
sources,
|
|
76
|
+
packageDependencies: readProjectDependencyMap(projectDir),
|
|
77
|
+
});
|
|
64
78
|
const manifest = buildServiceManifestFromPaths(projectDir, Object.keys(sources), opts);
|
|
65
79
|
return {
|
|
66
80
|
schema: 'resource_analyze_result_v0',
|
|
@@ -68,15 +82,18 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
|
|
|
68
82
|
project_id: projectId,
|
|
69
83
|
manifest,
|
|
70
84
|
findings,
|
|
85
|
+
declared_external_apis,
|
|
71
86
|
stats: {
|
|
72
87
|
files_scanned: Object.keys(sources).length,
|
|
73
88
|
findings: findings.length,
|
|
74
89
|
by_mechanism,
|
|
90
|
+
declared_external_apis: declared_external_apis.length,
|
|
75
91
|
},
|
|
76
92
|
notes: [
|
|
77
93
|
'MP4 scaffold: TypeScript AST preferred for all current RD0 twins; heuristics fallback when typescript absent',
|
|
78
94
|
'Stable mechanism_id/evidence_state aligned to resource_finding_v1 + RD0 disposition',
|
|
79
95
|
'Does not modify RunSession upload, CLI, or VSCE wiring',
|
|
96
|
+
'declared_external_apis: package.json + static import/require (Python twin); Analyze CLI upload=never — post via SDK findings/batch to seed catalog',
|
|
80
97
|
'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)',
|
|
81
98
|
`typescript AST available=${isTypescriptAnalyzeAvailable()}`,
|
|
82
99
|
'Candidates are fail-closed filtered through vendored resource_finding_v1 JSON Schema (Ajv)',
|
package/dist/analyze/cli.d.ts
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
* --json-summary print machine-readable gate summary only (CI)
|
|
15
15
|
* --fail-on any|<mechanism>[,…] CI gate (exit 1 when exceeded)
|
|
16
16
|
* --max-at-or-above <n> with --fail-on: allow up to N matches (default 0)
|
|
17
|
+
* --depth quick|standard|thorough Python-parity LLM file budget (accepted; static analyze ignores)
|
|
17
18
|
* --quiet suppress non-JSON status lines on stderr
|
|
18
19
|
*/
|
|
19
20
|
/** Run analyze subcommand; ``argv`` is args after ``analyze`` / bin name. */
|
package/dist/analyze/cli.js
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
* --json-summary print machine-readable gate summary only (CI)
|
|
15
15
|
* --fail-on any|<mechanism>[,…] CI gate (exit 1 when exceeded)
|
|
16
16
|
* --max-at-or-above <n> with --fail-on: allow up to N matches (default 0)
|
|
17
|
+
* --depth quick|standard|thorough Python-parity LLM file budget (accepted; static analyze ignores)
|
|
17
18
|
* --quiet suppress non-JSON status lines on stderr
|
|
18
19
|
*/
|
|
19
20
|
import { accessSync, constants, statSync } from 'node:fs';
|
|
@@ -22,6 +23,7 @@ import { pathToFileURL } from 'node:url';
|
|
|
22
23
|
import { buildAnalyzeGateSummary, findingsExceedFailThreshold, formatAnalyzeGateFailureMessage, resolveAnalyzeGateLimit, } from './analyzeGate.js';
|
|
23
24
|
import { buildResourceAnalyzeResultFromPaths } from './buildResourceFindings.js';
|
|
24
25
|
import { formatAnalyzeHelp } from '../cli/helpText.js';
|
|
26
|
+
const LLM_DEPTHS = new Set(['quick', 'standard', 'thorough']);
|
|
25
27
|
function printHelp() {
|
|
26
28
|
process.stdout.write(formatAnalyzeHelp());
|
|
27
29
|
}
|
|
@@ -34,6 +36,7 @@ function parseArgs(argv) {
|
|
|
34
36
|
jsonSummary: false,
|
|
35
37
|
failOn: null,
|
|
36
38
|
maxAtOrAbove: null,
|
|
39
|
+
depth: 'standard',
|
|
37
40
|
quiet: false,
|
|
38
41
|
help: false,
|
|
39
42
|
positional: [],
|
|
@@ -56,6 +59,24 @@ function parseArgs(argv) {
|
|
|
56
59
|
flags.jsonSummary = true;
|
|
57
60
|
continue;
|
|
58
61
|
}
|
|
62
|
+
if (arg === '--depth') {
|
|
63
|
+
const value = String(argv[++i] || '')
|
|
64
|
+
.trim()
|
|
65
|
+
.toLowerCase();
|
|
66
|
+
if (!LLM_DEPTHS.has(value)) {
|
|
67
|
+
throw new Error(`Invalid --depth ${value || '(empty)'}. Use quick, standard, or thorough.`);
|
|
68
|
+
}
|
|
69
|
+
flags.depth = value;
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
if (arg.startsWith('--depth=')) {
|
|
73
|
+
const value = arg.slice('--depth='.length).trim().toLowerCase();
|
|
74
|
+
if (!LLM_DEPTHS.has(value)) {
|
|
75
|
+
throw new Error(`Invalid --depth ${value || '(empty)'}. Use quick, standard, or thorough.`);
|
|
76
|
+
}
|
|
77
|
+
flags.depth = value;
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
59
80
|
if (arg === '--quiet') {
|
|
60
81
|
flags.quiet = true;
|
|
61
82
|
continue;
|
|
@@ -166,7 +187,7 @@ export function runAnalyzeCli(argv) {
|
|
|
166
187
|
: result;
|
|
167
188
|
process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
|
|
168
189
|
if (!flags.quiet && !flags.jsonSummary) {
|
|
169
|
-
process.stderr.write(`netgreener analyze: files=${result.stats.files_scanned} findings=${result.stats.findings} upload=never\n`);
|
|
190
|
+
process.stderr.write(`netgreener analyze: files=${result.stats.files_scanned} findings=${result.stats.findings} declared_apis=${result.stats.declared_external_apis} upload=never\n`);
|
|
170
191
|
}
|
|
171
192
|
const limit = resolveAnalyzeGateLimit(flags.failOn, flags.maxAtOrAbove);
|
|
172
193
|
if (flags.failOn && limit != null) {
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Collect structured external-API declarations for Analyze output.
|
|
3
|
+
*
|
|
4
|
+
* Twin of Python ``declared_external_apis.py``: seeds the server catalog via
|
|
5
|
+
* ``POST /findings/batch`` when a caller uploads. Node Analyze CLI remains
|
|
6
|
+
* ``upload=never``; this only builds the payload (package.json + static imports).
|
|
7
|
+
*
|
|
8
|
+
* See ``docs/EXTERNAL_API_PR_TO_RELEASE.md``.
|
|
9
|
+
*/
|
|
10
|
+
export type DeclaredExternalApiEntry = {
|
|
11
|
+
provider_key: string;
|
|
12
|
+
detection_method: string;
|
|
13
|
+
module_roots: string[];
|
|
14
|
+
file_paths: string[];
|
|
15
|
+
};
|
|
16
|
+
/** Extract package specs from JS/TS import / require / dynamic import. */
|
|
17
|
+
export declare function extractImportPackageRoots(source: string): string[];
|
|
18
|
+
export type CollectDeclaredExternalApisInput = {
|
|
19
|
+
/** path → source (repo-relative keys). */
|
|
20
|
+
sources?: Record<string, string>;
|
|
21
|
+
/** Parsed package.json dependencies (merged deps + optional peer/optional). */
|
|
22
|
+
packageDependencies?: Record<string, string> | null;
|
|
23
|
+
/** Label for package.json file_paths (default ``package.json``). */
|
|
24
|
+
packageJsonPath?: string;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Build ``declared_external_apis`` rows for analyze / findings-batch.
|
|
28
|
+
*/
|
|
29
|
+
export declare function collectDeclaredExternalApis(input?: CollectDeclaredExternalApisInput): DeclaredExternalApiEntry[];
|
|
30
|
+
/** Read dependency map from a package.json object. */
|
|
31
|
+
export declare function dependencyMapFromPackageJson(pkg: unknown): Record<string, string> | null;
|