@dtt_siye/atool 1.1.0

package/lib/analyze-source.sh

@@ -0,0 +1,1265 @@
+#!/usr/bin/env bash
+# aTool - lib/analyze-source.sh
+# Bash-level source code analysis module for project documentation generation
+# Pure bash implementation using find + grep + jq + wc — no AI/LLM required
+
+set -euo pipefail
+
+# ── Configuration ────────────────────────────────────────────────────────────
+
+# Directories to exclude from scanning
+ATOOL_SCAN_EXCLUDE_DIRS=(
+    "node_modules" ".git" "dist" "build" "target"
+    "vendor" "__pycache__" ".next" ".nuxt" ".output"
+    ".atool-docs" "coverage" ".cache" ".turbo"
+)
+
+# Max scan depth for directory listings
+ATOOL_SCAN_MAX_DEPTH=3
+
+# ── Internal Helpers ─────────────────────────────────────────────────────────
+
+# Build find exclude arguments (space-separated for cross-shell compatibility)
+_build_exclude_args() {
+    local args=""
+    for d in "${ATOOL_SCAN_EXCLUDE_DIRS[@]}"; do
+        args+="-not -path */${d}/* "
+    done
+    printf '%s' "$args"
+}
+
+# Count files matching a pattern in a directory
+_count_files() {
+    local dir="$1" pattern="$2"
+    local exclude_args=()
+    for d in "${ATOOL_SCAN_EXCLUDE_DIRS[@]}"; do
+        exclude_args+=(-not -path "*/${d}/*")
+    done
+    # shellcheck disable=SC2068
+    find "$dir" -type f -name "$pattern" "${exclude_args[@]}" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Read package.json field safely
+_pkg_field() {
+    local pkg="$1" field="$2"
+    if [[ -f "$pkg" ]]; then
+        # Use input field as raw jq expression
+        # Replace dots in key names with bracket notation for safety
+        local jq_expr
+        # Convert .x.y-z to .x["y-z"] for keys containing hyphens or @
+        jq_expr=$(echo "$field" | sed -E 's/\.([a-zA-Z_@][a-zA-Z0-9_-]*)/.\["\1"\]/g')
+        jq -r "${jq_expr} // empty" "$pkg" 2>/dev/null || true
+    fi
+}
+
+# Generic dependency detector: checks if any dep name from a list exists in package.json
+# Args: PROJECT_DIR, DEP_NAME [DEP_NAME2...]
+# Outputs: first matching dep name or empty
+_has_dep() {
+    local pkg="$1"; shift
+    [[ ! -f "$pkg" ]] && return 1
+    for dep_name in "$@"; do
+        if jq -e --arg d "$dep_name" '(.dependencies // {} | has($d)) or (.devDependencies // {} | has($d))' "$pkg" &>/dev/null; then
+            echo "$dep_name"
+            return 0
+        fi
+    done
+    return 1
+}
+
+# ── Framework Detection ──────────────────────────────────────────────────────
+
+detect_framework() {
+    local dir="$1"
+
+    # Tauri detection: check for src-tauri/ with Cargo.toml
+    if [[ -d "$dir/src-tauri" ]] && [[ -f "$dir/src-tauri/Cargo.toml" ]]; then
+        local frontend=""
+        local pkg="$dir/package.json"
+        if [[ -f "$pkg" ]]; then
+            if _has_dep "$pkg" "vue" &>/dev/null; then
+                frontend="Vue"
+            elif _has_dep "$pkg" "react" &>/dev/null; then
+                frontend="React"
+            elif _has_dep "$pkg" "svelte" &>/dev/null; then
+                frontend="Svelte"
+            fi
+        fi
+        if [[ -n "$frontend" ]]; then
+            echo "Tauri + ${frontend}"
+        else
+            echo "Tauri"
+        fi
+        return 0
+    fi
+
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    if dep=$(_has_dep "$pkg" "next"); then
+        echo "Next.js"
+    elif dep=$(_has_dep "$pkg" "nuxt"); then
+        echo "Nuxt"
+    elif dep=$(_has_dep "$pkg" "vue"); then
+        echo "Vue"
+    elif dep=$(_has_dep "$pkg" "react"); then
+        echo "React"
+    elif dep=$(_has_dep "$pkg" "svelte"); then
+        echo "Svelte"
+    fi
+}
+
+detect_framework_version() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local framework
+    framework=$(detect_framework "$dir")
+
+    case "$framework" in
+        Vue)     _pkg_field "$pkg" ".dependencies.vue" ;;
+        React)   _pkg_field "$pkg" ".dependencies.react" ;;
+        Next.js) _pkg_field "$pkg" ".dependencies.next" ;;
+        Nuxt)    _pkg_field "$pkg" ".dependencies.nuxt" ;;
+        Svelte)  _pkg_field "$pkg" ".dependencies.svelte" ;;
+        *)       ;;
+    esac
+}
+
+# ── UI Library Detection ─────────────────────────────────────────────────────
+
+detect_ui_library() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    # Order matters: more specific first
+    if dep=$(_has_dep "$pkg" "@arco-design/web-vue" "@arco-design/web-react"); then
+        case "$dep" in @arco-design/web-vue) echo "Arco Design Vue" ;; *) echo "Arco Design React" ;; esac
+    elif dep=$(_has_dep "$pkg" "ant-design-vue"); then
+        echo "Ant Design Vue"
+    elif dep=$(_has_dep "$pkg" "antd"); then
+        echo "Ant Design"
+    elif dep=$(_has_dep "$pkg" "element-plus"); then
+        echo "Element Plus"
+    elif dep=$(_has_dep "$pkg" "@mui/material" "material-ui"); then
+        echo "Material UI"
+    elif dep=$(_has_dep "$pkg" "vuetify"); then
+        echo "Vuetify"
+    elif dep=$(_has_dep "$pkg" "primevue"); then
+        echo "PrimeVue"
+    elif dep=$(_has_dep "$pkg" "naive-ui"); then
+        echo "Naive UI"
+    elif dep=$(_has_dep "$pkg" "@chakra-ui/react"); then
+        echo "Chakra UI"
+    elif dep=$(_has_dep "$pkg" "@radix-ui/react" "@headlessui/react"); then
+        echo "Headless UI"
+    elif dep=$(_has_dep "$pkg" "tailwindcss"); then
+        echo "Tailwind CSS (utility-first)"
+    elif dep=$(_has_dep "$pkg" "vant"); then
+        echo "Vant"
+    elif dep=$(_has_dep "$pkg" "bootstrap"); then
+        echo "Bootstrap"
+    fi
+}
+
+detect_ui_library_version() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    dep=$(_has_dep "$pkg" "element-plus" "ant-design-vue" "antd" "vuetify" "primevue" "naive-ui" "@mui/material" "@chakra-ui/react" "tailwindcss" || true)
+    if [[ -n "$dep" ]]; then
+        _pkg_field "$pkg" ".dependencies.${dep}" || _pkg_field "$pkg" ".devDependencies.${dep}" || true
+    fi
+}
+
+# ── State Management Detection ───────────────────────────────────────────────
+
+detect_state_management() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    if dep=$(_has_dep "$pkg" "@reduxjs/toolkit"); then
+        echo "Redux Toolkit"
+    elif dep=$(_has_dep "$pkg" "pinia"); then
+        echo "Pinia"
+    elif dep=$(_has_dep "$pkg" "vuex"); then
+        echo "Vuex"
+    elif dep=$(_has_dep "$pkg" "redux"); then
+        echo "Redux"
+    elif dep=$(_has_dep "$pkg" "zustand"); then
+        echo "Zustand"
+    elif dep=$(_has_dep "$pkg" "mobx"); then
+        echo "MobX"
+    elif dep=$(_has_dep "$pkg" "recoil"); then
+        echo "Recoil"
+    elif dep=$(_has_dep "$pkg" "jotai"); then
+        echo "Jotai"
+    elif dep=$(_has_dep "$pkg" "effector"); then
+        echo "Effector"
+    fi
+}
+
+# ── Builder Detection ────────────────────────────────────────────────────────
+
+detect_builder() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    if dep=$(_has_dep "$pkg" "vite"); then
+        echo "Vite"
+    elif dep=$(_has_dep "$pkg" "rspack"); then
+        echo "Rspack"
+    elif dep=$(_has_dep "$pkg" "webpack"); then
+        echo "Webpack"
+    elif dep=$(_has_dep "$pkg" "next" "nuxt"); then
+        echo "${dep^} (built-in)"
+    elif dep=$(_has_dep "$pkg" "parcel"); then
+        echo "Parcel"
+    elif dep=$(_has_dep "$pkg" "esbuild"); then
+        echo "esbuild"
+    elif [[ -f "$dir/angular.json" ]]; then
+        echo "Angular CLI"
+    fi
+}
+
+# ── CSS Solution Detection ───────────────────────────────────────────────────
+
+detect_css_solution() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    if dep=$(_has_dep "$pkg" "tailwindcss"); then
+        echo "Tailwind CSS"
+    elif dep=$(_has_dep "$pkg" "sass"); then
+        echo "SCSS"
+    elif dep=$(_has_dep "$pkg" "less"); then
+        echo "Less"
+    elif dep=$(_has_dep "$pkg" "stylus"); then
+        echo "Stylus"
+    elif dep=$(_has_dep "$pkg" "unocss"); then
+        echo "UnoCSS"
+    elif dep=$(_has_dep "$pkg" "postcss"); then
+        echo "PostCSS"
+    fi
+}
+
+# ── Router Detection ─────────────────────────────────────────────────────────
+
+detect_router() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    if dep=$(_has_dep "$pkg" "vue-router"); then
+        echo "Vue Router"
+    elif dep=$(_has_dep "$pkg" "@tanstack/react-router"); then
+        echo "TanStack Router"
+    elif dep=$(_has_dep "$pkg" "react-router" "react-router-dom"); then
+        echo "React Router"
+    elif dep=$(_has_dep "$pkg" "next"); then
+        echo "Next.js App Router"
+    elif dep=$(_has_dep "$pkg" "nuxt"); then
+        echo "Nuxt Router"
+    elif dep=$(_has_dep "$pkg" "@sveltejs/kit"); then
+        echo "SvelteKit"
+    elif dep=$(_has_dep "$pkg" "svelte-spa-router"); then
+        echo "Svelte SPA Router"
+    elif dep=$(_has_dep "$pkg" "@angular/router"); then
+        echo "Angular Router"
+    fi
+}
+
+# ── HTTP Client Detection ────────────────────────────────────────────────────
+
+detect_http_client() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local dep
+    if dep=$(_has_dep "$pkg" "axios"); then
+        echo "Axios"
+    elif dep=$(_has_dep "$pkg" "ky"); then
+        echo "Ky"
+    elif dep=$(_has_dep "$pkg" "ofetch"); then
+        echo "ofetch"
+    elif dep=$(_has_dep "$pkg" "@tanstack/query"); then
+        echo "TanStack Query"
+    elif dep=$(_has_dep "$pkg" "swr"); then
+        echo "SWR"
+    fi
+}
+
+# ── Package Manager Detection ────────────────────────────────────────────────
+
+detect_package_manager() {
+    local dir="$1"
+
+    if [[ -f "$dir/pnpm-lock.yaml" ]]; then
+        echo "pnpm"
+    elif [[ -f "$dir/yarn.lock" ]]; then
+        echo "yarn"
+    elif [[ -f "$dir/package-lock.json" ]]; then
+        echo "npm"
+    elif [[ -f "$dir/bun.lockb" || -f "$dir/bun.lock" ]]; then
+        echo "bun"
+    elif [[ -f "$dir/package.json" ]]; then
+        echo "npm"
+    fi
+}
+
+# ── NPM Scripts Detection ────────────────────────────────────────────────────
+
+get_npm_script() {
+    local dir="$1" script_name="$2"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+    # Use bracket notation for script names with special chars (e.g. build:pro)
+    jq -r --arg name "$script_name" '.scripts[$name] // empty' "$pkg" 2>/dev/null || true
+}
+
+# ── Source File Scanning ─────────────────────────────────────────────────────
+
+count_source_files() {
+    local dir="$1"
+    [[ ! -d "$dir" ]] && echo "0 files" && return 0
+
+    local total=0
+    local ts_count js_count vue_count svelte_count
+    local java_count kt_count swift_count dart_count py_count
+    local go_count rs_count ets_count sh_count
+    local css_count scss_count less_count html_count
+
+    ts_count=$(_count_files "$dir" "*.ts") && ts_count=$((ts_count - $(_count_files "$dir" "*.tsx") - $(_count_files "$dir" "*.d.ts")))
+    local tsx_count=$(_count_files "$dir" "*.tsx")
+    js_count=$(_count_files "$dir" "*.js") && js_count=$((js_count - $(_count_files "$dir" "*.jsx")))
+    local jsx_count=$(_count_files "$dir" "*.jsx")
+    vue_count=$(_count_files "$dir" "*.vue")
+    svelte_count=$(_count_files "$dir" "*.svelte")
+    java_count=$(_count_files "$dir" "*.java")
+    kt_count=$(_count_files "$dir" "*.kt")
+    swift_count=$(_count_files "$dir" "*.swift")
+    dart_count=$(_count_files "$dir" "*.dart")
+    py_count=$(_count_files "$dir" "*.py")
+    go_count=$(_count_files "$dir" "*.go")
+    rs_count=$(_count_files "$dir" "*.rs")
+    sh_count=$(_count_files "$dir" "*.sh")
+    css_count=$(_count_files "$dir" "*.css")
+    scss_count=$(_count_files "$dir" "*.scss")
+    less_count=$(_count_files "$dir" "*.less")
+    html_count=$(_count_files "$dir" "*.html")
+
+    # Sum with type grouping
+    local typescript=$((ts_count + tsx_count))
+    local javascript=$((js_count + jsx_count))
+    total=$((typescript + javascript + vue_count + svelte_count + java_count + kt_count + swift_count + dart_count + py_count + go_count + rs_count + sh_count + css_count + scss_count + less_count + html_count))
+
+    if [[ "$total" -eq 0 ]]; then
+        echo "0 files"
+        return 0
+    fi
+
+    local detail=""
+    [[ "$typescript" -gt 0 ]] && detail+="TypeScript: $typescript, "
+    [[ "$javascript" -gt 0 ]] && detail+="JavaScript: $javascript, "
+    [[ "$vue_count" -gt 0 ]] && detail+="Vue: $vue_count, "
+    [[ "$svelte_count" -gt 0 ]] && detail+="Svelte: $svelte_count, "
+    [[ "$java_count" -gt 0 ]] && detail+="Java: $java_count, "
+    [[ "$py_count" -gt 0 ]] && detail+="Python: $py_count, "
+    [[ "$scss_count" -gt 0 ]] && detail+="SCSS: $scss_count, "
+    [[ "$css_count" -gt 0 ]] && detail+="CSS: $css_count, "
+    [[ "$kt_count" -gt 0 ]] && detail+="Kotlin: $kt_count, "
+    [[ "$swift_count" -gt 0 ]] && detail+="Swift: $swift_count, "
+    [[ "$go_count" -gt 0 ]] && detail+="Go: $go_count, "
+    [[ "$rs_count" -gt 0 ]] && detail+="Rust: $rs_count, "
+    [[ "$dart_count" -gt 0 ]] && detail+="Dart: $dart_count, "
+
+    # Remove trailing ", "
+    detail="${detail%, }"
+
+    echo "${total} files (${detail})"
+}
+
+# Scan project structure tree
+scan_project_structure() {
+    local dir="$1"
+    [[ ! -d "$dir" ]] && return 0
+
+    local src_dir=""
+    for candidate in "src" "lib" "app" "pkg"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            src_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$src_dir" ]] && src_dir="$dir"
+
+    local exclude_args=()
+    for d in "${ATOOL_SCAN_EXCLUDE_DIRS[@]}"; do
+        exclude_args+=(-not -path "*/${d}/*")
+    done
+    _print_tree "$src_dir" "" "$src_dir" 2 "${exclude_args[@]}"
+}
+
+_print_tree() {
+    local dir="$1" prefix="$2" base_dir="$3" max_depth="$4"
+    shift 4
+    # Remaining args are exclude predicates for find (array)
+    local -a exclude_args=("$@")
+
+    local depth=0
+    local tmp="$dir"
+    while [[ "$tmp" != "$base_dir" && "$tmp" != "/" ]]; do
+        tmp=$(dirname "$tmp")
+        depth=$((depth + 1))
+    done
+
+    if [[ "$depth" -ge "$max_depth" ]]; then
+        echo "${prefix}..."
+        return 0
+    fi
+
+    local entries
+    entries=$(ls -1A "$dir" 2>/dev/null | grep -v '^\.' | head -20 || true)
+    [[ -z "$entries" ]] && return 0
+
+    local count=0
+    local total
+    total=$(echo "$entries" | wc -l | tr -d ' ')
+
+    while IFS= read -r entry; do
+        [[ -z "$entry" ]] && continue
+        count=$((count + 1))
+
+        local is_last=false
+        [[ "$count" -eq "$total" ]] && is_last=true
+        local connector="├──"
+        $is_last && connector="└──"
+
+        local rel_path="${dir}/${entry}"
+        local entry_name="$entry"
+
+        if [[ -d "$rel_path" ]]; then
+            local file_count
+            file_count=$(find "$rel_path" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')
+            if [[ "$file_count" -gt 0 ]]; then
+                entry_name="${entry}/            (${file_count} files)"
+            else
+                entry_name="${entry}/"
+            fi
+        fi
+
+        echo "${prefix}${connector} ${entry_name}"
+
+        if [[ -d "$rel_path" ]]; then
+            local child_prefix
+            if $is_last; then
+                child_prefix="${prefix}    "
+            else
+                child_prefix="${prefix}│   "
+            fi
+            _print_tree "$rel_path" "$child_prefix" "$base_dir" "$max_depth" "${exclude_args[@]}"
+        fi
+    done <<< "$entries"
+}
+
+# Generic scanner: finds files in a directory pattern
+# Args: PROJECT_DIR, CANDIDATE_DIRS..., FILE_PATTERNS..., MAX_DEPTH
+_scan_dir_files() {
+    local dir="$1"; shift
+    local target_dir=""
+
+    # First args are candidate directory paths
+    local candidates=()
+    local max_depth=2
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --depth)
+                max_depth="$2"
+                shift 2
+                ;;
+            *)
+                candidates+=("$1")
+                shift
+                ;;
+        esac
+    done
+
+    for candidate in "${candidates[@]}"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            target_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$target_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r file_path; do
+        [[ -z "$file_path" ]] && continue
+        local rel="${file_path#$dir/}"
+        local name
+        name=$(basename "$file_path" | sed 's/\.[^.]*$//')
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$target_dir" -maxdepth "$max_depth" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -50
+}
+
+scan_components() {
+    local dir="$1"
+    local components_dir=""
+
+    for candidate in "src/components" "src/Components" "app/components" "components"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            components_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$components_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r comp_dir; do
+        [[ -z "$comp_dir" ]] && continue
+        [[ "$comp_dir" == "$components_dir" ]] && continue
+        local name
+        name=$(basename "$comp_dir")
+        local file_count
+        file_count=$(find "$comp_dir" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')
+        if [[ "$file_count" -gt 0 ]]; then
+            local rel="${comp_dir#$dir/}"
+            output+="- **${name}** (\`${rel}/\`, ${file_count} files)\n"
+        fi
+    done < <(find "$components_dir" -maxdepth 2 -type d 2>/dev/null | sort)
+
+    echo -e "$output" | head -50
+}
+
+scan_views() {
+    local dir="$1"
+    local views_dir=""
+    for candidate in "src/views" "src/pages" "src/screens" "app/pages" "pages"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            views_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$views_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r view_path; do
+        [[ -z "$view_path" ]] && continue
+        local rel="${view_path#$dir/}"
+        local name
+        name=$(basename "$view_path" | sed 's/\.[^.]*$//')
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$views_dir" -maxdepth 3 -type f \( -name "*.vue" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.ts" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -50
+}
+
+scan_stores() {
+    local dir="$1"
+    local stores_dir=""
+    for candidate in "src/store" "src/stores" "src/store/modules" "app/store" "store" "stores"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            stores_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$stores_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r store_path; do
+        [[ -z "$store_path" ]] && continue
+        local base
+        base=$(basename "$store_path")
+        [[ "$base" == "index.ts" || "$base" == "index.js" ]] && continue
+        local rel="${store_path#$dir/}"
+        local name
+        name=$(echo "$base" | sed 's/\.[^.]*$//')
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$stores_dir" -maxdepth 2 -type f \( -name "*.ts" -o -name "*.js" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -30
+}
+
+scan_api_services() {
+    local dir="$1"
+    local api_dir=""
+    for candidate in "src/api" "src/apis" "src/services" "app/api" "api" "services"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            api_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$api_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r api_path; do
+        [[ -z "$api_path" ]] && continue
+        local rel="${api_path#$dir/}"
+        local name
+        name=$(basename "$api_path" | sed 's/\.[^.]*$//')
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$api_dir" -maxdepth 2 -type f \( -name "*.ts" -o -name "*.js" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -30
+}
+
+scan_hooks() {
+    local dir="$1"
+    local hooks_dir=""
+    for candidate in "src/hooks" "src/composables" "app/hooks" "hooks" "composables"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            hooks_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$hooks_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r hook_path; do
+        [[ -z "$hook_path" ]] && continue
+        local rel="${hook_path#$dir/}"
+        local name
+        name=$(basename "$hook_path" | sed 's/\.[^.]*$//')
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$hooks_dir" -maxdepth 2 -type f \( -name "*.ts" -o -name "*.js" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -30
+}
+
+scan_utils() {
+    local dir="$1"
+    local utils_dir=""
+    for candidate in "src/utils" "src/util" "src/helpers" "src/lib" "app/utils" "utils" "helpers" "lib"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            utils_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$utils_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r util_path; do
+        [[ -z "$util_path" ]] && continue
+        local rel="${util_path#$dir/}"
+        local name
+        name=$(basename "$util_path" | sed 's/\.[^.]*$//')
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$utils_dir" -maxdepth 2 -type f \( -name "*.ts" -o -name "*.js" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -30
+}
+
+scan_routes() {
+    local dir="$1"
+    local router_file=""
+    for candidate in "src/router/index.ts" "src/router/index.js" "src/router.ts" "src/router.js" "src/routes.ts" "src/routes/index.ts"; do
+        if [[ -f "$dir/$candidate" ]]; then
+            router_file="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$router_file" ]] && return 0
+
+    local output=""
+    while IFS= read -r line; do
+        [[ -z "$line" ]] && continue
+        local path_val
+        path_val=$(echo "$line" | grep -oE "path:[[:space:]]*['\"][^'\"]+['\"]" | head -1 | sed "s/path:[[:space:]]*//;s/['\"]//g" || true)
+        if [[ -n "$path_val" ]]; then
+            local component=""
+            if echo "$line" | grep -qE "component:"; then
+                component=$(echo "$line" | grep -oE "import\(['\"][^'\"]+['\"]\)" | sed "s/import(['\"]//;s/['\"])//" | grep -oE "[^/]+$" | sed 's/\.[^.]*$//' || true)
+            fi
+            output+="| ${path_val} | ${component:-} |\n"
+        fi
+    done < "$router_file"
+
+    if [[ -n "$output" ]]; then
+        echo "| 路径 | 组件 |"
+        echo "|------|------|"
+        echo -e "$output" | head -30
+    fi
+}
+
+scan_style_files() {
+    local dir="$1"
+    local styles_dir=""
+    for candidate in "src/styles" "src/assets/styles" "src/scss" "src/css" "app/styles" "styles"; do
+        if [[ -d "$dir/$candidate" ]]; then
+            styles_dir="$dir/$candidate"
+            break
+        fi
+    done
+    [[ -z "$styles_dir" ]] && return 0
+
+    local output=""
+    while IFS= read -r style_path; do
+        [[ -z "$style_path" ]] && continue
+        local rel="${style_path#$dir/}"
+        local name
+        name=$(basename "$style_path")
+        output+="- **${name}** (\`${rel}\`)\n"
+    done < <(find "$styles_dir" -maxdepth 2 -type f \( -name "*.css" -o -name "*.scss" -o -name "*.less" -o -name "*.sass" \) 2>/dev/null | sort)
+
+    echo -e "$output" | head -20
+}
+
+# ── UI Theme Info ────────────────────────────────────────────────────────────
+
+detect_ui_theme_info() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    [[ ! -f "$pkg" ]] && return 0
+
+    local output=""
+
+    if _has_dep "$pkg" "element-plus" &>/dev/null; then
+        output+="### Element Plus 主题\n\n"
+        local ver
+        ver=$(_pkg_field "$pkg" ".dependencies.element-plus")
+        output+="**版本**: ${ver:-未知}\n\n"
+
+        local theme_files=""
+        for f in "src/styles/element-override.scss" "src/styles/element-variables.scss" "src/styles/element/index.scss"; do
+            if [[ -f "$dir/$f" ]]; then
+                theme_files+="- ${f}\n"
+            fi
+        done
+
+        if [[ -n "$theme_files" ]]; then
+            output+="**主题覆盖文件**:\n${theme_files}\n"
+        fi
+
+        local var_file
+        var_file=$(find_first "$dir/src" "variables.scss" 2>/dev/null || true)
+        if [[ -n "$var_file" ]]; then
+            local var_count
+            var_count=$(grep -cE '\-\-el-' "$var_file" 2>/dev/null || echo "0")
+            output+="**CSS 变量定义**: \`${var_file##*/}\` (${var_count} 个 Element Plus 变量)\n"
+        fi
+    fi
+
+    if _has_dep "$pkg" "tailwindcss" &>/dev/null; then
+        output+="### Tailwind CSS 配置\n\n"
+        local ver
+        ver=$(_pkg_field "$pkg" ".devDependencies.tailwindcss" 2>/dev/null || _pkg_field "$pkg" ".dependencies.tailwindcss" 2>/dev/null || true)
+        output+="**版本**: ${ver:-未知}\n\n"
+        for f in "tailwind.config.js" "tailwind.config.ts" "tailwind.config.cjs"; do
+            if [[ -f "$dir/$f" ]]; then
+                output+="**配置文件**: \`${f}\`\n"
+            fi
+        done
+    fi
+
+    echo -e "$output"
+}
+
+# ── Dev Conventions Inference ────────────────────────────────────────────────
+
+infer_dev_conventions() {
+    local dir="$1"
+    local pkg="$dir/package.json"
+    local output=""
+
+    if [[ -f "$dir/tsconfig.json" ]]; then
+        local strict=""
+        if grep -q '"strict": true' "$dir/tsconfig.json" 2>/dev/null; then
+            strict=" (strict mode)"
+        fi
+        output+="- **TypeScript**: 项目使用 TypeScript${strict}\n"
+    fi
+
+    if [[ -f "$dir/.eslintrc.js" || -f "$dir/.eslintrc.json" || -f "$dir/.eslintrc.cjs" || -f "$dir/eslint.config.js" || -f "$dir/eslint.config.ts" ]]; then
+        output+="- **ESLint**: 已配置代码检查\n"
+    fi
+
+    if [[ -f "$dir/.prettierrc" || -f "$dir/.prettierrc.js" || -f "$dir/.prettierrc.json" || -f "$dir/prettier.config.js" ]]; then
+        output+="- **Prettier**: 已配置代码格式化\n"
+    fi
+
+    if [[ -f "$dir/.husky/pre-commit" || -d "$dir/.husky" ]]; then
+        output+="- **Git Hooks**: 使用 Husky 管理 Git hooks\n"
+    fi
+
+    if [[ -f "$dir/commitlint.config.js" || -f "$dir/.commitlintrc.js" || -f "$dir/.commitlintrc.json" ]]; then
+        output+="- **Commitlint**: 已配置提交信息规范\n"
+    fi
+
+    if [[ -f "$pkg" ]] && _has_dep "$pkg" "vitest" &>/dev/null; then
+        output+="- **测试**: 使用 Vitest\n"
+    elif [[ -f "$pkg" ]] && _has_dep "$pkg" "jest" &>/dev/null; then
+        output+="- **测试**: 使用 Jest\n"
+    fi
+
+    if [[ -f "$pkg" ]] && _has_dep "$pkg" "unplugin-auto-import" "unplugin-vue-components" &>/dev/null; then
+        output+="- **自动导入**: 使用 unplugin 实现组件/API 自动导入\n"
+    fi
+
+    echo -e "$output"
+}
+
+# ── Java / Spring Detection ──────────────────────────────────────────────────
+
+# Detect Java build tool
+detect_java_build_tool() {
+    local dir="$1"
+    if [[ -f "$dir/build.gradle.kts" ]]; then
+        echo "Gradle (Kotlin DSL)"
+    elif [[ -f "$dir/build.gradle" ]]; then
+        echo "Gradle (Groovy DSL)"
+    elif [[ -f "$dir/pom.xml" ]]; then
+        echo "Maven"
+    fi
+}
+
+# Detect Java version from pom.xml or build.gradle
+# Uses cross-platform grep; no grep -P (not available on macOS)
+detect_java_version() {
+    local dir="$1"
+    if [[ -f "$dir/pom.xml" ]]; then
+        # Check <java.version> property
+        local ver
+        ver=$(grep '<java.version>' "$dir/pom.xml" 2>/dev/null | head -1 | sed 's/.*<java.version>//;s/<\/java.version>.*//' || true)
+        if [[ -n "$ver" ]]; then
+            echo "$ver"
+            return 0
+        fi
+        # Check maven-compiler-plugin <source>
+        ver=$(grep '<source>' "$dir/pom.xml" 2>/dev/null | head -1 | sed 's/.*<source>//;s/<\/source>.*//' || true)
+        if [[ -n "$ver" ]]; then
+            echo "$ver"
+            return 0
+        fi
+    fi
+    if [[ -f "$dir/build.gradle.kts" ]] || [[ -f "$dir/build.gradle" ]]; then
+        local gradle_file="$dir/build.gradle"
+        [[ -f "$dir/build.gradle.kts" ]] && gradle_file="$dir/build.gradle.kts"
+        local ver
+        ver=$(grep 'sourceCompatibility' "$gradle_file" 2>/dev/null | head -1 | sed 's/.*sourceCompatibility[[:space:]]*=[[:space:]]*//;s/[^0-9.]//g' || true)
+        if [[ -n "$ver" ]]; then
+            echo "$ver"
+            return 0
+        fi
+    fi
+}
+
+# Detect base package path from pom.xml groupId or first .java package declaration
+detect_java_package() {
+    local dir="$1"
+    # First try: from pom.xml groupId (skip framework groupIds)
+    if [[ -f "$dir/pom.xml" ]]; then
+        local gid
+        gid=$(grep '<groupId>' "$dir/pom.xml" 2>/dev/null | head -1 | sed 's/.*<groupId>//;s/<\/groupId>.*//' | tr -d '[:space:]' || true)
+        # Skip common parent/framework groupIds
+        if [[ -n "$gid" ]]; then
+            case "$gid" in
+                org.springframework*|org.apache*|com.alibaba*)
+                    # Framework groupId, skip and try next
+                    ;;
+                *)
+                    echo "$gid" | tr '.' '/'
+                    return 0
+                    ;;
+            esac
+        fi
+    fi
+    # Second try: from first .java file's package declaration
+    local first_java
+    first_java=$(find "$dir/src/main/java" -name "*.java" -type f 2>/dev/null | head -1 || true)
+    if [[ -n "$first_java" ]]; then
+        local pkg
+        pkg=$(grep '^package ' "$first_java" 2>/dev/null | head -1 | sed 's/package //;s/;//' || true)
+        if [[ -n "$pkg" ]]; then
+            echo "$pkg" | tr '.' '/'
+            return 0
+        fi
+    fi
+}
+
+# Detect Spring Boot/Cloud features from pom.xml and config files
+detect_spring_features() {
+    local dir="$1"
+    local features=""
+
+    if [[ -f "$dir/pom.xml" ]]; then
+        grep -q "spring-boot" "$dir/pom.xml" 2>/dev/null && features+="Spring Boot, "
+        grep -q "spring-cloud-starter" "$dir/pom.xml" 2>/dev/null && features+="Spring Cloud, "
+        grep -q "nacos" "$dir/pom.xml" 2>/dev/null && features+="Nacos, "
+        grep -q "sentinel" "$dir/pom.xml" 2>/dev/null && features+="Sentinel, "
+        grep -q "spring-cloud-gateway" "$dir/pom.xml" 2>/dev/null && features+="Gateway, "
+        grep -q "openfeign" "$dir/pom.xml" 2>/dev/null && features+="OpenFeign, "
+        grep -q "spring-cloud-stream" "$dir/pom.xml" 2>/dev/null && features+="Cloud Stream, "
+        grep -q "spring-cloud-sleuth" "$dir/pom.xml" 2>/dev/null && features+="Sleuth, "
+        grep -q "spring-security" "$dir/pom.xml" 2>/dev/null && features+="Spring Security, "
+    fi
+
+    # Also check YAML config for Spring Cloud indicators
+    local yml_files=("$dir/src/main/resources/application.yml" "$dir/src/main/resources/application.yaml" "$dir/src/main/resources/bootstrap.yml")
+    for yml in "${yml_files[@]}"; do
+        if [[ -f "$yml" ]]; then
+            grep -q "nacos" "$yml" 2>/dev/null && features+="Nacos-Config, "
+            grep -q "sentinel" "$yml" 2>/dev/null && features+="Sentinel-Config, "
+        fi
+    done
+
+    # Remove trailing ", "
+    features="${features%, }"
+    echo "$features"
+}
+
+# Detect ORM framework from pom.xml
+detect_java_orm() {
+    local dir="$1"
+    if [[ -f "$dir/pom.xml" ]]; then
+        if grep -q "mybatis-plus" "$dir/pom.xml" 2>/dev/null; then echo "MyBatis-Plus"; return 0; fi
+        if grep -q "mybatis-spring-boot" "$dir/pom.xml" 2>/dev/null; then echo "MyBatis"; return 0; fi
+        if grep -q "spring-boot-starter-data-jpa" "$dir/pom.xml" 2>/dev/null || grep -q "spring-data-jpa" "$dir/pom.xml" 2>/dev/null; then echo "Spring Data JPA"; return 0; fi
+        if grep -q "spring-boot-starter-jdbc" "$dir/pom.xml" 2>/dev/null; then echo "Spring JDBC"; return 0; fi
+    fi
+}
+
+# Parse Maven modules from root pom.xml <modules> section
+detect_maven_modules() {
+    local dir="$1"
+    if [[ ! -f "$dir/pom.xml" ]]; then return 0; fi
+
+    # Extract module names using grep + sed (cross-platform, no grep -P)
+    # Note: tr -d '[:space:]' is NOT used here because it would join all lines into one string
+    grep '<module>' "$dir/pom.xml" 2>/dev/null | sed 's/.*<module>//;s/<\/module>.*//' | while IFS= read -r mod; do
+        # Trim leading/trailing whitespace only (not internal)
+        mod=$(echo "$mod" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        [[ -n "$mod" ]] && echo "$mod"
+    done
+}
+
+# Scan Java source directory tree (3 levels deep)
+scan_java_structure() {
+    local dir="$1"
+    local pkg_path
+    pkg_path=$(detect_java_package "$dir")
+
+    local src_base="$dir/src/main/java"
+    if [[ -n "$pkg_path" ]] && [[ -d "$dir/src/main/java/$pkg_path" ]]; then
+        src_base="$dir/src/main/java/$pkg_path"
+    fi
+
+    [[ ! -d "$src_base" ]] && return 0
+
+    local exclude_args=()
+    for d in "${ATOOL_SCAN_EXCLUDE_DIRS[@]}"; do
+        exclude_args+=(-not -path "*/${d}/*")
+    done
+    # shellcheck disable=SC2068
+    _print_tree "$src_base" "" "$src_base" 3 "${exclude_args[@]}"
+}
+
+# Count Java source files by category
+count_java_sources() {
+    local dir="$1"
+    local controllers services service_impls repositories mappers configs total
+
+    controllers=$(_count_files "$dir" "*Controller.java")
+    services=$(_count_files "$dir" "*Service.java")
+    service_impls=$(_count_files "$dir" "*ServiceImpl.java")
+    repositories=$(_count_files "$dir" "*Repository.java")
+    mappers=$(_count_files "$dir" "*Mapper.java")
+    configs=$(_count_files "$dir" "*Config.java")
+    total=$(_count_files "$dir" "*.java")
+
+    # Ensure all values are valid integers
+    controllers=${controllers:-0} ; services=${services:-0} ; service_impls=${service_impls:-0}
+    repositories=${repositories:-0} ; mappers=${mappers:-0} ; configs=${configs:-0}
+    total=${total:-0}
+
+    local rep_map=$((repositories + mappers))
+    echo "${total} files (Controller: ${controllers}, Service: ${services}, ServiceImpl: ${service_impls}, Repository/Mapper: ${rep_map}, Config: ${configs})"
+}
+
+# Scan Spring REST controllers and extract API endpoint summary
+scan_java_controllers() {
+    local dir="$1"
+    local output=""
+
+    while IFS= read -r ctrl_file; do
+        [[ -z "$ctrl_file" ]] && continue
+        local name
+        name=$(basename "$ctrl_file" .java)
+        local rel="${ctrl_file#$dir/}"
+        local base_path
+        base_path=$(grep '@RequestMapping' "$ctrl_file" 2>/dev/null | head -1 | grep -oE '"[^"]+"' | tr -d '"' || echo "")
+        local method_count
+        method_count=$(grep -cE '@(Get|Post|Put|Delete|Patch)Mapping' "$ctrl_file" 2>/dev/null || echo "0")
+        output+="- **${name}** (\`${rel}\`, base: \`${base_path}\`, ${method_count} endpoints)\n"
+    done < <(find "$dir" -name "*Controller.java" -type f -not -path "*/target/*" -not -path "*/build/*" 2>/dev/null | sort | head -30)
+
+    echo -e "$output"
+}
+
+# Scan Spring application config files for key properties
+scan_spring_config() {
+    local dir="$1"
+    local output=""
+
+    for f in "src/main/resources/application.yml" "src/main/resources/application.yaml" "src/main/resources/application.properties" "src/main/resources/bootstrap.yml"; do
+        if [[ -f "$dir/$f" ]]; then
+            output+="- **${f}**\n"
+            # Extract port
+            local port
+            port=$(grep -E '^\s*port:' "$dir/$f" 2>/dev/null | head -1 | grep -oE '[0-9]+' || true)
+            if [[ -n "$port" ]]; then
+                output+="  - server.port: ${port}\n"
+            fi
+            # Extract application name
+            local app_name
+            app_name=$(grep -E '^\s*name:' "$dir/$f" 2>/dev/null | head -1 | sed 's/.*name:[[:space:]]*//' | tr -d ' ' || true)
+            if [[ -n "$app_name" ]]; then
+                output+="  - spring.application.name: ${app_name}\n"
+            fi
+        fi
+    done
+
+    echo -e "$output"
+}
+
+# Generate Java quick start commands (Maven/Gradle)
+detect_java_quick_start() {
+    local dir="$1"
+    local output=""
+
+    if [[ -f "$dir/pom.xml" ]]; then
+        if [[ -f "$dir/mvnw" ]]; then
+            output+="# 构建\n./mvnw clean package -DskipTests\n\n"
+            output+="# 运行\n./mvnw spring-boot:run\n\n"
+            output+="# 测试\n./mvnw test\n"
+        else
+            output+="# 构建\nmvn clean package -DskipTests\n\n"
+            output+="# 运行\nmvn spring-boot:run\n\n"
+            output+="# 测试\nmvn test\n"
+        fi
+    elif [[ -f "$dir/build.gradle" ]] || [[ -f "$dir/build.gradle.kts" ]]; then
+        if [[ -f "$dir/gradlew" ]]; then
+            output+="# 构建\n./gradlew build -x test\n\n"
+            output+="# 运行\n./gradlew bootRun\n\n"
+            output+="# 测试\n./gradlew test\n"
+        else
+            output+="# 构建\ngradle build -x test\n\n"
+            output+="# 运行\ngradle bootRun\n\n"
+            output+="# 测试\ngradle test\n"
+        fi
+    fi
+
+    echo -e "$output"
+}
+
+# Count Java test files and compute rough coverage ratio
+count_java_test_coverage() {
+    local dir="$1"
+    local test_count src_count
+
+    test_count=$(_count_files "$dir/src/test" "*.java" 2>/dev/null || true)
+    src_count=$(_count_files "$dir/src/main" "*.java" 2>/dev/null || true)
+
+    # Ensure valid integers (handle empty or multi-line output)
+    test_count=$(echo "$test_count" | head -1 | tr -cd '0-9')
+    src_count=$(echo "$src_count" | head -1 | tr -cd '0-9')
+    test_count=${test_count:-0}
+    src_count=${src_count:-0}
+
+    if [[ "$src_count" -eq 0 ]]; then
+        echo "0 test files / 0 source files"
+        return 0
+    fi
+
+    # Compute percentage (integer arithmetic)
+    local pct=$((test_count * 100 / src_count))
+    echo "${test_count} test files / ${src_count} source files (${pct}% ratio)"
+}
+
+# ── Master Orchestration ─────────────────────────────────────────────────────
+
+extract_source_metadata() {
+    local dir="$1"
+
+    # Detect project type
+    local is_java=false
+    if [[ -f "$dir/pom.xml" ]] || [[ -f "$dir/build.gradle" ]] || [[ -f "$dir/build.gradle.kts" ]]; then
+        is_java=true
+    fi
+    local is_node=false
+    if [[ -f "$dir/package.json" ]]; then
+        is_node=true
+    fi
+
+    # Multi-line values — write to temp files
+    local tmpdir="${ATOOL_ANALYSIS_TMPDIR:-$(mktemp -d)}"
+    mkdir -p "$tmpdir"
+
+    # ── Node.js metadata (existing) ──
+    if $is_node; then
+        echo "FRAMEWORK_NAME=$(detect_framework "$dir")"
+        echo "FRAMEWORK_VERSION=$(detect_framework_version "$dir")"
+        echo "UI_LIBRARY=$(detect_ui_library "$dir")"
+        echo "UI_LIBRARY_VERSION=$(detect_ui_library_version "$dir")"
+        echo "STATE_MANAGEMENT=$(detect_state_management "$dir")"
+        echo "BUILDER=$(detect_builder "$dir")"
+        echo "CSS_SOLUTION=$(detect_css_solution "$dir")"
+        echo "ROUTER=$(detect_router "$dir")"
+        echo "HTTP_CLIENT=$(detect_http_client "$dir")"
+        echo "PACKAGE_MANAGER=$(detect_package_manager "$dir")"
+
+        # NPM scripts
+        echo "SCRIPT_DEV=$(get_npm_script "$dir" "dev")"
+        echo "SCRIPT_BUILD=$(get_npm_script "$dir" "build")"
+        echo "SCRIPT_BUILD_PRO=$(get_npm_script "$dir" "build:pro")"
+        echo "SCRIPT_BUILD_DEV=$(get_npm_script "$dir" "build:dev")"
+        echo "SCRIPT_TEST=$(get_npm_script "$dir" "test")"
+        echo "SCRIPT_LINT=$(get_npm_script "$dir" "lint")"
+        echo "SCRIPT_PREVIEW=$(get_npm_script "$dir" "preview")"
+
+        scan_project_structure "$dir" > "$tmpdir/project_structure.txt"
+        echo "PROJECT_STRUCTURE=__BLOCK__:$tmpdir/project_structure.txt"
+
+        scan_components "$dir" > "$tmpdir/component_list.txt"
+        echo "COMPONENT_LIST=__BLOCK__:$tmpdir/component_list.txt"
+
+        scan_views "$dir" > "$tmpdir/view_list.txt"
+        echo "VIEW_LIST=__BLOCK__:$tmpdir/view_list.txt"
+
+        scan_stores "$dir" > "$tmpdir/store_list.txt"
+        echo "STORE_LIST=__BLOCK__:$tmpdir/store_list.txt"
+
+        scan_api_services "$dir" > "$tmpdir/api_list.txt"
+        echo "API_LIST=__BLOCK__:$tmpdir/api_list.txt"
+
+        scan_hooks "$dir" > "$tmpdir/hook_list.txt"
+        echo "HOOK_LIST=__BLOCK__:$tmpdir/hook_list.txt"
+
+        scan_utils "$dir" > "$tmpdir/util_list.txt"
+        echo "UTIL_LIST=__BLOCK__:$tmpdir/util_list.txt"
+
+        scan_routes "$dir" > "$tmpdir/route_table.txt"
+        echo "ROUTE_TABLE=__BLOCK__:$tmpdir/route_table.txt"
+
+        scan_style_files "$dir" > "$tmpdir/style_files.txt"
+        echo "STYLE_FILES=__BLOCK__:$tmpdir/style_files.txt"
+
+        detect_ui_theme_info "$dir" > "$tmpdir/ui_theme_info.txt"
+        echo "UI_THEME_INFO=__BLOCK__:$tmpdir/ui_theme_info.txt"
+
+        infer_dev_conventions "$dir" > "$tmpdir/dev_conventions.txt"
+        echo "DEV_CONVENTIONS=__BLOCK__:$tmpdir/dev_conventions.txt"
+
+        _generate_quick_start "$dir" > "$tmpdir/quick_start.txt"
+        echo "QUICK_START=__BLOCK__:$tmpdir/quick_start.txt"
+    fi
+
+    # ── Java metadata (new) ──
+    if $is_java; then
+        echo "JAVA_BUILD_TOOL=$(detect_java_build_tool "$dir")"
+        echo "JAVA_VERSION=$(detect_java_version "$dir")"
+        echo "JAVA_PACKAGE=$(detect_java_package "$dir")"
+        echo "SPRING_FEATURES=$(detect_spring_features "$dir")"
+        echo "JAVA_ORM=$(detect_java_orm "$dir")"
+        echo "JAVA_SOURCE_COUNT=$(count_java_sources "$dir")"
+        echo "JAVA_TEST_COVERAGE=$(count_java_test_coverage "$dir")"
+
+        detect_maven_modules "$dir" > "$tmpdir/maven_modules.txt"
+        echo "MAVEN_MODULES=__BLOCK__:$tmpdir/maven_modules.txt"
+
+        scan_java_structure "$dir" > "$tmpdir/java_structure.txt"
+        echo "JAVA_STRUCTURE=__BLOCK__:$tmpdir/java_structure.txt"
+
+        scan_java_controllers "$dir" > "$tmpdir/java_controllers.txt"
+        echo "JAVA_CONTROLLERS=__BLOCK__:$tmpdir/java_controllers.txt"
+
+        scan_spring_config "$dir" > "$tmpdir/spring_config.txt"
+        echo "SPRING_CONFIG=__BLOCK__:$tmpdir/spring_config.txt"
+
+        detect_java_quick_start "$dir" > "$tmpdir/java_quick_start.txt"
+        echo "JAVA_QUICK_START=__BLOCK__:$tmpdir/java_quick_start.txt"
+    fi
+
+    # ── Common metadata ──
+    echo "SOURCE_FILE_COUNT=$(count_source_files "$dir")"
+}
+
+_generate_quick_start() {
+    local dir="$1"
+    local pkg_mgr
+    pkg_mgr=$(detect_package_manager "$dir")
+    [[ -z "$pkg_mgr" ]] && pkg_mgr="npm"
+
+    local output=""
+
+    case "$pkg_mgr" in
+        pnpm) output+="pnpm install\n" ;;
+        yarn) output+="yarn install\n" ;;
+        bun)  output+="bun install\n" ;;
+        *)    output+="npm install\n" ;;
+    esac
+
+    local dev_script
+    dev_script=$(get_npm_script "$dir" "dev")
+    if [[ -n "$dev_script" ]]; then
+        output+="\n# 开发模式\n"
+        case "$pkg_mgr" in
+            pnpm) output+="pnpm dev\n" ;;
+            yarn) output+="yarn dev\n" ;;
+            bun)  output+="bun run dev\n" ;;
+            *)    output+="npm run dev\n" ;;
+        esac
+    fi
+
+    local build_script
+    build_script=$(get_npm_script "$dir" "build:pro")
+    if [[ -n "$build_script" ]]; then
+        output+="\n# 构建 (生产环境)\n"
+        case "$pkg_mgr" in
+            pnpm) output+="pnpm build:pro\n" ;;
+            yarn) output+="yarn build:pro\n" ;;
+            bun)  output+="bun run build:pro\n" ;;
+            *)    output+="npm run build:pro\n" ;;
+        esac
+    else
+        build_script=$(get_npm_script "$dir" "build")
+        if [[ -n "$build_script" ]]; then
+            output+="\n# 构建\n"
+            case "$pkg_mgr" in
+                pnpm) output+="pnpm build\n" ;;
+                yarn) output+="yarn build\n" ;;
+                bun)  output+="bun run build\n" ;;
+                *)    output+="npm run build\n" ;;
+            esac
+        fi
+    fi
+
+    local test_script
+    test_script=$(get_npm_script "$dir" "test")
+    if [[ -n "$test_script" ]]; then
+        output+="\n# 测试\n"
+        case "$pkg_mgr" in
+            pnpm) output+="pnpm test\n" ;;
+            yarn) output+="yarn test\n" ;;
+            bun)  output+="bun run test\n" ;;
+            *)    output+="npm run test\n" ;;
+        esac
+    fi
+
+    echo -e "$output"
+}