context-engineer 1.1.0

package/templates/core/scripts/extract-structure.sh

@@ -0,0 +1,757 @@
+#!/usr/bin/env bash
+#
+# extract-structure.sh — Extract project structure for context engineering
+#
+# Capabilities:
+#   1. Namespace/module listing with file counts
+#   2. Class/struct/interface definitions with inheritance
+#   3. Import/include dependency graph (module-level)
+#   4. Public function/method signatures
+#
+# Usage: bash scripts/extract-structure.sh [OPTIONS]
+#
+# Options:
+#   --all              Run all extractions (default)
+#   --class-index      Extract class/struct/interface index
+#   --module-graph     Extract module dependency graph
+#   --namespaces       Extract namespace/directory mapping
+#   --functions        Extract public function signatures
+#   --src-dir DIR      Source directory to scan (default: auto-detect)
+#   --output-dir DIR   Output directory (default: .context/architecture)
+#
+# Supported languages:
+#   C/C++:       class/struct, #include, namespace
+#   C#:          class/interface, using, namespace
+#   TypeScript:  class/interface, import, export
+#   Python:      class, import, def
+#   Rust:        struct/trait/impl, use, mod
+#   Go:          struct/interface, import, package
+#   Java:        class/interface, import, package
+
+set -euo pipefail
+
+CONTEXT_DIR=".context"
+OUTPUT_DIR="$CONTEXT_DIR/architecture"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+SRC_DIR=""
+
+# ============================================================
+# Language Detection
+# ============================================================
+
+detect_languages() {
+  local langs=()
+
+  # C/C++
+  if find . -maxdepth 5 -name "*.cpp" -o -name "*.h" -o -name "*.hpp" -o -name "*.cc" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("cpp")
+  fi
+
+  # C#
+  if find . -maxdepth 5 -name "*.cs" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("csharp")
+  fi
+
+  # TypeScript/JavaScript
+  if find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("typescript")
+  elif find . -maxdepth 5 -name "*.js" -o -name "*.jsx" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("javascript")
+  fi
+
+  # Python
+  if find . -maxdepth 5 -name "*.py" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("python")
+  fi
+
+  # Rust
+  if find . -maxdepth 5 -name "*.rs" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("rust")
+  fi
+
+  # Go
+  if find . -maxdepth 5 -name "*.go" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("go")
+  fi
+
+  # Java
+  if find . -maxdepth 5 -name "*.java" 2>/dev/null | head -1 | grep -q .; then
+    langs+=("java")
+  fi
+
+  echo "${langs[*]}"
+}
+
+# ============================================================
+# Source Directory Detection
+# ============================================================
+
+detect_src_dir() {
+  # Common source directory names
+  for dir in src source lib app Sources pkg cmd internal; do
+    if [ -d "$dir" ]; then
+      echo "$dir"
+      return
+    fi
+  done
+  # Fallback: current directory
+  echo "."
+}
+
+# ============================================================
+# Namespace / Directory Mapping
+# ============================================================
+
+extract_namespaces() {
+  local langs="$1"
+  echo "Extracting namespace/directory mapping..."
+
+  local output="$OUTPUT_DIR/module-graph.md"
+
+  # We'll append the namespace table to the module-graph if it exists
+  # For now, output to stdout for integration
+  echo ""
+  echo "## Namespace / Directory Mapping"
+  echo ""
+  echo "| Namespace / Package | Directory | File Count |"
+  echo "|---------------------|-----------|------------|"
+
+  if [[ "$langs" == *"cpp"* ]]; then
+    # C++: Extract namespaces from source files
+    find "$SRC_DIR" -name "*.h" -o -name "*.hpp" -o -name "*.cpp" -o -name "*.cc" 2>/dev/null | while read -r file; do
+      grep -oP 'namespace\s+\K[a-zA-Z_][a-zA-Z0-9_:]*' "$file" 2>/dev/null
+    done | sort -u | while read -r ns; do
+      local dir
+      dir=$(find "$SRC_DIR" -name "*.h" -o -name "*.hpp" -o -name "*.cpp" -o -name "*.cc" 2>/dev/null | xargs grep -l "namespace $ns" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "unknown")
+      local count
+      count=$(find "$SRC_DIR" -name "*.h" -o -name "*.hpp" -o -name "*.cpp" -o -name "*.cc" 2>/dev/null | xargs grep -l "namespace $ns" 2>/dev/null | wc -l || echo "0")
+      echo "| $ns | $dir | $count |"
+    done
+  fi
+
+  if [[ "$langs" == *"csharp"* ]]; then
+    # C#: Extract namespaces
+    find "$SRC_DIR" -name "*.cs" 2>/dev/null | while read -r file; do
+      grep -oP 'namespace\s+\K[a-zA-Z_][a-zA-Z0-9_.]*' "$file" 2>/dev/null
+    done | sort -u | while read -r ns; do
+      local count
+      count=$(find "$SRC_DIR" -name "*.cs" 2>/dev/null | xargs grep -l "namespace $ns" 2>/dev/null | wc -l || echo "0")
+      local dir
+      dir=$(find "$SRC_DIR" -name "*.cs" 2>/dev/null | xargs grep -l "namespace $ns" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "unknown")
+      echo "| $ns | $dir | $count |"
+    done
+  fi
+
+  if [[ "$langs" == *"python"* ]]; then
+    # Python: Extract packages (directories with __init__.py)
+    find "$SRC_DIR" -name "__init__.py" 2>/dev/null | while read -r init; do
+      local dir
+      dir=$(dirname "$init")
+      local pkg
+      pkg=$(echo "$dir" | tr '/' '.')
+      local count
+      count=$(find "$dir" -maxdepth 1 -name "*.py" 2>/dev/null | wc -l || echo "0")
+      echo "| $pkg | $dir | $count |"
+    done
+  fi
+
+  if [[ "$langs" == *"go"* ]]; then
+    # Go: Extract packages
+    find "$SRC_DIR" -name "*.go" 2>/dev/null | while read -r file; do
+      grep -oP 'package\s+\K[a-zA-Z_][a-zA-Z0-9_]*' "$file" 2>/dev/null
+    done | sort -u | while read -r pkg; do
+      local dir
+      dir=$(find "$SRC_DIR" -name "*.go" 2>/dev/null | xargs grep -l "package $pkg" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "unknown")
+      local count
+      count=$(find "$SRC_DIR" -name "*.go" 2>/dev/null | xargs grep -l "package $pkg" 2>/dev/null | wc -l || echo "0")
+      echo "| $pkg | $dir | $count |"
+    done
+  fi
+
+  if [[ "$langs" == *"java"* ]]; then
+    # Java: Extract packages
+    find "$SRC_DIR" -name "*.java" 2>/dev/null | while read -r file; do
+      grep -oP 'package\s+\K[a-zA-Z_][a-zA-Z0-9_.]*' "$file" 2>/dev/null
+    done | sort -u | while read -r pkg; do
+      local count
+      count=$(find "$SRC_DIR" -name "*.java" 2>/dev/null | xargs grep -l "package $pkg" 2>/dev/null | wc -l || echo "0")
+      local dir
+      dir=$(find "$SRC_DIR" -name "*.java" 2>/dev/null | xargs grep -l "package $pkg" 2>/dev/null | head -1 | xargs dirname 2>/dev/null || echo "unknown")
+      echo "| $pkg | $dir | $count |"
+    done
+  fi
+
+  if [[ "$langs" == *"rust"* ]]; then
+    # Rust: Extract modules from mod declarations and directory structure
+    find "$SRC_DIR" -name "*.rs" 2>/dev/null | while read -r file; do
+      local dir
+      dir=$(dirname "$file")
+      local modname
+      modname=$(basename "$file" .rs)
+      if [ "$modname" != "mod" ] && [ "$modname" != "lib" ] && [ "$modname" != "main" ]; then
+        echo "| $modname | $dir | 1 |"
+      fi
+    done | sort -u
+  fi
+
+  if [[ "$langs" == *"typescript"* ]] || [[ "$langs" == *"javascript"* ]]; then
+    # TypeScript/JavaScript: Extract by directory structure
+    find "$SRC_DIR" -maxdepth 3 -type d 2>/dev/null | while read -r dir; do
+      local count
+      count=$(find "$dir" -maxdepth 1 \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) 2>/dev/null | wc -l || echo "0")
+      if [ "$count" -gt 0 ]; then
+        echo "| $(basename "$dir") | $dir | $count |"
+      fi
+    done
+  fi
+}
+
+# ============================================================
+# Class / Struct / Interface Extraction
+# ============================================================
+
+extract_classes() {
+  local langs="$1"
+  echo "Extracting class/struct/interface definitions..."
+
+  echo ""
+  echo "## Core Classes by Module"
+  echo ""
+
+  if [[ "$langs" == *"cpp"* ]]; then
+    echo "### C/C++ Classes"
+    echo ""
+    echo "| Class | File | Type | Base Class |"
+    echo "|-------|------|------|-----------|"
+    find "$SRC_DIR" \( -name "*.h" -o -name "*.hpp" \) 2>/dev/null | sort | while read -r file; do
+      # Extract class/struct declarations with optional inheritance
+      grep -nP '^\s*(class|struct)\s+([A-Z][a-zA-Z0-9_]+)(\s*:\s*(public|protected|private)\s+([A-Z][a-zA-Z0-9_:]+))?' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local type name base
+        type=$(echo "$match" | grep -oP '^\s*\K(class|struct)')
+        name=$(echo "$match" | grep -oP '(class|struct)\s+\K[A-Z][a-zA-Z0-9_]+')
+        base=$(echo "$match" | grep -oP '(public|protected|private)\s+\K[A-Z][a-zA-Z0-9_:]+' || echo "—")
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $type | $base |"
+      done
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"csharp"* ]]; then
+    echo "### C# Classes"
+    echo ""
+    echo "| Class | File | Type | Base Class |"
+    echo "|-------|------|------|-----------|"
+    find "$SRC_DIR" -name "*.cs" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*(public|internal|protected)?\s*(abstract|sealed|static|partial)?\s*(class|interface|struct|record|enum)\s+([A-Z][a-zA-Z0-9_<>]+)(\s*:\s*([A-Z][a-zA-Z0-9_<>,\s]+))?' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local type name base
+        type=$(echo "$match" | grep -oP '(class|interface|struct|record|enum)')
+        name=$(echo "$match" | grep -oP '(class|interface|struct|record|enum)\s+\K[A-Z][a-zA-Z0-9_<>]+')
+        base=$(echo "$match" | grep -oP ':\s*\K[A-Z][a-zA-Z0-9_<>]+' || echo "—")
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $type | $base |"
+      done
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"python"* ]]; then
+    echo "### Python Classes"
+    echo ""
+    echo "| Class | File | Base Class |"
+    echo "|-------|------|-----------|"
+    find "$SRC_DIR" -name "*.py" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*class\s+([A-Z][a-zA-Z0-9_]+)\s*(\(([^)]*)\))?\s*:' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local name base
+        name=$(echo "$match" | grep -oP 'class\s+\K[A-Z][a-zA-Z0-9_]+')
+        base=$(echo "$match" | grep -oP '\(\K[^)]+' || echo "—")
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $base |"
+      done
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"typescript"* ]] || [[ "$langs" == *"javascript"* ]]; then
+    echo "### TypeScript/JavaScript Classes"
+    echo ""
+    echo "| Class | File | Type | Base/Implements |"
+    echo "|-------|------|------|----------------|"
+    find "$SRC_DIR" \( -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*(export\s+)?(abstract\s+)?(class|interface)\s+([A-Z][a-zA-Z0-9_<>]+)(\s+(extends|implements)\s+([A-Z][a-zA-Z0-9_<>,\s]+))?' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local type name base
+        type=$(echo "$match" | grep -oP '(class|interface)')
+        name=$(echo "$match" | grep -oP '(class|interface)\s+\K[A-Z][a-zA-Z0-9_<>]+')
+        base=$(echo "$match" | grep -oP '(extends|implements)\s+\K[A-Z][a-zA-Z0-9_<>]+' || echo "—")
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $type | $base |"
+      done
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"rust"* ]]; then
+    echo "### Rust Types"
+    echo ""
+    echo "| Type | File | Kind |"
+    echo "|------|------|------|"
+    find "$SRC_DIR" -name "*.rs" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*pub\s+(struct|enum|trait)\s+([A-Z][a-zA-Z0-9_<>]+)' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local kind name
+        kind=$(echo "$match" | grep -oP '(struct|enum|trait)')
+        name=$(echo "$match" | grep -oP '(struct|enum|trait)\s+\K[A-Z][a-zA-Z0-9_<>]+')
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $kind |"
+      done
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"go"* ]]; then
+    echo "### Go Types"
+    echo ""
+    echo "| Type | File | Kind |"
+    echo "|------|------|------|"
+    find "$SRC_DIR" -name "*.go" -not -name "*_test.go" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*type\s+([A-Z][a-zA-Z0-9_]+)\s+(struct|interface)' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local kind name
+        kind=$(echo "$match" | grep -oP '(struct|interface)$')
+        name=$(echo "$match" | grep -oP 'type\s+\K[A-Z][a-zA-Z0-9_]+')
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $kind |"
+      done
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"java"* ]]; then
+    echo "### Java Classes"
+    echo ""
+    echo "| Class | File | Type | Base/Implements |"
+    echo "|-------|------|------|----------------|"
+    find "$SRC_DIR" -name "*.java" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*(public|protected)?\s*(abstract|final)?\s*(class|interface|enum|record)\s+([A-Z][a-zA-Z0-9_<>]+)(\s+(extends|implements)\s+([A-Z][a-zA-Z0-9_<>,\s]+))?' "$file" 2>/dev/null | while IFS=: read -r lineno match; do
+        local type name base
+        type=$(echo "$match" | grep -oP '(class|interface|enum|record)')
+        name=$(echo "$match" | grep -oP '(class|interface|enum|record)\s+\K[A-Z][a-zA-Z0-9_<>]+')
+        base=$(echo "$match" | grep -oP '(extends|implements)\s+\K[A-Z][a-zA-Z0-9_<>]+' || echo "—")
+        [ -n "$name" ] && echo "| $name | $file:$lineno | $type | $base |"
+      done
+    done
+    echo ""
+  fi
+}
+
+# ============================================================
+# Module Dependency Graph
+# ============================================================
+
+extract_module_deps() {
+  local langs="$1"
+  echo "Extracting module dependency graph..."
+
+  echo ""
+  echo "## Module Dependencies (Import/Include Analysis)"
+  echo ""
+
+  if [[ "$langs" == *"cpp"* ]]; then
+    echo "### C/C++ Include Dependencies"
+    echo ""
+    echo "| Source Directory | Includes From |"
+    echo "|-----------------|--------------|"
+    # Analyze #include patterns at directory level
+    find "$SRC_DIR" \( -name "*.cpp" -o -name "*.cc" -o -name "*.h" -o -name "*.hpp" \) 2>/dev/null | while read -r file; do
+      local src_dir
+      src_dir=$(dirname "$file")
+      grep -oP '#include\s*["<]\K[^">]+' "$file" 2>/dev/null | while read -r inc; do
+        local inc_dir
+        inc_dir=$(dirname "$inc")
+        if [ "$inc_dir" != "." ] && [ "$inc_dir" != "$src_dir" ]; then
+          echo "$src_dir → $inc_dir"
+        fi
+      done
+    done | sort -u | head -50 | while read -r dep; do
+      local src tgt
+      src=$(echo "$dep" | cut -d'→' -f1 | xargs)
+      tgt=$(echo "$dep" | cut -d'→' -f2 | xargs)
+      echo "| $src | $tgt |"
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"csharp"* ]]; then
+    echo "### C# Namespace Dependencies"
+    echo ""
+    echo "| Namespace | Uses Namespaces |"
+    echo "|-----------|----------------|"
+    find "$SRC_DIR" -name "*.cs" 2>/dev/null | while read -r file; do
+      local ns
+      ns=$(grep -oP 'namespace\s+\K[a-zA-Z_][a-zA-Z0-9_.]*' "$file" 2>/dev/null | head -1)
+      [ -z "$ns" ] && continue
+      local usings
+      usings=$(grep -oP 'using\s+\K[a-zA-Z_][a-zA-Z0-9_.]*' "$file" 2>/dev/null | grep -v "^System" | sort -u | tr '\n' ', ' | sed 's/,$//')
+      [ -n "$usings" ] && echo "| $ns | $usings |"
+    done | sort -u | head -50
+    echo ""
+  fi
+
+  if [[ "$langs" == *"typescript"* ]] || [[ "$langs" == *"javascript"* ]]; then
+    echo "### TypeScript/JavaScript Import Dependencies"
+    echo ""
+    echo "| Source Module | Imports From |"
+    echo "|--------------|-------------|"
+    find "$SRC_DIR" \( -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" 2>/dev/null | while read -r file; do
+      local src_mod
+      src_mod=$(dirname "$file")
+      grep -oP "from\s+['\"]\.{1,2}/\K[^'\"]*" "$file" 2>/dev/null | while read -r imp; do
+        local imp_dir
+        imp_dir=$(dirname "$imp" 2>/dev/null)
+        if [ "$imp_dir" != "." ]; then
+          echo "$src_mod → $imp_dir"
+        fi
+      done
+    done | sort -u | head -50 | while read -r dep; do
+      local src tgt
+      src=$(echo "$dep" | cut -d'→' -f1 | xargs)
+      tgt=$(echo "$dep" | cut -d'→' -f2 | xargs)
+      echo "| $src | $tgt |"
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"python"* ]]; then
+    echo "### Python Import Dependencies"
+    echo ""
+    echo "| Module | Imports From |"
+    echo "|--------|-------------|"
+    find "$SRC_DIR" -name "*.py" 2>/dev/null | while read -r file; do
+      local src_mod
+      src_mod=$(dirname "$file" | tr '/' '.')
+      grep -oP '^\s*(from\s+\K[a-zA-Z_][a-zA-Z0-9_.]*|import\s+\K[a-zA-Z_][a-zA-Z0-9_.]*)' "$file" 2>/dev/null | while read -r imp; do
+        # Only show project-internal imports (skip stdlib and third-party)
+        if [ -d "$(echo "$imp" | tr '.' '/')" ] || [ -f "$(echo "$imp" | tr '.' '/').py" ]; then
+          echo "$src_mod → $imp"
+        fi
+      done
+    done | sort -u | head -50 | while read -r dep; do
+      local src tgt
+      src=$(echo "$dep" | cut -d'→' -f1 | xargs)
+      tgt=$(echo "$dep" | cut -d'→' -f2 | xargs)
+      echo "| $src | $tgt |"
+    done
+    echo ""
+  fi
+
+  if [[ "$langs" == *"go"* ]]; then
+    echo "### Go Package Dependencies"
+    echo ""
+    echo "| Package | Imports |"
+    echo "|---------|--------|"
+    # Get the module name from go.mod
+    local go_module=""
+    [ -f "go.mod" ] && go_module=$(head -1 go.mod | awk '{print $2}')
+    find "$SRC_DIR" -name "*.go" -not -name "*_test.go" 2>/dev/null | while read -r file; do
+      local pkg
+      pkg=$(grep -oP 'package\s+\K[a-zA-Z_]+' "$file" 2>/dev/null | head -1)
+      [ -z "$pkg" ] && continue
+      local imports
+      imports=$(grep -oP "\"${go_module}/\K[^\"]*" "$file" 2>/dev/null | sort -u | tr '\n' ', ' | sed 's/,$//')
+      [ -n "$imports" ] && echo "| $pkg | $imports |"
+    done | sort -u | head -50
+    echo ""
+  fi
+}
+
+# ============================================================
+# Public Function Signatures
+# ============================================================
+
+extract_functions() {
+  local langs="$1"
+  echo "Extracting public function signatures..."
+
+  echo ""
+  echo "## Public Function Signatures"
+  echo ""
+
+  if [[ "$langs" == *"cpp"* ]]; then
+    echo "### C/C++ Public Methods (from headers)"
+    echo ""
+    echo "| Class | Method | File |"
+    echo "|-------|--------|------|"
+    find "$SRC_DIR" \( -name "*.h" -o -name "*.hpp" \) 2>/dev/null | sort | while read -r file; do
+      # Extract public method declarations (simplified — after "public:" until "private:" or "protected:" or end of class)
+      grep -nP '^\s*(virtual\s+)?\S+\s+\S+\s*\([^;]*\)\s*(const)?\s*(override)?\s*(=\s*0)?\s*;' "$file" 2>/dev/null | head -20 | while IFS=: read -r lineno match; do
+        local method
+        method=$(echo "$match" | sed 's/^\s*//' | sed 's/\s*;$//')
+        echo "| — | \`$method\` | $file:$lineno |"
+      done
+    done | head -100
+    echo ""
+  fi
+
+  if [[ "$langs" == *"csharp"* ]]; then
+    echo "### C# Public Methods"
+    echo ""
+    echo "| Class | Method | File |"
+    echo "|-------|--------|------|"
+    find "$SRC_DIR" -name "*.cs" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*public\s+(static\s+)?(async\s+)?(virtual\s+)?(override\s+)?\S+\s+\S+\s*\(' "$file" 2>/dev/null | head -20 | while IFS=: read -r lineno match; do
+        local method
+        method=$(echo "$match" | sed 's/^\s*//' | grep -oP 'public\s+\K.*')
+        local class
+        class=$(head -n "$lineno" "$file" 2>/dev/null | grep -oP '(class|struct)\s+\K[A-Z][a-zA-Z0-9_]+' | tail -1 || echo "—")
+        echo "| $class | \`$method\` | $file:$lineno |"
+      done
+    done | head -100
+    echo ""
+  fi
+
+  if [[ "$langs" == *"python"* ]]; then
+    echo "### Python Public Functions/Methods"
+    echo ""
+    echo "| Module | Function | File |"
+    echo "|--------|----------|------|"
+    find "$SRC_DIR" -name "*.py" 2>/dev/null | sort | while read -r file; do
+      # Public functions (not starting with _)
+      grep -nP '^\s*def\s+([a-z][a-zA-Z0-9_]*)\s*\(' "$file" 2>/dev/null | grep -v '^\s*def\s+_' | head -20 | while IFS=: read -r lineno match; do
+        local func
+        func=$(echo "$match" | grep -oP 'def\s+\K[a-zA-Z0-9_]+\s*\([^)]*\)')
+        local mod
+        mod=$(basename "$file" .py)
+        echo "| $mod | \`$func\` | $file:$lineno |"
+      done
+    done | head -100
+    echo ""
+  fi
+
+  if [[ "$langs" == *"go"* ]]; then
+    echo "### Go Exported Functions"
+    echo ""
+    echo "| Package | Function | File |"
+    echo "|---------|----------|------|"
+    find "$SRC_DIR" -name "*.go" -not -name "*_test.go" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*func\s+(\([^)]+\)\s+)?[A-Z][a-zA-Z0-9_]*\s*\(' "$file" 2>/dev/null | head -20 | while IFS=: read -r lineno match; do
+        local func
+        func=$(echo "$match" | sed 's/^\s*func\s*//' | sed 's/\s*{$//')
+        local pkg
+        pkg=$(grep -oP 'package\s+\K[a-zA-Z_]+' "$file" 2>/dev/null | head -1)
+        echo "| $pkg | \`$func\` | $file:$lineno |"
+      done
+    done | head -100
+    echo ""
+  fi
+
+  if [[ "$langs" == *"rust"* ]]; then
+    echo "### Rust Public Functions"
+    echo ""
+    echo "| Module | Function | File |"
+    echo "|--------|----------|------|"
+    find "$SRC_DIR" -name "*.rs" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*pub\s+(async\s+)?fn\s+[a-z_][a-zA-Z0-9_]*' "$file" 2>/dev/null | head -20 | while IFS=: read -r lineno match; do
+        local func
+        func=$(echo "$match" | grep -oP 'pub\s+(async\s+)?fn\s+\K[a-zA-Z0-9_]+[^{]*' | sed 's/\s*{$//')
+        local mod
+        mod=$(basename "$file" .rs)
+        echo "| $mod | \`$func\` | $file:$lineno |"
+      done
+    done | head -100
+    echo ""
+  fi
+
+  if [[ "$langs" == *"java"* ]]; then
+    echo "### Java Public Methods"
+    echo ""
+    echo "| Class | Method | File |"
+    echo "|-------|--------|------|"
+    find "$SRC_DIR" -name "*.java" 2>/dev/null | sort | while read -r file; do
+      grep -nP '^\s*public\s+(static\s+)?\S+\s+\S+\s*\(' "$file" 2>/dev/null | head -20 | while IFS=: read -r lineno match; do
+        local method
+        method=$(echo "$match" | sed 's/^\s*//' | grep -oP 'public\s+\K.*')
+        local class
+        class=$(grep -oP '(class|interface)\s+\K[A-Z][a-zA-Z0-9_]+' "$file" 2>/dev/null | head -1 || echo "—")
+        echo "| $class | \`$method\` | $file:$lineno |"
+      done
+    done | head -100
+    echo ""
+  fi
+}
+
+# ============================================================
+# Generate class-index.md
+# ============================================================
+
+generate_class_index() {
+  local langs="$1"
+  local output="$OUTPUT_DIR/class-index.md"
+
+  echo "Generating $output..."
+
+  {
+    echo "# Class Index"
+    echo ""
+    echo "<!-- AUTO-GENERATED: Do not edit manually. Run scripts/extract-structure.sh to regenerate. -->"
+    echo "<!-- generated-from: source code analysis -->"
+    echo "<!-- generated-at: $TIMESTAMP -->"
+    echo ""
+    echo "## Summary"
+    echo ""
+    echo "Auto-generated index of core classes, interfaces, and key data structures per module."
+    echo ""
+    extract_classes "$langs"
+  } > "$output"
+
+  echo "  → Generated $output"
+}
+
+# ============================================================
+# Generate module-graph.md (partial — dependencies + namespaces)
+# ============================================================
+
+generate_module_graph() {
+  local langs="$1"
+  local output="$OUTPUT_DIR/module-graph.md"
+  local temp_file="${output}.tmp"
+  local marker="<!-- AUTO-GENERATED SECTIONS BELOW -->"
+
+  echo "Generating module dependency data for $output..."
+
+  # If file exists and has the auto-generated marker, preserve human-curated sections above it
+  if [ -f "$output" ] && grep -q "$marker" "$output" 2>/dev/null; then
+    # Keep everything up to and including the marker line
+    sed "/$marker/q" "$output" > "$temp_file"
+    {
+      cat "$temp_file"
+      echo ""
+      extract_module_deps "$langs"
+      extract_namespaces "$langs"
+      echo ""
+      echo "## Circular Dependencies"
+      echo ""
+      echo "None detected. <!-- Update if circular dependencies are found -->"
+    } > "$output"
+    rm -f "$temp_file"
+  else
+    # First time: generate full file with template
+    {
+      echo "# Module Graph"
+      echo ""
+      echo "<!-- confidence: medium -->"
+      echo "<!-- source: auto-extracted via scripts/extract-structure.sh -->"
+      echo "<!-- last-updated: $(date +%Y-%m-%d) -->"
+      echo ""
+      echo "## Summary"
+      echo ""
+      echo "Module dependency graph and namespace mapping. Auto-generated sections are marked below."
+      echo ""
+      echo "## Subsystems"
+      echo ""
+      echo "<!-- HUMAN-CURATED: Fill in module responsibilities and key classes -->"
+      echo ""
+      echo "| Module | Directory | Responsibility | Key Classes |"
+      echo "|--------|-----------|---------------|-------------|"
+      echo "| [TO BE FILLED] | | | |"
+      echo ""
+      echo "## Dependency Graph"
+      echo ""
+      echo "<!-- HUMAN-CURATED: Draw ASCII dependency diagram based on the data below -->"
+      echo ""
+      echo '```'
+      echo "[Draw based on Module Dependencies section below]"
+      echo '```'
+      echo ""
+      echo "## Module Interfaces"
+      echo ""
+      echo "<!-- HUMAN-CURATED: Document key public interfaces per module -->"
+      echo ""
+      echo "### [Module Name]"
+      echo ""
+      echo "**Public Interface**:"
+      echo '- `ClassName::method(params)` — One-line description'
+      echo ""
+      echo "**Depends on**: [Module1, Module2]"
+      echo "**Depended by**: [Module3, Module4]"
+      echo ""
+      echo "---"
+      echo ""
+      echo "$marker"
+      echo ""
+      extract_module_deps "$langs"
+      extract_namespaces "$langs"
+      echo ""
+      echo "## Circular Dependencies"
+      echo ""
+      echo "None detected. <!-- Update if circular dependencies are found -->"
+    } > "$output"
+  fi
+
+  echo "  → Generated $output"
+}
+
+# ============================================================
+# Main
+# ============================================================
+
+echo "========================================="
+echo "  Structure Extraction"
+echo "========================================="
+echo ""
+
+LANGS=$(detect_languages)
+echo "Detected languages: $LANGS"
+
+if [ -z "$LANGS" ]; then
+  echo "Error: No supported source files found."
+  exit 1
+fi
+
+# Detect or use provided source directory
+if [ -z "$SRC_DIR" ]; then
+  SRC_DIR=$(detect_src_dir)
+fi
+echo "Source directory: $SRC_DIR"
+echo ""
+
+# Parse arguments
+TARGET="${1:---all}"
+shift || true
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --src-dir)
+      SRC_DIR="$2"
+      shift 2
+      ;;
+    --output-dir)
+      OUTPUT_DIR="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+case "$TARGET" in
+  --all)
+    generate_class_index "$LANGS"
+    generate_module_graph "$LANGS"
+    ;;
+  --class-index)
+    generate_class_index "$LANGS"
+    ;;
+  --module-graph)
+    generate_module_graph "$LANGS"
+    ;;
+  --namespaces)
+    extract_namespaces "$LANGS"
+    ;;
+  --functions)
+    extract_functions "$LANGS"
+    ;;
+  *)
+    echo "Usage: bash scripts/extract-structure.sh [--all | --class-index | --module-graph | --namespaces | --functions]"
+    echo ""
+    echo "Options:"
+    echo "  --src-dir DIR      Source directory to scan (default: auto-detect)"
+    echo "  --output-dir DIR   Output directory (default: .context/architecture)"
+    exit 1
+    ;;
+esac
+
+echo ""
+echo "Done. Review the generated files and fill in human-curated sections."