170 lines
8.1 KiB
Markdown
170 lines
8.1 KiB
Markdown
# 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. |
|