e23922a1b7
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
- Multi-assignment clustering (no greedy 'used' set) - Adaptive ngram fallback (shrink when (other) > 60%) - Add docs/adr/ with 10 architecture decision records - Fix ADR 1 (query modification description) - Fix ADR 3 (multi-assignment + adaptive shrink) - Fix ADR 5 (import sort order clarification) - Fix ADR 6 (remove Kotlin call_suffix references) - New ADR 9 (adaptive clustering rationale) - New ADR 10 (universal package mapping via relpath)
45 lines
2.1 KiB
Markdown
45 lines
2.1 KiB
Markdown
# 5. Import extraction per cluster
|
|
|
|
**Date:** 2026-07-03
|
|
|
|
**Status:** Accepted
|
|
|
|
## Context
|
|
|
|
An LLM prompted with a behavioral convention like `every → assertEquals → verify` still needs to know *which imports to use*. Without imports, it will guess the wrong library — writing `from unittest.mock import patch` instead of `import io.mockk.every`, or importing from `jest` instead of `vitest`.
|
|
|
|
Imports are the bridge between abstract conventions and actionable code.
|
|
|
|
## Decision
|
|
|
|
For each cluster, scan the source files whose methods belong to that cluster and extract all unique import lines.
|
|
|
|
Language-agnostic approach: match lines against common import patterns:
|
|
- `import ...` (Java, Kotlin, Python, Go, JS/TS)
|
|
- `from ... import ...` (Python)
|
|
- `require ...` / `require_relative ...` (Ruby, JS)
|
|
- `#include ...` (C/C++)
|
|
- `use ...` (Rust)
|
|
- `include ...` (Ruby)
|
|
|
|
Scan the first 200 lines of each file (imports are always at the top), deduplicate across files, yielding stable file-visit order (files sorted by path).
|
|
|
|
File-to-cluster mapping is preserved by tracking `(file_path, sequence)` pairs through the pipeline. With multi-assignment clustering, methods may belong to multiple clusters — each gets the full import set from its source file.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
- Each cluster shows exact import lines used by its methods.
|
|
- An LLM can copy these directly — no guessing.
|
|
- Reveals *library choice conventions*: `kotlin.test.*` vs `org.junit.jupiter.api.*`, `io.mockk.coEvery` vs `io.mockk.every`.
|
|
|
|
**Negative:**
|
|
- Import scanning re-reads files (second pass). Negligible cost since files are small and OS-cached.
|
|
- 200-line scan limit might miss imports in files with very long license headers.
|
|
- Lines containing `import` in prose (comments, strings) may produce false positives — rare in practice.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Single global import list**: Simpler but useless — conflates imports from unrelated clusters.
|
|
- **No imports**: LLM must guess. Leads to wrong imports and broken code.
|
|
- **Per-file imports (not per-cluster)**: Too granular — mixes test imports with production imports in the same file.
|