<!-- Generated by codeindex at 2026-02-13T01:21:11+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, _print_post_init_message
- **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, PARSER_PACKAGES, CLAUDE_MD_MARKER_START, CLAUDE_MD_MARKER_END, CLAUDE_MD_SECTION, check_parser_installed, get_parser_install_guidance, detect_languages, detect_frameworks, infer_include_patterns, infer_exclude_patterns, calculate_parallel_workers, calculate_batch_size, count_files, inject_claude_md, has_claude_md_injection, 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, is_pass_through, 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


**Improved Init Setup Flow (CLAUDE.md Injection & Post-Init Message)**:
- **init_wizard.py**: `CLAUDE_MD_SECTION` template updated with structured first-time setup and daily usage sections — includes steps to review `.codeindex.yaml`, run `codeindex scan-all`, and optionally install post-commit hooks; removed "Full command reference: see CODEINDEX.md" line
- **cli_config.py**: `_print_post_init_message()` revised to a 3-step flow: (1) Review `.codeindex.yaml` to verify include/exclude patterns, (2) Run `codeindex scan-all` to generate documentation indexes, (3) Run `codeindex status` to check coverage; removed separate AI-enhanced documentation section

**CLAUDE.md Injection Feature**:
- **init_wizard.py**: `CLAUDE_MD_MARKER_START`, `CLAUDE_MD_MARKER_END` constants and `CLAUDE_MD_SECTION` template for marker-based idempotent injection
- **init_wizard.py**: `inject_claude_md()` function — creates CLAUDE.md if missing, prepends section if no markers found, replaces between markers if already injected
- **init_wizard.py**: `has_claude_md_injection()` helper to check for existing injection
- **init_wizard.py**: `WizardResult` gains `inject_claude_md` (default `True`) and `claude_md_injected` fields
- **init_wizard.py**: Interactive wizard expanded from 5 to 6 steps — new Step 5/6 asks "Inject codeindex instructions into CLAUDE.md?"
- **cli_config.py**: Non-interactive mode (`--yes`) always calls `inject_claude_md()` as safe default
- **cli_config.py**: Interactive mode calls `inject_claude_md()` when `result.inject_claude_md` is True
- **cli_config.py**: Both paths report injection in console output (`✓ Injected: CLAUDE.md`)

**Post-Commit Hook Auto-Update & Auto-Commit (Epic 19 Story 19.3)**:
- **cli_hooks.py**: Removed `set -e` from post-commit hook to prevent aborting on non-fatal errors
- **cli_hooks.py**: Hook now `cd`s to repo root before activating venv or running commands
- **cli_hooks.py**: Hook iterates affected directories, runs `codeindex scan` for each with existing README_AI.md, and auto-commits updated files with `--no-verify`
- **cli_hooks.py**: Skips directories without README_AI.md (warns user to run `codeindex scan` first)
- **init_wizard.py**: `create_codeindex_md()` now includes "Auto-Update Hooks" section documenting `codeindex hooks install post-commit`, `codeindex hooks status`, and `.codeindex.yaml` hooks configuration

**Parser Detection + Init Wizard Updates (Epic 19 Stories 19.4 + 19.2)**:
- **init_wizard.py**: New `PARSER_PACKAGES` mapping, `check_parser_installed()`, and `get_parser_install_guidance()` functions for detecting installed tree-sitter parsers and generating install commands
- **cli_config.py**: Non-interactive mode (`--yes`) now checks for missing parsers and warns with install guidance; new `_print_post_init_message()` helper provides unified post-init next steps for both interactive and non-interactive modes

**Java Tech-Debt Improvements (Epic 19 Stories 19.6a + 19.6b)**:
- **cli_tech_debt.py**: Auto-enables `--recursive` for Java projects instead of showing a post-hoc hint; removes the empty-directory hint code in favor of proactive behavior
- **tech_debt.py**: `_analyze_noise_breakdown()` is now language-aware via a `file_type` parameter; Java getter/setter methods (`get*`/`set*`) are no longer counted as noise, recognizing them as standard JavaBeans convention

**Pass-Through Directory Skipping (Epic 19 Story 19.5)**:
- **scanner.py**: New `is_pass_through()` function detects directories with no code files and a single subdirectory
- **directory_tree.py**: `get_processing_order()` filters out pass-through directories to avoid redundant README_AI.md generation in deep structures (e.g., Java Maven `src/main/java/com/...`)
- **directory_tree.py**: `print_tree()` switched from `print()` to `logger.debug()` for proper logging

**Reversed Scan Defaults (Epic 19 - v0.16.0+)**:
- **Structural mode is now the default** for both `scan` and `scan-all` commands
- New `--ai` opt-in flag replaces the previous AI-by-default behavior
- `DEFAULT_AI_COMMAND` in `config.py` changed to empty string (AI requires explicit configuration)
- Deprecated flags (`--fallback`, `--no-ai`) are hidden but still functional with deprecation warnings
- `--dry-run` now requires `--ai` flag (validates at command level)
- `--ai` validates that `ai_command` is configured in `.codeindex.yaml`
- Error messages and fallback text updated to reflect new terminology ("structural fallback")

**Dynamic Version Resolution**:
- `__init__.py` now uses `importlib.metadata.version("ai-codeindex")` instead of a hardcoded version string
- Falls back to `"0.0.0-dev"` when package metadata is unavailable
- `pyproject.toml` is the single source of truth for version numbers

**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

**Java scan-all, Tech Debt, and Getter/Setter Scoring Fixes**:
- **scanner.py**: Replaced per-language if/elif extension checks with unified `get_language_extensions()` call in both `scan_directory()` and `find_all_directories()`, making language support extensible via a single map
- **cli_tech_debt.py**: Added Java-aware hint when tech-debt analysis on a non-recursive scan returns empty results for Java-configured projects
- **symbol_scorer.py**: Java files no longer penalize getter/setter method names (`get*`, `set*`, `is*`, `has*`) since these follow standard JavaBeans convention; penalty retained for other languages


**Commit ``**: 

Changed files:
- `smart_writer.py`


**Commit ``**: 

Changed files:
- `smart_writer.py`


**Commit ``**: 

Changed files:
- `parser.py`
- `scanner.py`


**Commit ``**: 

Changed files:
- `smart_writer.py`


**Commit ``**: 

Changed files:
- `file_classifier.py`
- `tech_debt.py`


**Commit ``**: 

Changed files:
- `parser.py`


**Commit ``**: 

Changed files:
- `tech_debt.py`


**Commit ``**: 

Changed files:
- `parser.py`


**Commit ``**: 

Changed files:
- `objc_association.py`


**Commit ``**: 

Changed files:
- `cli_tech_debt.py`


**Commit ``**: 

Changed files:
- `tech_debt.py`


**Commit ``**: 

Changed files:
- `cli.py`
- `cli_tech_debt.py`
- `tech_debt_formatters.py`
- `test_smells.py`


**Commit ``**: 

Changed files:
- `cli_tech_debt.py`
- `tech_debt_formatters.py`


**Commit ``**: 

Changed files:
- `cli_scan.py`


**Commit ``**: 

Changed files:
- `cli_scan.py`


**Commit ``**: 

Changed files:
- `parser.py`


**Commit ``**: 

Changed files:
- `cli_tech_debt.py`
- `directory_tree.py`
- `hierarchical.py`
- `tech_debt.py`


**Commit ``**: 

Changed files:
- `hooks.py`


**Commit ``**: 

Changed files:
- `hooks.py`


**Commit ``**: 

Changed files:
- `skill_helpers.py`

---

## Recent Changes

**Commit ``**: 

Changed files:
- `skill_helpers.py`
