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:

FixtureUpdater and GoldenPairs pull data from live services or local corpora and write deterministic fixture files to the repository.
PolicyDslValidator and PolicySchemaExporter read policy definitions and produce validation results or schema files.
PolicySimulationSmoke and LanguageAnalyzerSmoke execute tests against upstream services/libraries and produce pass/fail reports.
RustFsMigrator reads from and writes to S3-compatible storage.
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.

4.6 KiB Raw Blame History