Implement local code indexing #50

New Issue

2026-01-03T23:46:23Z

KofTwentyTwo commented

2026-01-03 23:46:23 +00:00

(Migrated from github.com)

User Story

As a developer, I want qstudio to index my local codebase so that AI planning has context about my project structure, dependencies, and existing patterns.

Design

Command Interface

# Index current project
qstudio index

# Index specific directory
qstudio index --path /path/to/project

# Force re-index (ignore cache)
qstudio index --force

# Show index status
qstudio index --status

# Clear index
qstudio index --clear

Output Format

Indexing project: /Users/james/projects/orders-service

  Scanning files...
    Found 234 source files
    Found 45 test files
    Found 12 config files

  Analyzing structure...
    Language: Java (Maven)
    Framework: QQQ 0.27.0
    Modules: 3 (core, api, web)

  Building index...
    Parsing AST... done
    Extracting symbols... done
    Mapping dependencies... done

Index complete. 291 files indexed in 4.2s
Index location: ~/.qctl/index/orders-service/

Index Storage

~/.qctl/index/
└── orders-service/
    ├── manifest.json      # Project metadata
    ├── files.json         # File list with hashes
    ├── symbols.json       # Classes, methods, fields
    ├── dependencies.json  # Import graph
    └── chunks/            # Embeddings (optional)
        ├── chunk-001.bin
        └── ...

Manifest Format

{
  "project": "orders-service",
  "path": "/Users/james/projects/orders-service",
  "indexed_at": "2024-01-15T10:30:00Z",
  "language": "java",
  "build_tool": "maven",
  "framework": "qqq",
  "framework_version": "0.27.0",
  "stats": {
    "files": 291,
    "classes": 156,
    "methods": 1234,
    "lines": 45000
  }
}

Files to Create/Modify

File	Action	Purpose
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/IndexCommand.java`	Create	Main index command
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/CodeIndexer.java`	Create	Core indexing logic
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/FileScanner.java`	Create	File discovery
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/JavaParser.java`	Create	Java AST parsing
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/SymbolExtractor.java`	Create	Symbol extraction
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/IndexStore.java`	Create	Index persistence
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/ProjectIndex.java`	Create	Index model
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/SourceFile.java`	Create	File model
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/Symbol.java`	Create	Symbol model

Implementation Tasks

Create IndexCommand with Picocli annotations
Add --path, --force, --status, --clear options
Implement FileScanner with gitignore support
Implement JavaParser using Eclipse JDT or similar
Implement SymbolExtractor for classes/methods/fields
Create IndexStore for JSON persistence
Detect project type (Maven/Gradle, framework)
Support incremental indexing (hash-based change detection)
Add progress indicators for large projects
Implement index cache with TTL
Write unit tests for CodeIndexer
Write unit tests for JavaParser

Acceptance Criteria

qstudio index indexes current project
Detects Java/Maven projects automatically
Extracts classes, methods, and fields
Stores index in ~/.qctl/index/
Incremental update on re-index
--status shows index info
--clear removes index
Respects .gitignore patterns

## User Story As a developer, I want qstudio to index my local codebase so that AI planning has context about my project structure, dependencies, and existing patterns. ## Design ### Command Interface ```bash # Index current project qstudio index # Index specific directory qstudio index --path /path/to/project # Force re-index (ignore cache) qstudio index --force # Show index status qstudio index --status # Clear index qstudio index --clear ``` ### Output Format ``` Indexing project: /Users/james/projects/orders-service Scanning files... Found 234 source files Found 45 test files Found 12 config files Analyzing structure... Language: Java (Maven) Framework: QQQ 0.27.0 Modules: 3 (core, api, web) Building index... Parsing AST... done Extracting symbols... done Mapping dependencies... done Index complete. 291 files indexed in 4.2s Index location: ~/.qctl/index/orders-service/ ``` ### Index Storage ``` ~/.qctl/index/ └── orders-service/ ├── manifest.json # Project metadata ├── files.json # File list with hashes ├── symbols.json # Classes, methods, fields ├── dependencies.json # Import graph └── chunks/ # Embeddings (optional) ├── chunk-001.bin └── ... ``` ### Manifest Format ```json { "project": "orders-service", "path": "/Users/james/projects/orders-service", "indexed_at": "2024-01-15T10:30:00Z", "language": "java", "build_tool": "maven", "framework": "qqq", "framework_version": "0.27.0", "stats": { "files": 291, "classes": 156, "methods": 1234, "lines": 45000 } } ``` ## Files to Create/Modify | File | Action | Purpose | |------|--------|---------| | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/IndexCommand.java` | Create | Main index command | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/CodeIndexer.java` | Create | Core indexing logic | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/FileScanner.java` | Create | File discovery | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/JavaParser.java` | Create | Java AST parsing | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/SymbolExtractor.java` | Create | Symbol extraction | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/index/IndexStore.java` | Create | Index persistence | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/ProjectIndex.java` | Create | Index model | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/SourceFile.java` | Create | File model | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/Symbol.java` | Create | Symbol model | ## Implementation Tasks - [ ] Create IndexCommand with Picocli annotations - [ ] Add --path, --force, --status, --clear options - [ ] Implement FileScanner with gitignore support - [ ] Implement JavaParser using Eclipse JDT or similar - [ ] Implement SymbolExtractor for classes/methods/fields - [ ] Create IndexStore for JSON persistence - [ ] Detect project type (Maven/Gradle, framework) - [ ] Support incremental indexing (hash-based change detection) - [ ] Add progress indicators for large projects - [ ] Implement index cache with TTL - [ ] Write unit tests for CodeIndexer - [ ] Write unit tests for JavaParser ## Acceptance Criteria - [ ] `qstudio index` indexes current project - [ ] Detects Java/Maven projects automatically - [ ] Extracts classes, methods, and fields - [ ] Stores index in ~/.qctl/index/ - [ ] Incremental update on re-index - [ ] `--status` shows index info - [ ] `--clear` removes index - [ ] Respects .gitignore patterns

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#50