<!-- Generated by codeindex at 2026-02-10T19:35:35+08:00 -->

# README_AI.md - codeindex

## Overview

- **Files**: 42
- **Symbols**: 320+
- **Subdirectories**: 2

## Subdirectories

- **extractors/** - Framework-specific route extractors.
- **parsers/** - Java language parser module.

## Files

- __init__.py
- **adaptive_config.py** - AdaptiveSymbolsConfig
- **adaptive_selector.py** - AdaptiveSymbolSelector
- **ai_helper.py** - aggregate_parse_results
- **cli.py** - main
- cli_common.py
- **cli_config.py** - init (with interactive wizard), status, list_dirs
- **cli_config_commands.py** - config command group, explain command
- **cli_docs.py** - docs, show_ai_guide
- **cli_hooks.py** - HookStatus, HookManager, generate_hook_script
- **cli_parse.py** - parse
- **cli_scan.py** - _process_directory_with_smartwriter, scan, scan_all
- **cli_symbols.py** - extract_module_purpose, index, symbols
- **cli_tech_debt.py** - _find_source_files, _analyze_files, _format_and_output
- **config.py** - SymbolsConfig, GroupingConfig, SemanticConfig
- **config_help.py** - CONFIG_PARAMS, show_full_config_help, explain_parameter, get_current_config_value
- **directory_tree.py** - DirectoryNode, DirectoryTree, walk_directory
- **docstring_processor.py** - DocstringProcessor
- **errors.py** - ErrorCode, ErrorInfo, create_error_response
- __init__.py
- **spring.py** - SpringRouteExtractor
- **thinkphp.py** - ThinkPHPRouteExtractor
- **file_classifier.py** - FileSizeCategory, FileSizeAnalysis, FileSizeClassifier
- **framework_detect.py** - RouteInfo, ModelInfo, FrameworkInfo
- **hierarchical.py** - DirectoryInfo, build_directory_hierarchy, create_processing_batches
- **incremental.py** - UpdateLevel, FileChange, ChangeAnalysis
- **init_wizard.py** - WizardResult, detect_languages, detect_frameworks, infer_include_patterns, infer_exclude_patterns, calculate_parallel_workers, calculate_batch_size, count_files, run_interactive_wizard, generate_config_yaml, create_codeindex_md
- **invoker.py** - InvokeResult, clean_ai_output, validate_markdown_output
- **parallel.py** - BatchResult, parse_files_parallel, scan_directories_parallel
- **parser.py** - CallType, Call, Symbol, Import, Inheritance, ParseResult, JAVA_LANG_CLASSES, build_alias_map, resolve_alias, _extract_python_calls_from_tree, _extract_decorator_calls, _extract_python_calls, _parse_python_call, _determine_python_call_type, _extract_call_name, _is_simple_decorator, _extract_decorator_name, _count_arguments, _extract_package_namespace, _strip_generic_type, _resolve_java_type, _build_java_import_map, _extract_java_inheritances, _extract_type_from_node, _get_parser, _get_node_text, parse_file, _build_java_static_import_map, _resolve_java_static_import, _parse_java_method_call, _parse_java_constructor_call, _extract_java_calls, _extract_java_calls_from_tree, _extract_php_calls_from_tree, _extract_php_calls, _parse_php_function_call, _parse_php_member_call, _parse_php_scoped_call, _parse_php_object_creation
- __init__.py
- **java_parser.py** - is_java_file, get_java_parser, parse_java_file
- **route_extractor.py** - ExtractionContext, RouteExtractor
- **route_registry.py** - RouteExtractorRegistry
- **scanner.py** - ScanResult, get_language_extensions, should_exclude
- **semantic_extractor.py** - DirectoryContext, BusinessSemantic, SimpleDescriptionGenerator
- **smart_writer.py** - WriteResult, SmartWriter, determine_level
- **symbol_index.py** - SymbolEntry, GlobalSymbolIndex
- **symbol_scorer.py** - ScoringContext, SymbolImportanceScorer
- **tech_debt.py** - DebtSeverity, DebtIssue, DebtAnalysisResult
- **tech_debt_formatters.py** - ReportFormatter, ConsoleFormatter, MarkdownFormatter
- **writer.py** - WriteResult, format_symbols_for_prompt, format_imports_for_prompt

---

## Key Components

### Interactive Setup Wizard (NEW)

**File**: `init_wizard.py`

**Purpose**: Intelligent, interactive setup wizard for `codeindex init` command (Epic 15 Story 15.1)

**Core Features**:
- Auto-detects project languages (Python, PHP, Java - fully supported with parsers)
- Infers include/exclude patterns from project structure
- Auto-tunes performance settings (parallel_workers, batch_size)
- Configures AI CLI integration and Git Hooks
- Generates CODEINDEX.md guide for AI agents
- Supports both interactive and non-interactive (`--yes`) modes

**Language Support**:
- **Fully supported (with parser)**: Python, PHP, Java
- **Planned support**: JavaScript, TypeScript, Go, Rust, Ruby (detection only, parser implementation pending)

**Key Functions**:
- `detect_languages()` - Scans file extensions to identify programming languages
- `detect_frameworks()` - Identifies web frameworks (Spring, ThinkPHP, Laravel, etc.)
- `infer_include_patterns()` - Suggests source directories to scan
- `infer_exclude_patterns()` - Suggests directories to exclude (node_modules, __pycache__, etc.)
- `calculate_parallel_workers()` - Auto-tunes based on project size and CPU count
- `calculate_batch_size()` - Optimizes batch processing size
- `run_interactive_wizard()` - 5-step interactive setup flow
- `generate_config_yaml()` - Creates .codeindex.yaml from wizard results
- `create_codeindex_md()` - Generates AI agent integration guide

**Design Philosophy**:
- Smart defaults requiring zero manual input
- Complete setup in under 1 minute
- Support both interactive and CI/CD-friendly non-interactive modes

### Enhanced CLI Configuration

**File**: `cli_config.py`

**New Features**:
- `init` command now runs interactive wizard by default
- `--help-config` flag to show complete configuration reference
- `--yes` flag for non-interactive mode (CI/CD friendly)
- `--quiet` flag for minimal output
- `--force` flag to overwrite existing config
- Automatic Git Hooks installation (if enabled)
- CODEINDEX.md generation for AI agents

**Behavior**:
- Interactive mode: 5-step wizard with smart defaults
- Non-interactive mode: Auto-detect everything, use conservative defaults
- Post-setup: Provides clear next steps for users

### Enhanced Help System (NEW - Epic 15 Story 15.3)

**Files**: `config_help.py`, `cli_config_commands.py`

**Purpose**: Comprehensive configuration documentation and parameter explanation system

**Core Features**:

**config_help.py**:
- `CONFIG_PARAMS` dictionary with complete parameter documentation
- `show_full_config_help()` - Display full configuration reference with all parameters
- `explain_parameter()` - Explain individual configuration parameters with context
- `get_current_config_value()` - Retrieve current value from .codeindex.yaml

**Language Parameter Documentation**:
- **Supported Languages**: Python, PHP, Java (fully supported with parsers)
- **Description**: "Programming languages to index"
- **Example Configuration**:
  ```yaml
  languages:
    - python
    - php
    - java
  ```
- Note: Only Python, PHP, and Java have full parser support currently

**cli_config_commands.py**:
- `config` command group for configuration-related operations
- `config explain <parameter>` - Interactive parameter explanation
- Context-aware help showing current values and system-specific recommendations

**Documentation Coverage**:
- Performance settings (parallel_workers, batch_size)
- AI integration (ai_command)
- Project structure (languages, include, exclude)
- Git Hooks (hooks.post_commit.enabled, hooks.post_commit.mode)
- Output settings (output_file)

**Each Parameter Includes**:
- Description and purpose
- Type and default value
- Valid ranges/options
- Performance recommendations
- Trade-offs and considerations
- Current value (if config exists)
- System-specific validation (e.g., CPU count checks)
- YAML examples

**Usage Examples**:
```bash
# Show full configuration reference
codeindex init --help-config

# Explain specific parameters
codeindex config explain parallel_workers
codeindex config explain hooks.post_commit.mode
codeindex config explain languages
```

**Design Philosophy**:
- Context-aware help (shows current values)
- System-aware validation (warns about CPU count mismatches)
- Progressive disclosure (brief help → detailed explanation)
- Examples-driven documentation
- Clear language support indication (parser availability)

### CLI Entry Point

**File**: `cli.py`

**Purpose**: Main CLI entry point with command registration

**New Commands**:
- `config` - Configuration help and explanation command group (Epic 15 Story 15.3)

**Command Registration**:
- All CLI commands are registered through the `main` group
- New `config` command group added alongside existing commands (scan, init, status, hooks, etc.)

---

## Recent Changes

**Language Support Clarification**:
- **Supported Languages**: Documentation now correctly reflects that only Python, PHP, and Java have full parser support
- `config_help.py`: Updated language parameter to show "python, php, java (fully supported with parsers)"
- `init_wizard.py`: Commented out detection patterns for languages without parser support (JavaScript, TypeScript, Go, Rust, Ruby) with note "detection only, no parser yet"

**Implementation Details**:
- Detection logic preserved for future language support expansion
- Clear distinction between "fully supported" (with parser) and "planned support" (detection only)
- YAML examples updated to show Python, PHP, and Java configuration
