aihand 0.0.1 → 0.1.1

package/src/read/locate.ts

@@ -0,0 +1,104 @@
+// 一体化的反向态射 —— 运行时坐标 → 静态符号上下文（FUSION.md §2）。
+//
+// 正向半边是控制面板（旋钮 → store 态 → 转移）。反向半边回答用户原话:
+// 「页面 UI 变化时,直接映射到代码原因去改」。四投影共享主键 `相对文件:行`
+// (静态 SymbolNode{filePath,startLine,endLine} ⋉ 运行时 data-insp-path),
+// 缝合它们的只是一个 find —— symbolAtLine。没有第四个数据结构,没有 FusionGraph。
+//
+// 按符号名匹配会跨文件同名串号;symbolAtLine 拿到精确 uid,callers/callees 按 uid 取
+// (graph.in/out),不经名字,绝不串别文件同名符号。
+
+import type { CallGraph, SymbolNode } from './graph.js'
+import { fileOfInspPath } from './seam.js'
+
+// 运行时坐标 → 静态符号。融合体唯一真态射。
+// 多命中(嵌套:组件函数体 + 内嵌 handler arrow 都覆盖同一行)取区间最小者 = 最内层符号,
+// 那才是「这一行真正属于谁」。
+export function symbolAtLine(g: CallGraph, file: string, line: number): SymbolNode | undefined {
+    let best: SymbolNode | undefined
+    for (const s of Object.values(g.symbols)) {
+        if (s.filePath !== file || line < s.startLine || line > s.endLine)
+            continue
+        if (!best || (s.endLine - s.startLine) < (best.endLine - best.startLine))
+            best = s
+    }
+    return best
+}
+
+// data-insp-path = `rel:line:col:Name`(也可能只是 `rel:line`)→ {file, line}。
+// 禁正则:file 段复用 seam 的「砍末三段」(对绝对路径盘符冒号也稳);line 紧跟 file 段。
+// 形态 A `rel:line`(2 段)→ file=parts[0], line=parts[1]
+// 形态 B `rel:line:col:Name`(≥4 段)→ file=前 N-3 段, line=第 N-2 段(即 file 段后第一段)
+export function parseInspPath(p: string): { file: string, line: number } {
+    const parts = p.split(':')
+    const file = fileOfInspPath(p)
+    const lineStr = parts.length <= 3 ? parts[1] : parts[parts.length - 3]
+    return { file, line: Number(lineStr) }
+}
+
+export interface LocateResult {
+    symbol: SymbolNode
+    callers: SymbolNode[]
+    callees: SymbolNode[]
+}
+
+// symbolAtLine → 按 uid 取 callers/callees(精确,非名字,绝不串别文件同名符号)。
+export function locate(g: CallGraph, file: string, line: number): LocateResult | null {
+    const symbol = symbolAtLine(g, file, line)
+    if (!symbol)
+        return null
+    const byUid = (uids: string[] | undefined) => (uids ?? []).map(u => g.symbols[u]).filter(Boolean)
+    return {
+        symbol,
+        callers: byUid(g.in[symbol.uid]),
+        callees: byUid(g.out[symbol.uid]),
+    }
+}
+
+// CLI/JSON 渲染:locate 结果 → 文本。json 时直接 JSON.stringify。
+// 主键 file:line(1-based) —— 两个渲染投影(文本/HTML)共用同一坐标口径。
+const at = (s: SymbolNode) => `${s.filePath}:${s.startLine + 1}`
+
+export function renderLocate(r: LocateResult, json = false): string {
+    if (json)
+        return JSON.stringify(r, null, 2)
+    const lines = [`${r.symbol.name}  ${r.symbol.kind}  ${at(r.symbol)}`]
+    if (r.callers.length) {
+        lines.push(`\nCallers (${r.callers.length}):`)
+        for (const c of r.callers)
+            lines.push(`  ${c.name}  ${at(c)}`)
+    }
+    if (r.callees.length) {
+        lines.push(`\nCallees (${r.callees.length}):`)
+        for (const c of r.callees)
+            lines.push(`  ${c.name}  ${at(c)}`)
+    }
+    if (!r.callers.length && !r.callees.length)
+        lines.push('  (no call edges found)')
+    return lines.join('\n')
+}
+
+// 反向态射的 HTML 投影 —— 浮层让人点页面元素直接看代码原因,且每个 caller/callee 带
+// data-src-path 可继续点向上跳调用链(「直接映射」最后一跳的渲染端)。最瘦:只出结构 +
+// 可点锚点,样式由浮层容器统一管。client-patch 内联一份镜像(不能 import),这里是真值,
+// 那里靠 aihand 真页面验证镜像一致。esc 由调用方注入(浏览器用 textContent,Node 测用简单转义)。
+export function sourcePanelHtml(r: LocateResult, esc: (s: string) => string = escHtml): string {
+    const row = (c: SymbolNode) => `<div class="aihand-src-edge" data-src-path="${esc(at(c))}">${esc(c.name)} <span class="aihand-src-at">${esc(at(c))}</span></div>`
+    const out = [`<div class="aihand-src-head">${esc(r.symbol.name)} <span class="aihand-src-kind">${esc(r.symbol.kind)}</span> <span class="aihand-src-at">${esc(at(r.symbol))}</span></div>`]
+    if (r.callers.length)
+        out.push(`<div class="aihand-src-sec">Callers (${r.callers.length})</div>`, ...r.callers.map(row))
+    if (r.callees.length)
+        out.push(`<div class="aihand-src-sec">Callees (${r.callees.length})</div>`, ...r.callees.map(row))
+    if (!r.callers.length && !r.callees.length)
+        out.push(`<div class="aihand-src-empty">(no call edges found)</div>`)
+    return out.join('')
+}
+
+// 禁正则:字符替换走 split/join 词法,不用 /g。顺序固定 & 先行(否则二次转义)。
+function escHtml(s: string): string {
+    return s
+        .split('&').join('&amp;')
+        .split('<').join('&lt;')
+        .split('>').join('&gt;')
+        .split('"').join('&quot;')
+}

package/src/read/panel.ts

@@ -0,0 +1,335 @@
+// 控制面涌现 — 系统的控制论模型第一层（洗衣机面板）。
+//
+// 一个旋钮 = 一个 JSX 元素挂了 on* handler，且 handler 体里写了某个 store 字段。
+// 拨这个旋钮 → 系统状态变。旋钮名来自同元素的 label/title（免费，无需 LLM）。
+//
+// 命门验证（FUSION.md §0）：旋钮 ⋈ 运行时 /screen knobs 的 join 键是 `label + 文件`，
+// 不是 `文件:行`（host 行 vs handler 行在组件边界处错位）。故 Knob 同时带 label 与坐标。
+//
+// store 识别：词法启发式——标识符以 `Store` 结尾且被 `X.field = …` 赋值。确定性、零正则、
+// 零跨文件追踪。漏判的代价是少一个旋钮，不会误报（结尾约束 + 实际写约束双重门）。
+
+import type { Language, Node } from 'web-tree-sitter'
+import { readFileSync } from 'node:fs'
+import { Parser, Query } from 'web-tree-sitter'
+import { getLang } from './compact.js'
+
+// 一次状态转移：拨旋钮把 field 推向 to。控制论里旋钮是态射 `状态 →[旋钮] 新状态`，
+// field 是定义域、to 是值域。「AI 对话」→ mode='chat'、「群聊」→ mode='im' 由此区分。
+export interface Transition {
+    field: string // store 字段
+    to: string // 目标值表达式（'im' / !showSideBar / …）
+    args?: string // call 形态(field 以 '()' 结尾)的括号内实参原文；assignment 不填。
+    // 带参方法(setReply(msg))与无参方法(openPanel())不同命:无参可绿色通道直调，带参依赖运行时上下文必拒。
+}
+
+export interface Knob {
+    label: string | null // 旋钮名（label/title 文本），join 键之一；null = 仅图标无文本
+    tag: string // host 标签 / 组件名（<button> / NavItem）
+    event: string // onClick / onChange / onValueChange …
+    transitions: Transition[] // 拨它触发的状态转移（field → to）；同 field 多写取末次
+    store: string // 写入的 store 实例名（appUIStore / imStore …）
+    filePath: string // join 键之一
+    line: number // handler 写 store 那行（1-based）
+}
+
+// 一个 JSX 属性：name + value。value 是 jsx_expression（{...}）。
+const ATTR_QUERY = `
+(jsx_attribute
+  (property_identifier) @name
+  (jsx_expression) @val) @attr
+`
+
+// 折叠多行赋值右侧的空白成单空格（逐字符扫描，禁正则）。
+function collapseWs(s: string): string {
+    const tokens: string[] = []
+    let cur = ''
+    for (const ch of s) {
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+            if (cur) { tokens.push(cur); cur = '' }
+        }
+        else { cur += ch }
+    }
+    if (cur) tokens.push(cur)
+    return tokens.join(' ')
+}
+
+// 一次 store 写入：store.field = to。to 是赋值右侧文本（转移目标）——
+// 旋钮的态射值域：`mode = 'im'` 的 `'im'`、`showSideBar = !showSideBar` 的 `!showSideBar`。
+interface StoreWrite {
+    store: string
+    field: string
+    to: string // 右侧表达式原文（'im' / !showSideBar / x + 1 …）；缩进折叠成单空格
+    args?: string // call 形态的实参原文（括号内）；assignment 不填
+}
+
+// handler 体里所有 store 状态写入：两种形态都是「拨它→store 进新态」的旋钮，缺一则该旋钮静默丢失。
+//  ① `IDENT.field = …`（assignment 左侧 member，IDENT 以 Store 结尾）——抽右侧 = 转移目标。
+//  ② `IDENT.method(…)`（call 在 *Store 上）——方法体在别的文件改 store 字段（如 memoryStore.openPanel()
+//     → this.panelOpen=true）。目标字段藏在方法里、跨文件，但调用点已静态声明「这是 store 的状态转移」，
+//     不做跨文件解析,把方法名当转移渲染成 `store.{ openPanel() }`——忠实且不编造它静态不可知的字段值。
+//     不把 method 当 field 收进来,memory 面板这类旋钮就永远不在控制面里(投影自称「每个旋钮」却悄悄漏)。
+function storeWritesIn(node: Node): StoreWrite[] {
+    const out: StoreWrite[] = []
+    const walk = (n: Node) => {
+        if (n.type === 'assignment_expression') {
+            const left = n.childForFieldName('left')
+            const right = n.childForFieldName('right')
+            if (left?.type === 'member_expression') {
+                const obj = left.childForFieldName('object')
+                const prop = left.childForFieldName('property')
+                if (obj?.type === 'identifier' && obj.text.endsWith('Store') && prop)
+                    out.push({ store: obj.text, field: prop.text, to: collapseWs(right?.text ?? '') })
+            }
+        }
+        else if (n.type === 'call_expression') {
+            const fn = n.childForFieldName('function')
+            if (fn?.type === 'member_expression') {
+                const obj = fn.childForFieldName('object')
+                const method = fn.childForFieldName('property')
+                if (obj?.type === 'identifier' && obj.text.endsWith('Store') && method) {
+                    const argsNode = n.childForFieldName('arguments') // (a, b) 含括号
+                    const inner = argsNode ? collapseWs(argsNode.text).slice(1, -1).trim() : ''
+                    out.push({ store: obj.text, field: `${method.text}()`, to: '', args: inner })
+                }
+            }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) walk(n.namedChild(i)!)
+    }
+    walk(node)
+    return out
+}
+
+// 在 JSX 开标签里找 label/title 属性的文本（含三元 {a ? '收起' : '展开'} 取首个 string）。
+function labelOf(opening: Node): string | null {
+    for (let i = 0; i < opening.namedChildCount; i++) {
+        const a = opening.namedChild(i)!
+        if (a.type !== 'jsx_attribute') continue
+        if (a.namedChild(0)?.text !== 'label' && a.namedChild(0)?.text !== 'title') continue
+        const val = a.namedChild(1)
+        if (!val) continue
+        if (val.type === 'string') return val.text.slice(1, -1)
+        let found: string | null = null
+        const dig = (n: Node) => {
+            if (found) return
+            if (n.type === 'string') { found = n.text.slice(1, -1); return }
+            for (let j = 0; j < n.namedChildCount; j++) dig(n.namedChild(j)!)
+        }
+        dig(val)
+        if (found) return found
+    }
+    // 无 label/title 属性 → 退回 JSX 子节点的直接文本(如 <button>全部</button> 的「全部」)。
+    // join 键的运行时一侧(DOM elementLabel)读的就是可见文本,故静态侧也必须以文本为准,
+    // 否则文本内容型按钮的 label 恒为 null,与 live DOM 的文本 label 永不相交。
+    const element = opening.parent // jsx_element(opening 的父),其下有 jsx_text 子节点
+    if (element?.type === 'jsx_element') {
+        const parts: string[] = []
+        for (let i = 0; i < element.namedChildCount; i++) {
+            const child = element.namedChild(i)!
+            if (child.type === 'jsx_text') {
+                const t = collapseWs(child.text).trim()
+                if (t) parts.push(t)
+            }
+        }
+        if (parts.length) return parts.join(' ')
+    }
+    return null
+}
+
+// 纯核心：一个文件的源码 → 它声明的所有旋钮。可单测、可 fixture。
+export function extractKnobs(filePath: string, code: string, lang: Language): Knob[] {
+    const parser = new Parser()
+    parser.setLanguage(lang)
+    const tree = parser.parse(code)
+    if (!tree) return []
+
+    const knobs: Knob[] = []
+    for (const c of new Query(lang, ATTR_QUERY).captures(tree.rootNode)) {
+        if (c.name !== 'attr') continue
+        const event = c.node.namedChild(0)?.text
+        if (!event || !event.startsWith('on')) continue
+        const writes = storeWritesIn(c.node)
+        if (!writes.length) continue // handler 没碰 store → 不是状态旋钮（导航等不算）
+
+        const opening = c.node.parent! // jsx_opening_element / jsx_self_closing_element
+        // 同一 field 多次写取末次（顺序执行的终态）；保序去重。
+        const byField = new Map<string, { to: string, args?: string }>()
+        for (const w of writes) byField.set(w.field, { to: w.to, args: w.args })
+        const transitions: Transition[] = [...byField].map(([field, v]) =>
+            v.args !== undefined ? { field, to: v.to, args: v.args } : { field, to: v.to })
+        knobs.push({
+            label: labelOf(opening),
+            tag: opening.childForFieldName('name')?.text ?? '?',
+            event,
+            transitions,
+            store: writes[0].store,
+            filePath,
+            line: c.node.startPosition.row + 1,
+        })
+    }
+    return knobs
+}
+
+// 转移渲染：field=to（toggle 等 to 自明时省略，只显 field）。`mode='im'` / `showSideBar=!showSideBar`。
+export function fmtTransitions(ts: Transition[]): string {
+    return ts.map(t => (t.to ? `${t.field}=${t.to}` : t.field)).join(', ')
+}
+
+// 注入用紧凑渲染：控制面 → markdown 文本，按文件分组。一行一个旋钮：
+//   「名字」 event → store.{ field=to }  :line
+// 这是系统的控制论模型——AI 读它即知"这 App 能干什么、拨它把哪个状态推向什么、改它去哪"。
+export function formatPanel(knobs: Knob[]): string {
+    const byFile = new Map<string, Knob[]>()
+    for (const k of knobs) {
+        const arr = byFile.get(k.filePath) ?? []
+        arr.push(k)
+        byFile.set(k.filePath, arr)
+    }
+    const lines: string[] = []
+    for (const [file, ks] of byFile) {
+        lines.push(file)
+        for (const k of ks) {
+            const name = k.label ? `「${k.label}」` : `<${k.tag}>`
+            lines.push(`  ${name} ${k.event} → ${k.store}.{ ${fmtTransitions(k.transitions)} }  :${k.line}`)
+        }
+    }
+    return lines.join('\n')
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// 态射分类：把一个 Transition 的值域 `to` 判成可执行算子的种类。
+// 绿色通道(executeKnob)按 kind 分派；context 类诚实拒绝，绝不假装能字面 replay。
+// 逐字符 / `includes` 子串判定，禁正则(本仓铁律，同 collapseWs)。
+
+export type KnobKind = 'assign' | 'toggle' | 'call' | 'context'
+export type KnobArity = 'nullary' | 'param'
+
+export interface KnobOp {
+    field: string // store 字段(call 形态含尾 '()')
+    kind: KnobKind
+    arity: KnobArity
+    to?: string // assign/nullary 的字面值原文；assign/param 留空(值由运行时 ?value= 填)
+    reason?: string // context 类:为何不可字面 replay(给 AI 看的拒绝理由)
+}
+
+// 标识符字符:字母/数字/下划线/$。成员路径只含这些 + '.'。
+function isIdentChar(ch: string): boolean {
+    return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')
+        || (ch >= '0' && ch <= '9') || ch === '_' || ch === '$'
+}
+
+// to 是不是自洽字面量:true/false/null 整串 / 引号配对字符串 / 纯数字(含负号小数)。
+function isLiteral(to: string): boolean {
+    if (to === 'true' || to === 'false' || to === 'null') return true
+    if (to.length >= 2) {
+        const q = to[0]
+        if ((q === '\'' || q === '"' || q === '`') && to[to.length - 1] === q) {
+            // 中间不能再有同种未转义引号(排除 `a' + x + 'b` 拼接)
+            for (let i = 1; i < to.length - 1; i++) {
+                if (to[i] === q && to[i - 1] !== '\\') return false
+            }
+            return true
+        }
+    }
+    // 纯数字:可选前导 -，至多一个 .
+    let dot = 0
+    for (let i = 0; i < to.length; i++) {
+        const ch = to[i]
+        if (ch === '-' && i === 0) continue
+        if (ch === '.') { dot++; if (dot > 1) return false; continue }
+        if (ch < '0' || ch > '9') return false
+    }
+    return to.length > 0 && to !== '-' && to !== '.'
+}
+
+// 单一成员路径:只含标识符字符与 '.'，非空，不以 '.' 开头/结尾，无连续 '.'。
+function isMemberPath(s: string): boolean {
+    if (!s || s[0] === '.' || s[s.length - 1] === '.') return false
+    let prevDot = false
+    for (const ch of s) {
+        if (ch === '.') { if (prevDot) return false; prevDot = true; continue }
+        if (!isIdentChar(ch)) return false
+        prevDot = false
+    }
+    return true
+}
+
+// to 是 onChange 回调参数占位符:单段/双段成员路径，段数≤2，首段不以 Store 结尾。
+// `v` / `checked` / `provider.id` / `e2.target` 里 `e2.target` 会被 context 的 e.target 先截走。
+function isPlaceholder(to: string): boolean {
+    if (!isMemberPath(to)) return false
+    const segs = to.split('.')
+    if (segs.length > 2) return false
+    if (segs[0].endsWith('Store')) return false // store 读(appUIStore.x)不是回调参数
+    return true
+}
+
+// 末段字段名:'!appUIStore.showGroupInfo' → 'showGroupInfo'，'!show' → 'show'。
+function lastSeg(path: string): string {
+    const i = path.lastIndexOf('.')
+    return i < 0 ? path : path.slice(i + 1)
+}
+
+export function classifyTransition(t: Transition): KnobOp {
+    const field = t.field
+    const to = t.to
+
+    // ① call 形态:field 以 '()' 结尾。无参 → 可绿色通道直调；带参 → 依赖运行时上下文，拒。
+    if (field.endsWith('()')) {
+        if (t.args && t.args.length > 0)
+            return { field, kind: 'context', arity: 'nullary', reason: `方法带参 ${field.slice(0, -2)}(${t.args})，实参依赖运行时上下文` }
+        return { field, kind: 'call', arity: 'nullary' }
+    }
+
+    // ② 字面量赋值:store[field] = parseLiteral(to)。
+    if (isLiteral(to)) return { field, kind: 'assign', arity: 'nullary', to }
+
+    // ③ toggle:to 形如 !memberPath。
+    if (to.startsWith('!')) {
+        const inner = to.slice(1)
+        if (isMemberPath(inner)) return { field: lastSeg(inner), kind: 'toggle', arity: 'nullary' }
+    }
+
+    // ④ 回调参数占位符:值由运行时 ?value= 注入。
+    if (isPlaceholder(to)) return { field, kind: 'assign', arity: 'param' }
+
+    // ⑤ 其余依赖运行时上下文,诚实拒绝。reason 命中具体特征。
+    // 顺序按「特征具体度」从高到低:数组运算(含内联 => )比裸箭头函数更具体,先判,否则
+    // `items.filter(x => x.on)` 会被裸 `=>` 截成「箭头函数」误读。
+    let reason = '依赖运行时上下文'
+    if (to.includes('e.target') || to.includes('.target.')) reason = '依赖事件对象 e.target'
+    else if (to.includes('.filter(') || to.includes('.map(') || to.includes('.find(')) reason = '数组运算,依赖当前集合'
+    else if (to.includes('...')) reason = '展开运算符,依赖当前快照'
+    else if (to.includes('=>')) reason = '值是箭头函数/闭包'
+    else if (to.includes('?') && to.includes(':')) reason = '三元表达式,依赖运行时分支'
+    else if (to.includes('.message') || to.includes('.id') || to.includes('.name')) reason = '读运行时对象属性'
+    return { field, kind: 'context', arity: 'nullary', reason }
+}
+
+// 整个旋钮(可能多 transition)的综合判定:任一 context → 不可执行;任一 param → 整体需参。
+export function classifyKnob(transitions: Transition[]): { ops: KnobOp[], arity: KnobArity, executable: boolean } {
+    const ops = transitions.map(classifyTransition)
+    const executable = ops.length > 0 && ops.every(o => o.kind !== 'context')
+    const arity: KnobArity = ops.some(o => o.arity === 'param') ? 'param' : 'nullary'
+    return { ops, arity, executable }
+}
+
+// 全仓聚合：一批文件 → 整个 App 的控制面。
+export async function buildPanel(filePaths: string[], contents?: Map<string, string>): Promise<Knob[]> {
+    await Parser.init()
+    const tsx = await getLang('.tsx')
+    if (!tsx) return []
+
+    const panel: Knob[] = []
+    for (const fp of filePaths) {
+        if (!fp.endsWith('.tsx') && !fp.endsWith('.jsx')) continue
+        let code: string
+        if (contents?.has(fp)) code = contents.get(fp)!
+        else {
+            try { code = readFileSync(fp, 'utf-8') }
+            catch { continue }
+        }
+        panel.push(...extractKnobs(fp, code, tsx))
+    }
+    return panel
+}

package/src/read/pipeline.ts

@@ -0,0 +1,78 @@
+import type { FileBlock, FileDetailLevel } from './types.js'
+import ignore from 'ignore'
+
+export const estimateTokens = (s: string) => Math.ceil(s.length / 4)
+
+/**
+ * Sum estimated tokens of all non-empty root-file contents. Used in budget + display.
+ *  Trims content first to match formatOverview's normalization (otherwise the two
+ *  disagree on size for trailing-newline content, and budget math drifts).
+ */
+export function computeOverviewTokens(rootBlocks: FileBlock[]): number {
+    return rootBlocks.reduce((sum, b) => sum + estimateTokens(b.content.trim()), 0)
+}
+
+/**
+ * Budget for the signatures section.
+ *
+ * allocate() internally accounts for per-file tree entries (TREE_ENTRY_TOKENS×N),
+ * so we MUST NOT subtract the rendered src tree tokens here — that would double-count.
+ * We only subtract the static parts: overview + root file tree lines + a small header.
+ */
+export function computeSignaturesBudget(
+    maxTokens: number,
+    overviewTokens: number,
+    rootFileCount: number,
+    headerTokens = 30,
+): number {
+    const rootTreeTokens = rootFileCount * 4 // approx tokens per root file tree line
+    return maxTokens - overviewTokens - rootTreeTokens - headerTokens
+}
+
+/**
+ * Files explicitly named by user via fileDetailLevel globs.
+ * allocate() must not demote these — user intent is a hard constraint.
+ */
+export function computePinnedSet(
+    filePaths: string[],
+    fileDetailLevel: Record<string, FileDetailLevel>,
+): Set<string> {
+    const globs = Object.keys(fileDetailLevel)
+    if (!globs.length)
+        return new Set()
+    const matcher = ignore().add(globs)
+    return new Set(filePaths.filter(p => matcher.ignores(p)))
+}
+
+/** Filter src blocks to those whose display level is 'compact' — goes into signatures section. */
+export function selectSignatureBlocks(
+    srcBlocks: FileBlock[],
+    classifyDisplay: (path: string) => FileDetailLevel,
+): FileBlock[] {
+    return srcBlocks.filter(b => classifyDisplay(b.path) === 'compact')
+}
+
+/** Build raw 'full'-level blocks from paths whose display level is 'full'. */
+export function selectFullBlocks(
+    paths: string[],
+    contents: Map<string, string>,
+    classifyDisplay: (path: string) => FileDetailLevel,
+): FileBlock[] {
+    return paths
+        .filter(p => classifyDisplay(p) === 'full' && contents.get(p)?.trim())
+        .map(p => ({ path: p, level: 'full' as const, content: contents.get(p)! }))
+}
+
+/** Format root blocks into the overview section text. */
+export function formatOverview(blocks: FileBlock[]): string {
+    return blocks
+        .map(b => ({ path: b.path, content: b.content.trim() }))
+        .filter(b => b.content)
+        .map((b) => {
+            const lines = b.content.split('\n')
+            return lines.length > 1
+                ? `${b.path}:\n  ${lines.join('\n  ')}`
+                : `${b.path}: ${b.content}`
+        })
+        .join('\n')
+}