Initial commit (history squashed)

docs/18_CODING_STANDARDS.md

@@ -0,0 +1,169 @@
+#  18 · Coding Standards & Contributor Guide — **Stella Ops**  
+*(v2.0 — 12 Jul 2025 · supersedes v1.0)*  
+
+> **Audience** — Anyone sending a pull‑request to the open‑source Core.  
+> **Goal** — Keep the code‑base small‑filed, plug‑in‑friendly, DI‑consistent, and instantly readable.
+
+---
+
+##  0 Why read this?
+
+* Cuts review time → quicker merges.  
+* Guarantees code is **hot‑load‑safe** for run‑time plug‑ins.  
+* Prevents style churn and merge conflicts.  
+
+---
+
+##  1 High‑level principles
+
+1. **SOLID first** – especially Interface & Dependency Inversion.  
+2. **100‑line rule** – any file > 100 physical lines must be split or refactored.  
+3. **Contract‑level ownership** – public abstractions live in lightweight *Contracts* libraries; impl classes live in runtime projects.  
+4. **Single Composition Root** – all DI wiring happens in **`StellaOps.Web/Program.cs`** and in each plug‑in’s `IoCConfigurator`; nothing else calls `IServiceCollection.BuildServiceProvider`.  
+5. **No Service Locator** – constructor injection only; static `ServiceProvider` is banned.  
+6. **Fail‑fast startup** – configuration validated before the web‑host listens.  
+7. **Hot‑load compatible** – no static singletons that survive plug‑in unload; avoid `Assembly.LoadFrom` outside the built‑in plug‑in loader.  
+
+---
+
+##  2 Repository layout (flat, July‑2025)**
+
+```text
+src/
+├─ backend/
+│   ├─ StellaOps.Web/                # ASP.NET host + composition root
+│   ├─ StellaOps.Common/             # Serilog, Result<T>, helpers
+│   ├─ StellaOps.Contracts/          # DTO + interface contracts (no impl)
+│   ├─ StellaOps.Configuration/      # Options + validation
+│   ├─ StellaOps.Localization/
+│   ├─ StellaOps.PluginLoader/       # Cosign verify, hot‑load
+│   ├─ StellaOps.Scanners.Trivy/     # First‑party scanner
+│   ├─ StellaOps.TlsProviders.OpenSsl/
+│   └─ … (additional runtime projects)
+├─ plugins-sdk/                      # Templated contracts & abstractions
+└─ frontend/                         # Angular workspace
+tests/                               # Mirrors src structure 1‑to‑1
+```
+
+There are no folders named “Module” and no nested solutions.
+
+##  3 Naming & style conventions
+
+| Element                                                                         | Rule                                    | Example                         |
+| ------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------- |
+| Namespaces                                                                      | File‑scoped, StellaOps.<Area>           | namespace StellaOps.Scanners;   |
+| Interfaces                                                                      | I prefix, PascalCase                    | IScannerRunner                  |
+| Classes / records                                                               | PascalCase                              | ScanRequest, TrivyRunner        |
+| Private fields                                                                  | camelCase (no leading underscore)       | redisCache, httpClient          |
+| Constants                                                                       | SCREAMING_SNAKE_CASE                    | const int MAX_RETRIES = 3;      |
+| Async methods                                                                   | End with Async                          | Task<ScanResult> ScanAsync()    |
+| File length                                                                     | ≤ 100 lines incl. using & braces        | enforced by dotnet format check |
+| Using directives                                                                | Outside namespace, sorted, no wildcards | —                               |
+
+Static analyzers (.editorconfig, StyleCop.Analyzers package) enforce the above. 
+
+##  4 Dependency‑injection policy
+
+Composition root – exactly one per process:
+
+```csharp
+builder.Services
+       .AddStellaCore()          // extension methods from each runtime project
+       .AddPluginLoader("/Plugins", cfg);   // hot‑load signed DLLs
+```
+
+Plug‑ins register additional services via the IoCConfigurator convention described in the Plug‑in SDK Guide, §5.
+Never resolve services manually (provider.GetService<T>()) outside the composition root; tests may use WebApplicationFactory or ServiceProvider.New() helpers.
+Scoped lifetime is default; singletons only for stateless, thread‑safe helpers.
+
+##  5 Project organisation rules
+
+Contracts vs. Runtime – public DTO & interfaces live in <Area>.Contracts; implementation lives in sibling project.
+Feature folders – inside each runtime project group classes by use‑case, e.g.
+
+```text
+├─ Scan/
+│   ├─ ScanService.cs
+│   └─ ScanController.cs
+├─ Feed/
+└─ Tls/
+```
+
+Tests – mirror the structure under tests/ one‑to‑one; no test code inside production projects.
+
+##  6 C# language features
+
+Nullable reference types enabled.
+record for immutable DTOs.
+Pattern matching encouraged; avoid long switch‑cascades.
+Span<T> & Memory<T> OK when perf‑critical, but measure first.
+Use await foreach over manual paginator loops.
+
+##  7 Error‑handling template
+
+```csharp
+public async Task<IActionResult> PostScan([FromBody] ScanRequest req)
+{
+    if (!ModelState.IsValid) return BadRequest(ModelState);
+
+    try
+    {
+        ScanResult result = await scanService.ScanAsync(req);
+        if (result.Quota != null) 
+        {
+            Response.Headers.TryAdd("X-Stella-Quota-Remaining", result.Quota.Remaining.ToString());
+            Response.Headers.TryAdd("X-Stella-Reset", result.Quota.ResetUtc.ToString("o"));
+        }
+        return Ok(result);
+    }
+}
+```
+
+RFC 7807 ProblemDetails for all non‑200s.
+Capture structured logs with Serilog’s message‑template syntax.
+
+##  8 Async & threading
+
+* All I/O is async; no .Result / .Wait().
+* Library code: ConfigureAwait(false).
+* Limit concurrency via Channel<T> or Parallel.ForEachAsync, never raw Task.Run loops.
+
+##  9 Testing rules
+
+| Layer                    | Framework                | Coverage gate              |
+| ------------------------ | ------------------------ | -------------------------- |
+| Unit                     | xUnit + FluentAssertions | ≥ 80 % line, ≥ 60 % branch |
+| Integration              | Testcontainers           | Real Redis & Trivy         |
+| Mutation (critical libs) | Stryker.NET              | ≥ 60 % score               |
+
+One test project per runtime/contract project; naming <Project>.Tests.
+
+##  10 Static analysis & formatting
+
+* dotnet format must exit clean (CI gate).
+* StyleCop.Analyzers + Roslyn‑Security‑Guard run on every PR.
+* CodeQL workflow runs nightly on main.
+
+##  11 Commit & PR checklist
+
+* Conventional Commit prefix (feat:, fix:, etc.).
+* dotnet format & dotnet test both green.
+* Added or updated XML‑doc comments for public APIs.
+* File count & length comply with 100‑line rule.
+* If new public contract → update relevant markdown doc & JSON‑Schema.
+
+##  12 Common pitfalls
+
+|Symptom|  Root cause | Fix
+|-------|-------------|-------------------
+|InvalidOperationException: Cannot consume scoped service...| Mis‑matched DI lifetimes| Use scoped everywhere unless truly stateless
+|Hot‑reload plug‑in crash| Static singleton caching plugin types| Store nothing static; rely on DI scopes
+
+> 100‑line style violation |Large handlers or utils |Split into private helpers or new class
+
+##  13 Change log
+
+| Version | Date       | Notes                                                                                              |
+| ------- | ---------- | -------------------------------------------------------------------------------------------------- |
+| v2.0    | 2025‑07‑12 | Updated DI policy, 100‑line rule, new repo layout, camelCase fields, removed “Module” terminology. |
+| 1.0     | 2025‑07‑09 | Original standards.                                                                                |