stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
69651212ec42ade25a9c7952b5655e9d4a5514c7
git.stella-ops.org/src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node/AGENTS.md
master 90c244948a Update AGENTS.md files across multiple modules to standardize task status update instructions and introduce a new document for Secret Leak Detection operations. 
- Modified task status update instructions in AGENTS.md files to refer to corresponding sprint files as `/docs/implplan/SPRINT_*.md` instead of `docs/implplan/SPRINTS.md`.
- Added a comprehensive document for Secret Leak Detection operations detailing scope, prerequisites, rule bundle lifecycle, enabling the analyzer, policy patterns, observability, troubleshooting, and references.
2025-11-05 11:58:32 +02:00

3.0 KiB
Raw Blame History

StellaOps.Scanner.Analyzers.Lang.Node — Agent Charter

Role

Deliver the Node.js / npm / Yarn / PNPM analyzer plug-in that resolves workspace graphs, symlinks, and script metadata for Scanner Workers.

Scope

  • Deterministic filesystem walker for node_modules, PNPM store, Yarn Plug'n'Play, and workspace roots.
  • Component identity normalization to pkg:npm with provenance evidence (manifest path, integrity hashes, lockfile references).
  • Workspace + symlink attribution, script metadata (postinstall, lifecycle), and policy hints for risky scripts.
  • Plug-in manifest authoring, DI bootstrap, and benchmark harness integration.

Out of Scope

  • OS package detection, native library linkage, or vulnerability joins.
  • Language analyzers for other ecosystems (Python, Go, .NET, Rust).
  • CLI/UI surfacing of analyzer diagnostics (handed to UI guild post-gate).

Expectations

  • Deterministic output across Yarn/NPM/PNPM variations; normalized casing and path separators.
  • Performance targets: 10 k-module fixture <1.8 s, <220 MB RSS on 4 vCPU runner.
  • Offline-first; no network dependency to resolve registries.
  • Emit structured metrics + logs (analyzer=node) compatible with Scanner telemetry model.
  • Update TASKS.md, SPRINTS_LANG_IMPLEMENTATION_PLAN.md, and corresponding fixtures as progress occurs.

Dependencies

  • Shared language analyzer core (StellaOps.Scanner.Analyzers.Lang).
  • Worker dispatcher for plug-in discovery.
  • EntryTrace usage hints (for script usage classification).

Testing & Artifacts

  • Determinism golden fixtures under Fixtures/lang/node/.
  • Benchmark CSV + flamegraph stored in src/Bench/StellaOps.Bench/Scanner.Analyzers/.
  • Plug-in manifest + cosign workflow added to Offline Kit instructions once analyzer is production-ready.

Telemetry & Policy Hints

  • Metrics: scanner_analyzer_node_scripts_total{script} increments for each install lifecycle script discovered.
  • Metadata keys:
    • policyHint.installLifecycle lists lifecycle scripts (preinstall;install;postinstall) observed for a package.
    • script.<name> stores the canonical command string for each lifecycle script.
  • Evidence: lifecycle script entries emit LanguageEvidenceKind.Metadata pointing to package.json#scripts.<name> with SHA-256 hashes for determinism.

Required Reading

  • docs/modules/scanner/architecture.md
  • docs/modules/platform/architecture-overview.md

Working Agreement

    1. Update task status to DOING/DONE in both correspoding sprint file /docs/implplan/SPRINT_*.md and the local TASKS.md when you start or finish work.
    1. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
    1. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
    1. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
    1. Revert to TODO if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.