@aiready/pattern-detect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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

@@ -0,0 +1,249 @@
+# @aiready/pattern-detect
+
+> **Semantic duplicate pattern detection for AI-generated code**
+
+When AI tools generate code without awareness of existing patterns in your codebase, you end up with semantically similar but syntactically different implementations. This tool finds those patterns and quantifies their cost.
+
+## 🎯 Why This Tool?
+
+### The AI Code Problem
+
+AI coding assistants (GitHub Copilot, ChatGPT, Claude) generate functionally similar code in different ways because:
+- No awareness of existing patterns in your codebase
+- Different AI models have different coding styles
+- Team members use AI tools with varying contexts
+- AI can't see your full codebase (context window limits)
+
+### What Makes Us Different?
+
+| Feature | jscpd | @aiready/pattern-detect |
+|---------|-------|------------------------|
+| Detection Method | Byte-level exact matching | Semantic similarity |
+| Pattern Types | Generic blocks | Categorized (API, validators, utils, etc.) |
+| Token Cost | ❌ No | ✅ Yes - shows AI context waste |
+| Refactoring Suggestions | ❌ Generic | ✅ Specific to pattern type |
+| Output Formats | Text/JSON | Console/JSON/HTML with rich formatting |
+
+## 🚀 Installation
+
+```bash
+npm install -g @aiready/pattern-detect
+
+# Or use directly with npx
+npx @aiready/pattern-detect ./src
+```
+
+## 📊 Usage
+
+### CLI
+
+```bash
+# Basic usage
+aiready-patterns ./src
+
+# Adjust sensitivity
+aiready-patterns ./src --similarity 0.9
+
+# Only look at larger patterns
+aiready-patterns ./src --min-lines 10
+
+# Export to JSON
+aiready-patterns ./src --output json --output-file report.json
+
+# Generate HTML report
+aiready-patterns ./src --output html
+```
+
+### Programmatic API
+
+```typescript
+import { analyzePatterns, generateSummary } from '@aiready/pattern-detect';
+
+const results = await analyzePatterns({
+  rootDir: './src',
+  minSimilarity: 0.85, // 85% similar
+  minLines: 5,
+  include: ['**/*.ts', '**/*.tsx'],
+  exclude: ['**/*.test.ts', '**/node_modules/**'],
+});
+
+const summary = generateSummary(results);
+
+console.log(`Found ${summary.totalPatterns} duplicate patterns`);
+console.log(`Token cost: ${summary.totalTokenCost} tokens wasted`);
+console.log(`Pattern breakdown:`, summary.patternsByType);
+```
+
+## 🔍 Real-World Example
+
+### Before Analysis
+
+Two API handlers that were written by AI on different days:
+
+```typescript
+// File: src/api/users.ts
+app.get('/api/users/:id', async (request, response) => {
+  const user = await db.users.findOne({ id: request.params.id });
+  if (!user) {
+    return response.status(404).json({ error: 'User not found' });
+  }
+  response.json(user);
+});
+
+// File: src/api/posts.ts
+router.get('/posts/:id', async (req, res) => {
+  const post = await database.posts.findOne({ id: req.params.id });
+  if (!post) {
+    res.status(404).send({ message: 'Post not found' });
+    return;
+  }
+  res.json(post);
+});
+```
+
+### Analysis Output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  PATTERN ANALYSIS SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📁 Files analyzed: 47
+⚠  Duplicate patterns found: 23
+💰 Token cost (wasted): 8,450
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  PATTERNS BY TYPE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🌐 api-handler      12
+✓  validator        8
+🔧 utility          3
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  TOP DUPLICATE PATTERNS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. 87% 🌐 api-handler
+   src/api/users.ts:15
+   ↔ src/api/posts.ts:22
+   432 tokens wasted
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  CRITICAL ISSUES (>95% similar)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+● src/utils/validators.ts:15
+  validator pattern 97% similar to src/utils/checks.ts (125 tokens wasted)
+  → Consolidate validation logic into shared schema validators (Zod/Yup) (CRITICAL: Nearly identical code)
+```
+
+### Suggested Refactoring
+
+Create a generic handler:
+
+```typescript
+// utils/apiHandler.ts
+export const createResourceHandler = (resourceName: string, findFn: Function) => {
+  return async (req: Request, res: Response) => {
+    const item = await findFn({ id: req.params.id });
+    if (!item) {
+      return res.status(404).json({ error: `${resourceName} not found` });
+    }
+    res.json(item);
+  };
+};
+
+// src/api/users.ts
+app.get('/api/users/:id', createResourceHandler('User', db.users.findOne));
+
+// src/api/posts.ts
+router.get('/posts/:id', createResourceHandler('Post', database.posts.findOne));
+```
+
+**Result:** Reduced from 432 tokens to ~100 tokens in AI context.
+
+## ⚙️ Configuration
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `minSimilarity` | Similarity threshold (0-1) | `0.85` |
+| `minLines` | Minimum lines to consider a pattern | `5` |
+| `include` | File patterns to include | `['**/*.ts', '**/*.js']` |
+| `exclude` | File patterns to exclude | `['**/node_modules/**', '**/*.test.*']` |
+
+## 📈 Understanding the Output
+
+### Severity Levels
+
+- **CRITICAL (>95% similar)**: Nearly identical code - refactor immediately
+- **MAJOR (>90% similar)**: Very similar - refactor soon
+- **MINOR (>85% similar)**: Similar - consider refactoring
+
+### Pattern Types
+
+- **🌐 api-handler**: REST API endpoints, route handlers
+- **✓ validator**: Input validation, schema checks
+- **🔧 utility**: Pure utility functions
+- **📦 class-method**: Class methods with similar logic
+- **⚛️ component**: UI components (React, Vue, etc.)
+- **ƒ function**: Generic functions
+
+### Token Cost
+
+Estimated tokens wasted when AI tools process duplicate code:
+- Increases context window usage
+- Higher API costs for AI-powered tools
+- Slower analysis and generation
+- More potential for AI confusion
+
+## 🎓 Best Practices
+
+1. **Run regularly**: Integrate into CI/CD to catch new duplicates early
+2. **Start with high similarity**: Use `--similarity 0.9` to find obvious wins
+3. **Focus on critical issues**: Fix >95% similar patterns first
+4. **Use pattern types**: Prioritize refactoring by category (API handlers → validators → utilities)
+5. **Export reports**: Generate HTML reports for team reviews
+
+## 🔧 CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Pattern Detection
+
+on: [pull_request]
+
+jobs:
+  detect-patterns:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npx @aiready/pattern-detect ./src --output json --output-file patterns.json
+      - name: Check for critical issues
+        run: |
+          CRITICAL=$(jq '.summary.topDuplicates | map(select(.similarity > 0.95)) | length' patterns.json)
+          if [ "$CRITICAL" -gt "0" ]; then
+            echo "Found $CRITICAL critical duplicate patterns"
+            exit 1
+          fi
+```
+
+## 🤝 Contributing
+
+We welcome contributions! This tool is part of the [AIReady](https://github.com/aiready/aiready) ecosystem.
+
+## 📝 License
+
+MIT - See LICENSE file
+
+## 🔗 Related Tools
+
+- **[@aiready/context-analyzer](../context-analyzer)** - Analyze token costs and context fragmentation
+- **[@aiready/doc-drift](../doc-drift)** - Track documentation freshness
+- **[@aiready/consistency](../consistency)** - Check naming pattern consistency
+
+---
+
+**Made with 💙 by the AIReady team** | [Docs](https://aiready.dev/docs) | [GitHub](https://github.com/aiready/aiready)

package/dist/chunk-K5O2HVB5.mjs

@@ -0,0 +1,114 @@
+// src/index.ts
+import { scanFiles, readFileContent } from "@aiready/core";
+
+// src/detector.ts
+import { similarityScore } from "@aiready/core";
+function extractCodeBlocks(content, minLines) {
+  const lines = content.split("\n");
+  const blocks = [];
+  let currentBlock = [];
+  let blockStart = 0;
+  let braceDepth = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const char of line) {
+      if (char === "{") braceDepth++;
+      if (char === "}") braceDepth--;
+    }
+    currentBlock.push(line);
+    if (braceDepth === 0 && currentBlock.length >= minLines) {
+      blocks.push({
+        content: currentBlock.join("\n"),
+        startLine: blockStart + 1
+      });
+      currentBlock = [];
+      blockStart = i + 1;
+    } else if (braceDepth === 0) {
+      currentBlock = [];
+      blockStart = i + 1;
+    }
+  }
+  return blocks;
+}
+function normalizeCode(code) {
+  return code.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\s+/g, " ").trim();
+}
+function detectDuplicatePatterns(files, options) {
+  const { minSimilarity, minLines } = options;
+  const duplicates = [];
+  const allBlocks = files.flatMap(
+    (file) => extractCodeBlocks(file.content, minLines).map((block) => ({
+      ...block,
+      file: file.file,
+      normalized: normalizeCode(block.content)
+    }))
+  );
+  for (let i = 0; i < allBlocks.length; i++) {
+    for (let j = i + 1; j < allBlocks.length; j++) {
+      const block1 = allBlocks[i];
+      const block2 = allBlocks[j];
+      if (block1.file === block2.file) continue;
+      const similarity = similarityScore(block1.normalized, block2.normalized);
+      if (similarity >= minSimilarity) {
+        duplicates.push({
+          file1: block1.file,
+          file2: block2.file,
+          line1: block1.startLine,
+          line2: block2.startLine,
+          similarity,
+          snippet: block1.content.split("\n").slice(0, 3).join("\n") + "..."
+        });
+      }
+    }
+  }
+  return duplicates.sort((a, b) => b.similarity - a.similarity);
+}
+
+// src/index.ts
+async function analyzePatterns(options) {
+  const {
+    minSimilarity = 0.85,
+    minLines = 5,
+    ...scanOptions
+  } = options;
+  const files = await scanFiles(scanOptions);
+  const results = [];
+  const fileContents = await Promise.all(
+    files.map(async (file) => ({
+      file,
+      content: await readFileContent(file)
+    }))
+  );
+  const duplicates = detectDuplicatePatterns(fileContents, {
+    minSimilarity,
+    minLines
+  });
+  for (const file of files) {
+    const fileDuplicates = duplicates.filter(
+      (dup) => dup.file1 === file || dup.file2 === file
+    );
+    const issues = fileDuplicates.map((dup) => ({
+      type: "duplicate-pattern",
+      severity: dup.similarity > 0.95 ? "critical" : "major",
+      message: `Similar pattern found in ${dup.file1 === file ? dup.file2 : dup.file1}`,
+      location: {
+        file,
+        line: dup.file1 === file ? dup.line1 : dup.line2
+      },
+      suggestion: "Consider extracting common logic into a shared utility"
+    }));
+    results.push({
+      fileName: file,
+      issues,
+      metrics: {
+        consistencyScore: 1 - fileDuplicates.length * 0.1
+      }
+    });
+  }
+  return results;
+}
+
+export {
+  detectDuplicatePatterns,
+  analyzePatterns
+};

package/dist/chunk-RLWJXASG.mjs

@@ -0,0 +1,227 @@
+// src/index.ts
+import { scanFiles, readFileContent } from "@aiready/core";
+
+// src/detector.ts
+import { similarityScore, estimateTokens } from "@aiready/core";
+function categorizePattern(code) {
+  const lower = code.toLowerCase();
+  if (lower.includes("request") && lower.includes("response") || lower.includes("router.") || lower.includes("app.get") || lower.includes("app.post") || lower.includes("express") || lower.includes("ctx.body")) {
+    return "api-handler";
+  }
+  if (lower.includes("validate") || lower.includes("schema") || lower.includes("zod") || lower.includes("yup") || lower.includes("if") && lower.includes("throw")) {
+    return "validator";
+  }
+  if (lower.includes("return (") || lower.includes("jsx") || lower.includes("component") || lower.includes("props")) {
+    return "component";
+  }
+  if (lower.includes("class ") || lower.includes("this.")) {
+    return "class-method";
+  }
+  if (lower.includes("return ") && !lower.includes("this") && !lower.includes("new ")) {
+    return "utility";
+  }
+  if (lower.includes("function") || lower.includes("=>")) {
+    return "function";
+  }
+  return "unknown";
+}
+function extractCodeBlocks(content, minLines) {
+  const lines = content.split("\n");
+  const blocks = [];
+  let currentBlock = [];
+  let blockStart = 0;
+  let braceDepth = 0;
+  let inFunction = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!inFunction && (trimmed.includes("function ") || trimmed.includes("=>") || trimmed.includes("async ") || /^(export\s+)?(async\s+)?function\s+/.test(trimmed) || /^(export\s+)?const\s+\w+\s*=\s*(async\s*)?\(/.test(trimmed))) {
+      inFunction = true;
+      blockStart = i;
+    }
+    for (const char of line) {
+      if (char === "{") braceDepth++;
+      if (char === "}") braceDepth--;
+    }
+    if (inFunction) {
+      currentBlock.push(line);
+    }
+    if (inFunction && braceDepth === 0 && currentBlock.length >= minLines) {
+      const blockContent = currentBlock.join("\n");
+      const linesOfCode = currentBlock.filter(
+        (l) => l.trim() && !l.trim().startsWith("//")
+      ).length;
+      blocks.push({
+        content: blockContent,
+        startLine: blockStart + 1,
+        patternType: categorizePattern(blockContent),
+        linesOfCode
+      });
+      currentBlock = [];
+      inFunction = false;
+    } else if (inFunction && braceDepth === 0) {
+      currentBlock = [];
+      inFunction = false;
+    }
+  }
+  return blocks;
+}
+function normalizeCode(code) {
+  return code.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/"[^"]*"/g, '"STR"').replace(/'[^']*'/g, "'STR'").replace(/`[^`]*`/g, "`STR`").replace(/\b\d+\b/g, "NUM").replace(/\s+/g, " ").trim();
+}
+function calculateSimilarity(block1, block2) {
+  const norm1 = normalizeCode(block1);
+  const norm2 = normalizeCode(block2);
+  const baseSimilarity = similarityScore(norm1, norm2);
+  const tokens1 = norm1.split(/[\s(){}[\];,]+/).filter(Boolean);
+  const tokens2 = norm2.split(/[\s(){}[\];,]+/).filter(Boolean);
+  const tokenSimilarity = similarityScore(tokens1.join(" "), tokens2.join(" "));
+  return baseSimilarity * 0.4 + tokenSimilarity * 0.6;
+}
+function detectDuplicatePatterns(files, options) {
+  const { minSimilarity, minLines } = options;
+  const duplicates = [];
+  const allBlocks = files.flatMap(
+    (file) => extractCodeBlocks(file.content, minLines).map((block) => ({
+      ...block,
+      file: file.file,
+      normalized: normalizeCode(block.content),
+      tokenCost: estimateTokens(block.content)
+    }))
+  );
+  console.log(`Extracted ${allBlocks.length} code blocks for analysis`);
+  for (let i = 0; i < allBlocks.length; i++) {
+    for (let j = i + 1; j < allBlocks.length; j++) {
+      const block1 = allBlocks[i];
+      const block2 = allBlocks[j];
+      if (block1.file === block2.file) continue;
+      const similarity = calculateSimilarity(block1.content, block2.content);
+      if (similarity >= minSimilarity) {
+        duplicates.push({
+          file1: block1.file,
+          file2: block2.file,
+          line1: block1.startLine,
+          line2: block2.startLine,
+          similarity,
+          snippet: block1.content.split("\n").slice(0, 5).join("\n") + "\n...",
+          patternType: block1.patternType,
+          tokenCost: block1.tokenCost + block2.tokenCost,
+          linesOfCode: block1.linesOfCode
+        });
+      }
+    }
+  }
+  return duplicates.sort(
+    (a, b) => b.similarity - a.similarity || b.tokenCost - a.tokenCost
+  );
+}
+
+// src/index.ts
+function getRefactoringSuggestion(patternType, similarity) {
+  const baseMessages = {
+    "api-handler": "Extract common middleware or create a base handler class",
+    validator: "Consolidate validation logic into shared schema validators (Zod/Yup)",
+    utility: "Move to a shared utilities file and reuse across modules",
+    "class-method": "Consider inheritance or composition to share behavior",
+    component: "Extract shared logic into a custom hook or HOC",
+    function: "Extract into a shared helper function",
+    unknown: "Extract common logic into a reusable module"
+  };
+  const urgency = similarity > 0.95 ? " (CRITICAL: Nearly identical code)" : similarity > 0.9 ? " (HIGH: Very similar, refactor soon)" : "";
+  return baseMessages[patternType] + urgency;
+}
+async function analyzePatterns(options) {
+  const { minSimilarity = 0.85, minLines = 5, ...scanOptions } = options;
+  const files = await scanFiles(scanOptions);
+  const results = [];
+  const fileContents = await Promise.all(
+    files.map(async (file) => ({
+      file,
+      content: await readFileContent(file)
+    }))
+  );
+  const duplicates = detectDuplicatePatterns(fileContents, {
+    minSimilarity,
+    minLines
+  });
+  for (const file of files) {
+    const fileDuplicates = duplicates.filter(
+      (dup) => dup.file1 === file || dup.file2 === file
+    );
+    const issues = fileDuplicates.map((dup) => {
+      const otherFile = dup.file1 === file ? dup.file2 : dup.file1;
+      const severity = dup.similarity > 0.95 ? "critical" : dup.similarity > 0.9 ? "major" : "minor";
+      return {
+        type: "duplicate-pattern",
+        severity,
+        message: `${dup.patternType} pattern ${Math.round(dup.similarity * 100)}% similar to ${otherFile} (${dup.tokenCost} tokens wasted)`,
+        location: {
+          file,
+          line: dup.file1 === file ? dup.line1 : dup.line2
+        },
+        suggestion: getRefactoringSuggestion(dup.patternType, dup.similarity)
+      };
+    });
+    const totalTokenCost = fileDuplicates.reduce(
+      (sum, dup) => sum + dup.tokenCost,
+      0
+    );
+    results.push({
+      fileName: file,
+      issues,
+      metrics: {
+        tokenCost: totalTokenCost,
+        consistencyScore: Math.max(0, 1 - fileDuplicates.length * 0.1)
+      }
+    });
+  }
+  return results;
+}
+function generateSummary(results) {
+  const allIssues = results.flatMap((r) => r.issues);
+  const totalTokenCost = results.reduce(
+    (sum, r) => sum + (r.metrics.tokenCost || 0),
+    0
+  );
+  const patternsByType = {
+    "api-handler": 0,
+    validator: 0,
+    utility: 0,
+    "class-method": 0,
+    component: 0,
+    function: 0,
+    unknown: 0
+  };
+  allIssues.forEach((issue) => {
+    const match = issue.message.match(/^(\S+(?:-\S+)*) pattern/);
+    if (match) {
+      const type = match[1];
+      patternsByType[type] = (patternsByType[type] || 0) + 1;
+    }
+  });
+  const topDuplicates = allIssues.slice(0, 10).map((issue) => {
+    const similarityMatch = issue.message.match(/(\d+)% similar/);
+    const tokenMatch = issue.message.match(/\((\d+) tokens/);
+    const typeMatch = issue.message.match(/^(\S+(?:-\S+)*) pattern/);
+    const fileMatch = issue.message.match(/similar to (.+?) \(/);
+    return {
+      file1: issue.location.file,
+      file2: fileMatch?.[1] || "unknown",
+      similarity: similarityMatch ? parseInt(similarityMatch[1]) / 100 : 0,
+      patternType: typeMatch?.[1] || "unknown",
+      tokenCost: tokenMatch ? parseInt(tokenMatch[1]) : 0
+    };
+  });
+  return {
+    totalPatterns: allIssues.length,
+    totalTokenCost,
+    patternsByType,
+    topDuplicates
+  };
+}
+
+export {
+  detectDuplicatePatterns,
+  analyzePatterns,
+  generateSummary
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node