mustflow 2.75.2 → 2.84.0

package/dist/core/code-outline.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { ensureInside, ensureInsideWithoutSymlinks, readFileInsideWithoutSymlinks } from './safe-filesystem.js';
-import { parseSourceAnchorsInContent, sourceAnchorTextContainsSecretLike, splitSourceAnchorList, } from './source-anchors.js';
+import { listSourceAnchorFiles, parseSourceAnchorsInContent, sourceAnchorTextContainsSecretLike, splitSourceAnchorList, } from './source-anchors.js';
 export const CODE_PACK_ID = 'code';
 export const CODE_OUTLINE_SCRIPT_ID = 'outline';
 export const CODE_OUTLINE_SCRIPT_REF = `${CODE_PACK_ID}/${CODE_OUTLINE_SCRIPT_ID}`;
@@ -13,7 +13,12 @@ const DEFAULT_MAX_FILES = 200;
 const DEFAULT_CONTEXT_LINES = 0;
 const DEFAULT_MAX_SNIPPET_LINES = 250;
 const RETURN_PREVIEW_MAX_CHARS = 120;
-const CODE_FILE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const TYPESCRIPT_JAVASCRIPT_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const ASTRO_EXTENSIONS = ['.astro'];
+const SVELTE_EXTENSIONS = ['.svelte'];
+const GO_EXTENSIONS = ['.go'];
+const RUST_EXTENSIONS = ['.rs'];
+const PYTHON_EXTENSIONS = ['.py'];
 const IGNORED_DIRECTORIES = [
     '.git',
     '.mustflow/cache',
@@ -36,6 +41,9 @@ const ERROR_SYMBOL_READ_CODES = new Set([
     'code_symbol_read_unreadable_path',
     'code_symbol_read_invalid_range',
     'code_symbol_read_no_symbol_at_line',
+    'code_symbol_read_anchor_not_found',
+    'code_symbol_read_anchor_ambiguous',
+    'code_symbol_read_anchor_without_symbol',
     'code_symbol_read_snippet_too_large',
 ]);
 function toPosixPath(value) {
@@ -47,7 +55,7 @@ function normalizeRelativePath(value) {
 function sha256Tagged(buffer) {
     return `sha256:${createHash('sha256').update(buffer).digest('hex')}`;
 }
-function languageForPath(filePath) {
+function typescriptJavascriptLanguageForPath(filePath) {
     switch (path.extname(filePath).toLowerCase()) {
         case '.ts':
         case '.mts':
@@ -67,6 +75,27 @@ function languageForPath(filePath) {
             return null;
     }
 }
+function astroLanguageForPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.astro' ? 'astro' : null;
+}
+function svelteLanguageForPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.svelte' ? 'svelte' : null;
+}
+function goLanguageForPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.go' ? 'go' : null;
+}
+function rustLanguageForPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.rs' ? 'rust' : null;
+}
+function pythonLanguageForPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.py' ? 'python' : null;
+}
+function languageAdapterForPath(filePath) {
+    return CODE_OUTLINE_LANGUAGE_ADAPTERS.find((adapter) => adapter.languageForPath(filePath) !== null) ?? null;
+}
+export function languageForPath(filePath) {
+    return languageAdapterForPath(filePath)?.languageForPath(filePath) ?? null;
+}
 function isIgnoredDirectory(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
     return IGNORED_DIRECTORIES.some((directory) => normalized === directory || normalized.startsWith(`${directory}/`));
@@ -206,6 +235,7 @@ function declarationFromLine(line) {
             name: functionMatch.groups.name ?? '<anonymous>',
             exported: Boolean(functionMatch.groups.exported),
             async: Boolean(functionMatch.groups.async),
+            returnType: null,
         };
     }
     const shapeMatch = /^(?<exported>export\s+)?(?<kind>class|interface|type|enum)\s+(?<name>[$A-Z_a-z][$\w]*)/u.exec(trimmed);
@@ -215,6 +245,7 @@ function declarationFromLine(line) {
             name: shapeMatch.groups.name ?? '<anonymous>',
             exported: Boolean(shapeMatch.groups.exported),
             async: false,
+            returnType: null,
         };
     }
     const variableMatch = /^(?<exported>export\s+)?(?:const|let|var)\s+(?<name>[$A-Z_a-z][$\w]*)\s*[:=]/u.exec(trimmed);
@@ -224,6 +255,7 @@ function declarationFromLine(line) {
             name: variableMatch.groups.name ?? '<anonymous>',
             exported: Boolean(variableMatch.groups.exported),
             async: /async\s*(?:\(|[A-Z_a-z_$])/u.test(trimmed),
+            returnType: null,
         };
     }
     return null;
@@ -256,7 +288,7 @@ function buildSignature(lines, startLine, endLine) {
         if (trimmed.length > 0) {
             parts.push(trimmed);
         }
-        if (/[{;]\s*$/u.test(trimmed) || /=>/u.test(trimmed)) {
+        if (/[{;]\s*$/u.test(trimmed) || /=>/u.test(trimmed) || /^(?:async\s+)?(?:def|class)\b.*:\s*$/u.test(trimmed)) {
             break;
         }
     }
@@ -270,6 +302,9 @@ function extractExplicitReturnType(signature, match) {
     if (match.kind !== 'function') {
         return null;
     }
+    if (match.returnType !== null) {
+        return match.returnType;
+    }
     const functionReturnMatch = /\bfunction(?:\s+[$A-Z_a-z][$\w]*)?\s*\([^)]*\)\s*:\s*(?<returnType>[^={;]+?)(?=\s*(?:\{|$))/u.exec(signature);
     if (functionReturnMatch?.groups?.returnType) {
         return normalizeReturnType(functionReturnMatch.groups.returnType);
@@ -304,7 +339,7 @@ function extractArrowExpressionReturnPreview(signature) {
 function isIdentifierCharacter(value) {
     return typeof value === 'string' && /[$\w]/u.test(value);
 }
-function findReturnKeywordIndex(line) {
+function findReturnKeywordIndex(line, lineCommentStart) {
     let quote = null;
     let escaped = false;
     for (let index = 0; index < line.length; index += 1) {
@@ -324,7 +359,8 @@ function findReturnKeywordIndex(line) {
             }
             continue;
         }
-        if (character === '/' && nextCharacter === '/') {
+        if ((lineCommentStart === '//' && character === '/' && nextCharacter === '/') ||
+            (lineCommentStart === '#' && character === '#')) {
             return -1;
         }
         if (character === '"' || character === "'" || character === '`') {
@@ -339,21 +375,21 @@ function findReturnKeywordIndex(line) {
     }
     return -1;
 }
-function extractReturnExpressionPreview(line) {
-    const returnIndex = findReturnKeywordIndex(line);
+function extractReturnExpressionPreview(line, lineCommentStart) {
+    const returnIndex = findReturnKeywordIndex(line, lineCommentStart);
     if (returnIndex < 0) {
         return null;
     }
-    const expression = line
-        .slice(returnIndex + 'return'.length)
-        .replace(/\/\/.*$/u, '')
+    const rawExpression = line.slice(returnIndex + 'return'.length);
+    const commentIndex = rawExpression.indexOf(lineCommentStart);
+    const expression = (commentIndex >= 0 ? rawExpression.slice(0, commentIndex) : rawExpression)
         .trim()
         .replace(/;\s*$/u, '')
         .trim();
     return expression.length === 0 ? null : truncateReturnPreview(expression);
 }
-function hasReturnStatement(line) {
-    return findReturnKeywordIndex(line) >= 0;
+function hasReturnStatement(line, lineCommentStart) {
+    return findReturnKeywordIndex(line, lineCommentStart) >= 0;
 }
 function simpleBodyThrowsOnly(lines, startLine, endLine, returnType) {
     let sawThrow = false;
@@ -373,7 +409,26 @@ function simpleBodyThrowsOnly(lines, startLine, endLine, returnType) {
     }
     return sawThrow && (!sawOtherExecutableLine || returnType === 'never');
 }
-function extractReturnMetadata(lines, startLine, endLine, signature, match) {
+function stripLineComment(line, lineCommentStart) {
+    const commentIndex = line.indexOf(lineCommentStart);
+    return commentIndex >= 0 ? line.slice(0, commentIndex) : line;
+}
+function extractTailExpressionReturnPreview(lines, startLine, endLine) {
+    let index = endLine - 2;
+    while (index >= startLine) {
+        const trimmed = stripLineComment(lines[index] ?? '', '//').trim();
+        if (trimmed.length === 0 || trimmed === '{' || trimmed === '}') {
+            index -= 1;
+            continue;
+        }
+        if (trimmed.endsWith(';') || /^(?:let|return|if|for|while|loop|match)\b/u.test(trimmed)) {
+            return null;
+        }
+        return truncateReturnPreview(trimmed.replace(/,\s*$/u, ''));
+    }
+    return null;
+}
+function extractReturnMetadata(lines, startLine, endLine, signature, match, lineCommentStart = '//', tailExpressionReturn = false) {
     const returnType = extractExplicitReturnType(signature, match);
     if (match.kind !== 'function') {
         return {
@@ -389,11 +444,11 @@ function extractReturnMetadata(lines, startLine, endLine, signature, match) {
     let voidReturnCount = 0;
     for (let index = startLine - 1; index < endLine; index += 1) {
         const line = lines[index] ?? '';
-        if (!hasReturnStatement(line)) {
+        if (!hasReturnStatement(line, lineCommentStart)) {
             continue;
         }
         returnLines.push(index + 1);
-        const preview = extractReturnExpressionPreview(line);
+        const preview = extractReturnExpressionPreview(line, lineCommentStart);
         if (preview === null) {
             voidReturnCount += 1;
         }
@@ -402,11 +457,12 @@ function extractReturnMetadata(lines, startLine, endLine, signature, match) {
         }
     }
     const arrowExpressionPreview = returnLines.length === 0 ? extractArrowExpressionReturnPreview(signature) : null;
+    const tailExpressionPreview = tailExpressionReturn && returnLines.length === 0 && returnType !== null ? extractTailExpressionReturnPreview(lines, startLine, endLine) : null;
     let returnBehavior;
     if (valueReturnPreviews.length > 0 && voidReturnCount > 0) {
         returnBehavior = 'mixed';
     }
-    else if (valueReturnPreviews.length > 0 || arrowExpressionPreview !== null) {
+    else if (valueReturnPreviews.length > 0 || arrowExpressionPreview !== null || tailExpressionPreview !== null) {
         returnBehavior = 'value';
     }
     else if (voidReturnCount > 0) {
@@ -423,21 +479,141 @@ function extractReturnMetadata(lines, startLine, endLine, signature, match) {
         return_behavior: returnBehavior,
         return_count: returnLines.length,
         return_lines: returnLines,
-        return_preview: valueReturnPreviews[0] ?? arrowExpressionPreview,
+        return_preview: valueReturnPreviews[0] ?? arrowExpressionPreview ?? tailExpressionPreview,
     };
 }
-function extractSymbols(relativePath, language, contentSha256, text) {
+function startsWithUppercase(value) {
+    const [first] = value;
+    return typeof first === 'string' && first.toLocaleUpperCase() === first && first.toLocaleLowerCase() !== first;
+}
+function goDeclarationFromLine(line) {
+    const trimmed = line.trim();
+    const functionMatch = /^func\s+(?:\([^)]*\)\s*)?(?<name>[A-Z_a-z]\w*)\s*\([^)]*\)\s*(?<returnType>[^{]+?)?\s*(?:\{|$)/u.exec(trimmed);
+    if (functionMatch?.groups) {
+        const returnType = functionMatch.groups.returnType?.trim() ?? '';
+        return {
+            kind: 'function',
+            name: functionMatch.groups.name ?? '<anonymous>',
+            exported: startsWithUppercase(functionMatch.groups.name ?? ''),
+            async: false,
+            returnType: returnType.length > 0 ? normalizeReturnType(returnType) : null,
+        };
+    }
+    const typeMatch = /^type\s+(?<name>[A-Z_a-z]\w*)\s+(?<shape>struct|interface)?\b/u.exec(trimmed);
+    if (typeMatch?.groups) {
+        return {
+            kind: typeMatch.groups.shape === 'interface' ? 'interface' : 'type',
+            name: typeMatch.groups.name ?? '<anonymous>',
+            exported: startsWithUppercase(typeMatch.groups.name ?? ''),
+            async: false,
+            returnType: null,
+        };
+    }
+    return null;
+}
+function rustDeclarationFromLine(line) {
+    const trimmed = line.trim();
+    const visibility = String.raw `(?:pub(?:\([^)]*\))?\s+)?`;
+    const functionPattern = [
+        String.raw `^${visibility}`,
+        String.raw `(?:(?:async|const|unsafe)\s+)*`,
+        String.raw `(?:extern\s+"[^"]+"\s+)?`,
+        String.raw `fn\s+(?<name>[A-Z_a-z]\w*)\s*[^{;]*?`,
+        String.raw `(?:->\s*(?<returnType>[^{]+?))?\s*(?:where\b|\{|$)`,
+    ].join('');
+    const functionMatch = new RegExp(functionPattern, 'u').exec(trimmed);
+    if (functionMatch?.groups) {
+        const returnType = functionMatch.groups.returnType?.replace(/\bwhere\b.*$/u, '').trim() ?? '';
+        return {
+            kind: 'function',
+            name: functionMatch.groups.name ?? '<anonymous>',
+            exported: /^pub\b/u.test(trimmed),
+            async: /\basync\s+fn\b/u.test(trimmed) || /\basync\s+(?:const\s+|unsafe\s+)*fn\b/u.test(trimmed),
+            returnType: returnType.length > 0 ? normalizeReturnType(returnType) : null,
+        };
+    }
+    const shapeMatch = new RegExp(String.raw `^${visibility}(?<shape>struct|trait|type|enum)\s+(?<name>[A-Z_a-z]\w*)\b`, 'u').exec(trimmed);
+    if (shapeMatch?.groups) {
+        const shape = shapeMatch.groups.shape;
+        return {
+            kind: shape === 'trait' ? 'interface' : shape === 'enum' ? 'enum' : 'type',
+            name: shapeMatch.groups.name ?? '<anonymous>',
+            exported: /^pub\b/u.test(trimmed),
+            async: false,
+            returnType: null,
+        };
+    }
+    return null;
+}
+function pythonDeclarationFromLine(line) {
+    const trimmed = line.trim();
+    const functionMatch = /^(?<async>async\s+)?def\s+(?<name>[A-Z_a-z]\w*)\s*\([^)]*\)\s*(?:->\s*(?<returnType>[^:]+))?:/u.exec(trimmed);
+    if (functionMatch?.groups) {
+        const returnType = functionMatch.groups.returnType?.trim() ?? '';
+        return {
+            kind: 'function',
+            name: functionMatch.groups.name ?? '<anonymous>',
+            exported: !functionMatch.groups.name?.startsWith('_'),
+            async: Boolean(functionMatch.groups.async),
+            returnType: returnType.length > 0 ? normalizeReturnType(returnType) : null,
+        };
+    }
+    const classMatch = /^class\s+(?<name>[A-Z_a-z]\w*)\b/u.exec(trimmed);
+    if (classMatch?.groups) {
+        return {
+            kind: 'class',
+            name: classMatch.groups.name ?? '<anonymous>',
+            exported: !classMatch.groups.name?.startsWith('_'),
+            async: false,
+            returnType: null,
+        };
+    }
+    return null;
+}
+function leadingWhitespaceWidth(line) {
+    let width = 0;
+    for (const character of line) {
+        if (character === ' ') {
+            width += 1;
+        }
+        else if (character === '\t') {
+            width += 4;
+        }
+        else {
+            break;
+        }
+    }
+    return width;
+}
+function findPythonDeclarationEndLine(lines, startIndex) {
+    const startIndent = leadingWhitespaceWidth(lines[startIndex] ?? '');
+    let index = startIndex + 1;
+    while (index < lines.length) {
+        const line = lines[index] ?? '';
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith('#')) {
+            index += 1;
+            continue;
+        }
+        if (leadingWhitespaceWidth(line) <= startIndent) {
+            return index;
+        }
+        index += 1;
+    }
+    return lines.length;
+}
+function extractSymbolsFromDeclarations(relativePath, language, contentSha256, text, declarationForLine, endLineForMatch, lineCommentStart, tailExpressionReturn = false) {
     const lines = text.split(/\r\n|\r|\n/u);
     const symbols = [];
     for (const [index, line] of lines.entries()) {
-        const match = declarationFromLine(line);
+        const match = declarationForLine(line);
         if (!match) {
             continue;
         }
         const startLine = index + 1;
-        const endLine = findDeclarationEndLine(lines, index);
+        const endLine = endLineForMatch(lines, index);
         const signature = buildSignature(lines, startLine, endLine);
-        const returnMetadata = extractReturnMetadata(lines, startLine, endLine, signature, match);
+        const returnMetadata = extractReturnMetadata(lines, startLine, endLine, signature, match, lineCommentStart, tailExpressionReturn);
         symbols.push({
             id: `${relativePath}:${startLine}:${match.kind}:${match.name}`,
             path: relativePath,
@@ -456,6 +632,114 @@ function extractSymbols(relativePath, language, contentSha256, text) {
     }
     return symbols;
 }
+function extractTypescriptJavascriptSymbols(relativePath, language, contentSha256, text) {
+    return extractSymbolsFromDeclarations(relativePath, language, contentSha256, text, declarationFromLine, findDeclarationEndLine, '//');
+}
+function maskAstroFrontmatter(text) {
+    const lines = text.split(/\r\n|\r|\n/u);
+    if ((lines[0] ?? '').trim() !== '---') {
+        return lines.map(() => '').join('\n');
+    }
+    const masked = lines.map(() => '');
+    let index = 1;
+    while (index < lines.length) {
+        const line = lines[index] ?? '';
+        if (line.trim() === '---') {
+            return masked.join('\n');
+        }
+        masked[index] = line;
+        index += 1;
+    }
+    return lines.map(() => '').join('\n');
+}
+function maskSvelteScriptBlocks(text) {
+    const lines = text.split(/\r\n|\r|\n/u);
+    const masked = lines.map(() => '');
+    let insideScript = false;
+    for (const [index, line] of lines.entries()) {
+        let remaining = line;
+        if (!insideScript) {
+            const openMatch = /<script\b[^>]*>/iu.exec(remaining);
+            if (!openMatch || openMatch.index === undefined) {
+                continue;
+            }
+            remaining = remaining.slice(openMatch.index + openMatch[0].length);
+            insideScript = true;
+        }
+        const closeIndex = remaining.search(/<\/script\s*>/iu);
+        if (closeIndex >= 0) {
+            masked[index] = remaining.slice(0, closeIndex);
+            insideScript = false;
+            continue;
+        }
+        masked[index] = remaining;
+    }
+    return masked.join('\n');
+}
+function extractAstroSymbols(relativePath, language, contentSha256, text) {
+    return extractTypescriptJavascriptSymbols(relativePath, language, contentSha256, maskAstroFrontmatter(text));
+}
+function extractSvelteSymbols(relativePath, language, contentSha256, text) {
+    return extractTypescriptJavascriptSymbols(relativePath, language, contentSha256, maskSvelteScriptBlocks(text));
+}
+function extractGoSymbols(relativePath, language, contentSha256, text) {
+    return extractSymbolsFromDeclarations(relativePath, language, contentSha256, text, goDeclarationFromLine, findDeclarationEndLine, '//');
+}
+function extractRustSymbols(relativePath, language, contentSha256, text) {
+    return extractSymbolsFromDeclarations(relativePath, language, contentSha256, text, rustDeclarationFromLine, findDeclarationEndLine, '//', true);
+}
+function extractPythonSymbols(relativePath, language, contentSha256, text) {
+    return extractSymbolsFromDeclarations(relativePath, language, contentSha256, text, pythonDeclarationFromLine, findPythonDeclarationEndLine, '#');
+}
+const TYPESCRIPT_JAVASCRIPT_LANGUAGE_ADAPTER = {
+    id: 'typescript-javascript',
+    extensions: TYPESCRIPT_JAVASCRIPT_EXTENSIONS,
+    languageForPath: typescriptJavascriptLanguageForPath,
+    extractSymbols: extractTypescriptJavascriptSymbols,
+};
+const ASTRO_LANGUAGE_ADAPTER = {
+    id: 'astro',
+    extensions: ASTRO_EXTENSIONS,
+    languageForPath: astroLanguageForPath,
+    extractSymbols: extractAstroSymbols,
+};
+const SVELTE_LANGUAGE_ADAPTER = {
+    id: 'svelte',
+    extensions: SVELTE_EXTENSIONS,
+    languageForPath: svelteLanguageForPath,
+    extractSymbols: extractSvelteSymbols,
+};
+const GO_LANGUAGE_ADAPTER = {
+    id: 'go',
+    extensions: GO_EXTENSIONS,
+    languageForPath: goLanguageForPath,
+    extractSymbols: extractGoSymbols,
+};
+const RUST_LANGUAGE_ADAPTER = {
+    id: 'rust',
+    extensions: RUST_EXTENSIONS,
+    languageForPath: rustLanguageForPath,
+    extractSymbols: extractRustSymbols,
+};
+const PYTHON_LANGUAGE_ADAPTER = {
+    id: 'python',
+    extensions: PYTHON_EXTENSIONS,
+    languageForPath: pythonLanguageForPath,
+    extractSymbols: extractPythonSymbols,
+};
+const CODE_OUTLINE_LANGUAGE_ADAPTERS = [
+    TYPESCRIPT_JAVASCRIPT_LANGUAGE_ADAPTER,
+    ASTRO_LANGUAGE_ADAPTER,
+    SVELTE_LANGUAGE_ADAPTER,
+    GO_LANGUAGE_ADAPTER,
+    RUST_LANGUAGE_ADAPTER,
+    PYTHON_LANGUAGE_ADAPTER,
+];
+const CODE_FILE_EXTENSIONS = CODE_OUTLINE_LANGUAGE_ADAPTERS.flatMap((adapter) => adapter.extensions);
+export function extractSymbols(relativePath, language, contentSha256, text) {
+    const adapter = CODE_OUTLINE_LANGUAGE_ADAPTERS.find((candidate) => candidate.languageForPath(relativePath) === language);
+    return adapter?.extractSymbols(relativePath, language, contentSha256, text) ?? [];
+}
 function sourceAnchorEndLine(lineStart, rawText) {
     return lineStart + rawText.split(/\r\n|\r|\n/u).length - 1;
 }
@@ -465,7 +749,11 @@ function canBridgeAnchorToSymbol(lines, anchorEndLine, symbolStartLine) {
     }
     for (let lineNumber = anchorEndLine + 1; lineNumber < symbolStartLine; lineNumber += 1) {
         const trimmed = (lines[lineNumber - 1] ?? '').trim();
-        if (trimmed.length === 0 || trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('@')) {
+        if (trimmed.length === 0 ||
+            trimmed.startsWith('//') ||
+            trimmed.startsWith('#') ||
+            trimmed.startsWith('*') ||
+            trimmed.startsWith('@')) {
             continue;
         }
         return false;
@@ -631,10 +919,12 @@ function createSymbolReadInputHash(policy, target, findings) {
             : {
                 path: target.path,
                 sha256: target.sha256,
+                requested_anchor_id: target.requested_anchor_id,
                 requested_start_line: target.requested_start_line,
                 requested_end_line: target.requested_end_line,
                 context_start_line: target.context_start_line,
                 context_end_line: target.context_end_line,
+                anchor_id: target.anchor?.id ?? null,
             },
         input_errors: findings
             .filter((finding) => ERROR_SYMBOL_READ_CODES.has(finding.code))
@@ -647,75 +937,66 @@ function createSymbolReadInputHash(policy, target, findings) {
     };
     return sha256Tagged(JSON.stringify(inputState));
 }
-export function readCodeSymbol(projectRoot, options) {
-    const root = path.resolve(projectRoot);
-    const policy = {
-        start_line: options.startLine,
-        end_line: options.endLine ?? null,
-        context_lines: options.contextLines ?? DEFAULT_CONTEXT_LINES,
-        max_file_bytes: options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
-        max_snippet_lines: options.maxSnippetLines ?? DEFAULT_MAX_SNIPPET_LINES,
-    };
-    const findings = [];
-    const issues = [];
-    if (policy.start_line < 1 || (policy.end_line !== null && policy.end_line < policy.start_line) || policy.context_lines < 0) {
-        findings.push(makeSymbolReadFinding('code_symbol_read_invalid_range', 'high', options.path, policy.start_line, policy.end_line, 'Line range must use 1-based positive lines, and end_line must be greater than or equal to start_line.'));
-        return createEmptySymbolReadReport(root, policy, findings, issues);
-    }
-    let absolutePath;
-    let relativePath;
-    try {
-        const normalized = normalizeTargetPath(root, options.path);
-        absolutePath = normalized.absolutePath;
-        relativePath = normalized.relativePath;
-        ensureInsideWithoutSymlinks(root, absolutePath);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        issues.push(message);
-        findings.push(makeSymbolReadFinding('code_symbol_read_path_outside_root', 'high', options.path, policy.start_line, policy.end_line, message));
-        return createEmptySymbolReadReport(root, policy, findings, issues);
-    }
-    const language = languageForPath(absolutePath);
-    if (!language || !existsSync(absolutePath)) {
-        const message = `${relativePath} is not a supported existing code file.`;
-        issues.push(message);
-        findings.push(makeSymbolReadFinding('code_symbol_read_unreadable_path', 'high', relativePath, policy.start_line, policy.end_line, message));
-        return createEmptySymbolReadReport(root, policy, findings, issues);
-    }
-    let buffer;
-    try {
-        buffer = readFileInsideWithoutSymlinks(root, absolutePath, { maxBytes: policy.max_file_bytes });
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        issues.push(`${relativePath}: ${message}`);
-        findings.push(makeSymbolReadFinding('code_symbol_read_unreadable_path', 'high', relativePath, policy.start_line, policy.end_line, message));
-        return createEmptySymbolReadReport(root, policy, findings, issues);
+function collectAnchorReadCandidates(root, anchorId, maxFileBytes) {
+    const candidates = [];
+    for (const relativePath of listSourceAnchorFiles(root, { allowedExtensions: CODE_FILE_EXTENSIONS, maxFileBytes })) {
+        const absolutePath = path.join(root, ...relativePath.split('/'));
+        const language = languageForPath(absolutePath);
+        if (!language || !existsSync(absolutePath)) {
+            continue;
+        }
+        let buffer;
+        try {
+            buffer = readFileInsideWithoutSymlinks(root, absolutePath, { maxBytes: maxFileBytes });
+        }
+        catch {
+            continue;
+        }
+        const contentSha256 = sha256Tagged(buffer);
+        const text = buffer.toString('utf8');
+        const lines = text.split(/\r\n|\r|\n/u);
+        const symbols = extractSymbols(relativePath, language, contentSha256, text);
+        const anchors = extractAnchors(relativePath, lines, text, symbols);
+        for (const anchor of anchors) {
+            if (anchor.id === anchorId) {
+                candidates.push({ relativePath, anchor });
+            }
+        }
     }
+    return candidates.sort((left, right) => left.relativePath.localeCompare(right.relativePath) || left.anchor.line_start - right.anchor.line_start);
+}
+function createSymbolReadReportFromFile(root, policy, relativePath, language, buffer, findings, issues, anchor) {
     const contentSha256 = sha256Tagged(buffer);
     const text = buffer.toString('utf8');
     const lines = text.split(/\r\n|\r|\n/u);
-    if (policy.start_line > lines.length || (policy.end_line !== null && policy.end_line > lines.length)) {
-        const message = `Line range ${policy.start_line}${policy.end_line === null ? '' : `-${policy.end_line}`} is outside ${relativePath}, which has ${lines.length} lines.`;
+    if ((policy.start_line !== null && policy.start_line > lines.length) || (policy.end_line !== null && policy.end_line > lines.length)) {
+        const requestedRange = policy.start_line === null
+            ? `anchor ${policy.anchor_id ?? '<unknown>'}`
+            : `${policy.start_line}${policy.end_line === null ? '' : `-${policy.end_line}`}`;
+        const message = `Line range ${requestedRange} is outside ${relativePath}, which has ${lines.length} lines.`;
         issues.push(message);
         findings.push(makeSymbolReadFinding('code_symbol_read_invalid_range', 'high', relativePath, policy.start_line, policy.end_line, message));
         return createEmptySymbolReadReport(root, policy, findings, issues);
     }
     const symbols = extractSymbols(relativePath, language, contentSha256, text);
-    const matchedSymbol = policy.end_line === null
-        ? (symbols.find((symbol) => symbol.start_line === policy.start_line) ??
-            symbols.find((symbol) => symbol.start_line <= policy.start_line && symbol.end_line >= policy.start_line) ??
-            null)
-        : null;
-    const resolvedStartLine = matchedSymbol?.start_line ?? policy.start_line;
+    const requestedStartLine = policy.start_line;
+    const matchedSymbol = anchor
+        ? (symbols.find((symbol) => symbol.id === anchor.target_symbol_id) ?? null)
+        : policy.end_line === null && requestedStartLine !== null
+            ? (symbols.find((symbol) => symbol.start_line === requestedStartLine) ??
+                symbols.find((symbol) => symbol.start_line <= requestedStartLine && symbol.end_line >= requestedStartLine) ??
+                null)
+            : null;
+    const resolvedStartLine = matchedSymbol?.start_line ?? requestedStartLine;
     const resolvedEndLine = matchedSymbol?.end_line ?? policy.end_line;
     if (resolvedEndLine === null) {
-        const message = `No outline symbol starts at or contains line ${policy.start_line} in ${relativePath}. Pass --end-line to read an explicit range.`;
+        const message = anchor
+            ? `Source anchor ${anchor.id} in ${relativePath}:${anchor.line_start} does not target a readable outline symbol.`
+            : `No outline symbol starts at or contains line ${policy.start_line} in ${relativePath}. Pass --end-line to read an explicit range.`;
         issues.push(message);
-        findings.push(makeSymbolReadFinding('code_symbol_read_no_symbol_at_line', 'high', relativePath, policy.start_line, null, message));
+        findings.push(makeSymbolReadFinding(anchor ? 'code_symbol_read_anchor_without_symbol' : 'code_symbol_read_no_symbol_at_line', 'high', relativePath, policy.start_line ?? anchor?.line_start ?? null, null, message));
     }
-    const contextStartLine = resolvedEndLine === null ? null : Math.max(1, resolvedStartLine - policy.context_lines);
+    const contextStartLine = resolvedEndLine === null || resolvedStartLine === null ? null : Math.max(1, resolvedStartLine - policy.context_lines);
     const contextEndLine = resolvedEndLine === null ? null : Math.min(lines.length, resolvedEndLine + policy.context_lines);
     const target = {
         path: relativePath,
@@ -723,12 +1004,14 @@ export function readCodeSymbol(projectRoot, options) {
         sha256: contentSha256,
         size_bytes: buffer.byteLength,
         line_count: lines.length,
+        requested_anchor_id: policy.anchor_id,
         requested_start_line: policy.start_line,
         requested_end_line: policy.end_line,
         resolved_start_line: resolvedEndLine === null ? null : resolvedStartLine,
         resolved_end_line: resolvedEndLine,
         context_start_line: contextStartLine,
         context_end_line: contextEndLine,
+        anchor,
         symbol: matchedSymbol,
     };
     let snippet = null;
@@ -769,3 +1052,101 @@ export function readCodeSymbol(projectRoot, options) {
         issues,
     };
 }
+export function readCodeSymbol(projectRoot, options) {
+    const root = path.resolve(projectRoot);
+    const policy = {
+        anchor_id: options.anchorId ?? null,
+        start_line: options.startLine ?? null,
+        end_line: options.endLine ?? null,
+        context_lines: options.contextLines ?? DEFAULT_CONTEXT_LINES,
+        max_file_bytes: options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+        max_snippet_lines: options.maxSnippetLines ?? DEFAULT_MAX_SNIPPET_LINES,
+    };
+    const findings = [];
+    const issues = [];
+    if (policy.context_lines < 0 ||
+        (policy.start_line !== null && policy.start_line < 1) ||
+        (policy.end_line !== null && (policy.start_line === null || policy.end_line < policy.start_line))) {
+        findings.push(makeSymbolReadFinding('code_symbol_read_invalid_range', 'high', options.path ?? '.', policy.start_line, policy.end_line, 'Line range must use 1-based positive lines, and end_line must be greater than or equal to start_line.'));
+        return createEmptySymbolReadReport(root, policy, findings, issues);
+    }
+    if (policy.anchor_id !== null) {
+        const anchorCandidates = collectAnchorReadCandidates(root, policy.anchor_id, policy.max_file_bytes);
+        if (anchorCandidates.length === 0) {
+            const message = `No source anchor found with id ${policy.anchor_id}.`;
+            issues.push(message);
+            findings.push(makeSymbolReadFinding('code_symbol_read_anchor_not_found', 'high', '.', null, null, message));
+            return createEmptySymbolReadReport(root, policy, findings, issues);
+        }
+        if (anchorCandidates.length > 1) {
+            const locations = anchorCandidates.map((candidate) => `${candidate.relativePath}:${candidate.anchor.line_start}`).join(', ');
+            const message = `Source anchor id ${policy.anchor_id} is ambiguous: ${locations}.`;
+            issues.push(message);
+            findings.push(makeSymbolReadFinding('code_symbol_read_anchor_ambiguous', 'high', '.', null, null, message));
+            return createEmptySymbolReadReport(root, policy, findings, issues);
+        }
+        const candidate = anchorCandidates[0];
+        const anchor = candidate?.anchor ?? null;
+        const relativePath = candidate?.relativePath ?? '.';
+        const absolutePath = path.join(root, ...relativePath.split('/'));
+        const language = languageForPath(absolutePath);
+        if (!anchor || !language || !existsSync(absolutePath)) {
+            const message = `${relativePath} is not a supported existing code file.`;
+            issues.push(message);
+            findings.push(makeSymbolReadFinding('code_symbol_read_unreadable_path', 'high', relativePath, null, null, message));
+            return createEmptySymbolReadReport(root, policy, findings, issues);
+        }
+        let buffer;
+        try {
+            buffer = readFileInsideWithoutSymlinks(root, absolutePath, { maxBytes: policy.max_file_bytes });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push(`${relativePath}: ${message}`);
+            findings.push(makeSymbolReadFinding('code_symbol_read_unreadable_path', 'high', relativePath, null, null, message));
+            return createEmptySymbolReadReport(root, policy, findings, issues);
+        }
+        const anchorPolicy = {
+            ...policy,
+            start_line: null,
+            end_line: null,
+        };
+        return createSymbolReadReportFromFile(root, anchorPolicy, relativePath, language, buffer, findings, issues, anchor);
+    }
+    if (!options.path || policy.start_line === null) {
+        findings.push(makeSymbolReadFinding('code_symbol_read_invalid_range', 'high', options.path ?? '.', policy.start_line, policy.end_line, 'Path and --start-line are required unless --anchor is provided.'));
+        return createEmptySymbolReadReport(root, policy, findings, issues);
+    }
+    let absolutePath;
+    let relativePath;
+    try {
+        const normalized = normalizeTargetPath(root, options.path);
+        absolutePath = normalized.absolutePath;
+        relativePath = normalized.relativePath;
+        ensureInsideWithoutSymlinks(root, absolutePath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(message);
+        findings.push(makeSymbolReadFinding('code_symbol_read_path_outside_root', 'high', options.path, policy.start_line, policy.end_line, message));
+        return createEmptySymbolReadReport(root, policy, findings, issues);
+    }
+    const language = languageForPath(absolutePath);
+    if (!language || !existsSync(absolutePath)) {
+        const message = `${relativePath} is not a supported existing code file.`;
+        issues.push(message);
+        findings.push(makeSymbolReadFinding('code_symbol_read_unreadable_path', 'high', relativePath, policy.start_line, policy.end_line, message));
+        return createEmptySymbolReadReport(root, policy, findings, issues);
+    }
+    let buffer;
+    try {
+        buffer = readFileInsideWithoutSymlinks(root, absolutePath, { maxBytes: policy.max_file_bytes });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`${relativePath}: ${message}`);
+        findings.push(makeSymbolReadFinding('code_symbol_read_unreadable_path', 'high', relativePath, policy.start_line, policy.end_line, message));
+        return createEmptySymbolReadReport(root, policy, findings, issues);
+    }
+    return createSymbolReadReportFromFile(root, policy, relativePath, language, buffer, findings, issues, null);
+}