@ivannikov-pro/ai-context-surgeon 1.0.0

package/tools/measure-context-cost.sh

@@ -0,0 +1,206 @@
+#!/bin/bash
+# Tool: measure-context-cost — Estimate AI agent context cost for a package | DEPS: none
+# USAGE: bash tools/measure-context-cost.sh /path/to/package
+# OUTPUT: estimated token costs and efficiency metrics
+# 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/measure-context-cost.sh /path/to/package"
+  echo "Usage: bash tools/measure-context-cost.sh /path/to/package [--internal-scope=scope1,scope2]"
+  echo ""
+  echo "Estimates the context cost (in tokens) for an AI agent to understand"
+  echo "a package. Compares cost with and without README/navigation aids."
+  echo ""
+  echo "Token estimation: 1 token ≈ 4 characters (rough approximation)"
+  exit 0
+fi
+
+TARGET="."
+INTERNAL_SCOPES=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --internal-scope=*)
+      INTERNAL_SCOPES="${1#*=}"
+      shift
+      ;;
+    -h|--help)
+      exit 0
+      ;;
+    *)
+      TARGET="$1"
+      shift
+      ;;
+  esac
+done
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+PKG_NAME=$(basename "$TARGET")
+CHARS_PER_TOKEN=4
+
+echo "📊 Context Cost Analysis: $PKG_NAME"
+if [[ -n "$INTERNAL_SCOPES" ]]; then
+  echo "🔍 Treating scopes as local: $INTERNAL_SCOPES"
+fi
+echo "────────────────────────────────────────"
+
+# Construct regex for local imports
+if [[ -n "$INTERNAL_SCOPES" ]]; then
+  SCOPE_PATTERN=$(echo "$INTERNAL_SCOPES" | tr ',' '|')
+  LOCAL_REGEX="^(import |from |use |const .* = require\()).*['\"](\.|/|@/|~/|${SCOPE_PATTERN})"
+else
+  LOCAL_REGEX="^(import |from |use |const .* = require\()).*['\"](\.|/|@/|~/)"
+fi
+
+# Count source files
+SRC_FILES=$(find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' -o -name '*.py' -o -name '*.rs' \) \
+  -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' \
+ | wc -l | tr -d ' ')
+
+# Total source bytes
+TOTAL_BYTES=$(find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' -o -name '*.py' -o -name '*.rs' \) \
+  -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' \
+  -exec wc -c {} + 2>/dev/null | grep total | awk '{print $1}')
+
+if [[ -z "$TOTAL_BYTES" ]]; then
+  TOTAL_BYTES=0
+fi
+
+TOTAL_TOKENS=$((TOTAL_BYTES / CHARS_PER_TOKEN))
+
+IMPORTS_ALL=$(find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' -o -name '*.py' -o -name '*.rs' \) \
+  -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' \
+  -exec grep -E "^(import |from |use |const .* = require\()" {} + 2>/dev/null | wc -l | tr -d ' ' || true)
+
+IMPORTS_LOCAL=$(find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' -o -name '*.py' -o -name '*.rs' \) \
+  -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' \
+  -exec grep -E "$LOCAL_REGEX" {} + 2>/dev/null | wc -l | tr -d ' ' || true)
+
+TOTAL_LINES=$(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 -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' \
+  -exec cat {} + 2>/dev/null | wc -l | tr -d ' ' || true)
+
+if [[ $SRC_FILES -gt 0 ]]; then
+  IMPORTS_GLOBAL=$((IMPORTS_ALL - IMPORTS_LOCAL))
+  FANOUT_LOCAL=$(awk "BEGIN {printf \"%.1f\", $IMPORTS_LOCAL/$SRC_FILES}")
+  FANOUT_GLOBAL=$(awk "BEGIN {printf \"%.1f\", $IMPORTS_GLOBAL/$SRC_FILES}")
+  AVG_LOC=$((TOTAL_LINES / SRC_FILES))
+  AVG_WEIGHT=$(awk "BEGIN {print int($AVG_LOC + ($IMPORTS_LOCAL/$SRC_FILES) * 20 + ($IMPORTS_GLOBAL/$SRC_FILES) * 5)}")
+else
+  FANOUT_LOCAL=0
+  FANOUT_GLOBAL=0
+  AVG_LOC=0
+  AVG_WEIGHT=0
+fi
+
+# Determine Weight Category
+if [[ $AVG_WEIGHT -gt 300 ]]; then
+  WEIGHT_CLASS="🔴 Heavy"
+elif [[ $AVG_WEIGHT -gt 150 ]]; then
+  WEIGHT_CLASS="⚠️ Moderate"
+else
+  WEIGHT_CLASS="✅ Light"
+fi
+
+echo "Source files: $SRC_FILES"
+echo "Total source: ~${TOTAL_TOKENS} tokens (${TOTAL_BYTES} bytes, $TOTAL_LINES lines)"
+echo "Fan-out: $FANOUT_LOCAL Local / $FANOUT_GLOBAL Global (Avg dependencies per file)"
+echo "Avg Context Weight (LOC + Loc*20 + Glob*5): $AVG_WEIGHT ($WEIGHT_CLASS)"
+echo ""
+
+# Scenario 1: No README (blind navigation)
+echo "📍 WITHOUT README (blind navigation)"
+echo "────────────────────────────────────────"
+
+LIST_DIR_CALLS=0
+VIEW_FILE_CALLS=0
+
+# Count directories that need list_dir
+SEARCH_DIR="$TARGET/src"
+if [[ ! -d "$SEARCH_DIR" ]]; then
+  SEARCH_DIR="$TARGET"
+fi
+
+DIR_COUNT=$(find "$SEARCH_DIR" -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' -not -path '*/.*' 2>/dev/null | wc -l | tr -d ' ')
+LIST_DIR_CALLS=$((DIR_COUNT))
+
+# Agent would need to view ~30% of files to understand the package
+VIEW_FILE_CALLS=$((SRC_FILES * 30 / 100))
+[[ $VIEW_FILE_CALLS -lt 3 ]] && VIEW_FILE_CALLS=3
+
+# Estimate tokens per operation
+LIST_DIR_TOKENS=$((LIST_DIR_CALLS * 250))  # ~250 tokens per list_dir
+AVG_FILE_TOKENS=$((TOTAL_TOKENS / SRC_FILES))
+[[ $AVG_FILE_TOKENS -lt 100 ]] && AVG_FILE_TOKENS=100
+VIEW_FILE_TOKENS=$((VIEW_FILE_CALLS * AVG_FILE_TOKENS))
+
+BLIND_TOTAL=$((LIST_DIR_TOKENS + VIEW_FILE_TOKENS))
+
+echo "  list_dir calls:  ${LIST_DIR_CALLS} (~${LIST_DIR_TOKENS} tokens)"
+echo "  view_file calls: ${VIEW_FILE_CALLS} (~${VIEW_FILE_TOKENS} tokens)"
+echo "  TOTAL:           ~${BLIND_TOTAL} tokens"
+echo ""
+
+# Scenario 2: With README (guided navigation)
+echo "📍 WITH README (guided navigation)"
+echo "────────────────────────────────────────"
+
+README_EXISTS="No"
+README_TOKENS=0
+if [[ -f "$TARGET/README.md" ]]; then
+  README_EXISTS="Yes"
+  README_BYTES=$(wc -c < "$TARGET/README.md" | tr -d ' ')
+  README_TOKENS=$((README_BYTES / CHARS_PER_TOKEN))
+fi
+
+# With README, agent only needs README + 1-3 target files
+GUIDED_VIEW_CALLS=3
+GUIDED_VIEW_TOKENS=$((GUIDED_VIEW_CALLS * AVG_FILE_TOKENS))
+GUIDED_TOTAL=$((README_TOKENS + GUIDED_VIEW_TOKENS))
+
+echo "  README exists:   ${README_EXISTS}"
+echo "  README size:     ~${README_TOKENS} tokens"
+echo "  view_file calls: ${GUIDED_VIEW_CALLS} (targeted)"
+echo "  TOTAL:           ~${GUIDED_TOTAL} tokens"
+echo ""
+
+# Comparison
+echo "📈 COMPARISON"
+echo "────────────────────────────────────────"
+
+if [[ $BLIND_TOTAL -gt 0 ]]; then
+  SAVINGS=$(( (BLIND_TOTAL - GUIDED_TOTAL) * 100 / BLIND_TOTAL ))
+else
+  SAVINGS=0
+fi
+
+echo "  Without README:  ~${BLIND_TOTAL} tokens"
+echo "  With README:     ~${GUIDED_TOTAL} tokens"
+echo "  Savings:         ${SAVINGS}%"
+echo ""
+
+if [[ "$README_EXISTS" == "No" ]]; then
+  echo "⚠️  README.md is MISSING! Creating one would save ~$((BLIND_TOTAL - GUIDED_TOTAL)) tokens per task."
+else
+  # Check if README has Source Structure
+  if grep -q "Source Structure\|src/" "$TARGET/README.md" 2>/dev/null; then
+    echo "✅ README has Source Structure — agent can navigate efficiently"
+  else
+    echo "⚠️  README exists but lacks Source Structure section"
+    echo "   Adding it would improve navigation further."
+  fi
+fi

package/tools/scan-fnh.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# Tool: scan-fnh — Generate a repository map from FNH headers | DEPS: none
+# USAGE: bash tools/scan-fnh.sh [path] [--internal-scope=...] [--depth=N] [--no-legend]
+# OUTPUT: File map mapping paths to their semantic FNH descriptions and context metrics
+# MODE: read-only analysis
+
+set -euo pipefail
+
+TARGET="."
+INTERNAL_SCOPES=""
+DEPTH="all"
+SHOW_LEGEND=true
+
+show_help() {
+  echo "Usage: bash tools/scan-fnh.sh [target] [options]"
+  echo ""
+  echo "Scans files and extracts their FNH (File Navigation Header)."
+  echo "If FNH is missing, computes 'Context Weight' (LOC + Fan-out) on the fly."
+  echo "Respects .gitignore natively via git ls-files."
+  echo ""
+  echo "Arguments:"
+  echo "  target                        Directory or specific file to scan (default: .)"
+  echo ""
+  echo "Options:"
+  echo "  --depth=N                     Limit scan depth to N subdirectories (default: all)."
+  echo "  --internal-scope=@org,pkg     Treat these scopes as local imports when calculating penalty weight."
+  echo "  --no-legend                   Hide formatting legend and headers, returning pure table data."
+  echo "  -h, --help                    Show this help message."
+  exit 0
+}
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --internal-scope=*)
+      INTERNAL_SCOPES="${1#*=}"
+      shift
+      ;;
+    --depth=*)
+      DEPTH="${1#*=}"
+      shift
+      ;;
+    --no-legend)
+      SHOW_LEGEND=false
+      shift
+      ;;
+    -h|--help)
+      show_help
+      ;;
+    *)
+      TARGET="$1"
+      shift
+      ;;
+  esac
+done
+
+if [[ ! -e "$TARGET" ]]; then
+  echo "❌ Error: target '$TARGET' does not exist"
+  exit 1
+fi
+
+IS_SINGLE_FILE=false
+if [[ -f "$TARGET" ]]; then
+  IS_SINGLE_FILE=true
+  TARGET_DIR="$(dirname "$TARGET")"
+  TARGET_FILE="$(basename "$TARGET")"
+  cd "$TARGET_DIR"
+else
+  cd "$TARGET"
+fi
+
+if [[ "$SHOW_LEGEND" == true ]]; then
+  echo "🗺️  File Navigation Header (FNH) Semantic Map: $(pwd)"
+  if [[ -n "$INTERNAL_SCOPES" ]]; then
+    echo "🔍 Treating scopes as local: $INTERNAL_SCOPES"
+  fi
+  echo "FORMAT: [LOC L] path/to/file | Semantic Description OR 🔴 [NO FNH] ContextWeight W (L_loc: local_deps, I_glb: global_deps)"
+  echo "───────────────────────────────────────────────────────────────────────────────"
+fi
+
+# Construct regex for local imports (used if we need to calculate context weight)
+if [[ -n "$INTERNAL_SCOPES" ]]; then
+  SCOPE_PATTERN=$(echo "$INTERNAL_SCOPES" | tr ',' '|')
+  LOCAL_REGEX="^(import |from |use |const .* = require\()).*['\"](\.|/|@/|~/|${SCOPE_PATTERN})"
+else
+  LOCAL_REGEX="^(import |from |use |const .* = require\()).*['\"](\.|/|@/|~/)"
+fi
+
+# FNH Matching Regex (includes all common AI directives across languages)
+FNH_REGEX="(FNH:|Category:|Tool:|Role:|Guide:|Checklist:|Knowledge:|Architecture:|Report:|Skill:|Service:|Middleware:|Controller:|Repository:|Entity:|Types:|Utility:|Config:|Schema:|Hook:|Component:|Test:|Migration:|Script:|Constants:|Factory:|Adapter:|Event:|Guard:|Package:)"
+
+# Extension filter for code/doc files
+EXT_REGEX='\.(ts|tsx|js|jsx|sol|py|rs|md|yml|yaml|sh|json)$|^Dockerfile'
+
+# Discover files (Prefer git ls-files to automatically respect all .gitignore files)
+if [[ "$IS_SINGLE_FILE" == true ]]; then
+  FILES="$TARGET_FILE"
+else
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    FILES=$(git ls-files | grep -E "$EXT_REGEX" | grep -vE '(package-lock\.json|yarn\.lock|pnpm-lock\.yaml)' || true)
+  else
+    FILES=$(find . -type f | sed 's|^\./||' | grep -E "$EXT_REGEX" | grep -v 'node_modules/' | grep -v 'dist/' | grep -v '\.git/' | grep -vE '(package-lock\.json|yarn\.lock|pnpm-lock\.yaml)' || true)
+  fi
+
+  if [[ "$DEPTH" != "all" && "$DEPTH" =~ ^[0-9]+$ ]]; then
+    FILES=$(echo "$FILES" | awk -F'/' -v d="$DEPTH" '{ if (NF <= d) print $0 }')
+  fi
+fi
+
+if [[ -z "$FILES" ]]; then
+  if [[ "$SHOW_LEGEND" == true ]]; then
+    echo "No relevant files found."
+  fi
+  exit 0
+fi
+
+echo "$FILES" | sort | while read -r FILE; do
+  
+  if [[ ! -f "$FILE" ]]; then continue; fi
+
+  # Count LOC (trimming whitespace)
+  LOC=$(wc -l < "$FILE" | tr -d ' ')
+  
+  # Extract FNH string
+  DESC=""
+  if [[ "$FILE" == *.json ]]; then
+    # Light JSON parsing for description
+    DESC=$(grep -E '"description"\s*:' "$FILE" 2>/dev/null | head -n 1 | sed -E 's/.*"description"\s*:\s*"([^"]+)".*/\1/' || true)
+    if [[ -n "$DESC" ]]; then
+      DESC="Description: $DESC"
+    fi
+  else
+    # 5-line lookahead is purely a search window. We output only the matched line.
+    HEADER=$(head -n 5 "$FILE" | grep -iE "$FNH_REGEX" | head -n 1 || true)
+    
+    if [[ -n "$HEADER" ]]; then
+      # Clean up formatting wrappers (HTML, JSDoc, blockquotes, python docstrings)
+      CL_HEADER=$(echo "$HEADER" | sed -E 's/<!--\s*|\s*-->//g' | sed -E 's/\/\*\*\s*|\s*\*\///g' | sed -E 's/^[>#"-]+ //g' | sed -E 's/"""//g')
+      # Strip leading/trailing margins
+      DESC=$(echo "$CL_HEADER" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+    fi
+  fi
+
+  # Report Output Formatting
+  # Minimal formatting to preserve AI context tokens (no excessive space padding)
+  if [[ -n "$DESC" ]]; then
+    echo "[$LOC L] $FILE | $DESC"
+  else
+    # If standard markdown, just say NO FNH without calculating code context weight
+    if [[ "$FILE" == *.md || "$FILE" == *.json || "$FILE" == *.yml || "$FILE" == *.yaml ]]; then
+       if [[ $(basename "$FILE") == "README.md" ]]; then
+         echo "[$LOC L] $FILE | ⚠️ [Standard README]"
+       else
+         echo "[$LOC L] $FILE | 🔴 [NO FNH]"
+       fi
+    else
+       # If code file, calculate Context Weight as a penalty/diagnostic string!
+       IMPORTS_ALL=$(grep -E "^(import |from |use |const .* = require\()" "$FILE" 2>/dev/null | wc -l | tr -d ' ' || true)
+       IMPORTS_LOCAL=$(grep -E "$LOCAL_REGEX" "$FILE" 2>/dev/null | wc -l | tr -d ' ' || true)
+       IMPORTS_GLOBAL=$((IMPORTS_ALL - IMPORTS_LOCAL))
+       
+       WEIGHT=$((LOC + (IMPORTS_LOCAL * 20) + (IMPORTS_GLOBAL * 5)))
+       
+       # Print with rich context penalty warning
+       echo "[$LOC L] $FILE | 🔴 [NO FNH] $WEIGHT W (L_loc: $IMPORTS_LOCAL, I_glb: $IMPORTS_GLOBAL)"
+    fi
+  fi
+
+done
+
+if [[ "$SHOW_LEGEND" == true ]]; then
+  echo "───────────────────────────────────────────────────────────────────────────────"
+  echo "AI Context Tip: Use this map to navigate the repository instantly without blind list_dir scans."
+fi
+exit 0

package/tools/shared/config.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Tool: shared/config.sh
+# FNH: Global Configuration for ai-context-surgeon Bash Tools | SECTIONS: Exclusions, Environment
+# Description: Provides unified exclusion logic for CI scanners to ensure blind ecosystem adaptability.
+
+# -----------------------------------------------------------------------------
+# FIND_EXCLUDES: Used by tools calling `find` directly
+# Usage: find "$DIR" -type f "${FIND_EXCLUDES[@]}"
+# -----------------------------------------------------------------------------
+export FIND_EXCLUDES=(
+  "!" "-path" "*/node_modules/*"
+  "!" "-path" "*/lib/forge-std/*"
+  "!" "-path" "*/lib/openzeppelin-contracts*"
+  "!" "-path" "*/lib/erc721a*"
+  "!" "-path" "*/venv/*"
+  "!" "-path" "*/.venv/*"
+  "!" "-path" "*/vendor/*"
+  "!" "-path" "*/target/*"
+  "!" "-path" "*/dist/*"
+  "!" "-path" "*/build/*"
+  "!" "-path" "*/out/*"
+  "!" "-path" "*/out_forge/*"
+  "!" "-path" "*/.next/*"
+  "!" "-path" "*/.cache/*"
+  "!" "-path" "*/.turbo/*"
+  "!" "-path" "*/.git/*"
+)
+
+# -----------------------------------------------------------------------------
+# GREP_EXCLUDES_REGEX: Used for fast `grep -vE` filtering
+# -----------------------------------------------------------------------------
+export GREP_EXCLUDES_REGEX="node_modules|lib/(forge-std|openzeppelin|erc721a)|venv|\.venv|vendor|target|dist|build|out|out_forge|\.next|\.cache|\.turbo|\.git"
+
+# -----------------------------------------------------------------------------
+# BASH_ARRAY_EXCLUDES: Used when scripting bash loops and `find` match conditions
+# -----------------------------------------------------------------------------
+export BASH_ARRAY_EXCLUDES=(
+  "*/node_modules/*"
+  "*/lib/forge-std/*"
+  "*/lib/openzeppelin-contracts*"
+  "*/lib/erc721a*"
+  "*/venv/*"
+  "*/.venv/*"
+  "*/vendor/*"
+  "*/target/*"
+  "*/dist/*"
+  "*/build/*"
+  "*/out/*"
+  "*/.next/*"
+  "*/.cache/*"
+  "*/.turbo/*"
+  "*/.git/*"
+)

package/tools/validate-context-hygiene.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Tool: validate-context-hygiene — Verify target directories contain compliance files | DEPS: none
+# USAGE: bash tools/validate-context-hygiene.sh [directory_patterns...]
+# OUTPUT: success/fail logs for file presence
+# MODE: ci-compliance
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+if [[ "$1" == "--help" || "$1" == "-h" ]]; then
+  echo "Usage: bash tools/validate-context-hygiene.sh [directories...]"
+  echo "Example: bash tools/validate-context-hygiene.sh apps/* packages/*"
+  exit 0
+fi
+
+if [ "$#" -eq 0 ]; then
+  echo "❌ Error: Please provide directories to check."
+  echo "Example: bash tools/validate-context-hygiene.sh apps/* packages/*"
+  exit 1
+fi
+
+errors=0
+checked=0
+
+for dir in "$@"; do
+  [ -d "$dir" ] || continue
+
+  checked=$((checked + 1))
+
+  for file in README.md .gitignore .antigravityignore; do
+    if [ ! -f "$dir/$file" ]; then
+      echo -e "${RED}❌ Missing${NC} $dir/$file"
+      errors=$((errors + 1))
+    fi
+  done
+done
+
+echo ""
+if [ "$errors" -eq 0 ]; then
+  echo -e "${GREEN}✅ All $checked directories have README.md, .gitignore, .antigravityignore${NC}"
+  exit 0
+else
+  echo -e "${RED}❌ $errors missing files across $checked directories${NC}"
+  echo ""
+  echo "Fix: Each target package needs self-contained ignore files + README."
+  exit 1
+fi

package/tools/validate-context-weight.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# Tool: validate-context-weight — Identify files with massive context weight | DEPS: none
+# USAGE: bash tools/validate-context-weight.sh /path/to/package
+# OUTPUT: files exceeding context weight threshold
+# MODE: read-only analysis
+
+set -euo pipefail
+
+TARGET="."
+INTERNAL_SCOPES=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --internal-scope=*)
+      INTERNAL_SCOPES="${1#*=}"
+      shift
+      ;;
+    -h|--help)
+      echo "Usage: bash tools/validate-context-weight.sh [target_dir] [--internal-scope=@myorg,my-package]"
+      echo ""
+      echo "Finds files that are highly complex based on Context Weight formula:"
+      echo "Weight = LOC + (Local Imports * 20) + (Global Imports * 5)"
+      exit 0
+      ;;
+    *)
+      TARGET="$1"
+      shift
+      ;;
+  esac
+done
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "❌ Error: '$TARGET' is not a directory"
+  exit 1
+fi
+
+echo "⚖️ Context Weight Analysis: $TARGET"
+if [[ -n "$INTERNAL_SCOPES" ]]; then
+  echo "🔍 Treating scopes as local: $INTERNAL_SCOPES"
+fi
+echo "────────────────────────────────────────"
+
+# Construct regex for local imports
+if [[ -n "$INTERNAL_SCOPES" ]]; then
+  SCOPE_PATTERN=$(echo "$INTERNAL_SCOPES" | tr ',' '|')
+  LOCAL_REGEX="^(import |from |use |const .* = require\()).*['\"](\.|/|@/|~/|${SCOPE_PATTERN})"
+else
+  LOCAL_REGEX="^(import |from |use |const .* = require\()).*['\"](\.|/|@/|~/)"
+fi
+
+# Temporary file to store results
+TMP_RESULTS=$(mktemp)
+
+# Find all relevant files
+find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' -o -name '*.py' -o -name '*.rs' \) \
+  -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/lib/forge-std/*' -not -path '*/lib/openzeppelin-contracts*' -not -path '*/lib/erc721a*' \
+  -not -name '*.d.ts' -not -name '*.test.*' -not -name '*.spec.*' | while read -r FILE; do
+  
+  LOC=$(wc -l < "$FILE" | tr -d ' ')
+  
+  IMPORTS_ALL=$(grep -E "^(import |from |use |const .* = require\()" "$FILE" 2>/dev/null | wc -l | tr -d ' ' || true)
+  IMPORTS_LOCAL=$(grep -E "$LOCAL_REGEX" "$FILE" 2>/dev/null | wc -l | tr -d ' ' || true)
+  IMPORTS_GLOBAL=$((IMPORTS_ALL - IMPORTS_LOCAL))
+  
+  WEIGHT=$((LOC + (IMPORTS_LOCAL * 20) + (IMPORTS_GLOBAL * 5)))
+  
+  # Only report if weight is high enough
+  if [[ $WEIGHT -gt 150 ]]; then
+    echo "$WEIGHT|$LOC|$IMPORTS_LOCAL|$IMPORTS_GLOBAL|$FILE" >> "$TMP_RESULTS"
+  fi
+done
+
+# Check if there are results
+if [[ -s "$TMP_RESULTS" ]]; then
+  echo "Found files with high Context Weight (Warning > 150, Critical > 300):"
+  
+  # Sort by weight (descending) and format output
+  sort -t '|' -k1 -rn "$TMP_RESULTS" | awk -F '|' '{
+    weight=$1; loc=$2; i_loc=$3; i_glob=$4; file=$5;
+    
+    if (weight > 300) {
+      color="\033[0;31m"; # Red
+      icon="🔴";
+    } else {
+      color="\033[1;33m"; # Yellow
+      icon="⚠️ ";
+    }
+    
+    printf "  %s%s %d W\033[0m  (L:%d, I_loc:%d, I_glb:%d)  %s\n", color, icon, weight, loc, i_loc, i_glob, file
+  }'
+  
+  echo ""
+  echo "Context Weight = LOC + (Local Imports * 20) + (Global Imports * 5)"
+  echo "To reduce weight, either extract dependencies or split the logic."
+else
+  echo "✅ No files exceed context weight threshold (150 W)!"
+fi
+
+rm "$TMP_RESULTS"
+exit 0

package/tools/validate-naming.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# Tool: validate-naming — checks naming conventions across monorepo | DEPS: none
+# USAGE: bash tools/validate-naming.sh /path/to/repo
+# OUTPUT: naming violations grouped by type
+# MODE: read-only, no modifications
+
+set -euo pipefail
+
+source "$(dirname "$0")/shared/config.sh"
+
+TARGET="${1:-.}"
+VIOLATIONS=0
+
+echo "📝 Naming Convention Validator"
+echo "  Target: $TARGET"
+echo "  ──────────────────────────────────"
+echo ""
+
+# Rule 1: Files should be kebab-case (except special files)
+echo "  ### Rule 1: Files must be kebab-case.ts"
+echo "  Exceptions: index.ts, AGENTS.md, README.md, LICENSE, Dockerfile, .env"
+echo ""
+
+SPECIAL_FILES="index\|README\|AGENTS\|LICENSE\|Dockerfile\|CHANGELOG\|CONTRIBUTING\|SECURITY\|\.env\|\.gitignore\|\.npmrc\|\.eslintrc\|\.prettierrc\|node_modules\|\.git"
+
+BAD_FILES=$(find "$TARGET" -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.sol' \) \
+  ! -path '*/node_modules/*' ! -path '*/lib/forge-std/*' ! -path '*/lib/openzeppelin-contracts*' ! -path '*/lib/erc721a*' ! -path '*/.git/*' ! -path '*/dist/*' ! -path '*/.next/*' \
+ | xargs -I {} basename {} \
+ | grep -v "^index\." \
+ | grep -v "^[a-z][a-z0-9]*\(-[a-z0-9]*\)*\.\(ts\|tsx\|js\|jsx\)$" \
+ | sort -u 2>/dev/null || true)
+
+if [ -n "$BAD_FILES" ]; then
+  echo "$BAD_FILES" | while IFS= read -r name; do
+    echo "  ❌ $name — should be kebab-case"
+  done
+  echo ""
+else
+  echo "  ✅ All source files use kebab-case"
+  echo ""
+fi
+
+# Rule 2: Directories should be kebab-case
+echo "  ### Rule 2: Directories must be kebab-case"
+echo "  Exceptions: node_modules, .git, .agents, .github, __tests__, __mocks__"
+echo ""
+
+BAD_DIRS=$(find "$TARGET" -type d \
+  ! -path '*/node_modules/*' ! -path '*/lib/forge-std/*' ! -path '*/lib/openzeppelin-contracts*' ! -path '*/lib/erc721a*' ! -path '*/.git/*' ! -path '*/dist/*' ! -path '*/.next/*' \
+ | xargs -I {} basename {} \
+ | grep -v '^\.' \
+ | grep -v '^__' \
+ | grep -v '^node_modules$' \
+ | grep -v '^[a-z][a-z0-9]*\(-[a-z0-9]*\)*$' \
+ | sort -u 2>/dev/null || true)
+
+if [ -n "$BAD_DIRS" ]; then
+  echo "$BAD_DIRS" | while IFS= read -r name; do
+    echo "  ⚠️  $name — should be kebab-case"
+  done
+  echo ""
+else
+  echo "  ✅ All directories use kebab-case"
+  echo ""
+fi
+
+# Rule 3: Check for inconsistent naming in same directory
+echo "  ### Rule 3: Consistency within directories"
+echo ""
+
+MIXED=0
+OLD_IFS=$IFS
+IFS='
+'
+for dir in $(find "$TARGET" -type d ! -path '*/node_modules/*' ! -path '*/lib/forge-std/*' ! -path '*/lib/openzeppelin-contracts*' ! -path '*/lib/erc721a*' ! -path '*/.git/*' ! -path '*/dist/*' 2>/dev/null); do
+  [ -z "$dir" ] && continue
+
+  FILES=$(find "$dir" -maxdepth 1 -type f \( -name '*.ts' -o -name '*.js' -o -name '*.sol' \) ! -name 'index.*' 2>/dev/null)
+  [ -z "$FILES" ] && continue
+
+  HAS_CAMEL=$(echo "$FILES" | xargs -I {} basename {} | grep -c '[A-Z]' || true)
+  HAS_KEBAB=$(echo "$FILES" | xargs -I {} basename {} | grep -c '\-' || true)
+
+  if [ "$HAS_CAMEL" -gt 0 ] && [ "$HAS_KEBAB" -gt 0 ]; then
+    echo "  ⚠️  Mixed naming in: $dir"
+    echo "      camelCase: $HAS_CAMEL files, kebab-case: $HAS_KEBAB files"
+    MIXED=$((MIXED + 1))
+  fi
+done
+IFS=$OLD_IFS
+
+if [ "$MIXED" -eq 0 ]; then
+  echo "  ✅ No mixed naming conventions within directories"
+fi
+
+echo ""
+echo "  ──────────────────────────────────"
+echo "  Naming check complete"