@ivannikov-pro/ai-context-surgeon 1.0.0

package/tools/audit-jsdoc.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+# Tool: audit-jsdoc — Analyze JSDoc quality for AI-agent readiness | DEPS: none
+# USAGE: bash tools/audit-jsdoc.sh /path/to/directory
+# OUTPUT: JSDoc quality audit report
+# MODE: read-only analysis
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/audit-jsdoc.sh /path/to/directory"
+  echo ""
+  echo "Analyzes JSDoc comments in TypeScript/JavaScript files for AI-readiness."
+  echo "Detects:"
+  echo "  - Missing file headers"
+  echo "  - Wasteful tags (@author, @since, @copyright, @param {type} in TS)"
+  echo "  - Missing critical tags (@throws, side effects)"
+  echo "  - Multi-line blocks that could be one-liners"
+  echo "  - Token cost estimation"
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "📝 JSDoc AI-Readiness Audit: $TARGET"
+echo "════════════════════════════════════════════════════════"
+
+# Find source files
+SRC_FILES=$(find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' \) \
+  -not -path '*/node_modules/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' -not -path '*/dist/*' -not -path '*/.git/*' \
+  -not -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' -not -name '*.min.*')
+
+TOTAL_FILES=$(echo "$SRC_FILES" | wc -l | tr -d ' ')
+echo "Scanning $TOTAL_FILES source files..."
+echo ""
+
+# Metrics
+FILES_NO_HEADER=0
+FILES_WITH_HEADER=0
+WASTEFUL_TAGS=0
+MULTILINE_BLOCKS=0
+TOTAL_JSDOC_LINES=0
+USEFUL_ANNOTATIONS=0
+
+echo "$SRC_FILES" | while read -r file; do
+  [[ -z "$file" ]] && continue
+  
+  rel_path="${file#$TARGET/}"
+  first_line=$(head -1 "$file" 2>/dev/null || echo "")
+  issues=""
+  
+  # Check file header
+  if ! echo "$first_line" | grep -q '/\*\*'; then
+    FILES_NO_HEADER=$((FILES_NO_HEADER + 1))
+  else
+    FILES_WITH_HEADER=$((FILES_WITH_HEADER + 1))
+  fi
+  
+  # Count JSDoc lines
+  file_jsdoc_lines=$(grep -c '^\s*\*\|^\s*/\*\*' "$file" || true)
+  TOTAL_JSDOC_LINES=$((TOTAL_JSDOC_LINES + file_jsdoc_lines))
+  
+  # Detect wasteful tags (Tier 4 — should be removed)
+  wasteful=""
+  for tag in "@author" "@since" "@version" "@copyright" "@license" "@date" "@fileoverview" "@module" "@namespace" "@memberof" "@classdesc" "@constructs"; do
+    if grep -q "$tag" "$file" 2>/dev/null; then
+      count=$(grep -c "$tag" "$file" || true)
+      wasteful="$wasteful $tag(${count})"
+      WASTEFUL_TAGS=$((WASTEFUL_TAGS + count))
+    fi
+  done
+  
+  # Detect @param {type} in TypeScript files (redundant)
+  if [[ "$file" == *.ts || "$file" == *.tsx ]]; then
+    param_type_count=$(grep -cE '@param\s+\{' "$file" || true)
+    if [[ $param_type_count -gt 0 ]]; then
+      wasteful="$wasteful @param{type}(${param_type_count})"
+      WASTEFUL_TAGS=$((WASTEFUL_TAGS + param_type_count))
+    fi
+    
+    returns_type_count=$(grep -cE '@returns?\s+\{' "$file" || true)
+    if [[ $returns_type_count -gt 0 ]]; then
+      wasteful="$wasteful @returns{type}(${returns_type_count})"
+      WASTEFUL_TAGS=$((WASTEFUL_TAGS + returns_type_count))
+    fi
+  fi
+  
+  # Detect useful tags
+  useful=""
+  for tag in "@throws" "@deprecated" "@mutates" "@sideeffect"; do
+    if grep -q "$tag" "$file" 2>/dev/null; then
+      count=$(grep -c "$tag" "$file" || true)
+      useful="$useful $tag(${count})"
+      USEFUL_ANNOTATIONS=$((USEFUL_ANNOTATIONS + count))
+    fi
+  done
+  
+  # Detect multi-line JSDoc blocks (>3 lines)
+  multiline=$(python3 -c "
+import re
+with open('$file') as f:
+    content = f.read()
+blocks = re.findall(r'/\*\*[\s\S]*?\*/', content)
+big_blocks = [b for b in blocks if b.count('\n') > 3]
+print(len(big_blocks))
+" 2>/dev/null || echo "0")
+  
+  if [[ $multiline -gt 0 ]]; then
+    MULTILINE_BLOCKS=$((MULTILINE_BLOCKS + multiline))
+  fi
+  
+  # Report per-file issues
+  if [[ -n "$wasteful" || $multiline -gt 0 ]] || ! echo "$first_line" | grep -q '/\*\*'; then
+    echo "  📄 $rel_path"
+    
+    if ! echo "$first_line" | grep -q '/\*\*'; then
+      echo "     🟡 No file header"
+    fi
+    
+    if [[ -n "$wasteful" ]]; then
+      echo "     🔴 Wasteful:$wasteful"
+    fi
+    
+    if [[ $multiline -gt 0 ]]; then
+      echo "     🟡 $multiline multi-line block(s) — consider one-liners"
+    fi
+    
+    if [[ -n "$useful" ]]; then
+      echo "     ✅ Useful:$useful"
+    fi
+  fi
+  
+done
+
+echo ""
+echo "════════════════════════════════════════════════════════"
+echo ""
+echo "📊 SUMMARY"
+echo "────────────────────────────────────────"
+echo "Total source files:     $TOTAL_FILES"
+echo "Files with header:      $FILES_WITH_HEADER"
+echo "Files without header:   $FILES_NO_HEADER"
+echo "Total JSDoc lines:      $TOTAL_JSDOC_LINES"
+echo "Wasteful tag instances: $WASTEFUL_TAGS"
+echo "Multi-line blocks:      $MULTILINE_BLOCKS"
+echo "Useful annotations:     $USEFUL_ANNOTATIONS"
+echo ""
+
+# Token estimate
+EST_WASTEFUL_TOKENS=$((WASTEFUL_TAGS * 8))
+EST_MULTILINE_TOKENS=$((MULTILINE_BLOCKS * 30))
+EST_TOTAL_WASTE=$((EST_WASTEFUL_TOKENS + EST_MULTILINE_TOKENS))
+
+echo "💰 ESTIMATED WASTE"
+echo "────────────────────────────────────────"
+echo "Wasteful tags:     ~${EST_WASTEFUL_TOKENS} tokens"
+echo "Multi-line blocks: ~${EST_MULTILINE_TOKENS} tokens (could be one-liners)"
+echo "Total waste:       ~${EST_TOTAL_WASTE} tokens"
+echo ""
+
+if [[ $EST_TOTAL_WASTE -gt 1000 ]]; then
+  echo "🔴 HIGH WASTE — significant context budget being burned on noise"
+elif [[ $EST_TOTAL_WASTE -gt 300 ]]; then
+  echo "🟡 MODERATE WASTE — some cleanup recommended"
+else
+  echo "✅ LOW WASTE — JSDoc is fairly optimized"
+fi
+
+echo ""
+echo "📖 See strategy/jsdoc-guide.md for full optimization guide"

package/tools/check-fnh-freshness.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Tool: check-fnh-freshness — warns if source files changed but their FNH headers didn't | DEPS: none
+# USAGE: bash tools/check-fnh-freshness.sh [base-ref]
+# OUTPUT: list of files with potentially stale FNH headers
+# MODE: read-only, git-based analysis
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+BASE_REF="${1:-HEAD~1}"
+WARN_COUNT=0
+CHECKED=0
+
+echo "🧭 FNH Freshness Check"
+echo "  Comparing against: $BASE_REF"
+echo "  ──────────────────────────────────"
+
+# Check TypeScript/JavaScript files
+for file in $(git diff --name-only "$BASE_REF" -- '*.ts' '*.js' '*.tsx' '*.jsx' '*.sol' 2>/dev/null || true); do
+  [ -f "$file" ] || continue
+  CHECKED=$((CHECKED + 1))
+
+  # Count how many lines changed in the FNH region (first 8 lines)
+  fnh_diff=$(git diff "$BASE_REF" -- "$file" | awk '/^@@/{found=1} found{print}' | head -30 | grep -cE '^\+.*(/\*\*|\* )' || true)
+
+  # Count total changed lines (excluding FNH)
+  total_changes=$(git diff "$BASE_REF" -- "$file" | grep -cE '^[+-]' || true)
+
+  if [ "$total_changes" -gt 5 ] && [ "$fnh_diff" -eq 0 ]; then
+    echo "  ⚠️  $file"
+    echo "      $total_changes lines changed, FNH header unchanged"
+    WARN_COUNT=$((WARN_COUNT + 1))
+  fi
+done
+
+# Check Markdown files — look for > blockquote after H1
+for file in $(git diff --name-only "$BASE_REF" -- '*.md' 2>/dev/null || true); do
+  [ -f "$file" ] || continue
+  CHECKED=$((CHECKED + 1))
+
+  # Check if file has a > context line in first 5 lines
+  has_fnh=$(head -5 "$file" | grep -c '^>' || true)
+  if [ "$has_fnh" -eq 0 ]; then
+    echo "  ❌  $file — missing FNH (no > blockquote after H1)"
+    WARN_COUNT=$((WARN_COUNT + 1))
+  fi
+done
+
+# Check shell scripts
+for file in $(git diff --name-only "$BASE_REF" -- '*.sh' 2>/dev/null || true); do
+  [ -f "$file" ] || continue
+  CHECKED=$((CHECKED + 1))
+
+  has_fnh=$(head -3 "$file" | grep -c '^# Tool:\|^# Script:\|^# Config:' || true)
+  if [ "$has_fnh" -eq 0 ]; then
+    echo "  ❌  $file — missing FNH (no # Tool/Script/Config header)"
+    WARN_COUNT=$((WARN_COUNT + 1))
+  fi
+done
+
+echo ""
+echo "  ──────────────────────────────────"
+echo "  Files checked: $CHECKED"
+echo "  Warnings: $WARN_COUNT"
+
+if [ "$WARN_COUNT" -gt 0 ]; then
+  echo ""
+  echo "  💡 Run the annotate-jsdoc skill to fix missing/stale FNH headers"
+  exit 1
+else
+  echo "  ✅ All FNH headers look fresh"
+  exit 0
+fi

package/tools/detect-circular-deps.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# Tool: detect-circular-deps — Detect circular dependencies between packages | DEPS: none
+# USAGE: bash tools/detect-circular-deps.sh /path/to/monorepo
+# OUTPUT: list of circular dependency chains
+# MODE: read-only analysis
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/detect-circular-deps.sh /path/to/monorepo"
+  echo ""
+  echo "Detects circular dependencies between packages in a monorepo."
+  echo "Scans package.json files for internal dependencies and builds a graph."
+  echo "Reports any cycles found."
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "🔍 Checking circular dependencies in: $TARGET"
+echo "────────────────────────────────────────"
+
+# Build dependency graph from package.json files
+TEMP_FILE=$(mktemp)
+PACKAGES_DIR="$TARGET/packages"
+APPS_DIR="$TARGET/apps"
+
+# Collect all internal package names
+declare -a INTERNAL_PACKAGES=()
+
+for pkg_json in "$PACKAGES_DIR"/*/package.json "$APPS_DIR"/*/package.json; do
+  if [[ -f "$pkg_json" ]]; then
+    pkg_name=$(python3 -c "import json; print(json.load(open('$pkg_json'))['name'])" 2>/dev/null || echo "unknown")
+    if [[ "$pkg_name" != "unknown" ]]; then
+      INTERNAL_PACKAGES+=("$pkg_name")
+    fi
+  fi
+done
+
+if [[ ${#INTERNAL_PACKAGES[@]} -eq 0 ]]; then
+  echo "⚠️  No packages found in packages/ or apps/"
+  echo "   This tool expects a monorepo with packages/*/package.json"
+  rm -f "$TEMP_FILE"
+  exit 0
+fi
+
+echo "Found ${#INTERNAL_PACKAGES[@]} internal packages"
+echo ""
+
+# Check for cycles using import scanning
+CYCLES_FOUND=0
+
+for pkg_dir in "$PACKAGES_DIR"/* "$APPS_DIR"/*; do
+  if [[ -d "$pkg_dir" && -f "$pkg_dir/package.json" ]]; then
+    pkg_name=$(python3 -c "import json; print(json.load(open('$pkg_dir/package.json'))['name'])" 2>/dev/null || continue)
+    
+    # Get dependencies
+    deps=$(python3 -c "
+import json
+data = json.load(open('$pkg_dir/package.json'))
+all_deps = {}
+all_deps.update(data.get('dependencies', {}))
+all_deps.update(data.get('devDependencies', {}))
+internals = [d for d in all_deps if any(d == p for p in '''${INTERNAL_PACKAGES[*]}'''.split())]
+print(' '.join(internals))
+" 2>/dev/null || echo "")
+    
+    if [[ -n "$deps" ]]; then
+      for dep in $deps; do
+        echo "$pkg_name -> $dep" >> "$TEMP_FILE"
+      done
+    fi
+  fi
+done
+
+echo "📊 DEPENDENCY GRAPH"
+echo "────────────────────────────────────────"
+
+if [[ -s "$TEMP_FILE" ]]; then
+  cat "$TEMP_FILE"
+else
+  echo "No internal dependencies found."
+fi
+
+echo ""
+echo "────────────────────────────────────────"
+
+# Simple cycle detection using Python
+python3 -c "
+import sys
+
+edges = []
+with open('$TEMP_FILE') as f:
+    for line in f:
+        parts = line.strip().split(' -> ')
+        if len(parts) == 2:
+            edges.append((parts[0], parts[1]))
+
+# Build adjacency list
+graph = {}
+for src, dst in edges:
+    graph.setdefault(src, []).append(dst)
+
+# DFS cycle detection
+WHITE, GRAY, BLACK = 0, 1, 2
+color = {node: WHITE for node in graph}
+for node in set(dst for _, dst in edges):
+    color.setdefault(node, WHITE)
+
+cycles = []
+
+def dfs(node, path):
+    color[node] = GRAY
+    path.append(node)
+    for neighbor in graph.get(node, []):
+        if color.get(neighbor) == GRAY:
+            cycle_start = path.index(neighbor)
+            cycles.append(path[cycle_start:] + [neighbor])
+        elif color.get(neighbor) == WHITE:
+            dfs(neighbor, path)
+    path.pop()
+    color[node] = BLACK
+
+for node in list(color.keys()):
+    if color[node] == WHITE:
+        dfs(node, [])
+
+if cycles:
+    print(f'🔴 CIRCULAR DEPENDENCIES FOUND: {len(cycles)} cycle(s)')
+    print()
+    for i, cycle in enumerate(cycles, 1):
+        print(f'  Cycle {i}: {\" → \".join(cycle)}')
+    print()
+    print('These MUST be resolved before restructuring.')
+    sys.exit(1)
+else:
+    print('✅ No circular dependencies detected!')
+" 2>/dev/null || echo "⚠️  Python3 required for cycle detection"
+
+rm -f "$TEMP_FILE"

package/tools/detect-god-files.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Tool: detect-god-files — Find files exceeding a line threshold | DEPS: none
+# USAGE: bash tools/detect-god-files.sh /path/to/monorepo [threshold]
+# OUTPUT: list of files with line counts exceeding threshold
+# MODE: read-only analysis
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+THRESHOLD="${2:-500}"
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/detect-god-files.sh /path/to/monorepo [threshold]"
+  echo ""
+  echo "Finds source files exceeding [threshold] lines (default: 500)."
+  echo "These 'god-files' are candidates for decomposition."
+  echo ""
+  echo "Arguments:"
+  echo "  path       Path to monorepo (default: current directory)"
+  echo "  threshold  Line count threshold (default: 500)"
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "🔍 Searching for files > ${THRESHOLD} lines in: $TARGET"
+echo "────────────────────────────────────────"
+
+GOD_FILES=$(find "$TARGET" \
+  -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.sol' \) \
+  -not -path '*/node_modules/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/build/*' \
+  -not -path '*/.next/*' \
+  -not -path '*/generated/*' \
+  -not -path '*.min.*' \
+  -not -path '*.d.ts' \
+  -exec wc -l {} + 2>/dev/null \
+ | grep -v ' total$' \
+ | awk -v t="$THRESHOLD" '$1 > t' \
+ | sort -rn)
+
+if [[ -z "$GOD_FILES" ]]; then
+  echo "✅ No god-files found! All files are within ${THRESHOLD} lines."
+  exit 0
+fi
+
+COUNT=$(echo "$GOD_FILES" | wc -l | tr -d ' ')
+echo "🔴 Found ${COUNT} god-file(s):"
+echo ""
+
+echo "$GOD_FILES" | while read -r line; do
+  lines=$(echo "$line" | awk '{print $1}')
+  file=$(echo "$line" | awk '{print $2}')
+  severity="🟡"
+  [[ $lines -gt 1000 ]] && severity="🔴"
+  [[ $lines -gt 2000 ]] && severity="💀"
+  echo "${severity} ${lines} lines — ${file}"
+done
+
+echo ""
+echo "────────────────────────────────────────"
+echo "Severity: 🟡 ${THRESHOLD}-1000 | 🔴 1000-2000 | 💀 2000+"
+echo ""
+echo "Next: Use the Architect role to plan decomposition of these files."

package/tools/enforce-god-files.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Tool: enforce-god-files — Enforce file size limits across the codebase (CI blocker) | DEPS: none
+# USAGE: bash tools/enforce-god-files.sh /path/to/scan [--strict]
+# OUTPUT: File size compliance report
+# MODE: ci-compliance
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+DIM='\033[2m'
+NC='\033[0m'
+
+CRITICAL_LIMIT=300
+WARN_LIMIT=150
+NOTICE_LIMIT=100
+STRICT=false
+
+TARGET="${1:-.}"
+
+if [[ "$TARGET" == "--help" || "$TARGET" == "-h" ]]; then
+  echo "Usage: bash tools/enforce-god-files.sh /path/to/scan [--strict]"
+  echo "Enforces file size limits and exits with 1 if limit is exceeded."
+  echo ""
+  echo "Tiers:"
+  echo "  CRITICAL (>300 lines) — hard blocker, exit 1"
+  echo "  WARNING  (151-300)    — soft warning, logged but not blocking"
+  echo "  NOTICE   (101-150)    — consider refactoring on next edit"
+  echo "  OK       (≤100)       — fully compliant"
+  echo ""
+  echo "Arguments:"
+  echo "  --strict      Fail on WARNING tier (>150 lines) as well"
+  exit 0
+fi
+
+if [[ "${2:-}" == "--strict" || "${1:-}" == "--strict" ]]; then
+  STRICT=true
+  [[ "${1:-}" == "--strict" ]] && TARGET="."
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+
+critical_count=0
+warn_count=0
+notice_count=0
+ok_count=0
+critical_files=""
+warn_files=""
+notice_files=""
+
+echo "━━━ File Size Compliance Check ━━━"
+
+while IFS= read -r file; do
+  lines=$(wc -l < "$file" | tr -d ' ')
+
+  if [ "$lines" -gt "$CRITICAL_LIMIT" ]; then
+    critical_count=$((critical_count + 1))
+    critical_files="${critical_files}\n  ${RED}🚫 ${lines} lines${NC}  $file"
+  elif [ "$lines" -gt "$WARN_LIMIT" ]; then
+    warn_count=$((warn_count + 1))
+    warn_files="${warn_files}\n  ${YELLOW}⚠️  ${lines} lines${NC}  $file"
+  elif [ "$lines" -gt "$NOTICE_LIMIT" ]; then
+    notice_count=$((notice_count + 1))
+    notice_files="${notice_files}\n  ${CYAN}🔍 ${lines} lines${NC}  $file"
+  else
+    ok_count=$((ok_count + 1))
+  fi
+done < <(find "$TARGET" -type f \( -name '*.ts' -o -name '*.js' -o -name '*.tsx' -o -name '*.jsx' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.sol' \) "${FIND_EXCLUDES[@]}" 2>/dev/null)
+
+echo ""
+if [ "$critical_count" -gt 0 ]; then
+  echo -e "${RED}🚫 CRITICAL ($critical_count files > $CRITICAL_LIMIT lines) — MUST split before merge:${NC}"
+  echo -e "$critical_files"
+  echo ""
+fi
+
+if [ "$warn_count" -gt 0 ]; then
+  echo -e "${YELLOW}⚠️  WARNING ($warn_count files > $WARN_LIMIT lines) — split when editing:${NC}"
+  echo -e "$warn_files"
+  echo ""
+fi
+
+if [ "$notice_count" -gt 0 ]; then
+  echo -e "${CYAN}🔍 NOTICE ($notice_count files > $NOTICE_LIMIT lines) — consider refactoring:${NC}"
+  echo -e "$notice_files"
+  echo ""
+fi
+
+echo -e "${GREEN}✅ $ok_count files fully compliant (≤$NOTICE_LIMIT lines)${NC}"
+echo -e "${DIM}   $notice_count notice, $warn_count warnings, $critical_count critical${NC}"
+echo ""
+
+if [ "$critical_count" -gt 0 ]; then
+  echo -e "${RED}FAILED: $critical_count files exceed $CRITICAL_LIMIT lines. Split them first.${NC}"
+  exit 1
+fi
+
+if [ "$STRICT" = true ] && [ "$warn_count" -gt 0 ]; then
+  echo -e "${YELLOW}FAILED (strict mode): $warn_count files exceed $WARN_LIMIT lines.${NC}"
+  exit 1
+fi
+
+echo -e "${GREEN}PASSED${NC}"
+exit 0