aihand 0.0.1 → 0.1.1

package/src/read/compact.ts

@@ -0,0 +1,286 @@
+import type { Parser, Tree } from 'web-tree-sitter'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { Language, Query } from 'web-tree-sitter'
+
+const queryCache = new Map<Language, Map<string, Query>>()
+
+function cachedQuery(lang: Language, source: string): Query {
+    let byLang = queryCache.get(lang)
+    if (!byLang) {
+        byLang = new Map()
+        queryCache.set(lang, byLang)
+    }
+    let q = byLang.get(source)
+    if (!q) {
+        q = new Query(lang, source)
+        byLang.set(source, q)
+    }
+    return q
+}
+
+export const SEPARATOR = '⋮----'
+
+// True if the trimmed signature ends with an empty param list: "( )" with only whitespace inside.
+function isNoParamFn(trimmed: string): boolean {
+    if (!trimmed.endsWith(')'))
+        return false
+    let i = trimmed.length - 2 // before the ')'
+    while (i >= 0 && (trimmed[i] === ' ' || trimmed[i] === '\t')) i--
+    return i >= 0 && trimmed[i] === '('
+}
+
+// True if a comment line is a section separator: "//" + optional whitespace + "──".
+function isSectionComment(text: string): boolean {
+    if (!text.startsWith('//'))
+        return false
+    let i = 2
+    while (i < text.length && (text[i] === ' ' || text[i] === '\t')) i++
+    return text.startsWith('──', i)
+}
+
+export const IMPORT_QUERY = `
+(import_statement
+  source: (string (string_fragment) @source))
+`
+
+export const TS_QUERY = `
+(export_statement (function_declaration)) @fn
+(export_statement (lexical_declaration (variable_declarator value: (arrow_function)))) @fn
+(export_statement (generator_function_declaration)) @fn
+(type_alias_declaration) @internal_type
+(export_statement (type_alias_declaration)) @type
+(interface_declaration) @internal_type
+(export_statement (interface_declaration)) @type
+(enum_declaration) @internal_type
+(export_statement (enum_declaration)) @type
+(class_declaration) @class
+(export_statement (class_declaration)) @class
+(export_statement value: (assignment_expression)) @export_val
+(export_statement (lexical_declaration)) @export_val
+(export_statement source: (string)) @reexport
+(comment) @comment
+`
+
+interface Chunk { content: string, startRow: number, endRow: number }
+
+const WASM_MAP: Record<string, string> = {
+    '.ts': 'tree-sitter-tsx.wasm',
+    '.tsx': 'tree-sitter-tsx.wasm',
+    '.mts': 'tree-sitter-tsx.wasm',
+    '.js': 'tree-sitter-tsx.wasm',
+    '.jsx': 'tree-sitter-tsx.wasm',
+    '.mjs': 'tree-sitter-tsx.wasm',
+}
+
+// Known WASM package locations to probe
+const WASM_PROBE_PATHS = [
+    '@repomix/tree-sitter-wasms/out',
+    '@anthropic-ai/tree-sitter-wasms/out',
+    '@anthropic-ai/codemap-tree-sitter-wasms/out',
+]
+
+const langCache = new Map<string, Language>()
+let wasmWarnedOnce = false
+
+function findWasmDir(wasmDir?: string): string | null {
+    if (wasmDir)
+        return existsSync(wasmDir) ? wasmDir : null
+    // Check relative to cwd (project has it installed)
+    for (const probe of WASM_PROBE_PATHS) {
+        const full = resolve('node_modules', probe)
+        if (existsSync(full))
+            return full
+    }
+    // Check from package's own location (npx / global install)
+    try {
+        const req = createRequire(import.meta.url)
+        return dirname(req.resolve('@repomix/tree-sitter-wasms/out/tree-sitter-tsx.wasm'))
+    }
+    catch {}
+    return null
+}
+
+export async function getLang(ext: string, wasmDir?: string): Promise<Language | null> {
+    const wasm = WASM_MAP[ext]
+    if (!wasm)
+        return null
+    const dir = findWasmDir(wasmDir)
+    if (!dir) {
+        if (!wasmWarnedOnce) {
+            wasmWarnedOnce = true
+            const pkgs = WASM_PROBE_PATHS.map(p => p.split('/')[0]).join(', ')
+            console.warn(`[repodex] ⚠ tree-sitter wasm not found. Install one of: ${pkgs}`)
+        }
+        return null
+    }
+    const wasmPath = join(dir, wasm)
+    if (!existsSync(wasmPath))
+        return null
+    const cached = langCache.get(wasmPath)
+    if (cached)
+        return cached
+    const lang = await Language.load(wasmPath)
+    langCache.set(wasmPath, lang)
+    return lang
+}
+
+export function cleanFnSignature(text: string): string {
+    const lines = text.split('\n')
+    let braceDepth = 0
+    let parenDepth = 0
+    let angleDepth = 0
+    let afterArrow = false
+    let arrowI = 0
+    let arrowJ = 0
+    let prevTopChar = ''
+
+    for (let i = 0; i < lines.length; i++) {
+        for (let j = 0; j < lines[i].length; j++) {
+            const ch = lines[i][j]
+            if (ch === ' ' || ch === '\t')
+                continue
+            if (ch === '(') {
+                parenDepth++
+                afterArrow = false
+            }
+            else if (ch === ')') {
+                parenDepth--
+                afterArrow = false
+            }
+            else if (ch === '<') {
+                angleDepth++
+                afterArrow = false
+            }
+            else if (ch === '>') {
+                if (angleDepth > 0)
+                    angleDepth--
+                afterArrow = false
+            }
+            else if (ch === '{') {
+                if (afterArrow) {
+                    lines[arrowI] = lines[arrowI].slice(0, arrowJ).trimEnd()
+                    return lines.slice(0, arrowI + 1).join('\n')
+                }
+                if (parenDepth <= 0 && braceDepth <= 0 && angleDepth <= 0 && prevTopChar !== ':') {
+                    lines[i] = lines[i].slice(0, j).trimEnd()
+                    return lines.slice(0, i + 1).join('\n')
+                }
+                braceDepth++
+                afterArrow = false
+            }
+            else if (ch === '}') {
+                if (braceDepth > 0)
+                    braceDepth--
+                afterArrow = false
+            }
+            else if (ch === '=' && lines[i][j + 1] === '>') {
+                if (parenDepth <= 0 && braceDepth <= 0 && angleDepth <= 0) {
+                    lines[i] = lines[i].slice(0, j).trimEnd()
+                    return lines.slice(0, i + 1).join('\n')
+                }
+                afterArrow = true
+                arrowI = i
+                arrowJ = j
+                j++ // skip >
+            }
+            else {
+                afterArrow = false
+            }
+            if (parenDepth <= 0 && braceDepth <= 0 && angleDepth <= 0)
+                prevTopChar = ch
+        }
+    }
+    return text.split('\n')[0]
+}
+
+export interface CompactFlags {
+    skipNoParamFn?: boolean
+}
+
+export function compact(code: string, parser: Parser, lang: Language, flags: CompactFlags = {}, existingTree?: Tree): string {
+    const { skipNoParamFn = true } = flags
+    const tree = existingTree ?? parser.parse(code)
+    if (!tree)
+        return ''
+    const query = cachedQuery(lang, TS_QUERY)
+    const captures = query.captures(tree.rootNode)
+    const ownTree = !existingTree
+    captures.sort((a, b) => a.node.startPosition.row - b.node.startPosition.row)
+
+    const chunks: Chunk[] = []
+    const seen = new Set<number>()
+
+    for (const { name, node } of captures) {
+        const startRow = node.startPosition.row
+        if (seen.has(startRow))
+            continue
+        seen.add(startRow)
+
+        let content: string
+        if (name === 'fn' || name === 'class') {
+            content = cleanFnSignature(node.text)
+        }
+        else if (name === 'comment') {
+            if (isSectionComment(node.text))
+                content = node.text
+            else continue
+        }
+        else if (name === 'reexport') {
+            content = node.text
+        }
+        else if (name === 'export_val') {
+            if (node.descendantsOfType('arrow_function').length > 0) {
+                content = cleanFnSignature(node.text)
+            }
+            else if (node.text.includes('\n')) {
+                content = node.text.split('\n')[0]
+            }
+            else {
+                content = node.text
+            }
+        }
+        else if (name === 'internal_type' || name === 'type') {
+            content = node.text
+        }
+        else {
+            content = node.text
+        }
+
+        const trimmed = content.trim()
+        if (skipNoParamFn && (name === 'fn' || name === 'export_val') && isNoParamFn(trimmed))
+            continue
+        chunks.push({ content: trimmed, startRow, endRow: node.endPosition.row })
+    }
+
+    // Merge chunks within 1 blank line of each other (endRow + 2 covers 0–1 row gaps)
+    const GAP = 2
+    const merged: Chunk[] = []
+    for (const chunk of chunks) {
+        const last = merged[merged.length - 1]
+        if (last && last.endRow + GAP >= chunk.startRow) {
+            last.content += `\n${chunk.content}`
+            last.endRow = chunk.endRow
+        }
+        else {
+            merged.push({ ...chunk })
+        }
+    }
+
+    const result = merged.map(c => c.content).join(`\n${SEPARATOR}\n`)
+    if (ownTree)
+        tree.delete()
+    return result
+}
+
+export function extractImports(code: string, parser: Parser, lang: Language, existingTree?: Tree): string[] {
+    const tree = existingTree ?? parser.parse(code)
+    if (!tree)
+        return []
+    const query = cachedQuery(lang, IMPORT_QUERY)
+    const result = query.captures(tree.rootNode).map(c => c.node.text)
+    if (!existingTree)
+        tree.delete()
+    return result
+}

package/src/read/config.ts

@@ -0,0 +1,62 @@
+import type { AidevConfig, Config, ReadOptions, RuntimeOptions } from './types.js'
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createJiti } from 'jiti'
+import { DEFAULT_CONFIG, resolveModule } from './types.js'
+
+export const CONFIG_PATH = 'aihand.config.ts'
+const SELF_PATH = fileURLToPath(import.meta.url)
+
+const TS_EXTS = ['.ts', '.tsx', '.js', '.jsx']
+export const isTsFile = (p: string): boolean => TS_EXTS.some(ext => p.endsWith(ext))
+
+// 加载 aihand.config.ts 合并进 DEFAULT_CONFIG。root 缺省 = cwd（CLI 行为）；插件传 server.config.root。
+// 抽出 cli.ts 是融合的需要:ui server 要跑同一份 read 配置去构图,不能welded 在带 process.exit 的 CLI 壳里。
+export async function loadConfig(root: string = resolve('.')): Promise<Config> {
+    const configFile = join(root, CONFIG_PATH)
+    if (!existsSync(configFile))
+        return DEFAULT_CONFIG
+    // Resolve the bare `aihand` a user's config imports `defineConfig` from to THIS install's
+    // index. dist: read cli bundles to a sibling chunk in dist/ → dist/index.js. src (tsx dev):
+    // this file is src/read/config.ts → ../index.ts. Pick whichever exists.
+    const selfDir = dirname(SELF_PATH)
+    const aihandIndex = [join(selfDir, 'index.js'), resolve(selfDir, '../index.ts')].find(existsSync)
+        ?? join(selfDir, 'index.js')
+    const jiti = createJiti(root, {
+        alias: { aihand: aihandIndex },
+        moduleCache: false,
+        fsCache: false,
+    })
+    const mod = await jiti.import(configFile) as Record<string, unknown>
+    const raw = (mod.default ?? mod) as AidevConfig
+    return normalizeConfig(raw)
+}
+
+// Three module switches → resolved nested Config. Each module: undefined/true → on+defaults,
+// false → off, object → on + shallow override. include is the one merge (root config files
+// from defaults stay, the config's globs add on); everything else is plain override.
+export function normalizeConfig(raw: AidevConfig): Config {
+    const read = resolveModule<ReadOptions>(raw.read, {})
+    const d = DEFAULT_CONFIG.read
+    return {
+        read: {
+            enabled: read.enabled,
+            include: [...d.include, ...(read.include ?? ['src/**'])],
+            ignore: read.ignore ?? d.ignore,
+            fileDetailLevel: { ...d.fileDetailLevel, ...read.fileDetailLevel },
+            injectDetailLevel: read.injectDetailLevel ?? d.injectDetailLevel,
+            injectTargetFiles: read.injectTargetFiles ?? d.injectTargetFiles,
+            injectDevToolInstructions: read.injectDevToolInstructions ?? d.injectDevToolInstructions,
+            injectCodemap: read.injectCodemap ?? d.injectCodemap,
+            showNoParamFn: read.showNoParamFn ?? d.showNoParamFn,
+            treeFoldThreshold: read.treeFoldThreshold ?? d.treeFoldThreshold,
+            maxTokens: typeof read.maxTokens === 'number' ? read.maxTokens : d.maxTokens,
+        },
+        refactor: { enabled: raw.refactor !== false },
+        runtime: ((): Config['runtime'] => {
+            const r = resolveModule<RuntimeOptions>(raw.runtime, {})
+            return { enabled: r.enabled, storeMarker: r.storeMarker ?? '_loading' }
+        })(),
+    }
+}

package/src/read/graph.ts

@@ -0,0 +1,182 @@
+import type { Language } from 'web-tree-sitter'
+import { readFileSync } from 'node:fs'
+import { Parser, Query } from 'web-tree-sitter'
+import { getLang } from './compact.js'
+
+// ── Types ─────────────────────────────────────────────────
+
+export interface SymbolNode {
+    uid: string // "src/models/gen.ts::gen"
+    name: string
+    kind: 'function' | 'method' | 'class'
+    filePath: string
+    startLine: number
+    endLine: number
+}
+
+export interface CallGraph {
+    symbols: Record<string, SymbolNode> // uid → node
+    out: Record<string, string[]> // uid → callees (uid[])
+    in: Record<string, string[]> // uid → callers (uid[])
+}
+
+// ── Tree-sitter queries ───────────────────────────────────
+
+const DEFS_QUERY = `
+(function_declaration name: (identifier) @name) @def
+(generator_function_declaration name: (identifier) @name) @def
+(class_declaration name: (type_identifier) @name) @def
+(method_definition name: (property_identifier) @name) @def
+(variable_declarator name: (identifier) @name value: (arrow_function)) @def
+`
+
+const CALLS_QUERY = `
+(call_expression function: (identifier) @callee)
+(call_expression function: (member_expression property: (property_identifier) @callee))
+(new_expression constructor: (identifier) @callee)
+`
+
+// ── Internal helpers ──────────────────────────────────────
+
+interface RawDef {
+    name: string
+    kind: 'function' | 'method' | 'class'
+    startLine: number
+    endLine: number
+}
+
+interface RawAttributed {
+    callerDef: RawDef
+    callee: string
+}
+
+function extractFileGraph(
+    code: string,
+    parser: Parser,
+    defsQuery: Query,
+    callsQuery: Query,
+): { defs: RawDef[], attributed: RawAttributed[] } {
+    const tree = parser.parse(code)
+    if (!tree)
+        return { defs: [], attributed: [] }
+
+    // Extract defs via matches() to pair @def + @name
+    const defs: RawDef[] = []
+    for (const match of defsQuery.matches(tree.rootNode)) {
+        const defCapture = match.captures.find(c => c.name === 'def')
+        const nameCapture = match.captures.find(c => c.name === 'name')
+        if (!defCapture || !nameCapture)
+            continue
+        const KIND_MAP: Record<string, 'class' | 'method' | 'function'> = {
+            class_declaration: 'class',
+            method_definition: 'method',
+        }
+        const kind = KIND_MAP[defCapture.node.type] ?? 'function'
+        defs.push({
+            name: nameCapture.node.text,
+            kind,
+            startLine: defCapture.node.startPosition.row,
+            endLine: defCapture.node.endPosition.row,
+        })
+    }
+
+    // Extract calls via captures()
+    const rawCalls: Array<{ callee: string, row: number }> = []
+    for (const { node } of callsQuery.captures(tree.rootNode))
+        rawCalls.push({ callee: node.text, row: node.startPosition.row })
+
+    // Interval overlap: attribute each call to its innermost enclosing def
+    const attributed: RawAttributed[] = []
+    for (const call of rawCalls) {
+        let best: RawDef | null = null
+        let bestSize = Infinity
+        for (const def of defs) {
+            if (call.row >= def.startLine && call.row <= def.endLine) {
+                const size = def.endLine - def.startLine
+                if (size < bestSize) {
+                    best = def
+                    bestSize = size
+                }
+            }
+        }
+        if (best)
+            attributed.push({ callerDef: best, callee: call.callee })
+    }
+
+    tree.delete()
+    return { defs, attributed }
+}
+
+// ── Public API ────────────────────────────────────────────
+
+export async function buildCallGraph(filePaths: string[], contents?: Map<string, string>): Promise<CallGraph> {
+    await Parser.init()
+    const parser = new Parser()
+
+    // Derive language from the first file whose extension has a known wasm
+    let lang: Language | null = null
+    for (const fp of filePaths) {
+        const ext = fp.slice(fp.lastIndexOf('.'))
+        lang = await getLang(ext)
+        if (lang)
+            break
+    }
+    if (!lang)
+        return { symbols: {}, out: {}, in: {} }
+
+    parser.setLanguage(lang)
+
+    // Create queries once, outside the file loop
+    const defsQuery = new Query(lang, DEFS_QUERY)
+    const callsQuery = new Query(lang, CALLS_QUERY)
+
+    const symbols: Record<string, SymbolNode> = {}
+    const nameToUids = new Map<string, string[]>()
+    const fileGraphs: Array<{ filePath: string, attributed: RawAttributed[] }> = []
+
+    // Phase 1: collect all defs
+    for (const filePath of filePaths) {
+        let code: string
+        if (contents?.has(filePath)) {
+            code = contents.get(filePath)!
+        }
+        else {
+            try {
+                code = readFileSync(filePath, 'utf-8')
+            }
+            catch { continue }
+        }
+
+        const { defs, attributed } = extractFileGraph(code, parser, defsQuery, callsQuery)
+        for (const def of defs) {
+            const uid = `${filePath}::${def.name}:${def.startLine}`
+            symbols[uid] = { uid, name: def.name, kind: def.kind, filePath, startLine: def.startLine, endLine: def.endLine }
+            if (!nameToUids.has(def.name))
+                nameToUids.set(def.name, [])
+            nameToUids.get(def.name)!.push(uid)
+        }
+        fileGraphs.push({ filePath, attributed })
+    }
+
+    // Phase 2: build edges (use Sets for O(1) dedup)
+    const outSets: Record<string, Set<string>> = {}
+    const inSets: Record<string, Set<string>> = {}
+
+    for (const { filePath, attributed } of fileGraphs) {
+        for (const { callerDef, callee } of attributed) {
+            const callerUid = `${filePath}::${callerDef.name}:${callerDef.startLine}`
+            for (const calleeUid of nameToUids.get(callee) ?? []) {
+                ;(outSets[callerUid] ??= new Set()).add(calleeUid)
+                ;(inSets[calleeUid] ??= new Set()).add(callerUid)
+            }
+        }
+    }
+
+    const out = Object.fromEntries(Object.entries(outSets).map(([k, v]) => [k, [...v]]))
+    const inEdges = Object.fromEntries(Object.entries(inSets).map(([k, v]) => [k, [...v]]))
+
+    defsQuery.delete()
+    callsQuery.delete()
+    parser.delete()
+    return { symbols, out, in: inEdges }
+}

package/src/read/index.ts

@@ -0,0 +1,12 @@
+export { cleanFnSignature, compact, extractImports, getLang, IMPORT_QUERY, SEPARATOR, TS_QUERY } from './compact.js'
+export type { CallGraph, SymbolNode } from './graph.js'
+export { buildCallGraph } from './graph.js'
+export { ensureMarkers, injectAll, injectFile } from './inject.js'
+export type { LocateResult } from './locate.js'
+export { locate, parseInspPath, renderLocate, symbolAtLine } from './locate.js'
+export { buildBlocks, buildClassifier, formatTree, formatXml } from './render.js'
+export { scan } from './scan.js'
+export { scanSecrets } from './security.js'
+export { allocate, buildImportGraph, computeCentrality, computeRecency, expandByBudget } from './signals.js'
+export type { Config, FileBlock, FileDetailLevel, RepodexData } from './types.js'
+export { configTemplate, DEFAULT_CONFIG, defineConfig } from './types.js'

package/src/read/inject.ts

@@ -0,0 +1,121 @@
+import type { Config, RepodexData } from './types.js'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const START_TAG = '<!-- AIDEV:START -->'
+const END_TAG = '<!-- AIDEV:END -->'
+
+export type EnsureMarkersResult = 'created' | 'marked' | 'skipped'
+
+export function ensureMarkers(filePath: string): EnsureMarkersResult {
+    if (!existsSync(filePath)) {
+        const dir = dirname(filePath)
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true })
+        writeFileSync(filePath, `${START_TAG}\n${END_TAG}\n`)
+        return 'created'
+    }
+    const content = readFileSync(filePath, 'utf-8')
+    if (content.includes(START_TAG))
+        return 'skipped'
+    const sep = content.endsWith('\n') ? '' : '\n'
+    writeFileSync(filePath, `${content}${sep}\n${START_TAG}\n${END_TAG}\n`)
+    return 'marked'
+}
+
+const DEV_TOOL_HINT = '> Before changing code: `aihand` is this repo\'s read·ui·refactor tool (read the control panel / reverse-locate, drive the running page, AST refactor). Run `aihand --help` to expand.'
+
+// Overview stays resident (what this repo is). Everything else is one command away by intent —
+// no "pull the whole map then eyeball it" round-trip (kills the multi-layer routing).
+const CODEMAP_HINT = [
+    '> **Locate code** (on demand, don\'t pull the whole map first):',
+    '> · change a UI behavior → `aihand read panel` (knob × store morphism: one line per control, which field it writes)',
+    '> · where files live / the layout → `aihand read tree`',
+    '> · runtime coord → static symbol → `aihand read source <file:line>` (with callers/callees)',
+    '> · the full map at once → `aihand read --stdout`',
+].join('\n')
+
+const DEFAULT_INJECT_FILES = ['CLAUDE.md', 'AGENTS.md']
+
+/**
+ * Pure: config + data → the codemap body that belongs between the markers (assembled sections).
+ * The inject path (computeInjection) and the stdout path (aihand read --stdout) share this one
+ * renderer — "what you see == what was once injected". When injectCodemap=false the queryable
+ * map (panel/state/tree/...) collapses to a pointer; Overview stays resident. The map is a
+ * queryable product, pulled on demand via a command, paying no per-session residency tax.
+ */
+export function renderSections(config: Config, data: RepodexData): string {
+    const sections: string[] = []
+    // Overview is the entry point (what this repo is) — without it in context the AI has no
+    // starting point to build a topology, so "always fetch" ≠ "on demand". Always resident,
+    // never gated by injectCodemap. What IS gated: the few hundred lines of queryable
+    // panel/state/tree/sig/full products.
+    if (data.overview)
+        sections.push(`# Overview\n\n${data.overview}`)
+    if (config.read.injectCodemap) {
+        if (data.panel)
+            sections.push(`# Control Panel — 系统的控制论模型\n\n这是最高抽象层：一个洗衣机面板。系统无论内部多复杂（几千组件），其本质 = **(旋钮 × 状态) → 状态转移**。旋钮是完整接口，拨任一旋钮整个 App 进入新状态；下面的状态显示是输出端/可观测量。下面的几千组件全是这十几个控制量的展开。读它即知"这 App 能干什么、由哪些状态驱动、改某个 UI 去哪个 store 字段"。改 UI 行为前先在这里定位，再 \`aihand read source\` 展开。\n\n## 旋钮（输入端）\n\n一行一个旋钮：\`「名字」 事件 → store.{ 字段=目标值 }  :行号\`——拨它把哪个 store 状态推向什么值。\n\n\`\`\`\n${data.panel}\n\`\`\``)
+        if (data.state)
+            sections.push(`## 状态显示（输出端 / 可观测量）\n\n系统由哪些状态量构成、各自初值、各自值域（\`{a|b|c}\` = 可枚举的离散态，即面板能显示的状态机；无标注 = boolean/对象等非枚举态）。旋钮拨动的就是这些量。\n\n\`\`\`\n${data.state}\n\`\`\``)
+        if (data.tree)
+            sections.push(`# File Tree\n\n${data.tree}`)
+        if (data.signatures)
+            sections.push(`# Signatures\n\n\`\`\`\n${data.signatures}\n\`\`\``)
+        if (data.full)
+            sections.push(`# Full Source\n\n\`\`\`\n${data.full}\n\`\`\``)
+    }
+    else {
+        sections.push(CODEMAP_HINT)
+    }
+    if (config.read.injectDevToolInstructions)
+        sections.push(DEV_TOOL_HINT)
+    return sections.join('\n\n')
+}
+
+/** 纯核心：已有文件内容 → 注入后的新内容；返回 null 表示无 marker 或 repodex 段无变化。 */
+export function computeInjection(
+    content: string,
+    config: Config,
+    data: RepodexData,
+): string | null {
+    const si = content.indexOf(START_TAG)
+    const ei = content.indexOf(END_TAG)
+    if (si === -1 || ei === -1)
+        return null
+
+    // 只比较标记之间的 repodex 段：标记外的手写内容变动不触发重写
+    const oldBody = content.slice(si + START_TAG.length, ei)
+    const newBody = `\n\n${renderSections(config, data)}\n`
+    if (oldBody === newBody)
+        return null
+    const before = content.slice(0, si + START_TAG.length)
+    const after = content.slice(ei)
+    return `${before}${newBody}${after}`
+}
+
+export function injectFile(
+    config: Config,
+    data: RepodexData,
+    filePath: string,
+): boolean {
+    if (!existsSync(filePath))
+        return false
+    const next = computeInjection(readFileSync(filePath, 'utf-8'), config, data)
+    if (next === null)
+        return false
+    writeFileSync(filePath, next)
+    return true
+}
+
+export function injectAll(
+    config: Config,
+    data: RepodexData,
+    files = DEFAULT_INJECT_FILES,
+): string[] {
+    const injected: string[] = []
+    for (const f of files) {
+        if (injectFile(config, data, f))
+            injected.push(f)
+    }
+    return injected
+}