Merge pull request #3 from grove-platform/analyze-composables

Add analyze composables command

Author: dacharyc

AGENTS.md

@@ -10,6 +10,7 @@ This document provides essential context for LLMs performing development tasks i
 - Extract code examples and procedures from RST files
 - Search documentation for patterns
 - Analyze file dependencies and relationships
+- Analyze composable definitions and usage across projects
 - Compare files across documentation versions
 - Count documentation pages and tested code examples
 
@@ -31,13 +32,17 @@ audit-cli/
 │   ├── analyze/              # Analyze RST structures
 │   │   ├── includes/         # Analyze include relationships
 │   │   ├── usage/            # Find file usages
-│   │   └── procedures/       # Analyze procedure variations
+│   │   ├── procedures/       # Analyze procedure variations
+│   │   └── composables/      # Analyze composable definitions and usage
 │   ├── compare/              # Compare files across versions
 │   │   └── file-contents/    # Compare file contents
 │   └── count/                # Count documentation content
 │       ├── tested-examples/  # Count tested code examples
 │       └── pages/            # Count documentation pages
 ├── internal/                 # Internal packages (not importable externally)
+│   ├── config/               # Configuration management
+│   │   ├── config.go         # Config loading from file/env/args
+│   │   └── config_test.go    # Config tests
 │   ├── projectinfo/          # MongoDB docs project structure utilities
 │   │   ├── pathresolver.go  # Path resolution
 │   │   ├── source_finder.go # Source directory detection
@@ -47,7 +52,8 @@ audit-cli/
 │       ├── directive_parser.go # Directive parsing
 │       ├── directive_regex.go  # Regex patterns for directives
 │       ├── parse_procedures.go # Procedure parsing (core logic)
-│       └── get_procedure_variations.go # Variation extraction
+│       ├── get_procedure_variations.go # Variation extraction
+│       └── rstspec.go        # Fetch and parse canonical rstspec.toml
 ├── testdata/                 # Test fixtures (auto-ignored by Go build)
 │   ├── input-files/source/   # Test RST files
 │   ├── expected-output/      # Expected extraction results
@@ -66,6 +72,7 @@ audit-cli/
 - **CLI Framework**: [spf13/cobra](https://github.com/spf13/cobra)
 - **Diff Library**: [aymanbagabas/go-udiff](https://github.com/aymanbagabas/go-udiff)
 - **YAML Parsing**: gopkg.in/yaml.vX
+- **TOML Parsing**: [github.com/BurntSushi/toml](https://github.com/BurntSushi/toml) v1.5.0
 - **Testing**: Go standard library (`testing` package)
 
 Refer to the `go.mod` for version info.
@@ -93,6 +100,14 @@ Refer to the `go.mod` for version info.
 - `.. include::` - Include RST content from other files
 - `.. toctree::` - Table of contents (navigation, not content inclusion)
 
+**Composables**:
+- Defined in `snooty.toml` files at project/version root
+- Canonical definitions also exist in `rstspec.toml` in the snooty-parser repository
+- Used in `.. composable-tutorial::` directives with `:options:` parameter
+- Enable context-specific documentation (e.g., different languages, deployment types)
+- Each composable has an ID, title, default, and list of options
+- The `internal/rst` module provides `FetchRstspec()` to retrieve canonical definitions
+
 ### MongoDB Documentation Structure
 
 **Versioned Projects**: `content/{project}/{version}/source/`
@@ -103,6 +118,83 @@ Refer to the `go.mod` for version info.
 **Tested Code Examples**: `content/code-examples/tested/{language}/{product}/`
 - Products: `pymongo`, `mongosh`, `go/driver`, `go/atlas-sdk`, `javascript/driver`, `java/driver-sync`, `csharp/driver`
 
+## Configuration
+
+### Monorepo Path Configuration
+
+Some commands require a monorepo path (`analyze composables`, `count tested-examples`, `count pages`). The path can be configured in three ways, with the following priority (highest to lowest):
+
+1. **Command-line argument** - Passed directly to the command
+2. **Environment variable** - `AUDIT_CLI_MONOREPO_PATH`
+3. **Config file** - `.audit-cli.yaml` in current directory or home directory
+
+**Config File Format** (`.audit-cli.yaml`):
+```yaml
+monorepo_path: /path/to/docs-monorepo
+```
+
+**Config File Locations** (searched in order):
+1. Current directory: `./.audit-cli.yaml`
+2. Home directory: `~/.audit-cli.yaml`
+
+**Implementation**:
+- Config loading is handled by `internal/config` package
+- Commands use `config.GetMonorepoPath(cmdLineArg)` to resolve the path
+- Commands accept 0 or 1 arguments using `cobra.MaximumNArgs(1)`
+- If no path is configured, a helpful error message is displayed
+
+**Example Usage**:
+```go
+// In command RunE function
+var cmdLineArg string
+if len(args) > 0 {
+    cmdLineArg = args[0]
+}
+monorepoPath, err := config.GetMonorepoPath(cmdLineArg)
+if err != nil {
+    return err
+}
+```
+
+### File Path Resolution
+
+File-based commands support flexible path resolution through `config.ResolveFilePath()`. This allows users to specify paths in three ways:
+
+1. **Absolute path** - Used as-is
+2. **Relative to monorepo root** - If monorepo is configured and path exists there
+3. **Relative to current directory** - Fallback if not found in monorepo
+
+**Priority Order**:
+1. If path is absolute → return as-is (after verifying it exists)
+2. If monorepo is configured and path exists relative to monorepo → use monorepo-relative path
+3. Otherwise → resolve relative to current directory
+
+**Implementation**:
+- File path resolution is handled by `config.ResolveFilePath(pathArg)` in `internal/config` package
+- Commands that take file paths should use this function in their `RunE` function
+- The function returns an absolute path or an error if the path doesn't exist
+
+**Example Usage**:
+```go
+// In command RunE function for file-based commands
+RunE: func(cmd *cobra.Command, args []string) error {
+    // Resolve file path (supports absolute, monorepo-relative, or cwd-relative)
+    filePath, err := config.ResolveFilePath(args[0])
+    if err != nil {
+        return err
+    }
+    return runCommand(filePath, ...)
+}
+```
+
+**Commands Using File Path Resolution**:
+- `extract code-examples`
+- `extract procedures`
+- `analyze includes`
+- `analyze usage`
+- `search find-string`
+- `compare file-contents`
+
 ## Building and Running
 
 ### Build from Source

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to audit-cli will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-12-12
+
+### Added
+
+#### Analyze Commands
+- `analyze composables` - Analyze composable definitions in snooty.toml files
+  - Inventory all composables across projects and versions
+  - Identify identical composables (same ID, title, and options) across different projects/versions
+  - Find similar composables with different IDs but overlapping option sets using Jaccard similarity (60% threshold)
+  - Track composable usage in RST files via `composable-tutorial` directives
+  - Identify unused composables that may be candidates for removal
+  - Flags:
+    - `--for-project` - Filter to a specific project
+    - `--current-only` - Only analyze current versions
+    - `--verbose` - Show full option details with titles
+    - `--find-similar` - Show identical and similar composables for consolidation
+    - `--find-usages` - Show where each composable is used in RST files with file paths
+    - `--with-rstspec` - Show canonical composable definitions from rstspec.toml
+
+#### Configuration System
+- Monorepo path configuration via three methods (priority order):
+  1. Command-line argument (highest priority)
+  2. Environment variable `AUDIT_CLI_MONOREPO_PATH`
+  3. Config file `.audit-cli.yaml` in current or home directory (lowest priority)
+- Config file format:
+  ```yaml
+  monorepo_path: /path/to/docs-monorepo
+  ```
+- Applies to commands: `analyze composables`, `count tested-examples`, `count pages`
+
+#### File Path Resolution
+- Flexible path resolution for all file-based commands
+- Supports three path types (priority order):
+  1. Absolute paths - Used as-is
+  2. Relative to monorepo root - If monorepo configured and file exists there
+  3. Relative to current directory - Fallback
+- Applies to commands: `extract code-examples`, `extract procedures`, `analyze includes`, `analyze usage`, `search find-string`, `compare file-contents`
+- Eliminates need to type full paths when working with monorepo files
+
+#### Internal Packages
+- `internal/config` - Configuration management
+  - Config file loading from `.audit-cli.yaml`
+  - Environment variable support
+  - Monorepo path resolution with priority order
+  - File path resolution with flexible resolution
+- `internal/rst` - Enhanced RST parsing
+  - `FetchRstspec()` - Fetches canonical composable definitions from snooty-parser rstspec.toml
+  - Provides standard composable IDs, titles, defaults, and options
+
 ## [0.1.0] - 2025-12-10
 
 ### Added