b6b9ffc050
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented the PhpAnalyzerPlugin to analyze PHP projects. - Created ComposerLockData class to represent data from composer.lock files. - Developed ComposerLockReader to load and parse composer.lock files asynchronously. - Introduced ComposerPackage class to encapsulate package details. - Added PhpPackage class to represent PHP packages with metadata and evidence. - Implemented PhpPackageCollector to gather packages from ComposerLockData. - Created PhpLanguageAnalyzer to perform analysis and emit results. - Added capability signals for known PHP frameworks and CMS. - Developed unit tests for the PHP language analyzer and its components. - Included sample composer.lock and expected output for testing. - Updated project files for the new PHP analyzer library and tests.
45 lines
3.2 KiB
Markdown
45 lines
3.2 KiB
Markdown
# Deno Runtime Trace Shim (draft v0.1)
|
|
|
|
This document specifies how the Deno analyzer will generate `deno-runtime.ndjson` traces offline for tasks DENO-26-009/010/011.
|
|
|
|
## Objectives
|
|
- Capture module loads, permission uses, npm resolutions, and wasm loads during harnessed execution.
|
|
- Operate offline, deterministic ordering, and path redaction via relative paths + SHA256.
|
|
- Emit NDJSON per `deno-runtime-signals.md` and store to `deno-runtime.ndjson` at analyzer root.
|
|
|
|
## Approach
|
|
1) **Shim loader**
|
|
- Entry file `trace-shim.ts` is written alongside the analyzer and executed via `deno run --cached-only --allow-read --allow-env --quiet trace-shim.ts` with `STELLA_DENO_ENTRYPOINT` set to the target module.
|
|
- Registers listeners:
|
|
- `Deno.permissions.request/query/revoke` wrappers to capture permission uses and maintain a granted-permission snapshot (normalized to fs/net/env/ffi/process/worker).
|
|
- Hooks `Deno[Deno.internal].moduleLoader.load` when available to observe module loads (static/dynamic/npm) before execution.
|
|
- Wraps `WebAssembly.instantiate` / `instantiateStreaming` to record wasm loads.
|
|
- Wraps `Deno.dlopen` to record FFI permission use.
|
|
- Uses a synchronous SHA-256 implementation (no WebCrypto) to hash normalized module paths for determinism/offline safety.
|
|
|
|
2) **Event buffering**
|
|
- Collects events in-memory; each event includes UTC timestamp and relative path (computed against analyzer root) plus `path_sha256`.
|
|
- Origin normalization: for remote specifiers, strip query/fragment; record registry host/version if npm.
|
|
|
|
3) **Execution**
|
|
- Analyzer/worker runs `deno run --cached-only --allow-read --allow-env --quiet trace-shim.ts` with `STELLA_DENO_ENTRYPOINT=<entry>` (absolute or cwd-relative) and optional `STELLA_DENO_BINARY` override.
|
|
- Respects `DENO_DIR` if present for npm cache resolution; still offline (`--cached-only`).
|
|
|
|
4) **Output**
|
|
- After user code exits, shim writes buffered events as NDJSON sorted by timestamp then type to `<root>/deno-runtime.ndjson`.
|
|
- Analyzer ingests the NDJSON, hashes content, stores payload in AnalysisStore under `ScanAnalysisKeys.DenoRuntimePayload` (legacy alias `"deno.runtime"` kept for backward compatibility), and emits policy signals keyed `surface.lang.deno.*`.
|
|
|
|
5) **Determinism & safety**
|
|
- Timestamps: `Date.now()` captured and converted to ISO-8601 UTC; events sorted by ts then type.
|
|
- Paths: resolved to analyzer-relative form, forward-slash normalized, hashed with built-in synchronous SHA-256 (lowercase hex); remote origins normalized to protocol//host/path.
|
|
- No module source or env values persisted; only paths + hashes; npm resolutions recorded as cache hits only.
|
|
|
|
## Validation plan
|
|
- Add fixtures: simple import graph, dynamic import, wasm load, npm: chalk (cached), permission use via `Deno.permissions.request`.
|
|
- Golden NDJSON and hash comparison in tests; ensure stable ordering.
|
|
|
|
## Open items
|
|
- Confirm `--unstable-preload-module` availability on target Deno version; fallback to import-map injection if unavailable.
|
|
- Verify WASM load interception across `WebAssembly.instantiate` vs `instantiateStreaming`.
|
|
- Ensure `--cached-only` works with npm cache; otherwise fallback to static npm graph without runtime fetch.
|