token-pilot 0.16.2 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to Token Pilot will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] - 2026-04-05
+
+### Added
+- **`read_section` tool** — read a specific section from Markdown, YAML, JSON, or CSV files. Markdown: by heading name. YAML/JSON: by top-level key. CSV: by row range (`rows:1-50`). Much cheaper than reading the whole file.
+- **`read_for_edit` section parameter** — prepare edit context for non-code file sections. Works with all 4 formats.
+- **Markdown outline with line ranges** — `smart_read` on `.md` files now shows `[L5-20]` ranges and hints for `read_section`.
+- **YAML/JSON section ranges** — `smart_read` on `.yaml`/`.json` shows top-level key ranges.
+- **CSV smart_read** — shows columns, row count, sample rows, and hints for row-range reading.
+- **4 section parsers** — `markdown-sections.ts`, `yaml-sections.ts`, `json-sections.ts`, `csv-sections.ts`.
+
+### Changed
+- **20 tools** (was 19) — added `read_section`.
+- **492 tests** (was 441).
+
+### Fixed
+- `npm audit` — resolved brace-expansion, path-to-regexp, picomatch vulnerabilities.
+
+## [0.17.0] - 2026-04-02
+
+### Added
+- **`smart_read` scope parameter** — `scope="nav"` returns names + line ranges only (2-3x smaller), `scope="exports"` shows only public API. Default `scope="full"` unchanged.
+- **`smart_read` auto-delta** — when a file changed since last load (within 120s), shows ADDED/REMOVED/UNCHANGED symbols instead of full re-read. Config: `smartRead.autoDelta.enabled`.
+- **`read_symbol` include_edit_context** — optional `include_edit_context=true` appends raw code block (max 60 lines) to save a separate `read_for_edit` call. Large symbols fall back to `read_for_edit`.
+- **`find_usages` mode=list** — compact `file:line` output for initial discovery, 5-10x smaller than full mode.
+- **`smart_read_many` per-file dedup** — skips files already in context and unchanged, returns compact reminder instead.
+- **Actionable hints** — `read_for_edit` suggests `read_diff` after editing. Config: `display.actionableHints`.
+- **`symbol-display-constants.ts`** — shared display constants for symbol rendering.
+
+### Changed
+- **441 tests** (was 427) — new tests for scope, list mode, include_edit_context, dedup.
+- **MCP instructions** updated with scope/mode/include_edit_context guidance.
+- **find_usages context rendering** — sequential instead of concurrent to prevent shared cache race condition.
+
 ## [0.16.1] - 2026-03-21
 
 ### Added

package/dist/config/defaults.js

@@ -12,6 +12,10 @@ export const DEFAULT_CONFIG = {
         smallFileThreshold: 200,
         showDependencyHints: true,
         advisoryReminders: true,
+        autoDelta: {
+            enabled: true,
+            maxAgeSec: 120,
+        },
     },
     git: {
         watchHead: true,
@@ -33,6 +37,7 @@ export const DEFAULT_CONFIG = {
         showReferences: false,
         maxDepth: 2,
         showTokenSavings: true,
+        actionableHints: true,
     },
     contextMode: {
         enabled: 'auto',

package/dist/core/context-registry.d.ts

@@ -40,6 +40,10 @@ export declare class ContextRegistry {
         entries: ContextEntry[];
     };
     estimateTokens(): number;
+    trackStructureSymbols(path: string, symbolNames: string[]): void;
+    getSymbolNames(path: string): string[] | undefined;
+    /** Get the timestamp when a file was last loaded into context. */
+    getLoadedAt(path: string): number | undefined;
     invalidateByGitDiff(changedFiles: string[]): void;
 }
 //# sourceMappingURL=context-registry.d.ts.map

package/dist/core/context-registry.js

@@ -182,6 +182,19 @@ export class ContextRegistry {
         }
         return total;
     }
+    trackStructureSymbols(path, symbolNames) {
+        const entry = this.entries.get(path);
+        if (entry) {
+            entry.symbolNames = symbolNames;
+        }
+    }
+    getSymbolNames(path) {
+        return this.entries.get(path)?.symbolNames;
+    }
+    /** Get the timestamp when a file was last loaded into context. */
+    getLoadedAt(path) {
+        return this.entries.get(path)?.loadedAt;
+    }
     invalidateByGitDiff(changedFiles) {
         for (const file of changedFiles) {
             this.entries.delete(file);

package/dist/core/validation.d.ts

@@ -59,6 +59,7 @@ export interface FindUsagesArgs {
     limit?: number;
     lang?: string;
     context_lines?: number;
+    mode?: 'full' | 'list';
 }
 export declare function validateFindUsagesArgs(args: unknown): FindUsagesArgs;
 /**
@@ -79,6 +80,7 @@ export declare function validateReadForEditArgs(args: unknown): {
     include_callers?: boolean;
     include_tests?: boolean;
     include_changes?: boolean;
+    section?: string;
 };
 /**
  * Validate related_files arguments.
@@ -154,6 +156,10 @@ export interface TestSummaryArgs {
     timeout?: number;
 }
 export declare function validateTestSummaryArgs(args: unknown): TestSummaryArgs;
+export declare function validateReadSectionArgs(args: unknown): {
+    path: string;
+    heading: string;
+};
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export declare function isDangerousRoot(root: string): boolean;
 //# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.js

@@ -160,6 +160,14 @@ export function validateFindUsagesArgs(args) {
     if (context_lines !== undefined && (context_lines < 0 || context_lines > 10)) {
         throw new Error('"context_lines" must be between 0 and 10.');
     }
+    let mode;
+    if (a.mode !== undefined && a.mode !== null) {
+        const validModes = ['full', 'list'];
+        if (typeof a.mode !== 'string' || !validModes.includes(a.mode)) {
+            throw new Error(`"mode" must be one of: ${validModes.join(', ')}`);
+        }
+        mode = a.mode;
+    }
     return {
         symbol: a.symbol,
         scope: optionalString(a.scope, 'scope'),
@@ -167,6 +175,7 @@ export function validateFindUsagesArgs(args) {
         limit,
         lang: optionalString(a.lang, 'lang'),
         context_lines,
+        mode,
     };
 }
 /**
@@ -219,8 +228,8 @@ export function validateReadForEditArgs(args) {
     if (typeof a.path !== 'string' || a.path.length === 0) {
         throw new Error('Required parameter "path" must be a non-empty string.');
     }
-    if (!a.symbol && !a.line && (!Array.isArray(a.symbols) || a.symbols.length === 0)) {
-        throw new Error('Either "symbol", "symbols", or "line" must be provided.');
+    if (!a.symbol && !a.line && (!Array.isArray(a.symbols) || a.symbols.length === 0) && !a.section) {
+        throw new Error('Either "symbol", "symbols", "line", or "section" must be provided.');
     }
     // Validate symbols array (batch mode)
     let symbols;
@@ -247,6 +256,7 @@ export function validateReadForEditArgs(args) {
         include_callers: optionalBool(a.include_callers, 'include_callers'),
         include_tests: optionalBool(a.include_tests, 'include_tests'),
         include_changes: optionalBool(a.include_changes, 'include_changes'),
+        section: optionalString(a.section, 'section'),
     };
 }
 /**
@@ -444,6 +454,19 @@ export function validateTestSummaryArgs(args) {
     }
     return { command: a.command, runner, timeout };
 }
+export function validateReadSectionArgs(args) {
+    if (!args || typeof args !== 'object') {
+        throw new Error('Arguments must be an object.');
+    }
+    const a = args;
+    if (typeof a.path !== 'string' || a.path.length === 0) {
+        throw new Error('Required parameter "path" must be a non-empty string.');
+    }
+    if (typeof a.heading !== 'string' || a.heading.length === 0) {
+        throw new Error('Required parameter "heading" must be a non-empty string.');
+    }
+    return { path: a.path, heading: a.heading };
+}
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export function isDangerousRoot(root) {
     const normalized = root.replace(/\/+$/, '') || '/';

package/dist/formatters/structure.d.ts

@@ -5,6 +5,7 @@ export interface FormatOptions {
     showDependencyHints?: boolean;
     maxDepth?: number;
     showTokenSavings?: boolean;
+    scope?: 'full' | 'nav' | 'exports';
 }
 /**
  * Format a FileStructure as token-optimized text for LLMs.

package/dist/formatters/structure.js

@@ -2,13 +2,48 @@
  * Format a FileStructure as token-optimized text for LLMs.
  */
 export function formatOutline(structure, options = {}) {
-    const { showImports = true, showDocs = true, showDependencyHints = true, maxDepth = 2, } = options;
+    const { showImports = true, showDocs = true, showDependencyHints = true, maxDepth = 2, scope = 'full', } = options;
     const lines = [];
     // Header
     const sizeKB = (structure.meta.bytes / 1024).toFixed(1);
-    lines.push(`FILE: ${structure.path} (${structure.meta.lines} lines, ${sizeKB}KB)`);
+    const scopeLabel = scope !== 'full' ? `, ${scope} mode` : '';
+    lines.push(`FILE: ${structure.path} (${structure.meta.lines} lines, ${sizeKB}KB${scopeLabel})`);
     lines.push(`LANGUAGE: ${structure.language}`);
     lines.push('');
+    // NAV scope: compact names + line ranges only
+    if (scope === 'nav') {
+        lines.push('SYMBOLS:');
+        for (const sym of structure.symbols) {
+            formatSymbolNav(sym, lines, 1, maxDepth);
+        }
+        lines.push('');
+        lines.push('HINT: Use scope="full" for type signatures and imports. Use read_symbol(path, symbol) to load code.');
+        return lines.join('\n');
+    }
+    // EXPORTS scope: only exported symbols
+    if (scope === 'exports') {
+        const exportNames = new Set(structure.exports.map(e => e.name));
+        const exportedSymbols = structure.symbols.filter(s => exportNames.has(s.name));
+        const hiddenCount = structure.symbols.length - exportedSymbols.length;
+        lines.push('EXPORTS:');
+        for (const exp of structure.exports) {
+            const defaultLabel = exp.isDefault ? ' (default)' : '';
+            lines.push(`  ${exp.kind} ${exp.name}${defaultLabel}`);
+        }
+        lines.push('');
+        lines.push('STRUCTURE:');
+        for (const sym of exportedSymbols) {
+            formatSymbolTree(sym, lines, 1, maxDepth, showDocs, showDependencyHints);
+        }
+        lines.push('');
+        if (hiddenCount > 0) {
+            lines.push(`HINT: ${hiddenCount} non-exported symbol(s) hidden. Use scope="full" to see all symbols.`);
+        }
+        else {
+            lines.push('HINT: Use read_symbol(path, symbol) to load a specific symbol\'s code.');
+        }
+        return lines.join('\n');
+    }
     // Imports
     if (showImports && structure.imports.length > 0) {
         lines.push('IMPORTS:');
@@ -111,6 +146,17 @@ function formatSymbolTree(sym, lines, depth, maxDepth, showDocs, showDeps, paren
         lines.push(`${indent}  (${sym.children.length} members — increase depth to see)`);
     }
 }
+function formatSymbolNav(sym, lines, depth, maxDepth) {
+    const indent = '  '.repeat(depth);
+    const loc = `[L${sym.location.startLine}-${sym.location.endLine}]`;
+    const callable = sym.kind === 'function' || sym.kind === 'method' ? '()' : '';
+    lines.push(`${indent}${sym.name}${callable} ${loc}`);
+    if (depth < maxDepth && sym.children.length > 0) {
+        for (const child of sym.children) {
+            formatSymbolNav(child, lines, depth + 1, maxDepth);
+        }
+    }
+}
 /**
  * Detect HTTP route decorators and format as "METHOD /path".
  * Uses standard HTTP verbs — not framework-specific.

package/dist/handlers/csv-sections.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CSV parser — column-aware reading with row/column subsetting.
+ */
+export interface CsvOutline {
+    columns: string[];
+    rowCount: number;
+    sampleRows: string[][];
+}
+export interface CsvSection {
+    heading: string;
+    startLine: number;
+    endLine: number;
+    lineCount: number;
+}
+/**
+ * Parse CSV into an outline: columns, row count, sample.
+ * Simple parser — handles quoted fields with commas.
+ */
+export declare function parseCsvOutline(content: string): CsvOutline;
+/**
+ * Parse a row range specification into a CsvSection.
+ * Supported formats:
+ *   "rows:1-50" — row range (1-indexed, refers to data rows, not header)
+ *   "rows:1-50" with column filter isn't supported at section level
+ */
+export declare function parseCsvSectionSpec(heading: string, totalDataRows: number): CsvSection | null;
+/**
+ * Extract CSV rows for a section. Returns header + requested rows.
+ */
+export declare function extractCsvSectionContent(lines: string[], section: CsvSection): string;
+/**
+ * Format CSV outline for smart_read output.
+ */
+export declare function formatCsvOutline(filePath: string, outline: CsvOutline, lineCount: number): string;
+//# sourceMappingURL=csv-sections.d.ts.map

package/dist/handlers/csv-sections.js

@@ -0,0 +1,129 @@
+/**
+ * CSV parser — column-aware reading with row/column subsetting.
+ */
+/**
+ * Parse CSV into an outline: columns, row count, sample.
+ * Simple parser — handles quoted fields with commas.
+ */
+export function parseCsvOutline(content) {
+    const lines = content.split('\n').filter(l => l.trim());
+    if (lines.length === 0)
+        return { columns: [], rowCount: 0, sampleRows: [] };
+    const columns = parseCsvRow(lines[0]);
+    const dataLines = lines.slice(1);
+    const sampleRows = dataLines.slice(0, 5).map(parseCsvRow);
+    return {
+        columns,
+        rowCount: dataLines.length,
+        sampleRows,
+    };
+}
+/**
+ * Parse a row range specification into a CsvSection.
+ * Supported formats:
+ *   "rows:1-50" — row range (1-indexed, refers to data rows, not header)
+ *   "rows:1-50" with column filter isn't supported at section level
+ */
+export function parseCsvSectionSpec(heading, totalDataRows) {
+    // rows:N-M format
+    const rowMatch = heading.match(/^rows?:\s*(\d+)\s*-\s*(\d+)$/i);
+    if (rowMatch) {
+        const start = Math.max(1, parseInt(rowMatch[1], 10));
+        const end = Math.min(totalDataRows, parseInt(rowMatch[2], 10));
+        if (start > end || start > totalDataRows)
+            return null;
+        // +1 for header line offset
+        return {
+            heading: `rows ${start}-${end}`,
+            startLine: start + 1, // +1 because line 1 is header
+            endLine: end + 1,
+            lineCount: end - start + 1,
+        };
+    }
+    // Single row number
+    const singleMatch = heading.match(/^rows?:\s*(\d+)$/i);
+    if (singleMatch) {
+        const row = parseInt(singleMatch[1], 10);
+        if (row < 1 || row > totalDataRows)
+            return null;
+        return {
+            heading: `row ${row}`,
+            startLine: row + 1,
+            endLine: row + 1,
+            lineCount: 1,
+        };
+    }
+    return null;
+}
+/**
+ * Extract CSV rows for a section. Returns header + requested rows.
+ */
+export function extractCsvSectionContent(lines, section) {
+    const header = lines[0]; // always include header
+    const dataRows = lines.slice(section.startLine - 1, section.endLine);
+    return [header, ...dataRows].join('\n');
+}
+/**
+ * Parse a single CSV row handling quoted fields.
+ */
+function parseCsvRow(line) {
+    const fields = [];
+    let current = '';
+    let inQuote = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuote) {
+            if (ch === '"') {
+                if (i + 1 < line.length && line[i + 1] === '"') {
+                    current += '"';
+                    i++; // skip escaped quote
+                }
+                else {
+                    inQuote = false;
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inQuote = true;
+            }
+            else if (ch === ',') {
+                fields.push(current.trim());
+                current = '';
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    fields.push(current.trim());
+    return fields;
+}
+/**
+ * Format CSV outline for smart_read output.
+ */
+export function formatCsvOutline(filePath, outline, lineCount) {
+    const lines = [
+        `FILE: ${filePath} (${lineCount} lines, CSV)`,
+        '',
+        `COLUMNS (${outline.columns.length}): ${outline.columns.join(', ')}`,
+        `ROWS: ${outline.rowCount}`,
+        '',
+    ];
+    if (outline.sampleRows.length > 0) {
+        lines.push(`SAMPLE (first ${outline.sampleRows.length} rows):`);
+        for (const row of outline.sampleRows) {
+            // Format as: col1=val1, col2=val2, ...
+            const pairs = outline.columns.map((col, i) => `${col}=${row[i] ?? ''}`);
+            lines.push(`  ${pairs.join(', ')}`);
+        }
+    }
+    lines.push('');
+    lines.push(`HINT: Use read_section("${filePath}", heading="rows:1-50") to load specific rows.`);
+    lines.push(`      Use read_section("${filePath}", heading="rows:${outline.rowCount}") for last row.`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=csv-sections.js.map

package/dist/handlers/find-usages.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { assessConfidence, formatConfidence } from '../core/confidence.js';
 /**
@@ -53,10 +53,15 @@ function renderSection(title, items) {
     lines.push('');
     return lines;
 }
+/** Max unique files to read for context (prevents unbounded I/O). */
+const MAX_CONTEXT_FILES = 30;
+/** Max file size (bytes) to read for context lines. */
+const MAX_CONTEXT_FILE_SIZE = 500_000;
 /**
  * Render a section with surrounding source context lines.
+ * Uses shared fileCache to avoid re-reading the same file across sections.
  */
-async function renderSectionWithContext(title, items, contextLines, projectRoot) {
+async function renderSectionWithContext(title, items, contextLines, projectRoot, fileCache) {
     if (items.length === 0)
         return [];
     const lines = [`${title}:`];
@@ -66,17 +71,30 @@ async function renderSectionWithContext(title, items, contextLines, projectRoot)
         arr.push({ line: item.line, text: item.text });
         byFile.set(item.file, arr);
     }
+    let filesRead = 0;
     for (const [file, matches] of byFile) {
         matches.sort((a, b) => a.line - b.line);
         lines.push(`  ${file}:`);
-        // Read file for context
+        // Read file for context (with shared cache and limits)
         let fileLines = null;
-        try {
-            const content = await readFile(resolve(projectRoot, file), 'utf-8');
-            fileLines = content.split('\n');
+        if (fileCache.has(file)) {
+            fileLines = fileCache.get(file);
         }
-        catch {
-            // File unreadable — fall back to text-only
+        else if (filesRead < MAX_CONTEXT_FILES) {
+            try {
+                const fileStat = await stat(resolve(projectRoot, file));
+                if (fileStat.size <= MAX_CONTEXT_FILE_SIZE) {
+                    const content = await readFile(resolve(projectRoot, file), 'utf-8');
+                    fileLines = content.split('\n');
+                }
+            }
+            catch {
+                // File unreadable
+            }
+            fileCache.set(file, fileLines);
+            filesRead++;
+        }
+        if (!fileLines) {
             for (const m of matches) {
                 lines.push(`    :${m.line}  ${m.text}`);
             }
@@ -218,6 +236,36 @@ export async function handleFindUsages(args, astIndex, projectRoot) {
             meta: { files: [], definitions: 0, imports: 0, usages: 0, total: 0 },
         };
     }
+    // ─── List mode — compact file:line output ───
+    if (args.mode === 'list') {
+        const allItems = [...definitions, ...allImports, ...allUsages];
+        const byFile = new Map();
+        for (const item of allItems) {
+            const arr = byFile.get(item.file) ?? [];
+            arr.push(item.line);
+            byFile.set(item.file, arr);
+        }
+        const listLines = [
+            `USAGES OF "${args.symbol}" (${allItems.length} matches in ${byFile.size} files):`,
+            '',
+        ];
+        for (const [file, fileLines] of byFile) {
+            const sorted = [...new Set(fileLines)].sort((a, b) => a - b);
+            listLines.push(`  ${file}: L${sorted.join(', L')}`);
+        }
+        listLines.push('');
+        listLines.push(`HINT: Use find_usages("${args.symbol}", path="specific_dir/") to narrow, or read_symbol() on specific matches.`);
+        return {
+            content: [{ type: 'text', text: listLines.join('\n') }],
+            meta: {
+                files: Array.from(byFile.keys()),
+                definitions: definitions.length,
+                imports: allImports.length,
+                usages: allUsages.length,
+                total: allItems.length,
+            },
+        };
+    }
     // Build header with active filters
     const filterHints = [];
     if (args.scope)
@@ -232,11 +280,11 @@ export async function handleFindUsages(args, astIndex, projectRoot) {
         '',
     ];
     if (args.context_lines !== undefined && args.context_lines > 0 && projectRoot) {
-        const [defSection, impSection, useSection] = await Promise.all([
-            renderSectionWithContext('DEFINITIONS', definitions, args.context_lines, projectRoot),
-            renderSectionWithContext('IMPORTS', allImports, args.context_lines, projectRoot),
-            renderSectionWithContext('USAGES', allUsages, args.context_lines, projectRoot),
-        ]);
+        // Shared file cache across sections — sequential to avoid concurrent Map writes
+        const contextFileCache = new Map();
+        const defSection = await renderSectionWithContext('DEFINITIONS', definitions, args.context_lines, projectRoot, contextFileCache);
+        const impSection = await renderSectionWithContext('IMPORTS', allImports, args.context_lines, projectRoot, contextFileCache);
+        const useSection = await renderSectionWithContext('USAGES', allUsages, args.context_lines, projectRoot, contextFileCache);
         lines.push(...defSection);
         lines.push(...impSection);
         lines.push(...useSection);
@@ -247,6 +295,10 @@ export async function handleFindUsages(args, astIndex, projectRoot) {
         lines.push(...renderSection('USAGES', allUsages));
     }
     lines.push('HINT: Use read_symbol() or read_range() to load specific results.');
+    if (totalCount > 20) {
+        lines.push('');
+        lines.push(`NARROW: ${totalCount} matches found. Use find_usages("${args.symbol}", path="specific_dir/") to filter by location.`);
+    }
     // Confidence metadata
     const confidenceMeta = assessConfidence({
         refsFound: totalCount > 0,

package/dist/handlers/json-sections.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JSON section parser — parses top-level keys with line ranges.
+ */
+export interface JsonSection {
+    heading: string;
+    startLine: number;
+    endLine: number;
+    lineCount: number;
+}
+/**
+ * Parse JSON into sections based on top-level keys.
+ * Works with formatted JSON (pretty-printed). For minified JSON, returns empty.
+ */
+export declare function parseJsonSections(content: string): JsonSection[];
+export declare function findJsonSection(sections: JsonSection[], heading: string): JsonSection | undefined;
+export declare function extractJsonSectionContent(lines: string[], section: JsonSection): string;
+//# sourceMappingURL=json-sections.d.ts.map

package/dist/handlers/json-sections.js

@@ -0,0 +1,66 @@
+/**
+ * JSON section parser — parses top-level keys with line ranges.
+ */
+/**
+ * Parse JSON into sections based on top-level keys.
+ * Works with formatted JSON (pretty-printed). For minified JSON, returns empty.
+ */
+export function parseJsonSections(content) {
+    if (!content.trim())
+        return [];
+    const lines = content.split('\n');
+    if (lines.length < 3)
+        return []; // minified or trivial
+    // Find top-level keys: lines matching /^\s{0,2}"key":/ (0-2 spaces indent = top level)
+    const topKeys = [];
+    // Track brace depth to identify top-level
+    let depth = 0;
+    let inString = false;
+    let lineIdx = 0;
+    for (lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const line = lines[lineIdx];
+        // Simple top-level key detection: at depth 1 (inside root object)
+        // Match: "key": or "key" : at the beginning of a line (with indent)
+        if (depth === 1) {
+            const keyMatch = line.match(/^\s*"([^"]+)"\s*:/);
+            if (keyMatch) {
+                topKeys.push({ key: keyMatch[1], line: lineIdx + 1 });
+            }
+        }
+        // Track depth (simplified — doesn't handle strings perfectly but good enough for formatted JSON)
+        for (let ci = 0; ci < line.length; ci++) {
+            const ch = line[ci];
+            if (ch === '"' && (ci === 0 || line[ci - 1] !== '\\')) {
+                inString = !inString;
+            }
+            if (!inString) {
+                if (ch === '{' || ch === '[')
+                    depth++;
+                if (ch === '}' || ch === ']')
+                    depth--;
+            }
+        }
+    }
+    if (topKeys.length === 0)
+        return [];
+    const sections = [];
+    for (let i = 0; i < topKeys.length; i++) {
+        const start = topKeys[i].line;
+        const end = i + 1 < topKeys.length ? topKeys[i + 1].line - 1 : lines.length - 1; // -1 to exclude closing }
+        sections.push({
+            heading: topKeys[i].key,
+            startLine: start,
+            endLine: end,
+            lineCount: end - start + 1,
+        });
+    }
+    return sections;
+}
+export function findJsonSection(sections, heading) {
+    const normalized = heading.trim().toLowerCase();
+    return sections.find(s => s.heading.toLowerCase() === normalized);
+}
+export function extractJsonSectionContent(lines, section) {
+    return lines.slice(section.startLine - 1, section.endLine).join('\n');
+}
+//# sourceMappingURL=json-sections.js.map

package/dist/handlers/markdown-sections.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Markdown section parser — shared helper for section-aware tools.
+ * Parses heading structure with line ranges for targeted reading.
+ */
+export interface MarkdownSection {
+    heading: string;
+    level: number;
+    startLine: number;
+    endLine: number;
+    lineCount: number;
+}
+export declare function parseMarkdownSections(content: string): MarkdownSection[];
+export declare function findSection(sections: MarkdownSection[], heading: string): MarkdownSection | undefined;
+export declare function extractSectionContent(lines: string[], section: MarkdownSection): string;
+//# sourceMappingURL=markdown-sections.d.ts.map