@aiready/cli 0.14.14 → 0.14.16

package/CONTRIBUTING.md

@@ -39,15 +39,100 @@ The CLI follows a **hub-and-spoke** pattern:
 - **Spoke integration**: Each analysis tool is independent and imported as needed
 - **Unified interface**: Consistent CLI options across all tools
 
+## � Development Setup
+
+1. Clone the [monorepo](https://github.com/caopengau/aiready):
+
+   ```bash
+   git clone https://github.com/caopengau/aiready.git
+   cd aiready
+   pnpm install
+   ```
+
+2. The CLI is located in `packages/cli/`
+
+3. Build and develop:
+
+   ```bash
+   # Build the CLI
+   pnpm build
+
+   # Watch mode for development
+   pnpm dev
+
+   # Run tests
+   pnpm test
+
+   # Run linter
+   pnpm lint
+   ```
+
+## 🔧 Making Changes
+
+1. Create a feature branch from `main`:
+
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. Make your changes and write tests if applicable
+
+3. Run tests and linter:
+
+   ```bash
+   pnpm test
+   pnpm lint
+   ```
+
+4. Commit with [Conventional Commits](https://www.conventionalcommits.org/):
+
+   ```bash
+   git commit -m "feat: add new feature"
+   git commit -m "fix: resolve issue"
+   git commit -m "docs: update guide"
+   ```
+
+5. Push to your fork and open a Pull Request
+
+## 📋 Pull Request Guidelines
+
+- Ensure all tests pass
+- Update documentation if needed
+- Link related issues
+- Keep PRs focused on a single feature or fix
+- Use clear, descriptive commit messages
+
+## 📦 Publishing
+
+Publishing is handled automatically via the monorepo's release process:
+
+```bash
+# From monorepo root
+make sync               # Syncs all spokes and publishes
+make npm-publish SPOKE=cli  # Publish CLI individually
+```
+
+For more details, see [Release Management](../../.github/sub-instructions/release-management.md)
+
 ## 🐛 Reporting Issues
 
-Found a bug or have a feature request? [Open an issue](https://github.com/caopengau/aiready-cli/issues) with:
+Found a bug or have a feature request? [Open an issue on GitHub](https://github.com/caopengau/aiready/issues) with:
 
 - Clear description of the problem or feature
 - Steps to reproduce (for bugs)
 - Expected vs actual behavior
 - Your environment (Node version, OS)
 
+## ❓ Questions?
+
+- Review the [README.md](./README.md)
+- Check [AIReady documentation](https://getaiready.dev/)
+- Browse existing [discussions and issues](https://github.com/caopengau/aiready/discussions)
+
+## 📄 License
+
+All contributions are licensed under the MIT License.
+
 ## 🔧 Development Setup
 
 ```bash

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AIReady Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,93 +1,193 @@
 # @aiready/cli
 
-> Unified command-line interface for the AIReady framework.
+> Assess and improve your codebase's AI-readiness. Get an AI Readiness Score (0-100) and detect issues that confuse AI models.
 
-## 🏛️ Architecture
+[![npm version](https://img.shields.io/npm/v/@aiready/cli)](https://www.npmjs.com/package/@aiready/cli)
+[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/pengcao.aiready?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=pengcao.aiready)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Actions](https://github.com/caopengau/aiready-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/caopengau/aiready-cli/actions)
 
-```markdown
-# @aiready/cli
+## 🚀 Quick Start
 
-> Unified command-line interface for the AIReady framework.
+```bash
+# Install globally
+npm install -g @aiready/cli
 
-## 🏛️ Architecture
+# Scan your codebase
+aiready scan .
+
+# Get detailed analysis
+aiready scan . --output report.json
 ```
 
-                    🎯 USER
-                      │
-                      ▼
-         🎛️  @aiready/cli (orchestrator)  ← YOU ARE HERE
-          │     │     │     │     │     │     │     │     │
-          ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼
-        [PAT] [CTX] [CON] [AMP] [DEP] [DOC] [SIG] [AGT] [TST]
-          │     │     │     │     │     │     │     │     │
-          └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
-                               │
-                               ▼
-                      🏢 @aiready/core
+## 🤖 Why AIReady?
+
+As AI becomes deeply integrated into software development, codebases become harder for AI models to understand due to:
+
+- **Knowledge cutoff limitations** in AI models
+- **Context fragmentation** that breaks AI understanding
+- **Duplicated patterns** AI doesn't recognize
+- **Inconsistent naming** across the codebase
 
-Legend:
-PAT = pattern-detect CTX = context-analyzer
-CON = consistency AMP = change-amplification
-DEP = deps-health DOC = doc-drift
-SIG = ai-signal-clarity AGT = agent-grounding
-TST = testability
+AIReady helps teams **assess, visualize, and prepare** repositories for better AI adoption.
 
-````
+## 🌟 The AIReady Ecosystem
 
-## Language Support
+| Integration       | Package                                                                          | Description                                     |
+| ----------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- |
+| **CLI**           | [`@aiready/cli`](https://www.npmjs.com/package/@aiready/cli)                     | Unified command-line interface                  |
+| **VS Code**       | [`aiready`](https://marketplace.visualstudio.com/items?itemName=pengcao.aiready) | Real-time AI readiness analysis in VS Code      |
+| **GitHub Action** | [`aiready-action`](https://github.com/marketplace/actions/aiready-action)        | CI/CD integration for automated scans           |
+| **MCP Server**    | [`@aiready/mcp-server`](https://www.npmjs.com/package/@aiready/mcp-server)       | Model Context Protocol server for AI assistants |
+| **Skills**        | [`@aiready/skills`](https://github.com/caopengau/aiready-skills)                 | AI-friendly coding practices for agents         |
+| **Docker**        | [`aiready/cli`](https://hub.docker.com/r/aiready/cli)                            | Containerized CLI                               |
+| **Homebrew**      | `brew install caopengau/aiready/aiready`                                         | macOS package                                   |
 
-Analyzes **TypeScript, JavaScript, Python, Java, Go, and C#** (95% market coverage).
+## ✨ Features
 
-## Overview
+- **AI Readiness Score** - Get a 0-100 score indicating how AI-ready your codebase is
+- **Semantic Duplicate Detection** - Find duplicate patterns that waste AI context window tokens
+- **Context Analysis** - Analyze context window costs, import depth, and dependency fragmentation
+- **Consistency Checks** - Ensure naming conventions and pattern consistency
+- **Documentation Drift** - Track documentation freshness vs code churn
+- **Testability Assessment** - Measure code testability for AI agents
+- **Agent Grounding** - Evaluate how well code aids AI agents
+- **Interactive Visualization** - Generate force-directed graph visualizations
+- **CI/CD Integration** - Quality gates for AI readiness in your pipeline
 
-The CLI provides both unified analysis (scan multiple tools at once) and individual tool access for pattern detection, context analysis, and consistency checking.
+## 📋 Commands
 
-## Usage
+### Unified Scan
+
+Run all analysis tools at once:
 
 ```bash
-# Scan a codebase
 aiready scan .
-
-# Run a specific tool
-aiready patterns . --similarity 0.6
+aiready scan . --output report.json
+aiready scan . --threshold 70
 ```
 
-## 🛠️ Building Your Own Tool (Spokes)
+### Individual Tools
 
-Want to build your own analysis tool that integrates with the AIReady ecosystem? Check out our [Spoke Development Guide](./docs/SPOKE_GUIDE.md).
+| Command               | Description                                |
+| --------------------- | ------------------------------------------ |
+| `aiready patterns`    | Detect semantic duplicates and patterns    |
+| `aiready context`     | Analyze context window cost & dependencies |
+| `aiready consistency` | Check naming conventions                   |
+| `aiready testability` | Assess code testability                    |
+| `aiready visualize`   | Generate interactive visualizations        |
+| `aiready upload`      | Upload results to AIReady platform         |
 
-## 🌐 Platform Integration
+## 📦 Installation
 
+### npm / pnpm / yarn
 
-Connect your local scans to the [AIReady Dashboard](https://platform.getaiready.dev/dashboard).
+```bash
+# npm
+npm install -g @aiready/cli
 
-### Automatic Upload
+# pnpm
+pnpm add -g @aiready/cli
+
+# yarn
+yarn global add @aiready/cli
+```
 
-Scan and upload results in one step:
+### Docker
 
 ```bash
-aiready scan . --upload --api-key ar_...
-```
+# Pull from Docker Hub
+docker pull aiready/cli
+
+# Run
+docker run aiready/cli scan .
 
-### Manual Upload
+# Or use the image directly
+docker run -v $(pwd):/app aiready/cli scan /app
+```
 
-Upload an existing report JSON:
+### Homebrew
 
 ```bash
-aiready upload .aiready/latest.json --api-key ar_...
+brew install caopengau/aiready/aiready
 ```
 
-### Options
+### VS Code Extension
 
-- `--upload`: Automatically upload results after scan
-- `--api-key <key>`: Your platform API key (or set `AIREADY_API_KEY`)
-- `--server <url>`: Custom platform URL (optional)
+Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pengcao.aiready) or search for "AIReady" in VS Code extensions.
 
-## License
+### GitHub Action
 
-MIT
+```yaml
+- name: AIReady Code Analysis
+  uses: caopengau/aiready-action@v1
+  with:
+    threshold: 70
+```
 
+### MCP Server
+
+```bash
+npm install -g @aiready/mcp-server
+aiready-mcp
 ```
 
+## 🔧 Configuration
+
+Create an `aiready.json` config file:
+
+```json
+{
+  "scan": {
+    "exclude": ["**/dist/**", "**/node_modules/**"]
+  },
+  "tools": {
+    "pattern-detect": { "minSimilarity": 0.5 },
+    "context-analyzer": { "maxContextBudget": 15000 }
+  },
+  "output": { "format": "json", "directory": ".aiready" }
+}
 ```
-````
+
+## 🌐 Language Support
+
+**Currently Supported (95% market coverage):**
+
+- ✅ TypeScript / JavaScript
+- ✅ Python
+- ✅ Java
+- ✅ Go
+- ✅ C#
+
+## 🏗️ Architecture
+
+```text
+                    🎯 USER
+                      │
+                      ▼
+         🎛️  @aiready/cli (orchestrator)
+              │     │     │     │     │
+              ▼     ▼     ▼     ▼     ▼
+           [PAT] [CTX] [CON] [DOC] [TEST]
+              │     │     │     │     │
+              └─────┴─────┴─────┴─────┘
+                         │
+                         ▼
+                🏢 @aiready/core
+```
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## 🔗 Related Links
+
+- 🌐 [Website](https://getaiready.dev)
+- 📖 [Documentation](https://docs.getaiready.dev)
+- 📦 [npm](https://www.npmjs.com/package/@aiready/cli)
+- 📊 [GitHub Actions](https://github.com/marketplace/actions/aiready-action)
+- 🔌 [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=pengcao.aiready)

package/dist/cli.js

@@ -1039,29 +1039,64 @@ async function initAction(options) {
     // Tool-specific configurations
     tools: {
       [import_core7.ToolName.PatternDetect]: {
-        minSimilarity: 0.8,
+        // Core detection thresholds
+        minSimilarity: 0.4,
+        // Jaccard similarity threshold (0-1)
         minLines: 5,
-        minSharedTokens: 10,
+        // Minimum lines to consider a duplicate
+        minSharedTokens: 8,
+        // Minimum shared tokens for candidate matching
         approx: true,
+        // Use approximate matching for performance
+        // Performance tuning
+        batchSize: 100,
+        // Batch size for comparisons
+        maxCandidatesPerBlock: 100,
+        // Max candidates per code block
+        maxResults: 10,
+        // Max results in console output
+        // Cluster reporting
+        minClusterFiles: 3,
+        // Min files for cluster reporting
+        minClusterTokenCost: 1e3,
+        // Min token cost for cluster reporting
+        // Output
+        outputFormat: "console",
+        // Output format (console, json, html)
         ...options.full ? {
-          batchSize: 300,
-          maxCandidatesPerBlock: 500,
-          minClusterFiles: 3,
-          minClusterTokenCost: 1e3
+          // Advanced options (only included with --full)
+          // Add any additional advanced options here
         } : {}
       },
       [import_core7.ToolName.ContextAnalyzer]: {
-        maxContextBudget: 128e3,
-        minCohesion: 0.6,
+        // Smart defaults are generated dynamically based on repository size
+        // These are fallback values for when smart defaults can't be calculated
+        maxContextBudget: 25e3,
+        // Max acceptable token budget for a single context
+        minCohesion: 0.4,
+        // Minimum acceptable cohesion score (0-1)
         maxDepth: 7,
-        maxFragmentation: 0.4,
+        // Maximum acceptable import depth
+        maxFragmentation: 0.7,
+        // Maximum acceptable fragmentation score (0-1)
+        // Analysis focus
         focus: "all",
+        // Analysis focus: fragmentation, cohesion, depth, or all
         includeNodeModules: false
+        // Whether to include node_modules in analysis
       },
       [import_core7.ToolName.NamingConsistency]: {
+        // Core checks
         checkNaming: true,
+        // Check naming conventions and quality
         checkPatterns: true,
+        // Check code pattern consistency
         checkArchitecture: true,
+        // Check architectural consistency
+        // Minimum severity to report
+        minSeverity: "info",
+        // Severity filter: critical, major, minor, info
+        // Custom vocabulary
         shortWords: ["id", "db", "ui", "ai"],
         acceptedAbbreviations: [
           "API",
@@ -1098,34 +1133,60 @@ async function initAction(options) {
         ...options.full ? { disableChecks: [] } : {}
       },
       [import_core7.ToolName.AiSignalClarity]: {
+        // All signal clarity checks enabled by default
         checkMagicLiterals: true,
+        // Detect magic numbers and strings
         checkBooleanTraps: true,
+        // Detect boolean trap parameters
         checkAmbiguousNames: true,
+        // Detect ambiguous function/variable names
         checkUndocumentedExports: true,
+        // Detect exports without documentation
         checkImplicitSideEffects: true,
+        // Detect functions with hidden side effects
         checkDeepCallbacks: true,
+        // Detect deeply nested callbacks
         checkOverloadedSymbols: true,
+        // Detect overloaded function signatures
         checkLargeFiles: true
+        // Detect files that are too large
       },
       [import_core7.ToolName.AgentGrounding]: {
-        maxRecommendedDepth: 5,
-        readmeStaleDays: 30,
+        // Structure clarity
+        maxRecommendedDepth: 4,
+        // Max directory depth before flagging as "too deep"
+        // Documentation freshness
+        readmeStaleDays: 90,
+        // Days after which README is considered stale
+        // File naming
         additionalVagueNames: ["stuff", "misc", "temp", "test"]
+        // Custom vague file names
       },
       [import_core7.ToolName.TestabilityIndex]: {
-        minCoverageRatio: 0.7,
+        // Coverage thresholds
+        minCoverageRatio: 0.3,
+        // Minimum acceptable test/source ratio
+        // Test file patterns
         testPatterns: ["**/*.test.ts", "**/__tests__/**", "**/*.spec.ts"],
+        // Scan depth
         maxDepth: 10
+        // Maximum scan depth
       },
       [import_core7.ToolName.DocDrift]: {
+        // Drift detection
         maxCommits: 50,
+        // Maximum commit distance to check for drift
         staleMonths: 3
+        // Consider comments older than this as outdated
       },
       [import_core7.ToolName.DependencyHealth]: {
+        // Training cutoff for AI knowledge assessment
         trainingCutoffYear: 2023
+        // Year cutoff for AI training data
       },
       [import_core7.ToolName.ChangeAmplification]: {
         // Change amplification primarily relies on global scan settings
+        // No additional tool-specific configuration required
       }
     },
     // Visualizer settings (interactive graph)

package/dist/cli.mjs

@@ -776,29 +776,64 @@ async function initAction(options) {
     // Tool-specific configurations
     tools: {
       [ToolName2.PatternDetect]: {
-        minSimilarity: 0.8,
+        // Core detection thresholds
+        minSimilarity: 0.4,
+        // Jaccard similarity threshold (0-1)
         minLines: 5,
-        minSharedTokens: 10,
+        // Minimum lines to consider a duplicate
+        minSharedTokens: 8,
+        // Minimum shared tokens for candidate matching
         approx: true,
+        // Use approximate matching for performance
+        // Performance tuning
+        batchSize: 100,
+        // Batch size for comparisons
+        maxCandidatesPerBlock: 100,
+        // Max candidates per code block
+        maxResults: 10,
+        // Max results in console output
+        // Cluster reporting
+        minClusterFiles: 3,
+        // Min files for cluster reporting
+        minClusterTokenCost: 1e3,
+        // Min token cost for cluster reporting
+        // Output
+        outputFormat: "console",
+        // Output format (console, json, html)
         ...options.full ? {
-          batchSize: 300,
-          maxCandidatesPerBlock: 500,
-          minClusterFiles: 3,
-          minClusterTokenCost: 1e3
+          // Advanced options (only included with --full)
+          // Add any additional advanced options here
         } : {}
       },
       [ToolName2.ContextAnalyzer]: {
-        maxContextBudget: 128e3,
-        minCohesion: 0.6,
+        // Smart defaults are generated dynamically based on repository size
+        // These are fallback values for when smart defaults can't be calculated
+        maxContextBudget: 25e3,
+        // Max acceptable token budget for a single context
+        minCohesion: 0.4,
+        // Minimum acceptable cohesion score (0-1)
         maxDepth: 7,
-        maxFragmentation: 0.4,
+        // Maximum acceptable import depth
+        maxFragmentation: 0.7,
+        // Maximum acceptable fragmentation score (0-1)
+        // Analysis focus
         focus: "all",
+        // Analysis focus: fragmentation, cohesion, depth, or all
         includeNodeModules: false
+        // Whether to include node_modules in analysis
       },
       [ToolName2.NamingConsistency]: {
+        // Core checks
         checkNaming: true,
+        // Check naming conventions and quality
         checkPatterns: true,
+        // Check code pattern consistency
         checkArchitecture: true,
+        // Check architectural consistency
+        // Minimum severity to report
+        minSeverity: "info",
+        // Severity filter: critical, major, minor, info
+        // Custom vocabulary
         shortWords: ["id", "db", "ui", "ai"],
         acceptedAbbreviations: [
           "API",
@@ -835,34 +870,60 @@ async function initAction(options) {
         ...options.full ? { disableChecks: [] } : {}
       },
       [ToolName2.AiSignalClarity]: {
+        // All signal clarity checks enabled by default
         checkMagicLiterals: true,
+        // Detect magic numbers and strings
         checkBooleanTraps: true,
+        // Detect boolean trap parameters
         checkAmbiguousNames: true,
+        // Detect ambiguous function/variable names
         checkUndocumentedExports: true,
+        // Detect exports without documentation
         checkImplicitSideEffects: true,
+        // Detect functions with hidden side effects
         checkDeepCallbacks: true,
+        // Detect deeply nested callbacks
         checkOverloadedSymbols: true,
+        // Detect overloaded function signatures
         checkLargeFiles: true
+        // Detect files that are too large
       },
       [ToolName2.AgentGrounding]: {
-        maxRecommendedDepth: 5,
-        readmeStaleDays: 30,
+        // Structure clarity
+        maxRecommendedDepth: 4,
+        // Max directory depth before flagging as "too deep"
+        // Documentation freshness
+        readmeStaleDays: 90,
+        // Days after which README is considered stale
+        // File naming
         additionalVagueNames: ["stuff", "misc", "temp", "test"]
+        // Custom vague file names
       },
       [ToolName2.TestabilityIndex]: {
-        minCoverageRatio: 0.7,
+        // Coverage thresholds
+        minCoverageRatio: 0.3,
+        // Minimum acceptable test/source ratio
+        // Test file patterns
         testPatterns: ["**/*.test.ts", "**/__tests__/**", "**/*.spec.ts"],
+        // Scan depth
         maxDepth: 10
+        // Maximum scan depth
       },
       [ToolName2.DocDrift]: {
+        // Drift detection
         maxCommits: 50,
+        // Maximum commit distance to check for drift
         staleMonths: 3
+        // Consider comments older than this as outdated
       },
       [ToolName2.DependencyHealth]: {
+        // Training cutoff for AI knowledge assessment
         trainingCutoffYear: 2023
+        // Year cutoff for AI training data
       },
       [ToolName2.ChangeAmplification]: {
         // Change amplification primarily relies on global scan settings
+        // No additional tool-specific configuration required
       }
     },
     // Visualizer settings (interactive graph)