wip: doctor/cli/docs/api to vector db consolidation; api hardening for descriptions, tenant, and scopes; migrations and conversions of all DALs to EF v10
This commit is contained in:
master
41
docs/modules/tools/README.md
Normal file
41
docs/modules/tools/README.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Developer Tools
|
||||
|
||||
> Collection of CLI utilities for fixture management, policy validation, smoke testing, and workflow generation.
|
||||
|
||||
## Purpose
|
||||
|
||||
Developer Tools is a collection of standalone CLI utilities used by Stella Ops developers and operators during development and CI workflows. Each tool addresses a specific concern -- refreshing golden test fixtures from live APIs, validating policy DSL files, running smoke tests, or generating CI workflow definitions. The tools are not deployed as services; they run locally or in CI pipelines.
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Architecture](./architecture.md)
|
||||
|
||||
## Status
|
||||
|
||||
| Attribute | Value |
|
||||
|-------------|-------------------|
|
||||
| **Maturity** | Production |
|
||||
| **Source** | `src/Tools/` |
|
||||
|
||||
## Key Features
|
||||
|
||||
- FixtureUpdater: golden fixture refresh from live APIs
|
||||
- GoldenPairs: SBOM/advisory corpus management
|
||||
- PolicyDslValidator: policy language validation
|
||||
- PolicySchemaExporter: JSON schema export for IDE autocomplete
|
||||
- PolicySimulationSmoke: policy simulation smoke tests
|
||||
- LanguageAnalyzerSmoke: language detection tests
|
||||
- RustFsMigrator: filesystem migration for RustFS (S3-compatible) storage
|
||||
- WorkflowGenerator: CI workflow generation with F# DSL
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Upstream
|
||||
|
||||
- Policy Engine libraries - policy DSL parsing and schema definitions
|
||||
- Scanner libraries - language analyzer and SBOM processing
|
||||
|
||||
### Downstream
|
||||
|
||||
- CI pipelines - consume generated workflow definitions
|
||||
- Test suites - consume golden fixtures and SBOM/advisory pairs
|
||||
98
docs/modules/tools/architecture.md
Normal file
98
docs/modules/tools/architecture.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user