Add analyze composables command

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,7 +32,8 @@ 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
@@ -66,6 +68,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 +96,12 @@ 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
+- 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
+
 ### MongoDB Documentation Structure
 
 **Versioned Projects**: `content/{project}/{version}/source/`

CHANGELOG.md

@@ -5,6 +5,24 @@ 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-11
+
+### 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-consolidation-candidates` - Show identical and similar composables for consolidation
+    - `--find-usages` - Show where each composable is used in RST files with file paths
+
 ## [0.1.0] - 2025-12-10
 
 ### Added

README.md

@@ -65,7 +65,8 @@ audit-cli
 ├── analyze          # Analyze RST file structures
 │   ├── includes
 │   ├── usage
-│   └── procedures
+│   ├── procedures
+│   └── composables
 ├── compare          # Compare files across versions
 │   └── file-contents
 └── count            # Count code examples and documentation pages
@@ -835,6 +836,207 @@ The parser ensures deterministic results by:
 
 For more details about procedure parsing logic, refer to [docs/PROCEDURE_PARSING.md](docs/PROCEDURE_PARSING.md).
 
+#### `analyze composables`
+
+Analyze composable definitions in `snooty.toml` files across the MongoDB documentation monorepo. This command helps identify consolidation opportunities and track composable usage.
+
+Composables are configuration elements in `snooty.toml` that define content variations for different contexts (e.g., different programming languages, deployment types, or interfaces). They're used in `.. composable-tutorial::` directives to create context-specific documentation.
+
+**Use Cases:**
+
+This command helps writers:
+- Inventory all composables across projects and versions
+- Identify identical composables that could be consolidated across projects
+- Find similar composables with different IDs but overlapping options (potential consolidation candidates)
+- Track where composables are used in RST files
+- Identify unused composables that may be candidates for removal
+- Understand the scope of changes when updating a composable
+
+**Basic Usage:**
+
+```bash
+# Analyze all composables in the monorepo
+./audit-cli analyze composables /path/to/docs-monorepo
+
+# Analyze composables for a specific project
+./audit-cli analyze composables /path/to/docs-monorepo --for-project atlas
+
+# Analyze only current versions
+./audit-cli analyze composables /path/to/docs-monorepo --current-only
+
+# Show full option details with titles
+./audit-cli analyze composables /path/to/docs-monorepo --verbose
+
+# Find consolidation candidates
+./audit-cli analyze composables /path/to/docs-monorepo --find-consolidation-candidates
+
+# Find where composables are used
+./audit-cli analyze composables /path/to/docs-monorepo --find-usages
+
+# Combine flags for comprehensive analysis
+./audit-cli analyze composables /path/to/docs-monorepo --for-project atlas --find-consolidation-candidates --find-usages --verbose
+```
+
+**Flags:**
+
+- `--for-project <project>` - Only analyze composables for a specific project
+- `--current-only` - Only analyze composables in current versions (skips versioned directories)
+- `-v, --verbose` - Show full option details with titles instead of just IDs
+- `--find-consolidation-candidates` - Show identical and similar composables for consolidation
+- `--find-usages` - Show where each composable is used in RST files
+
+**Output:**
+
+**Default output (summary and table):**
+```
+Composables Analysis
+====================
+
+Total composables found: 24
+
+Composables by ID:
+  - deployment-type: 1
+  - interface: 1
+  - language: 1
+  ...
+
+All Composables
+===============
+
+Project              Version         ID                             Title                          Options
+------------------------------------------------------------------------------------------------------------------------
+atlas                (none)          deployment-type                Deployment Type                atlas, local, self, local-onprem
+atlas                (none)          interface                      Interface                      compass, mongosh, atlas-ui, driver
+atlas                (none)          language                       Language                       c, csharp, cpp, go, java-async, ...
+```
+
+**With `--find-consolidation-candidates`:**
+
+Shows two types of consolidation opportunities:
+
+1. **Identical Composables** - Same ID, title, and options across different projects/versions
+   ```
+   Identical Composables (Consolidation Candidates)
+   ================================================
+
+   ID: connection-mechanism
+   Occurrences: 15
+   Title: Connection Mechanism
+   Default: connection-string
+   Options: connection-string, mongocred
+
+   Found in:
+     - java/current
+     - java/v5.1
+     - kotlin/current
+     ...
+   ```
+
+2. **Similar Composables** - Different IDs but similar option sets (60%+ overlap)
+   ```
+   Similar Composables (Review Recommended)
+   ========================================
+
+   Similar Composables (100.0% similarity)
+   Composables: 2
+
+   Composables in this group:
+
+     1. ID: interface-atlas-only
+        Location: atlas
+        Title: Interface
+        Default: driver
+        Options: atlas-ui, driver, mongosh
+
+     2. ID: interface-local-only
+        Location: atlas
+        Title: Interface
+        Default: driver
+        Options: atlas-ui, driver, mongosh
+   ```
+
+**With `--find-usages`:**
+
+Shows where each composable is used in `.. composable-tutorial::` directives:
+
+```
+Composable Usages
+=================
+
+Composable ID: deployment-type
+Total usages: 28
+
+  atlas: 28 usages
+
+Composable ID: interface
+Total usages: 35
+
+  atlas: 35 usages
+
+Unused Composables
+------------------
+
+  connection-type:
+    - atlas
+```
+
+**With `--verbose` and `--find-usages`:**
+
+Shows file paths where each composable is used:
+
+```
+Composable ID: interface-atlas-only
+Total usages: 1
+
+  atlas: 1 usages
+    - content/atlas/source/atlas-vector-search/tutorials/vector-search-quick-start.txt
+```
+
+**Understanding Composables:**
+
+Composables are defined in `snooty.toml` files:
+```toml
+[[composables]]
+id = "language"
+title = "Language"
+default = "nodejs"
+
+[[composables.options]]
+id = "python"
+title = "Python"
+
+[[composables.options]]
+id = "nodejs"
+title = "Node.js"
+```
+
+They're used in RST files with `.. composable-tutorial::` directives:
+```rst
+.. composable-tutorial::
+   :options: language, interface
+   :defaults: nodejs, driver
+
+   .. procedure::
+      .. step:: Install dependencies
+         .. selected-content::
+            :selections: language=nodejs
+            npm install mongodb
+         .. selected-content::
+            :selections: language=python
+            pip install pymongo
+```
+
+**Consolidation Analysis:**
+
+The command uses Jaccard similarity (intersection / union) to compare option sets between composables with different IDs. A 60% similarity threshold is used to identify potential consolidation candidates.
+
+For example, if you have:
+- `language` with 15 options
+- `language-atlas-only` with 14 options (13 in common with `language`)
+- `language-local-only` with 14 options (13 in common with `language`)
+
+These would be flagged as similar composables (93.3% similarity) and potential consolidation candidates.
+
 ### Compare Commands
 
 #### `compare file-contents`

commands/analyze/analyze.go

@@ -5,11 +5,13 @@
 //   - includes: Analyze include directive relationships in RST files
 //   - usage: Find all files that use a target file
 //   - procedures: Analyze procedure variations and statistics
+//   - composables: Analyze composables in snooty.toml files
 //
 // Future subcommands could include analyzing cross-references, broken links, or content metrics.
 package analyze
 
 import (
+	"github.com/grove-platform/audit-cli/commands/analyze/composables"
 	"github.com/grove-platform/audit-cli/commands/analyze/includes"
 	"github.com/grove-platform/audit-cli/commands/analyze/procedures"
 	"github.com/grove-platform/audit-cli/commands/analyze/usage"
@@ -30,6 +32,7 @@ Currently supports:
   - includes: Analyze include directive relationships (forward dependencies)
   - usage: Find all files that use a target file (reverse dependencies)
   - procedures: Analyze procedure variations and statistics
+  - composables: Analyze composables in snooty.toml files
 
 Future subcommands may support analyzing cross-references, broken links, or content metrics.`,
 	}
@@ -38,6 +41,7 @@ Future subcommands may support analyzing cross-references, broken links, or cont
 	cmd.AddCommand(includes.NewIncludesCommand())
 	cmd.AddCommand(usage.NewUsageCommand())
 	cmd.AddCommand(procedures.NewProceduresCommand())
+	cmd.AddCommand(composables.NewComposablesCommand())
 
 	return cmd
 }