feat: add --json CLI flag and CHANGELOG.md (#5)

Add a global --json flag that outputs structured JSON for check,
coverage, and generate commands, enabling CI/CD and tooling integration.
Also add CHANGELOG.md documenting the v1.0.0 release. Fix pre-existing
rustfmt issues in if-let chains across multiple files.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: corvid-agent

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-18
+
+### Added
+
+- **Complete rewrite from TypeScript to Rust** for language-agnostic spec validation
+  with significantly improved performance and a single static binary.
+- **9 language backends** for export extraction: TypeScript/JavaScript, Rust, Go,
+  Python, Swift, Kotlin, Java, C#, and Dart.
+- **`check` command** — validates all spec files against source code, checking
+  frontmatter, file existence, required sections, API surface coverage,
+  DB table references, and dependency specs.
+- **`coverage` command** — reports file and module coverage, listing unspecced
+  files and modules.
+- **`generate` command** — scaffolds spec files for unspecced modules using
+  a customizable template (`_template.spec.md`).
+- **`init` command** — creates a default `specsync.json` configuration file.
+- **`--json` flag** — global CLI flag that outputs results as structured JSON
+  instead of colored terminal text, for CI/CD and tooling integration.
+- **`--strict` flag** — treats warnings as errors for CI enforcement.
+- **`--require-coverage N` flag** — fails if file coverage percent is below
+  the given threshold.
+- **`--root` flag** — overrides the project root directory.
+- **CI/CD workflows** with GitHub Actions for testing, linting, and
+  multi-platform release binary publishing (Linux x86_64/aarch64,
+  macOS x86_64/aarch64, Windows x86_64).
+- Configurable required sections, exclude patterns, source extensions,
+  and schema table validation via `specsync.json`.
+- YAML frontmatter parsing without external YAML dependencies.
+- API surface validation: detects undocumented exports (warnings) and
+  phantom documentation for non-existent exports (errors).
+- Dependency spec cross-referencing and Consumed By section validation.
+
+[1.0.0]: https://github.com/CorvidLabs/spec-sync/releases/tag/v1.0.0

src/generator.rs

@@ -212,3 +212,50 @@ pub fn generate_specs_for_unspecced_modules(
 
     generated
 }
+
+/// Generate spec files for all unspecced modules, returning the paths of generated files.
+pub fn generate_specs_for_unspecced_modules_paths(
+    root: &Path,
+    report: &CoverageReport,
+    config: &SpecSyncConfig,
+) -> Vec<String> {
+    let specs_dir = root.join(&config.specs_dir);
+    let mut generated_paths = Vec::new();
+
+    for module_name in &report.unspecced_modules {
+        let spec_dir = specs_dir.join(module_name);
+        let spec_file = spec_dir.join(format!("{module_name}.spec.md"));
+
+        if spec_file.exists() {
+            continue;
+        }
+
+        let mut module_files = Vec::new();
+        for src_dir in &config.source_dirs {
+            let module_dir = root.join(src_dir).join(module_name);
+            let files = find_module_source_files(&module_dir, config);
+            module_files.extend(files);
+        }
+
+        if module_files.is_empty() {
+            continue;
+        }
+
+        if fs::create_dir_all(&spec_dir).is_err() {
+            continue;
+        }
+
+        let spec_content = generate_spec(module_name, &module_files, root, &specs_dir);
+
+        if fs::write(&spec_file, &spec_content).is_ok() {
+            let rel = spec_file
+                .strip_prefix(root)
+                .unwrap_or(&spec_file)
+                .to_string_lossy()
+                .to_string();
+            generated_paths.push(rel);
+        }
+    }
+
+    generated_paths
+}

src/main.rs

@@ -13,7 +13,7 @@ use std::path::{Path, PathBuf};
 use std::process;
 
 use config::load_config;
-use generator::generate_specs_for_unspecced_modules;
+use generator::{generate_specs_for_unspecced_modules, generate_specs_for_unspecced_modules_paths};
 use validator::{compute_coverage, find_spec_files, get_schema_table_names, validate_spec};
 
 #[derive(Parser)]
@@ -37,6 +37,10 @@ struct Cli {
     /// Project root directory (default: cwd)
     #[arg(long, global = true)]
     root: Option<PathBuf>,
+
+    /// Output results as JSON instead of colored text
+    #[arg(long, global = true)]
+    json: bool,
 }
 
 #[derive(Subcommand)]
@@ -64,9 +68,9 @@ fn main() {
 
     match command {
         Command::Init => cmd_init(&root),
-        Command::Check => cmd_check(&root, cli.strict, cli.require_coverage),
-        Command::Coverage => cmd_coverage(&root, cli.strict, cli.require_coverage),
-        Command::Generate => cmd_generate(&root, cli.strict, cli.require_coverage),
+        Command::Check => cmd_check(&root, cli.strict, cli.require_coverage, cli.json),
+        Command::Coverage => cmd_coverage(&root, cli.strict, cli.require_coverage, cli.json),
+        Command::Generate => cmd_generate(&root, cli.strict, cli.require_coverage, cli.json),
         Command::Watch => watch::run_watch(&root, cli.strict, cli.require_coverage),
     }
 }
@@ -99,13 +103,31 @@ fn cmd_init(root: &Path) {
     println!("{} Created specsync.json", "✓".green());
 }
 
-fn cmd_check(root: &Path, strict: bool, require_coverage: Option<usize>) {
+fn cmd_check(root: &Path, strict: bool, require_coverage: Option<usize>, json: bool) {
     let (config, spec_files) = load_and_discover(root);
     let schema_tables = get_schema_table_names(root, &config);
-    let (total_errors, total_warnings, passed, total) =
-        run_validation(root, &spec_files, &schema_tables, &config);
+    let (total_errors, total_warnings, passed, total, all_errors, all_warnings) =
+        run_validation(root, &spec_files, &schema_tables, &config, json);
     let coverage = compute_coverage(root, &spec_files, &config);
 
+    if json {
+        let exit_code = compute_exit_code(
+            total_errors,
+            total_warnings,
+            strict,
+            &coverage,
+            require_coverage,
+        );
+        let output = serde_json::json!({
+            "passed": exit_code == 0,
+            "errors": all_errors,
+            "warnings": all_warnings,
+            "specs_checked": total,
+        });
+        println!("{}", serde_json::to_string_pretty(&output).unwrap());
+        process::exit(exit_code);
+    }
+
     print_summary(total, passed, total_warnings, total_errors);
     print_coverage_line(&coverage);
     exit_with_status(
@@ -117,13 +139,36 @@ fn cmd_check(root: &Path, strict: bool, require_coverage: Option<usize>) {
     );
 }
 
-fn cmd_coverage(root: &Path, strict: bool, require_coverage: Option<usize>) {
+fn cmd_coverage(root: &Path, strict: bool, require_coverage: Option<usize>, json: bool) {
     let (config, spec_files) = load_and_discover(root);
     let schema_tables = get_schema_table_names(root, &config);
-    let (total_errors, total_warnings, passed, total) =
-        run_validation(root, &spec_files, &schema_tables, &config);
+    let (total_errors, total_warnings, passed, total, _all_errors, _all_warnings) =
+        run_validation(root, &spec_files, &schema_tables, &config, json);
     let coverage = compute_coverage(root, &spec_files, &config);
 
+    if json {
+        let file_coverage = if coverage.total_source_files == 0 {
+            100.0
+        } else {
+            (coverage.specced_file_count as f64 / coverage.total_source_files as f64) * 100.0
+        };
+
+        let modules: Vec<serde_json::Value> = coverage
+            .unspecced_modules
+            .iter()
+            .map(|m| serde_json::json!({ "name": m, "has_spec": false }))
+            .collect();
+
+        let output = serde_json::json!({
+            "file_coverage": (file_coverage * 100.0).round() / 100.0,
+            "files_covered": coverage.specced_file_count,
+            "files_total": coverage.total_source_files,
+            "modules": modules,
+        });
+        println!("{}", serde_json::to_string_pretty(&output).unwrap());
+        process::exit(0);
+    }
+
     print_coverage_report(&coverage);
     print_summary(total, passed, total_warnings, total_errors);
     print_coverage_line(&coverage);
@@ -136,13 +181,22 @@ fn cmd_coverage(root: &Path, strict: bool, require_coverage: Option<usize>) {
     );
 }
 
-fn cmd_generate(root: &Path, strict: bool, require_coverage: Option<usize>) {
+fn cmd_generate(root: &Path, strict: bool, require_coverage: Option<usize>, json: bool) {
     let (config, spec_files) = load_and_discover(root);
     let schema_tables = get_schema_table_names(root, &config);
-    let (total_errors, total_warnings, passed, total) =
-        run_validation(root, &spec_files, &schema_tables, &config);
+    let (total_errors, total_warnings, passed, total, _all_errors, _all_warnings) =
+        run_validation(root, &spec_files, &schema_tables, &config, json);
     let coverage = compute_coverage(root, &spec_files, &config);
 
+    if json {
+        let generated_paths = generate_specs_for_unspecced_modules_paths(root, &coverage, &config);
+        let output = serde_json::json!({
+            "generated": generated_paths,
+        });
+        println!("{}", serde_json::to_string_pretty(&output).unwrap());
+        process::exit(0);
+    }
+
     print_coverage_report(&coverage);
 
     println!(
@@ -196,19 +250,34 @@ fn load_and_discover(root: &Path) -> (types::SpecSyncConfig, Vec<PathBuf>) {
     (config, spec_files)
 }
 
+/// Run validation, returning counts and collected error/warning strings.
 fn run_validation(
     root: &Path,
     spec_files: &[PathBuf],
     schema_tables: &std::collections::HashSet<String>,
     config: &types::SpecSyncConfig,
-) -> (usize, usize, usize, usize) {
+    json: bool,
+) -> (usize, usize, usize, usize, Vec<String>, Vec<String>) {
     let mut total_errors = 0;
     let mut total_warnings = 0;
     let mut passed = 0;
+    let mut all_errors: Vec<String> = Vec::new();
+    let mut all_warnings: Vec<String> = Vec::new();
 
     for spec_file in spec_files {
         let result = validate_spec(spec_file, root, schema_tables, config);
 
+        if json {
+            all_errors.extend(result.errors.iter().cloned());
+            all_warnings.extend(result.warnings.iter().cloned());
+            total_errors += result.errors.len();
+            total_warnings += result.warnings.len();
+            if result.errors.is_empty() {
+                passed += 1;
+            }
+            continue;
+        }
+
         println!("\n{}", result.spec_path.bold());
 
         // Frontmatter check
@@ -334,7 +403,36 @@ fn run_validation(
         }
     }
 
-    (total_errors, total_warnings, passed, spec_files.len())
+    (
+        total_errors,
+        total_warnings,
+        passed,
+        spec_files.len(),
+        all_errors,
+        all_warnings,
+    )
+}
+
+/// Compute exit code without printing or exiting.
+fn compute_exit_code(
+    total_errors: usize,
+    total_warnings: usize,
+    strict: bool,
+    coverage: &types::CoverageReport,
+    require_coverage: Option<usize>,
+) -> i32 {
+    if total_errors > 0 {
+        return 1;
+    }
+    if strict && total_warnings > 0 {
+        return 1;
+    }
+    if let Some(req) = require_coverage
+        && coverage.coverage_percent < req
+    {
+        return 1;
+    }
+    0
 }
 
 fn print_summary(total: usize, passed: usize, warnings: usize, _errors: usize) {