Frontend gaps fill work. Testing fixes work. Auditing in progress.

2025-12-30 01:22:58 +02:00
parent 1dc4bcbf10
commit 7a5210e2aa
928 changed files with 183942 additions and 3941 deletions
--- a/docs/dev/fixtures.md
+++ b/docs/dev/fixtures.md
@@ -43,3 +43,109 @@ fixture sets, where they live, and how to regenerate them safely.
 - **Regeneration:** `UPDATE_KISA_FIXTURES=1 dotnet test src/Concelier/__Tests/StellaOps.Concelier.Connector.Kisa.Tests/StellaOps.Concelier.Connector.Kisa.Tests.csproj`
 - **Verification:** Re-run the same test suite without the env var; confirm advisory content remains NFC-normalised and HTML is sanitised. Metrics assertions will fail if counters drift.
 - **Localisation note:** RSS `category` values (e.g. `취약점정보`) remain in Hangul—do not translate them in fixtures; they feed directly into metrics/log tags.
+
+---
+
+## Fixture Tiers & Retention Rules
+
+> Added in Sprint: SPRINT_20251229_004_LIB_fixture_harvester (FH-010)
+
+### Tier Classification
+
+Test fixtures in StellaOps are classified into tiers based on their source, purpose, and maintenance requirements:
+
+| Tier | Name | Purpose | Retention |
+|------|------|---------|-----------|
+| **T0** | Synthetic | Minimal, deterministic fixtures for unit testing | Permanent |
+| **T1** | Specification Examples | Reference fixtures from CycloneDX, SPDX, OpenVEX specs | Per spec version |
+| **T2** | Real-World Samples | Production-representative fixtures from real ecosystems | 6 months + current |
+| **T3** | Regression | Fixtures capturing specific bugs or production incidents | Permanent |
+
+### Tier Details
+
+**T0 - Synthetic Fixtures**
+- Source: Generated/hand-crafted
+- Size: Minimal (< 100 KB)
+- External Dependencies: None
+- Refresh Policy: Manual only
+- Use Cases: Unit tests, schema validation, edge cases, air-gap testing
+
+**T1 - Specification Examples**
+- Source: CycloneDX, SPDX, OpenVEX official specs
+- Size: Small to medium (< 1 MB)
+- External Dependencies: Spec repositories
+- Refresh Policy: Quarterly (with spec updates)
+- Use Cases: Format compliance, parser validation, interoperability
+
+**T2 - Real-World Samples**
+- Source: Public registries, OSS projects
+- Size: Medium (< 10 MB)
+- External Dependencies: Public APIs
+- Refresh Policy: Monthly or on-demand
+- Use Cases: Integration testing, performance benchmarks
+
+**T3 - Regression Fixtures**
+- Source: Bug reports, production incidents
+- Size: Varies
+- External Dependencies: None (self-contained)
+- Refresh Policy: Never (historical record)
+- Use Cases: Regression prevention, bug reproduction
+
+### Storage Guidelines
+
+| Tier | Git Storage | LFS Required | Archive |
+|------|-------------|--------------|---------|
+| T0 | Direct | No | No |
+| T1 | Direct | Optional | Spec releases |
+| T2 | Via LFS | Yes (> 1MB) | Monthly snapshots |
+| T3 | Direct | If > 1MB | Incident reports |
+
+### Fixture Harvester Tool
+
+The `FixtureHarvester` CLI tool manages fixture acquisition and validation:
+
+```bash
+# Harvest a new fixture
+dotnet run --project src/__Tests/Tools/FixtureHarvester harvest --type sbom --id my-fixture --source https://example.com/sbom.json
+
+# Validate all fixtures
+dotnet run --project src/__Tests/Tools/FixtureHarvester validate
+
+# Regenerate expected outputs (requires confirmation)
+dotnet run --project src/__Tests/Tools/FixtureHarvester regen --fixture my-fixture --confirm
+```
+
+### Fixture Directory Structure
+
+```
+src/__Tests/fixtures/
+├── fixtures.manifest.yml       # Root manifest
+├── sbom/
+│   └── <fixture-id>/
+│       ├── meta.json          # Provenance and metadata
+│       ├── raw/               # Original files
+│       ├── normalized/        # Processed files
+│       └── expected/          # Expected outputs
+├── feeds/
+│   └── <fixture-id>/...
+└── vex/
+    └── <fixture-id>/...
+```
+
+### meta.json Schema
+
+```json
+{
+  "id": "fixture-id",
+  "source": "local-build | url | api | manual",
+  "sourceUrl": "https://...",
+  "retrievedAt": "2025-12-29T00:00:00Z",
+  "license": "CC0-1.0",
+  "sha256": "sha256:...",
+  "refreshPolicy": "manual | monthly | quarterly",
+  "tier": "T0 | T1 | T2 | T3",
+  "notes": "Additional context"
+}
+```
+
+See also: [FixtureHarvester README](../src/__Tests/Tools/FixtureHarvester/README.md)