stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
f214edff824acc5d4e0573cb676a85940e522d02
git.stella-ops.org/src/Graph/AGENTS.md
StellaOps Bot b6b9ffc050
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Add PHP Analyzer Plugin and Composer Lock Data Handling 
- 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.
2025-11-22 14:02:49 +02:00

4.0 KiB
Raw Blame History

AGENTS · Graph Module

Purpose & Scope

  • Working directories: src/Graph/StellaOps.Graph.Api, src/Graph/StellaOps.Graph.Indexer, and src/Graph/__Tests.
  • Modules covered: Graph API (query/search/paths/diff/overlay/export) and Graph Indexer (ingest, snapshot, overlays).
  • Applicable sprints: docs/implplan/SPRINT_0207_0001_0001_graph.md, docs/implplan/SPRINT_0141_0001_0001_graph_indexer.md, and any follow-on graph docs sprints (docs/implplan/SPRINT_0321_0001_0001_docs_modules_graph.md).

Roles

  • Backend engineer (.NET 10) — API, planners, overlays, exports.
  • Data/ETL engineer — Indexer ingest, snapshots, overlays.
  • QA/Perf engineer — deterministic tests, load/fuzz, offline parity.
  • Docs maintainer — graph API/ops runbooks, Offline Kit notes.

Required Reading (treat as read before DOING)

  • docs/README.md
  • docs/07_HIGH_LEVEL_ARCHITECTURE.md
  • docs/modules/platform/architecture-overview.md
  • docs/modules/graph/architecture.md
  • docs/modules/graph/implementation_plan.md
  • Sprint doc for current work (e.g., docs/implplan/SPRINT_0207_0001_0001_graph.md).
  • Policy overlay contract refs when touching overlays: POLICY-ENGINE-30-001..003 (see policy module docs).

Determinism & Offline

  • Default to deterministic ordering for streams/exports; manifest checksums required for graphml/csv/ndjson exports.
  • Timestamps: UTC ISO-8601; avoid wall-clock in tests.
  • Snapshot/export roots configurable via STELLAOPS_GRAPH_SNAPSHOT_DIR or SbomIngestOptions.SnapshotRootDirectory.
  • Offline posture: no external calls beyond allowlisted feeds; prefer cached schemas and local nugets in local-nugets/.

Data & Environment

  • Canonical store: MongoDB (>=3.0 driver). Tests use STELLAOPS_TEST_MONGO_URI; fallback mongodb://127.0.0.1:27017, then Mongo2Go.
  • Collections: graph_nodes, graph_edges, graph_overlays_cache, graph_snapshots, graph_saved_queries.
  • Tenant isolation mandatory on every query and export.

Testing Expectations

  • Unit: node/edge builders, identifier stability, overlay calculators, planners, diff engine.
  • Integration: ingest → snapshot → query/paths/diff/export end-to-end; RBAC + tenant guards.
  • Performance: synthetic datasets (~500k nodes / 2M edges) with enforced budgets; capture latency metrics.
  • Security: RBAC scopes (graph:read/query/export), audit logging, rate limiting.
  • Offline: export/import parity for Offline Kit bundles; deterministic manifests verified in tests.

Observability

  • Metrics to emit: graph_ingest_lag_seconds, graph_tile_latency_seconds, graph_query_budget_denied_total, graph_overlay_cache_hit_ratio, clustering counters from architecture doc.
  • Structured logs with trace IDs; traces for ingest stages and query planner/executor.

Coding Standards

  • Target framework: net10.0 with latest C# preview features.
  • Use dependency injection; avoid static singletons.
  • Respect module boundaries; shared libs only if declared in sprint or architecture docs.
  • Naming: projects StellaOps.Graph.Api, StellaOps.Graph.Indexer; prefer Graph* prefixes for internal components.

Coordination & Status

  • Update sprint Delivery Tracker statuses (TODO → DOING → DONE/BLOCKED) in relevant sprint file.
  • If a required contract/doc is missing or stale, mark the affected task BLOCKED in the sprint and log under Decisions & Risks; do not pause work waiting for live answers.

Run/Test Commands (examples)

  • Restore: dotnet restore src/Graph/StellaOps.Graph.Api/StellaOps.Graph.Api.csproj --source ../local-nugets
  • Build: dotnet build src/Graph/StellaOps.Graph.Api/StellaOps.Graph.Api.csproj -c Release
  • Tests: dotnet test src/Graph/__Tests/StellaOps.Graph.Indexer.Tests/StellaOps.Graph.Indexer.Tests.csproj
  • Lint/style: follow repo-wide analyzers in Directory.Build.props / .editorconfig.

Evidence

  • Keep artefacts deterministic; attach manifest hashes in PR/sprint notes when delivering exports or snapshots.
  • Document new metrics/routes/schemas under docs/modules/graph and link from sprint Decisions & Risks.