Merge branch 'main' into feat/custom-validation-rules

Author: 0xGaspar

Cargo.lock

@@ -25,6 +25,10 @@ walkdir = "2"
 colored = "3"
 notify = "7"
 notify-debouncer-full = "0.4"
+tree-sitter = "0.24"
+tree-sitter-typescript = "0.23"
+tree-sitter-python = "0.23"
+tree-sitter-rust = "0.23"
 sha2 = "0.10"
 ureq = { version = "3", features = ["json"] }
 dialoguer = "0.11"

Cargo.toml

@@ -9,6 +9,7 @@ tracks: []
 depends_on:
   - specs/commands/commands.spec.md
   - specs/ai/ai.spec.md
+  - specs/git_utils/git_utils.spec.md
   - specs/hash_cache/hash_cache.spec.md
   - specs/ignore/ignore.spec.md
   - specs/output/output.spec.md

specs/cmd_check/cmd_check.spec.md

@@ -8,6 +8,7 @@ db_tables: []
 tracks: []
 depends_on:
   - specs/commands/commands.spec.md
+  - specs/git_utils/git_utils.spec.md
   - specs/parser/parser.spec.md
   - specs/types/types.spec.md
   - specs/validator/validator.spec.md

specs/cmd_report/cmd_report.spec.md

@@ -0,0 +1,79 @@
+---
+module: cmd_stale
+version: 1
+status: stable
+files:
+  - src/commands/stale.rs
+db_tables: []
+tracks:
+  - 188
+depends_on:
+  - specs/commands/commands.spec.md
+  - specs/git_utils/git_utils.spec.md
+  - specs/parser/parser.spec.md
+  - specs/types/types.spec.md
+---
+
+# Cmd Stale
+
+## Purpose
+
+Implements the `specsync stale` command — a focused staleness detection tool that identifies specs whose source files have diverged via git commit history. Reports which specs need updating, how many commits they are behind, and which specific source files have drifted. Supports text, JSON, markdown, and GitHub output formats.
+
+## Public API
+
+### Exported Functions
+
+| Function | Parameters | Returns | Description |
+|----------|-----------|---------|-------------|
+| `cmd_stale` | `root: &Path, format: OutputFormat, threshold: usize` | `()` | Detect and report stale specs based on git commit distance |
+
+## Invariants
+
+1. Staleness is determined by `git_commits_between`: a spec is stale when any source file has >= `threshold` commits since the spec was last modified (default: 5)
+2. Specs with no `files` in frontmatter are counted as fresh (no source files to compare against)
+3. Specs not yet tracked by git (no commit history) are skipped and counted as fresh
+4. Results are sorted by most-stale-first (highest `max_commits_behind`)
+5. Exit code is 1 when any stale specs are found, 0 when all are fresh
+6. Requires a git repository — exits with error if `is_git_repo` returns false
+
+## Behavioral Examples
+
+### Scenario: All specs fresh
+
+- **Given** all specs were updated after their source files
+- **When** `specsync stale` is run
+- **Then** prints "All specs are up to date" and exits 0
+
+### Scenario: Spec behind source by 8 commits (threshold 5)
+
+- **Given** module "auth" has source file `src/auth.rs` with 8 commits since spec was last updated
+- **When** `specsync stale --threshold 5` is run
+- **Then** reports auth as stale with "8 commits behind" and exits 1
+
+### Scenario: JSON output
+
+- **Given** 2 stale specs out of 10 total
+- **When** `specsync stale --format json` is run
+- **Then** outputs JSON with `total_specs: 10`, `stale_count: 2`, `stale_specs` array with per-file details
+
+## Error Cases
+
+| Condition | Behavior |
+|-----------|----------|
+| Not a git repository | Prints error, exits 1 |
+| Spec file unreadable | Skipped silently |
+| No frontmatter | Skipped silently |
+| Source file doesn't exist on disk | Skipped in commit distance check |
+
+## Dependencies
+
+- `git_utils` — git commit history queries
+- `parser` — frontmatter parsing for module name and files list
+- `commands` — `load_and_discover` for config and spec file discovery
+
+## Change Log
+
+| Date | Change |
+|------|--------|
+| 2026-04-10 | Initial — dedicated staleness detection command (closes #188) |

specs/cmd_stale/cmd_stale.spec.md

@@ -0,0 +1,22 @@
+---
+spec: cmd_stale.spec.md
+---
+
+## User Stories
+
+- As a developer, I want to know which specs have drifted from their source files so I can update them
+- As a CI operator, I want staleness checks integrated into the validation pipeline so drift is caught early
+
+## Acceptance Criteria
+
+- `specsync stale` lists specs whose source files have changed since the spec was last modified
+- Reports include commit count, changed file list, and last commit details
+- JSON output mode (`--format json`) produces machine-readable staleness data
+- `specsync check --stale` integrates drift warnings into the standard check pipeline
+- Exit code is non-zero when stale specs are detected (for CI usage)
+
+## Constraints
+
+- Must not panic on expected error conditions — return Results or print and exit
+- Must work with the project's Clap-based CLI argument parsing
+- Git operations must handle missing git repos gracefully (non-git directories)

specs/cmd_stale/requirements.md

@@ -59,6 +59,7 @@ Shared command infrastructure used by all CLI subcommands. Provides config loadi
 | `report` | Per-module coverage report with staleness |
 | `resolve` | Resolve cross-project dependency refs |
 | `rules` | List active validation rules (built-in and custom) |
+| `stale` | Git-based staleness detection for spec drift |
 | `scaffold` | Full spec scaffolding with templates |
 | `score` | Spec quality scoring (0-100, A-F) |
 | `view` | Role-filtered spec rendering |
@@ -129,6 +130,7 @@ Shared command infrastructure used by all CLI subcommands. Provides config loadi
 | cmd_score | `load_and_discover`, `filter_specs` |
 | cmd_report | `load_and_discover` |
 | cmd_resolve | `load_and_discover` |
+| cmd_stale | `load_and_discover` |
 | cmd_diff | `load_and_discover` |
 
 ## Change Log

specs/commands/commands.spec.md

@@ -15,6 +15,10 @@ files:
   - src/exports/csharp.rs
   - src/exports/php.rs
   - src/exports/ruby.rs
+  - src/exports/ast/mod.rs
+  - src/exports/ast/typescript.rs
+  - src/exports/ast/python.rs
+  - src/exports/ast/rust_lang.rs
 db_tables: []
 tracks: [60]
 depends_on:
@@ -25,7 +29,7 @@ depends_on:
 
 ## Purpose
 
-Language-aware export extraction from source files. Auto-detects the programming language from file extension and extracts public/exported symbol names using regex-based parsing (no AST required). Supports 11 languages: TypeScript/JS, Rust, Go, Python, Swift, Kotlin, Java, C#, Dart, PHP, and Ruby.
+Language-aware export extraction from source files. Auto-detects the programming language from file extension and extracts public/exported symbol names using regex-based parsing or tree-sitter AST analysis. Supports 11 languages: TypeScript/JS, Rust, Go, Python, Swift, Kotlin, Java, C#, Dart, PHP, and Ruby.
 
 ## Public API
 
@@ -40,6 +44,23 @@ Language-aware export extraction from source files. Auto-detects the programming
 | `has_extension` | `file_path: &Path, extensions: &[String]` | `bool` | Check if file matches specific extensions, or any supported language if extensions is empty |
 | `extract_exports` | `content: &str` | `Vec<String>` | Per-language backend function that parses source text and returns exported symbol names (one per backend file) |
 | `extract_exports_with_resolver` | `content: &str, resolver: Option<&ImportResolver>` | `Vec<String>` | TypeScript-specific: extract exports with optional wildcard re-export resolution via file resolver callback |
+| `get_exported_symbols_full` | `file_path: &Path, level: ExportLevel, parse_mode: ParseMode` | `Vec<String>` | Extract exports with full control over granularity and parse mode (Regex or Ast) |
+
+### Exported Modules
+
+| Module | Source | Description |
+|--------|--------|-------------|
+| `ast` | `src/exports/mod.rs` | Tree-sitter based AST export extraction backends |
+
+### Exported AST Sub-modules
+
+Tree-sitter based export extraction backends for TypeScript, Python, and Rust. Used when `ParseMode::Ast` is selected. Falls back to regex extraction for unsupported languages or when AST parsing fails.
+
+| Sub-module | File | Description |
+|------------|------|-------------|
+| `typescript` | `ast/typescript.rs` | Tree-sitter based TypeScript/JS export extraction with wildcard resolver support |
+| `python` | `ast/python.rs` | Tree-sitter based Python export extraction using `__all__` and top-level definitions |
+| `rust_lang` | `ast/rust_lang.rs` | Tree-sitter based Rust `pub` item extraction |
 
 ### Language Backend Functions
 

specs/exports/exports.spec.md

@@ -0,0 +1,71 @@
+---
+module: git_utils
+version: 1
+status: stable
+files:
+  - src/git_utils.rs
+db_tables: []
+tracks: []
+depends_on: []
+---
+
+# Git Utils
+
+## Purpose
+
+Shared git utility functions for querying repository history. Provides commit hash lookup, commit distance counting, and git repository detection. Used by the `stale`, `report`, and `scoring` modules to determine spec freshness relative to source file changes.
+
+## Public API
+
+### Exported Functions
+
+| Function | Parameters | Returns | Description |
+|----------|-----------|---------|-------------|
+| `git_last_commit_hash` | `root: &Path, file: &str` | `Option<String>` | Get the SHA hash of the last commit that touched a file |
+| `git_commits_between` | `root: &Path, spec_file: &str, source_file: &str` | `usize` | Count commits to source_file since spec_file was last modified |
+| `is_git_repo` | `root: &Path` | `bool` | Check if a directory is inside a git work tree |
+
+### Exported Types
+
+| Type | Kind | Description |
+|------|------|-------------|
+| `StaleInfo` | struct | Staleness summary for a single spec: path, module name, max commits behind, per-file details |
+
+## Invariants
+
+1. All git commands execute with `current_dir(root)` to ensure correct repository context
+2. Functions return safe defaults (None, 0, false) when git is unavailable or commands fail
+3. `git_commits_between` uses `git rev-list --count {spec_commit}..HEAD -- {source_file}` to count divergence
+4. `StaleInfo.source_details` only includes files with commits_behind > 0
+
+## Behavioral Examples
+
+### Scenario: File not tracked by git
+
+- **Given** a file that has never been committed
+- **When** `git_last_commit_hash` is called
+- **Then** returns `None`
+
+### Scenario: Source file changed after spec
+
+- **Given** a spec last committed at commit A, and a source file with 3 commits after A
+- **When** `git_commits_between` is called
+- **Then** returns `3`
+
+## Error Cases
+
+| Condition | Behavior |
+|-----------|----------|
+| Not a git repository | `is_git_repo` returns false; other functions return safe defaults |
+| Git not installed | All functions return None/0/false |
+| File doesn't exist in git history | Returns None or 0 |
+
+## Dependencies
+
+None (only uses `std::process::Command` for git CLI calls).
+
+## Change Log
+
+| Date | Change |
+|------|--------|
+| 2026-04-10 | Initial — extracted from cmd_report for shared use by stale, report, and scoring |

specs/git_utils/git_utils.spec.md

@@ -0,0 +1,21 @@
+---
+spec: git_utils.spec.md
+---
+
+## User Stories
+
+- As a developer, I want git-aware spec tooling so that staleness and freshness are tracked automatically
+- As a module consumer, I want a clean API for git log queries without reimplementing git2 boilerplate
+
+## Acceptance Criteria
+
+- `commits_since` returns accurate commit counts for files since a given timestamp
+- `last_commit_for_file` returns the most recent commit touching a specific file
+- `changed_files_since` lists files modified since a reference point
+- All functions handle missing repos, untracked files, and shallow clones gracefully
+
+## Constraints
+
+- Must not panic on expected error conditions — return Results
+- Must use git2 (libgit2) for git operations, not shell commands
+- Must not hold repository locks longer than necessary