@ivannikov-pro/ai-context-surgeon 1.0.0

package/tools/enrich-package-json.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/** Category: Tool — Enrich lean package.json with publish metadata before npm publish. | DEPS: node:fs, node:path
+ *
+ * Usage:
+ *   node tools/enrich-package-json.js /path/to/package [--dry-run]
+ *   node tools/enrich-package-json.js /path/to/monorepo --all [--dry-run]
+ *
+ * Reads .publish-meta.json from project root for shared metadata,
+ * merges it into the target package.json, and writes the result.
+ *
+ * Use --dry-run to preview without writing.
+ * Use --restore to strip publish metadata back to lean version.
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+
+// ── Config ──────────────────────────────────────────────
+
+const PUBLISH_META_FILE = ".publish-meta.json";
+
+// Fields that enrich adds (and --restore removes)
+const ENRICHED_FIELDS = [
+  "author",
+  "license",
+  "repository",
+  "bugs",
+  "homepage",
+  "keywords",
+  "funding",
+  "contributors",
+  "publishConfig",
+  "engines",
+  "os",
+  "cpu",
+  "sideEffects",
+  "files",
+];
+
+// Fields order for clean output (Tier 1 first, metadata last)
+const FIELD_ORDER = [
+  // Tier 1 — Critical
+  "name",
+  "version",
+  "description",
+  "private",
+  "type",
+  "main",
+  "module",
+  "types",
+  "exports",
+  "bin",
+  "scripts",
+  "dependencies",
+  // Tier 2 — Dev
+  "devDependencies",
+  "peerDependencies",
+  "peerDependenciesMeta",
+  "optionalDependencies",
+  // Build
+  "workspaces",
+  "engines",
+  "os",
+  "cpu",
+  "files",
+  "sideEffects",
+  "publishConfig",
+  // Metadata (publish-enriched)
+  "keywords",
+  "author",
+  "contributors",
+  "license",
+  "repository",
+  "bugs",
+  "homepage",
+  "funding",
+  // Overrides (root only)
+  "resolutions",
+  "overrides",
+  "pnpm",
+];
+
+// ── Helpers ──────────────────────────────────────────────
+
+function readJSON(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function writeJSON(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+function sortFields(obj) {
+  const sorted = {};
+  // Add fields in order
+  for (const key of FIELD_ORDER) {
+    if (key in obj) sorted[key] = obj[key];
+  }
+  // Add any remaining fields not in the order list
+  for (const key of Object.keys(obj)) {
+    if (!(key in sorted)) sorted[key] = obj[key];
+  }
+  return sorted;
+}
+
+function findMonorepoRoot(startPath) {
+  let dir = resolve(startPath);
+  while (dir !== "/") {
+    if (existsSync(join(dir, PUBLISH_META_FILE))) return dir;
+    if (existsSync(join(dir, "turbo.json")) || existsSync(join(dir, "nx.json"))) return dir;
+    dir = resolve(dir, "..");
+  }
+  return resolve(startPath);
+}
+
+function findAllPackages(root) {
+  const packages = [];
+  for (const dir of ["packages", "apps"]) {
+    const dirPath = join(root, dir);
+    if (!existsSync(dirPath)) continue;
+    for (const pkg of readdirSync(dirPath)) {
+      const pkgJson = join(dirPath, pkg, "package.json");
+      if (existsSync(pkgJson)) packages.push(join(dirPath, pkg));
+    }
+  }
+  // Also check root
+  if (existsSync(join(root, "package.json"))) {
+    packages.unshift(root);
+  }
+  return packages;
+}
+
+// ── Enrich ───────────────────────────────────────────────
+
+function enrich(pkgPath, meta, dryRun) {
+  const pkgJsonPath = join(pkgPath, "package.json");
+  if (!existsSync(pkgJsonPath)) {
+    console.log(`  ⚠️  No package.json in ${pkgPath}`);
+    return;
+  }
+
+  const pkg = readJSON(pkgJsonPath);
+  const pkgName = pkg.name || basename(pkgPath);
+
+  // Skip private packages (they don't need publish metadata)
+  if (pkg.private) {
+    console.log(`  ⏭️  ${pkgName} — private, skipping`);
+    return;
+  }
+
+  let changed = false;
+  const changes = [];
+
+  // Apply shared metadata (don't overwrite if already set)
+  for (const [key, value] of Object.entries(meta.shared || {})) {
+    if (!(key in pkg)) {
+      pkg[key] = value;
+      changes.push(`+${key}`);
+      changed = true;
+    }
+  }
+
+  // Apply per-package overrides
+  const overrides = (meta.packages || {})[pkgName] || {};
+  for (const [key, value] of Object.entries(overrides)) {
+    pkg[key] = value;
+    changes.push(`~${key}`);
+    changed = true;
+  }
+
+  // Auto-generate repository URL if pattern provided
+  if (meta.repositoryPattern && !pkg.repository) {
+    pkg.repository = {
+      type: "git",
+      url: meta.repositoryPattern,
+      directory: pkgPath.replace(findMonorepoRoot(pkgPath) + "/", ""),
+    };
+    changes.push("+repository");
+    changed = true;
+  }
+
+  // Auto-generate homepage from repository
+  if (pkg.repository && !pkg.homepage && meta.homepagePattern) {
+    pkg.homepage = meta.homepagePattern.replace("{{package}}", basename(pkgPath));
+    changes.push("+homepage");
+    changed = true;
+  }
+
+  // Auto-generate bugs URL
+  if (meta.bugsUrl && !pkg.bugs) {
+    pkg.bugs = { url: meta.bugsUrl };
+    changes.push("+bugs");
+    changed = true;
+  }
+
+  // Add default files array
+  if (!pkg.files && meta.defaultFiles) {
+    pkg.files = meta.defaultFiles;
+    changes.push("+files");
+    changed = true;
+  }
+
+  if (!changed) {
+    console.log(`  ✅ ${pkgName} — already enriched`);
+    return;
+  }
+
+  // Sort fields for clean output
+  const sorted = sortFields(pkg);
+
+  if (dryRun) {
+    console.log(`  🔍 ${pkgName} — would add: ${changes.join(", ")}`);
+  } else {
+    writeJSON(pkgJsonPath, sorted);
+    console.log(`  ✅ ${pkgName} — enriched: ${changes.join(", ")}`);
+  }
+}
+
+// ── Restore (strip publish metadata) ─────────────────────
+
+function restore(pkgPath, dryRun) {
+  const pkgJsonPath = join(pkgPath, "package.json");
+  if (!existsSync(pkgJsonPath)) return;
+
+  const pkg = readJSON(pkgJsonPath);
+  const pkgName = pkg.name || basename(pkgPath);
+  const removed = [];
+
+  for (const field of ENRICHED_FIELDS) {
+    if (field in pkg) {
+      delete pkg[field];
+      removed.push(`-${field}`);
+    }
+  }
+
+  if (removed.length === 0) {
+    console.log(`  ✅ ${pkgName} — already lean`);
+    return;
+  }
+
+  const sorted = sortFields(pkg);
+
+  if (dryRun) {
+    console.log(`  🔍 ${pkgName} — would remove: ${removed.join(", ")}`);
+  } else {
+    writeJSON(pkgJsonPath, sorted);
+    console.log(`  ✅ ${pkgName} — restored to lean: ${removed.join(", ")}`);
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+  console.log(`
+📦 enrich-package-json — Add publish metadata to lean package.json files
+
+Usage:
+  node tools/enrich-package-json.js ./packages/core          Enrich one package
+  node tools/enrich-package-json.js . --all                  Enrich all packages
+  node tools/enrich-package-json.js . --all --dry-run        Preview changes
+  node tools/enrich-package-json.js . --all --restore        Strip back to lean
+
+Config: Create ${PUBLISH_META_FILE} in project root (see template).
+
+Workflow:
+  1. Keep lean package.json during development (AI-optimized)
+  2. Before publish: node tools/enrich-package-json.js . --all
+  3. npm publish (or turbo publish)
+  4. After publish: node tools/enrich-package-json.js . --all --restore
+  `);
+  process.exit(0);
+}
+
+const dryRun = args.includes("--dry-run");
+const restoreMode = args.includes("--restore");
+const allMode = args.includes("--all");
+const targetPath = resolve(args.find((a) => !a.startsWith("--")) || ".");
+
+// Find monorepo root and load meta
+const root = findMonorepoRoot(targetPath);
+const metaPath = join(root, PUBLISH_META_FILE);
+
+let meta = {};
+if (existsSync(metaPath)) {
+  meta = readJSON(metaPath);
+  console.log(`📋 Loaded ${PUBLISH_META_FILE} from ${root}`);
+} else if (!restoreMode) {
+  console.log(`⚠️  No ${PUBLISH_META_FILE} found. Create one in project root.`);
+  console.log(`   See templates/publish-meta.template for format.`);
+  process.exit(1);
+}
+
+console.log(
+  `Mode: ${restoreMode ? "♻️ RESTORE (lean)" : "📦 ENRICH (publish)"} ${dryRun ? "[DRY RUN]" : ""}`,
+);
+console.log("");
+
+const packages = allMode ? findAllPackages(root) : [targetPath];
+
+for (const pkg of packages) {
+  if (restoreMode) {
+    restore(pkg, dryRun);
+  } else {
+    enrich(pkg, meta, dryRun);
+  }
+}
+
+console.log("");
+console.log(dryRun ? "🔍 Dry run complete. Run without --dry-run to apply." : "✅ Done!");

package/tools/generate-jsdoc-headers.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# Tool: generate-jsdoc-headers — Add JSDoc navigation headers to source files | DEPS: none
+# USAGE: bash tools/generate-jsdoc-headers.sh /path/to/directory [--dry-run]
+# OUTPUT: updated source files with JSDoc headers
+# MODE: write (modifies source files)
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+DRY_RUN=false
+[[ "${2:-}" == "--dry-run" ]] && DRY_RUN=true
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/generate-jsdoc-headers.sh /path/to/directory [--dry-run]"
+  echo ""
+  echo "Adds JSDoc navigation headers to TypeScript/JavaScript files in directories"
+  echo "with 20+ files. These headers help AI agents navigate without reading full files."
+  echo ""
+  echo "Options:"
+  echo "  --dry-run   Show what would be done without modifying files"
+  echo ""
+  echo "Header format:"
+  echo "  /** <Type>: <Name> — <description from filename> */"
+  echo ""
+  echo "Examples:"
+  echo "  /** Service: UserService — User entity business logic */"
+  echo "  /** Route: GET/POST /api/v1/users — User CRUD operations */"
+  echo "  /** Middleware: AuthGuard — JWT token verification */"
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "🔍 Scanning for directories with 20+ source files..."
+echo "────────────────────────────────────────"
+
+MODIFIED=0
+
+find "$TARGET" -type d \
+  -not -path '*/node_modules/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -path '*/.git/*' \
+  -not -path '*/dist/*' \
+ | while read -r dir; do
+  
+  file_count=$(find "$dir" -maxdepth 1 -type f \( -name '*.ts' -o -name '*.js' -o -name '*.sol' \) \
+    -not -name '*.test.*' -not -name '*.spec.*' -not -name '*.d.ts' \
+    2>/dev/null | wc -l | tr -d ' ')
+  
+  if [[ $file_count -ge 20 ]]; then
+    echo ""
+    echo "📁 $dir ($file_count files)"
+    
+    find "$dir" -maxdepth 1 -type f \( -name '*.ts' -o -name '*.js' -o -name '*.sol' \) \
+      -not -name '*.test.*' -not -name '*.spec.*' -not -name '*.d.ts' \
+ | while read -r file; do
+      
+      # Check if file already has JSDoc header
+      first_line=$(head -1 "$file" 2>/dev/null || echo "")
+      if echo "$first_line" | grep -q '^\s*/\*\*'; then
+        continue  # Already has JSDoc
+      fi
+      
+      basename=$(basename "$file" | sed 's/\.\(ts\|js\|tsx\|jsx\)$//')
+      
+      # Detect type from filename pattern
+      type="Module"
+      if echo "$basename" | grep -qi 'service'; then type="Service"
+      elif echo "$basename" | grep -qi 'route\|router\|handler'; then type="Route"
+      elif echo "$basename" | grep -qi 'middleware\|guard\|interceptor'; then type="Middleware"
+      elif echo "$basename" | grep -qi 'controller'; then type="Controller"
+      elif echo "$basename" | grep -qi 'model\|entity\|schema'; then type="Entity"
+      elif echo "$basename" | grep -qi 'util\|helper'; then type="Utility"
+      elif echo "$basename" | grep -qi 'config'; then type="Config"
+      elif echo "$basename" | grep -qi 'test\|spec'; then type="Test"
+      elif echo "$basename" | grep -qi 'type\|interface\|dto'; then type="Types"
+      elif echo "$basename" | grep -qi 'constant\|enum'; then type="Constants"
+      fi
+      
+      # Generate description from filename
+      desc=$(echo "$basename" | sed 's/[-_.]/ /g' | sed 's/\b\(.\)/\u\1/g')
+      header="/** ${type}: ${desc} — TODO: add description */"
+      
+      if $DRY_RUN; then
+        echo "  [DRY RUN] Would add to $(basename "$file"): ${header}"
+      else
+        # Prepend header
+        temp=$(mktemp)
+        echo "$header" > "$temp"
+        cat "$file" >> "$temp"
+        mv "$temp" "$file"
+        echo "  ✅ Added header to $(basename "$file")"
+        MODIFIED=$((MODIFIED + 1))
+      fi
+    done
+  fi
+done
+
+echo ""
+echo "────────────────────────────────────────"
+if $DRY_RUN; then
+  echo "🔍 Dry run complete. Use without --dry-run to apply changes."
+else
+  echo "✅ Complete. Review the TODO descriptions and replace with actual descriptions."
+fi

package/tools/generate-source-map.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Tool: generate-source-map — Generate Source Structure block for a package README | DEPS: none
+# USAGE: bash tools/generate-source-map.sh /path/to/package/src
+# OUTPUT: markdown tree of source files
+# 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/generate-source-map.sh /path/to/package/src"
+  echo ""
+  echo "Generates a Source Structure tree for a package, suitable for README.md."
+  echo "Annotates files with JSDoc descriptions if available."
+  echo ""
+  echo "Output can be copied into a README.md Source Structure section."
+  exit 0
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "## Source Structure"
+echo "\`\`\`"
+
+# Generate tree with annotations
+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 '*/*.test.*' \
+  -not -path '*/*.spec.*' \
+  -not -path '*/__tests__/*' \
+  -not -name '*.d.ts' \
+ | sort \
+ | while read -r filepath; do
+    # Get relative path
+    relpath="${filepath#$TARGET/}"
+    
+    # Try to extract JSDoc description from first line
+    desc=""
+    first_line=$(head -1 "$filepath" 2>/dev/null || echo "")
+    if echo "$first_line" | grep -q '^\s*/\*\*'; then
+      # Extract text between /** and */
+      desc=$(echo "$first_line" | sed 's/.*\/\*\*\s*//' | sed 's/\s*\*\/.*//' | head -c 60)
+    fi
+    
+    # Calculate indentation based on depth
+    depth=$(echo "$relpath" | tr -cd '/' | wc -c | tr -d ' ')
+    indent=""
+    for ((i=0; i<depth; i++)); do
+      indent="  $indent"
+    done
+    
+    basename=$(basename "$relpath")
+    
+    if [[ -n "$desc" ]]; then
+      echo "${indent}${basename}$(printf '%*s' $((40 - ${#indent} - ${#basename})) '')← ${desc}"
+    else
+      echo "${indent}${basename}"
+    fi
+  done
+
+echo "\`\`\`"
+echo ""
+echo "# Paste the above into your package README.md"
+echo "# Then manually add ← descriptions for files without JSDoc"

package/tools/lint-imports.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# Tool: lint-imports — detects cross-package boundary violations in monorepo | DEPS: none
+# USAGE: bash tools/lint-imports.sh /path/to/repo
+# OUTPUT: list of import violations (importing internal paths from other packages)
+# MODE: read-only, no modifications
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+VIOLATIONS=0
+CHECKED=0
+
+echo "🔍 Import Boundary Lint"
+echo "  Target: $TARGET"
+echo "  ──────────────────────────────────"
+
+# Find all packages directories
+PACKAGES_DIR=""
+if [ -d "$TARGET/packages" ]; then
+  PACKAGES_DIR="$TARGET/packages"
+elif [ -d "$TARGET/libs" ]; then
+  PACKAGES_DIR="$TARGET/libs"
+elif [ -d "$TARGET/modules" ]; then
+  PACKAGES_DIR="$TARGET/modules"
+fi
+
+if [ -z "$PACKAGES_DIR" ]; then
+  echo "  ⚠️  No packages/, libs/, or modules/ directory found"
+  exit 0
+fi
+
+echo "  Packages dir: $PACKAGES_DIR"
+echo ""
+
+# Pattern 1: Direct path imports crossing package boundaries
+# e.g., import { User } from '../../core/src/models/user'
+echo "  ### Pattern 1: Relative cross-package imports"
+echo ""
+CROSS_PKG=$(grep -rnI "from ['\"]\.\..*packages/\|from ['\"]\.\..*libs/\|from ['\"]\.\..*modules/" \
+  "$PACKAGES_DIR" \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.sol' \
+  2>/dev/null || true)
+
+if [ -n "$CROSS_PKG" ]; then
+  echo "$CROSS_PKG" | while IFS= read -r line; do
+    echo "  ❌ $line"
+    VIOLATIONS=$((VIOLATIONS + 1))
+  done
+  echo ""
+else
+  echo "  ✅ No relative cross-package imports found"
+  echo ""
+fi
+
+# Pattern 2: Importing from /src/ of another package
+# e.g., import { User } from '@scope/core/src/models/user'
+echo "  ### Pattern 2: Deep imports into package internals"
+echo ""
+DEEP_IMPORTS=$(grep -rnI "from ['\"]@[^'\"]*\/src\/" \
+  "$PACKAGES_DIR" \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.sol' \
+  2>/dev/null || true)
+
+if [ -n "$DEEP_IMPORTS" ]; then
+  echo "$DEEP_IMPORTS" | while IFS= read -r line; do
+    echo "  ❌ $line"
+  done
+  echo ""
+else
+  echo "  ✅ No deep imports into package internals found"
+  echo ""
+fi
+
+# Pattern 3: Importing from internal/ or _internal/ of another package
+echo "  ### Pattern 3: Internal module access violations"
+echo ""
+INTERNAL_IMPORTS=$(grep -rnI "from ['\"].*internal\/" \
+  "$PACKAGES_DIR" \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.sol' \
+  2>/dev/null | grep -vE "(node_modules|lib/forge-std|lib/openzeppelin|lib/erc721a)" || true)
+
+if [ -n "$INTERNAL_IMPORTS" ]; then
+  echo "$INTERNAL_IMPORTS" | while IFS= read -r line; do
+    echo "  ⚠️  $line"
+  done
+  echo ""
+else
+  echo "  ✅ No internal module access violations found"
+  echo ""
+fi
+
+# Pattern 4: Check each package has index.ts (public API boundary)
+echo "  ### Pattern 4: Missing public API boundary (index.ts)"
+echo ""
+for pkg in "$PACKAGES_DIR"/*/; do
+  [ -d "$pkg" ] || continue
+  pkg_name=$(basename "$pkg")
+
+  if [ -f "$pkg/src/index.ts" ] || [ -f "$pkg/src/index.tsx" ] || [ -f "$pkg/index.ts" ]; then
+    : # has boundary
+  else
+    echo "  ❌ $pkg_name — no src/index.ts (no public API boundary)"
+  fi
+done
+
+echo ""
+echo "  ──────────────────────────────────"
+
+# Count all violations
+TOTAL=$(echo "$CROSS_PKG$DEEP_IMPORTS$INTERNAL_IMPORTS" | grep -c "." || true)
+echo "  Total violations: $TOTAL"
+
+if [ "$TOTAL" -gt 0 ]; then
+  echo ""
+  echo "  💡 Fix: Replace internal imports with public API imports through index.ts"
+  echo "     Example: import { User } from '@scope/core'  (not from '@scope/core/src/...')"
+  exit 1
+else
+  echo "  ✅ All imports respect package boundaries"
+  exit 0
+fi