Avrolution.Cli 0.1.4

Avrolution

Avrolution helps teams evolve Avro schemas safely by combining validation, compatibility analysis, code generation, and visual schema authoring.

This repository is a layered monorepo:

• src/core contains parsing/validation primitives.
• src/app orchestrates use-cases (validate, compare, impact, codegen, infer).
• src/contracts defines request/response DTOs shared across surfaces.
• src/api exposes the app layer over HTTP.
• src/cli provides the public avrolution command surface.
• src/web/avrolution-web is the React UI.
• src/desktop/avrolution-desktop is the Tauri desktop shell that runs CLI commands locally.

What each feature does

Validate

Validate answers: “Is this AVSC valid, and what should I fix?”

Pipeline order:

1. JSON syntax check
2. Avro parser baseline check (Avro.Schema.Parse)
3. Profile diagnostics (standard or strict), plus optional inlineOnly

Output:

• A list of diagnostics with code, message, severity, and optional path.
• Many diagnostics include suggestedFix text you can apply directly.

Typical use:

• Use standard when you want Avro-baseline behavior.
• Use strict when you also want policy/lint guardrails.

Compare

Compare answers: “What changed between old and new schema, and is the change compatible?”

It produces:

• A changes list (add/remove/type-change/alias-related changes).
• Compatibility flags for backward, forward, and full modes.
• Risk levels per change (for triage and release decisions).

The web Compare page lets you switch status lens (overall, backward, forward, full) while still computing all compatibility signals.

Impact

Impact is a compact compatibility summary for downstream decisions (pipelines, release checks, migrations). It is derived from compare analysis and intended for quick machine/human consumption.

Codegen

Codegen turns AVSC into typed model code for multiple languages.

Current web/CLI language targets include:

• C#
• Java
• Kotlin
• Python
• Rust
• TypeScript
• Go

Codegen options include namespace fallback and nullable handling for nullable unions. The web surface supports copy and download workflows.

Builder

Builder is a visual schema editor that supports:

• Authoring root record metadata (name, namespace, docs)
• Creating and reordering fields
• Nested structures
• Import from AVSC
• Import from arbitrary JSON via infer
• Validation of generated AVSC
• Download/copy of generated AVSC

Builder validation combines local builder constraints with engine diagnostics so users get both immediate UX checks and engine-level correctness checks.

Diagnostics and suggested fixes

Diagnostics are the primary feedback mechanism across Validate, Compare, and Builder.

Each diagnostic typically includes:

• code: stable identifier for automation and filtering
• message: human-readable explanation
• severity: Info, Warning, or Error
• path (optional): where in the schema the issue occurred
• suggestedFix (optional): concrete next step text

Interpretation guidance:

• Treat Error as blocking.
• Treat Warning as “safe to review before release.”
• Treat Info as advisory/success context.

Profiles and inline mode

• standard: Avro-baseline behavior
• strict: standard plus extra lint/policy diagnostics
• inlineOnly: independent toggle that can be used with either profile

inlineOnly (“Require Inline Definitions”) disallows references to previously defined named types and requires inline record/enum/fixed definitions where used.

See docs/profiles.md for the detailed rule matrix.

Surfaces and runtime behavior

Avrolution supports the same core use-cases across API, CLI, web, and desktop:

• API and browser web: HTTP calls through src/api
• Desktop web (Tauri): local CLI bridge first, no required localhost API
• CLI: direct local invocation for CI and scripting

This keeps behavior consistent while allowing offline desktop workflows.

Quick start

Build and run

• Build solution: dotnet build Avrolution.sln
• Run API locally: dotnet run --project src/api/Avrolution.Api/Avrolution.Api.csproj
• Run web app: cd src/web/avrolution-web && npm install && npm run dev
• Run desktop app: cd src/desktop/avrolution-desktop && npm install && npm run tauri dev

CLI examples

• Validate file: dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- validate schema.avsc --profile standard
• Validate stdin (PowerShell): Get-Content schema.avsc -Raw | dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- validate --profile strict --inline-only
• Compare: dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- compare old.avsc new.avsc --profile strict --inline-only
• Impact: dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- impact old.avsc new.avsc --profile standard
• Codegen: dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- codegen schema.avsc --lang csharp --namespace AvroGenerated

Autofix flows (CLI): Avrolution supports both quick spot fixes and an interactive plan-based flow. Export a plan, review, then apply; or run targeted one-off applies with safety flags.

• Export plan: dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- validate schema.avsc --format plan-json --out plan.json
• Apply plan: dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- apply --plan plan.json --ids <id> --write
• Spot autofix (dry-run): dotnet run --project src/cli/Avrolution.Cli/Avrolution.Cli.csproj -- validate schema.avsc --apply --only nonbreaking --dry-run

Docs map

• docs/profiles.md profile semantics and validation pipeline
• docs/api.md API surface summary
• docs/architecture.md high-level architecture notes
• .github/copilot-instructions.md repository guidance for AI-assisted changes

CI and release

• CI workflow: .github/workflows/ci.yml
  • Builds/tests .NET projects
  • Runs CLI smoke checks
  • Builds/tests web app
• Release workflow: .github/workflows/release.yml
  • Packages Avrolution.Cli as a .NET tool package
  • Publishes artifacts and optional NuGet release when configured