ai-codeindex 0.7.0__tar.gz

ai_codeindex-0.7.0/.claude/skills/mo-arch/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: mo-arch
+description: Query code architecture using README_AI.md index files. Use when user asks about project structure, where features are implemented, how modules work, or wants to understand codebase architecture. Triggered by questions like "what does this do", "where is X implemented", "how does module Y work".
+---
+
+# mo-arch - Code Architecture Query
+
+Query code architecture using README_AI.md index files generated by codeindex.
+
+## Workflow
+
+### Step 1: Check Project Index
+
+```bash
+cat PROJECT_INDEX.md 2>/dev/null
+```
+
+If exists, this gives you the project overview with all modules listed.
+
+### Step 2: Find Directory Indexes
+
+```bash
+find . -name "README_AI.md" -type f | head -10
+```
+
+### Step 3: Read Relevant Module Index
+
+Based on user's question, locate the relevant module and read its README_AI.md:
+
+```bash
+# Example: user asks about parser
+cat src/parser/README_AI.md
+```
+
+### Step 4: Trace Dependencies
+
+Check the **Consumes** and **Provides** sections in README_AI.md to understand module relationships.
+
+### Step 5: Deep Dive (if needed)
+
+Only read actual source files when README_AI.md doesn't have enough detail.
+
+## Response Format
+
+When answering architecture questions:
+
+1. **Start with the module location** - "The parser is in `src/codeindex/parser.py`"
+2. **Explain its purpose** - From the Purpose section
+3. **Show relationships** - From Consumes/Provides
+4. **Provide code reference** - Line numbers if relevant
+
+## Example
+
+**User**: "Where is the parser implemented?"
+
+**Response**:
+```
+Based on README_AI.md, the parser is in `src/codeindex/parser.py`.
+
+**Purpose**: Tree-sitter based Python parser that extracts Symbol
+(classes, functions, methods) and Import statements into ParseResult.
+
+**Key exports**:
+- `parse_file()` - Parse a single Python file
+- `ParseResult` - Container for parsed data
+- `Symbol` - Represents a code symbol
+
+**Dependencies**: tree-sitter, tree-sitter-python
+```
+
+## When No Index Exists
+
+If README_AI.md files don't exist, suggest:
+
+```
+This directory is not indexed. Run:
+  codeindex scan ./path/to/dir
+
+Or for the entire project:
+  codeindex list-dirs | xargs -P 4 -I {} codeindex scan {}
+  codeindex index
+```

ai_codeindex-0.7.0/.claude/skills/mo-index/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: mo-index
+description: Generate AI-friendly code index using codeindex tool. Use when user wants to index a project, generate README_AI.md files, create code documentation, or make codebase searchable. Triggered by "index this project", "generate code index", "create documentation", "scan codebase".
+---
+
+# mo-index - Repository Indexing
+
+Generate AI-friendly index files (README_AI.md) for codebases using codeindex.
+
+## Prerequisites Check
+
+First, verify codeindex is available:
+
+```bash
+which codeindex || echo "Not installed. Run: pip install codeindex"
+```
+
+## Workflow
+
+### Step 1: Initialize (if needed)
+
+```bash
+# Check for config
+cat .codeindex.yaml 2>/dev/null || codeindex init
+```
+
+### Step 2: Review Configuration
+
+```bash
+cat .codeindex.yaml
+```
+
+Key settings to verify:
+- `ai_command` - Your AI CLI command (claude, openai, etc.)
+- `include` - Directories to scan
+- `exclude` - Patterns to skip
+
+### Step 3: Preview Indexable Directories
+
+```bash
+codeindex list-dirs
+```
+
+### Step 4: Index Directories
+
+**Single directory (test first):**
+```bash
+codeindex scan ./src/module --dry-run  # Preview
+codeindex scan ./src/module            # Execute
+```
+
+**All directories (parallel):**
+```bash
+codeindex list-dirs | xargs -P 4 -I {} codeindex scan {}
+```
+
+**Fallback mode (no AI):**
+```bash
+codeindex scan ./src/module --fallback
+```
+
+### Step 5: Generate Project Index
+
+```bash
+codeindex index
+```
+
+Creates `PROJECT_INDEX.md` with module overview.
+
+### Step 6: Verify Coverage
+
+```bash
+codeindex status
+```
+
+## Example Session
+
+```
+User: Index this project
+
+Claude: I'll help you index this project. Let me check the setup first.
+
+> codeindex status
+Indexed: 0/3 (0%)
+Not indexed: src/, tests/, examples/
+
+> codeindex list-dirs | xargs -P 4 -I {} codeindex scan {}
+✓ Created: src/codeindex/README_AI.md
+✓ Created: tests/README_AI.md
+✓ Created: examples/README_AI.md
+
+> codeindex index
+✓ Created: PROJECT_INDEX.md
+
+Done! Your project is now indexed:
+- 3 directory indexes (README_AI.md)
+- 1 project index (PROJECT_INDEX.md)
+- Coverage: 100%
+```
+
+## Configuration Reference
+
+`.codeindex.yaml` example:
+
+```yaml
+ai_command: 'claude -p "{prompt}" --allowedTools "Read"'
+
+include:
+  - src/
+  - lib/
+  - tests/
+  - examples/
+
+exclude:
+  - "**/__pycache__/**"
+  - "**/node_modules/**"
+
+output_file: README_AI.md
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| AI CLI timeout | `codeindex scan ./dir --timeout 180` |
+| Skip AI entirely | `codeindex scan ./dir --fallback` |
+| Debug prompt | `codeindex scan ./dir --dry-run` |
+
+## Post-Indexing Recommendations
+
+1. Commit README_AI.md files to git for team sharing
+2. Set up git hooks for auto-updates
+3. Add to CLAUDE.md: "Read README_AI.md before modifying code"

ai_codeindex-0.7.0/.github/workflows/publish.yml

@@ -0,0 +1,93 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'  # 匹配 v0.5.1, v1.0.0 等
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run tests
+      run: pytest -v
+
+    - name: Run linter
+      run: ruff check src/
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # For PyPI trusted publishing
+      contents: write  # For creating releases
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build distribution
+      run: python -m build
+
+    - name: Check distribution
+      run: twine check dist/*
+
+    # TestPyPI step disabled - requires TEST_PYPI_API_TOKEN
+    # - name: Publish to TestPyPI
+    #   if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    #   uses: pypa/gh-action-pypi-publish@release/v1
+    #   with:
+    #     repository-url: https://test.pypi.org/legacy/
+    #     password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+    #     skip-existing: true
+
+    - name: Publish to PyPI
+      if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+
+    - name: Extract version
+      id: version
+      run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+    - name: Extract changelog
+      id: changelog
+      run: |
+        VERSION=${{ steps.version.outputs.VERSION }}
+        sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | head -n -1 > release_notes.md
+        cat release_notes.md
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        body_path: release_notes.md
+        files: dist/*
+        draft: false
+        prerelease: false
+        token: ${{ secrets.GITHUB_TOKEN }}

ai_codeindex-0.7.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Project specific
+.codeindex.yaml

ai_codeindex-0.7.0/.serena/.gitignore

@@ -0,0 +1 @@
+/cache

ai_codeindex-0.7.0/.serena/memories/development_workflow.md

@@ -0,0 +1,73 @@
+# codeindex 开发指南
+
+## 必须阅读的文件
+1. **CLAUDE.md** - Claude Code工作流程指南
+2. **src/codeindex/README_AI.md** - 核心模块架构
+3. **tests/README_AI.md** - 测试结构和覆盖
+4. **docs/planning/** - Epic/Story规划文档
+
+## 代码导航最佳实践
+
+### 理解架构时
+1. 先读 README_AI.md 文件（分层结构）
+2. 使用 PROJECT_SYMBOLS.md 查找符号位置
+3. 使用 find_symbol 查看具体定义
+
+### 查找代码时
+```python
+# 查找符号定义
+find_symbol(name_path_pattern="AdaptiveSymbolSelector")
+
+# 查找符号引用
+find_referencing_symbols(name_path="calculate_limit", relative_path="src/codeindex/adaptive_selector.py")
+
+# 获取文件概览
+get_symbols_overview(relative_path="src/codeindex/parser.py", depth=1)
+```
+
+## TDD开发流程（严格）
+1. **Red**: 写失败的测试
+2. **Green**: 实现最小代码使测试通过
+3. **Refactor**: 重构优化
+
+### 测试命令
+```bash
+# 运行所有测试
+pytest -v
+
+# 运行特定测试
+pytest tests/test_new_feature.py -v
+
+# 测试覆盖率
+pytest --cov=src/codeindex --cov-report=term-missing
+
+# 要求：核心模块 ≥ 90%，整体 ≥ 80%
+```
+
+## 代码质量检查
+提交前必须通过：
+```bash
+# 1. 测试全部通过
+pytest -v
+
+# 2. 代码规范检查
+ruff check src/
+
+# 3. 类型检查（可选）
+mypy src/
+```
+
+## 修改代码流程
+1. **创建feature分支**
+2. **TDD实现**
+3. **更新CHANGELOG.md**
+4. **提交到develop**
+5. **合并到master并打tag**
+
+## 重要提醒
+- ❌ 不要直接修改生成的 README_AI.md
+- ❌ 不要跳过测试写实现
+- ❌ 不要用 Glob/Grep 搜索代码
+- ✅ 使用 Serena MCP 的符号工具
+- ✅ 先读 README_AI.md 理解架构
+- ✅ 遵循 GitFlow 工作流

ai_codeindex-0.7.0/.serena/memories/project_overview.md

@@ -0,0 +1,93 @@
+# codeindex 项目概览
+
+## 项目目的
+codeindex 是一个 AI 原生的代码索引工具，专为大型代码库设计。它自动使用 tree-sitter 解析和外部 AI CLI 生成智能文档 (`README_AI.md`)，帮助理解大型代码库、新开发者入职和维护活文档。
+
+## 技术栈
+- **语言**: Python 3.10+
+- **核心依赖**:
+  - click (CLI框架)
+  - pyyaml (配置文件)
+  - rich (终端输出)
+  - tree-sitter (代码解析)
+  - tree-sitter-python, tree-sitter-php (语言支持)
+- **开发工具**:
+  - pytest (测试)
+  - ruff (代码格式化和检查)
+  - hatchling (构建)
+
+## 代码风格和约定
+- **行长度**: 100字符
+- **代码格式**: 使用 ruff format
+- **代码检查**: ruff check
+- **测试**: TDD (测试驱动开发)
+- **文档字符串**: 100%覆盖
+- **类型提示**: Python 3.10+ 支持
+
+## 命令使用
+```bash
+# 开发模式安装
+pip install -e .
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 运行单个测试
+pytest tests/test_parser.py::test_parse_simple_function
+
+# 代码检查
+ruff check src/
+
+# 代码格式化
+ruff format src/
+
+# CLI使用
+codeindex scan-all --fallback    # 生成所有索引
+codeindex status                  # 查看覆盖率
+codeindex symbols                 # 生成符号索引
+```
+
+## 项目结构
+```
+src/codeindex/
+├── cli.py              # CLI入口点
+├── scanner.py          # 目录扫描
+├── parser.py           # tree-sitter解析
+├── writer.py           # 格式化和写入
+├── invoker.py          # AI CLI调用
+├── config.py           # 配置管理
+├── smart_writer.py     # 智能写入（分层）
+├── hierarchical.py     # 分层处理
+├── symbol_scorer.py    # 符号重要性评分 (v0.2.0新增)
+├── adaptive_config.py   # 自适应配置 (v0.2.0新增)
+├── adaptive_selector.py # 自适应符号选择 (v0.2.0新增)
+└── incremental.py       # 增量更新
+```
+
+## 关键特性
+1. **智能符号评分** (v0.2.0): 5维度评分系统，重要符号优先
+2. **自适应符号提取** (v0.2.0): 根据文件大小动态调整符号数量
+3. **分层文档生成**: 三级智能索引系统
+4. **AI增强**: 支持Claude、OpenAI等AI CLI
+5. **并行处理**: 支持多目录并发扫描
+
+## 配置文件
+- `.codeindex.yaml`: 项目配置文件
+- 支持include/exclude模式
+- 可配置AI命令
+- 可配置语言支持
+
+## Git工作流
+- GitFlow: master ← develop ← feature/*
+- 提交格式: feat/scope, fix/scope, docs/scope等
+- 版本标签: v0.2.0等
+
+## 重要文件
+- `CLAUDE.md`: Claude Code工作指南
+- `README_AI.md`: AI生成的目录文档（每个目录）
+- `PROJECT_INDEX.md`: 项目概览索引
+- `PROJECT_SYMBOLS.md`: 全局符号索引
+- `CHANGELOG.md`: 版本变更历史

ai_codeindex-0.7.0/.serena/memories/suggested_commands.md

@@ -0,0 +1,74 @@
+# codeindex 常用命令
+
+## 核心命令
+```bash
+# 生成所有目录索引（最常用）
+codeindex scan-all --fallback
+
+# 查看会扫描哪些目录
+codeindex list-dirs
+
+# 生成全局符号索引
+codeindex symbols
+
+# 查看索引覆盖率
+codeindex status
+
+# 初始化配置
+codeindex init
+```
+
+## 扫描命令
+```bash
+# 扫描单个目录
+codeindex scan ./src/auth
+
+# 预览prompt（不执行）
+codeindex scan ./src/auth --dry-run
+
+# 不使用AI生成（fallback模式）
+codeindex scan ./src/auth --fallback
+
+# AI增强所有目录（高质量）
+codeindex scan-all --ai-all
+```
+
+## 开发命令
+```bash
+# 安装（开发模式）
+pip install -e .
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 代码检查
+ruff check src/
+
+# 代码格式化
+ruff format src/
+
+# 重新生成所有索引
+codeindex scan-all --fallback
+```
+
+## 高级命令
+```bash
+# 查看符号详情
+codeindex find-symbol --name "ClassName" --path "./src/module.py"
+
+# 查看符号引用
+codeindex find-references --name "method_name"
+
+# 增量更新（只更新变更文件）
+codeindex scan-all --incremental
+
+# 并行处理（提高速度）
+codeindex scan-all --workers 8
+```
+
+## MCP技能（已安装）
+- `/mo:arch` - 查询代码架构
+- `/mo:index` - 生成项目索引

ai_codeindex-0.7.0/.serena/project.yml

@@ -0,0 +1,110 @@
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   powershell          python              python_jedi         r                   rego
+#   ruby                ruby_solargraph     rust                scala               swift
+#   terraform           toml                typescript          typescript_vts      vue
+#   yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+#   - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore in all projects
+# same syntax as gitignore, so you can use * and **
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+# the name by which the project can be referenced within Serena
+project_name: "codeindex"
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+included_optional_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []