99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# Developer Tools Architecture
|
|
|
|
> Standalone CLI utilities for development, testing, and CI support workflows.
|
|
|
|
## Overview
|
|
|
|
The Tools directory contains a set of independent CLI applications, each with its own `Program.cs` entry point. These tools are not deployed as services -- they are invoked locally by developers or executed in CI pipelines. Each tool is narrowly scoped to a single responsibility, from fixture management to workflow generation.
|
|
|
|
## Components
|
|
|
|
```
|
|
src/Tools/
|
|
FixtureUpdater/ # Golden fixture refresh from live APIs
|
|
Program.cs
|
|
GoldenPairs/ # SBOM/advisory corpus management
|
|
Program.cs
|
|
PolicyDslValidator/ # Policy DSL file validation
|
|
Program.cs
|
|
PolicySchemaExporter/ # JSON schema export for IDE support
|
|
Program.cs
|
|
PolicySimulationSmoke/ # Policy simulation smoke tests
|
|
Program.cs
|
|
LanguageAnalyzerSmoke/ # Language detection accuracy tests
|
|
Program.cs
|
|
RustFsMigrator/ # RustFS data migration between schema versions
|
|
Program.cs
|
|
WorkflowGenerator/ # CI workflow generation (F# DSL)
|
|
Program.fs
|
|
```
|
|
|
|
## Tool Descriptions
|
|
|
|
### FixtureUpdater
|
|
|
|
Pulls latest test data from running Stella Ops services and updates frozen golden fixtures deterministically. Ensures test suites use realistic, version-controlled data without manual fixture authoring.
|
|
|
|
### GoldenPairs
|
|
|
|
Manages SBOM/advisory pairs used for testing. Provides version tracking and diff tools for the test corpus, ensuring changes to upstream advisory formats are detected and accommodated.
|
|
|
|
### PolicyDslValidator
|
|
|
|
Validates policy DSL files against the current schema. Used in CI gates to catch policy syntax errors before merge.
|
|
|
|
### PolicySchemaExporter
|
|
|
|
Exports the Policy DSL schema to JSON format for documentation and IDE autocomplete support. Enables policy authors to get inline validation and completion in their editors.
|
|
|
|
### PolicySimulationSmoke
|
|
|
|
Runs end-to-end policy simulation smoke tests against a configured Policy Engine instance. Validates that policy evaluation produces expected verdicts for a known set of inputs.
|
|
|
|
### LanguageAnalyzerSmoke
|
|
|
|
Tests the language analyzer's detection accuracy against a curated set of source files. Reports precision and recall metrics for supported languages.
|
|
|
|
### RustFsMigrator
|
|
|
|
Migrates data stored in RustFS (S3-compatible object storage) between schema versions. Handles object key transformations and metadata updates required during platform upgrades.
|
|
|
|
### WorkflowGenerator
|
|
|
|
Generates GitHub Actions and .NET test workflow definitions from an F# DSL. Ensures CI workflow files are consistent, auditable, and derived from a single source of truth rather than hand-edited YAML.
|
|
|
|
## Data Flow
|
|
|
|
Tools are consumers and producers of artifacts:
|
|
|
|
1. **FixtureUpdater** and **GoldenPairs** pull data from live services or local corpora and write deterministic fixture files to the repository.
|
|
2. **PolicyDslValidator** and **PolicySchemaExporter** read policy definitions and produce validation results or schema files.
|
|
3. **PolicySimulationSmoke** and **LanguageAnalyzerSmoke** execute tests against upstream services/libraries and produce pass/fail reports.
|
|
4. **RustFsMigrator** reads from and writes to S3-compatible storage.
|
|
5. **WorkflowGenerator** reads F# DSL definitions and writes CI workflow YAML files.
|
|
|
|
## Database Schema
|
|
|
|
Not applicable. Tools are CLI utilities with no persistent database.
|
|
|
|
## Endpoints
|
|
|
|
Not applicable. Tools are client-side CLI applications with no HTTP endpoints.
|
|
|
|
## Dependencies
|
|
|
|
| Library/Tool | Purpose |
|
|
|---------------------|------------------------------------------------|
|
|
| Policy Engine libs | Policy DSL parsing, schema definitions |
|
|
| Scanner libs | Language analyzer, SBOM processing |
|
|
| F# compiler | WorkflowGenerator DSL compilation |
|
|
| DotNet.Glob | File pattern matching in fixture tools |
|
|
| AWS SDK (S3) | RustFsMigrator object storage access |
|
|
|
|
## Security Considerations
|
|
|
|
- **No network listeners**: Tools do not expose HTTP endpoints or accept inbound connections.
|
|
- **Credential handling**: Tools that connect to live services (FixtureUpdater, PolicySimulationSmoke) use the same Authority-issued tokens as other Stella Ops services. Credentials are never embedded in tool binaries or fixture files.
|
|
- **Deterministic output**: FixtureUpdater and GoldenPairs produce deterministic output to ensure reproducible test runs and prevent fixture drift.
|
|
- **CI isolation**: Tools run in isolated CI containers with scoped permissions; they do not have access to production secrets.
|