mustflow 2.75.0 → 2.75.2

package/dist/cli/lib/script-pack-registry.js

@@ -14,15 +14,15 @@ export const SCRIPT_PACKS = [
                 summaryKey: 'scriptPack.script.codeOutline.summary',
                 actions: ['scan'],
                 useWhen: [
-                    'Scan TypeScript or JavaScript files for symbol headers before reading large source files chunk by chunk.',
-                    'Build a bounded source outline with file paths, line ranges, signatures, export flags, and content hashes for codebase orientation.',
+                    'Scan TypeScript or JavaScript files for symbol headers and source anchors before reading large source files chunk by chunk.',
+                    'Build a bounded source outline with file paths, line ranges, signatures, export flags, source-anchor metadata, and content hashes for codebase orientation.',
                 ],
                 phases: ['before_change', 'during_change', 'review'],
                 readOnly: true,
                 mutates: false,
                 network: false,
                 inputs: ['path', 'max_files', 'max_file_bytes'],
-                outputs: ['human_summary', 'json_report', 'symbol_outline'],
+                outputs: ['human_summary', 'json_report', 'symbol_outline', 'source_anchors'],
                 relatedSkills: [
                     'codebase-orientation',
                     'javascript-code-change',

package/dist/core/code-outline.js

@@ -2,6 +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';
 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}`;
@@ -11,6 +12,7 @@ const DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
 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 IGNORED_DIRECTORIES = [
     '.git',
@@ -261,6 +263,169 @@ function buildSignature(lines, startLine, endLine) {
     const signature = parts.join(' ').replace(/\s+/gu, ' ');
     return signature.length > 240 ? `${signature.slice(0, 237)}...` : signature;
 }
+function normalizeReturnType(value) {
+    return value.replace(/\s+/gu, ' ').replace(/[;{]\s*$/u, '').trim();
+}
+function extractExplicitReturnType(signature, match) {
+    if (match.kind !== 'function') {
+        return null;
+    }
+    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);
+    }
+    const arrowReturnMatch = /\)\s*:\s*(?<returnType>[^=]+?)\s*=>/u.exec(signature);
+    if (arrowReturnMatch?.groups?.returnType) {
+        return normalizeReturnType(arrowReturnMatch.groups.returnType);
+    }
+    const arrowTypeAnnotationMatch = /:\s*(?:async\s*)?\([^)]*\)\s*=>\s*(?<returnType>[^=;]+?)\s*=/u.exec(signature);
+    if (arrowTypeAnnotationMatch?.groups?.returnType) {
+        return normalizeReturnType(arrowTypeAnnotationMatch.groups.returnType);
+    }
+    return null;
+}
+function truncateReturnPreview(value) {
+    const preview = value.replace(/\s+/gu, ' ').trim();
+    return preview.length > RETURN_PREVIEW_MAX_CHARS
+        ? `${preview.slice(0, RETURN_PREVIEW_MAX_CHARS - 3)}...`
+        : preview;
+}
+function extractArrowExpressionReturnPreview(signature) {
+    const arrowIndex = signature.lastIndexOf('=>');
+    if (arrowIndex < 0) {
+        return null;
+    }
+    const expression = signature.slice(arrowIndex + 2).trim().replace(/;\s*$/u, '');
+    if (expression.length === 0 || expression.startsWith('{')) {
+        return null;
+    }
+    return truncateReturnPreview(expression);
+}
+function isIdentifierCharacter(value) {
+    return typeof value === 'string' && /[$\w]/u.test(value);
+}
+function findReturnKeywordIndex(line) {
+    let quote = null;
+    let escaped = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const character = line[index];
+        const nextCharacter = line[index + 1];
+        if (quote !== null) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (character === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (character === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (character === '/' && nextCharacter === '/') {
+            return -1;
+        }
+        if (character === '"' || character === "'" || character === '`') {
+            quote = character;
+            continue;
+        }
+        if (line.startsWith('return', index) &&
+            !isIdentifierCharacter(line[index - 1]) &&
+            !isIdentifierCharacter(line[index + 'return'.length])) {
+            return index;
+        }
+    }
+    return -1;
+}
+function extractReturnExpressionPreview(line) {
+    const returnIndex = findReturnKeywordIndex(line);
+    if (returnIndex < 0) {
+        return null;
+    }
+    const expression = line
+        .slice(returnIndex + 'return'.length)
+        .replace(/\/\/.*$/u, '')
+        .trim()
+        .replace(/;\s*$/u, '')
+        .trim();
+    return expression.length === 0 ? null : truncateReturnPreview(expression);
+}
+function hasReturnStatement(line) {
+    return findReturnKeywordIndex(line) >= 0;
+}
+function simpleBodyThrowsOnly(lines, startLine, endLine, returnType) {
+    let sawThrow = false;
+    let sawOtherExecutableLine = false;
+    for (let index = startLine; index < endLine - 1; index += 1) {
+        const bodyLine = stripLineForBraceScan(lines[index] ?? '')
+            .replace(/[{};]/gu, '')
+            .trim();
+        if (bodyLine.length === 0) {
+            continue;
+        }
+        if (/^throw\b/u.test(bodyLine)) {
+            sawThrow = true;
+            continue;
+        }
+        sawOtherExecutableLine = true;
+    }
+    return sawThrow && (!sawOtherExecutableLine || returnType === 'never');
+}
+function extractReturnMetadata(lines, startLine, endLine, signature, match) {
+    const returnType = extractExplicitReturnType(signature, match);
+    if (match.kind !== 'function') {
+        return {
+            return_type: null,
+            return_behavior: 'unknown',
+            return_count: 0,
+            return_lines: [],
+            return_preview: null,
+        };
+    }
+    const returnLines = [];
+    const valueReturnPreviews = [];
+    let voidReturnCount = 0;
+    for (let index = startLine - 1; index < endLine; index += 1) {
+        const line = lines[index] ?? '';
+        if (!hasReturnStatement(line)) {
+            continue;
+        }
+        returnLines.push(index + 1);
+        const preview = extractReturnExpressionPreview(line);
+        if (preview === null) {
+            voidReturnCount += 1;
+        }
+        else {
+            valueReturnPreviews.push(preview);
+        }
+    }
+    const arrowExpressionPreview = returnLines.length === 0 ? extractArrowExpressionReturnPreview(signature) : null;
+    let returnBehavior;
+    if (valueReturnPreviews.length > 0 && voidReturnCount > 0) {
+        returnBehavior = 'mixed';
+    }
+    else if (valueReturnPreviews.length > 0 || arrowExpressionPreview !== null) {
+        returnBehavior = 'value';
+    }
+    else if (voidReturnCount > 0) {
+        returnBehavior = 'void';
+    }
+    else if (simpleBodyThrowsOnly(lines, startLine, endLine, returnType)) {
+        returnBehavior = 'throws_only';
+    }
+    else {
+        returnBehavior = 'implicit_undefined';
+    }
+    return {
+        return_type: returnType,
+        return_behavior: returnBehavior,
+        return_count: returnLines.length,
+        return_lines: returnLines,
+        return_preview: valueReturnPreviews[0] ?? arrowExpressionPreview,
+    };
+}
 function extractSymbols(relativePath, language, contentSha256, text) {
     const lines = text.split(/\r\n|\r|\n/u);
     const symbols = [];
@@ -271,6 +436,8 @@ function extractSymbols(relativePath, language, contentSha256, text) {
         }
         const startLine = index + 1;
         const endLine = findDeclarationEndLine(lines, index);
+        const signature = buildSignature(lines, startLine, endLine);
+        const returnMetadata = extractReturnMetadata(lines, startLine, endLine, signature, match);
         symbols.push({
             id: `${relativePath}:${startLine}:${match.kind}:${match.name}`,
             path: relativePath,
@@ -279,16 +446,70 @@ function extractSymbols(relativePath, language, contentSha256, text) {
             name: match.name,
             start_line: startLine,
             end_line: endLine,
-            signature: buildSignature(lines, startLine, endLine),
+            signature,
             exported: match.exported,
             async: match.async,
+            ...returnMetadata,
             parent: null,
             content_sha256: contentSha256,
         });
     }
     return symbols;
 }
-function createOutlineInputHash(policy, files, findings) {
+function sourceAnchorEndLine(lineStart, rawText) {
+    return lineStart + rawText.split(/\r\n|\r|\n/u).length - 1;
+}
+function canBridgeAnchorToSymbol(lines, anchorEndLine, symbolStartLine) {
+    if (symbolStartLine <= anchorEndLine) {
+        return false;
+    }
+    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('@')) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function findAnchorTargetSymbol(relativePath, lines, anchorEndLine, symbols) {
+    const followingSymbols = symbols
+        .filter((symbol) => symbol.path === relativePath && symbol.start_line > anchorEndLine)
+        .sort((left, right) => left.start_line - right.start_line);
+    const target = followingSymbols[0] ?? null;
+    if (!target || !canBridgeAnchorToSymbol(lines, anchorEndLine, target.start_line)) {
+        return null;
+    }
+    return target;
+}
+function extractAnchors(relativePath, lines, text, symbols) {
+    const anchors = [];
+    for (const anchor of parseSourceAnchorsInContent(relativePath, text)) {
+        if (!anchor.idValid || sourceAnchorTextContainsSecretLike(anchor.rawText)) {
+            continue;
+        }
+        const lineEnd = sourceAnchorEndLine(anchor.lineStart, anchor.rawText);
+        const target = findAnchorTargetSymbol(relativePath, lines, lineEnd, symbols);
+        anchors.push({
+            id: anchor.rawId,
+            path: relativePath,
+            line_start: anchor.lineStart,
+            line_end: lineEnd,
+            purpose: anchor.fields.get('purpose') ?? null,
+            search: splitSourceAnchorList(anchor.fields.get('search')),
+            invariant: anchor.fields.get('invariant') ?? null,
+            risk: splitSourceAnchorList(anchor.fields.get('risk')),
+            navigation_only: true,
+            can_instruct_agent: false,
+            target_symbol_id: target?.id ?? null,
+            target_kind: target?.kind ?? null,
+            target_name: target?.name ?? null,
+            target_start_line: target?.start_line ?? null,
+        });
+    }
+    return anchors;
+}
+function createOutlineInputHash(policy, files, anchors, findings) {
     const inputState = {
         policy,
         files: files.map((file) => ({
@@ -297,6 +518,13 @@ function createOutlineInputHash(policy, files, findings) {
             size_bytes: file.size_bytes,
             symbol_count: file.symbol_count,
         })),
+        anchors: anchors.map((anchor) => ({
+            id: anchor.id,
+            path: anchor.path,
+            line_start: anchor.line_start,
+            line_end: anchor.line_end,
+            target_symbol_id: anchor.target_symbol_id,
+        })),
         input_errors: findings
             .filter((finding) => ERROR_OUTLINE_CODES.has(finding.code))
             .map((finding) => ({ code: finding.code, path: finding.path })),
@@ -319,6 +547,7 @@ export function inspectCodeOutline(projectRoot, options) {
         ignored_directories: [...IGNORED_DIRECTORIES],
     };
     const files = [];
+    const anchors = [];
     const symbols = [];
     const findings = [];
     const issues = [];
@@ -339,15 +568,18 @@ export function inspectCodeOutline(projectRoot, options) {
         }
         const contentSha256 = sha256Tagged(buffer);
         const text = buffer.toString('utf8');
+        const lines = text.split(/\r\n|\r|\n/u);
         const fileSymbols = extractSymbols(candidate.relativePath, candidate.language, contentSha256, text);
+        const fileAnchors = extractAnchors(candidate.relativePath, lines, text, fileSymbols);
         symbols.push(...fileSymbols);
+        anchors.push(...fileAnchors);
         files.push({
             kind: 'source_file',
             path: candidate.relativePath,
             language: candidate.language,
             sha256: contentSha256,
             size_bytes: buffer.byteLength,
-            line_count: text.split(/\r\n|\r|\n/u).length,
+            line_count: lines.length,
             symbol_count: fileSymbols.length,
         });
     }
@@ -363,8 +595,9 @@ export function inspectCodeOutline(projectRoot, options) {
         ok: status === 'passed',
         mustflow_root: root,
         policy,
-        input_hash: createOutlineInputHash(policy, files, findings),
+        input_hash: createOutlineInputHash(policy, files, anchors, findings),
         files,
+        anchors: anchors.sort((left, right) => left.path.localeCompare(right.path) || left.line_start - right.line_start),
         symbols: symbols.sort((left, right) => left.path.localeCompare(right.path) || left.start_line - right.start_line),
         findings,
         issues,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.75.0",
+  "version": "2.75.2",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -67,11 +67,12 @@ Current schemas:
 - `code-outline-report.schema.json`: output of
   `mf script-pack run code/outline scan <path...> --json`, containing a bounded TypeScript and
   JavaScript source outline with file hashes, symbol names, declaration kinds, line ranges,
-  signatures, export flags, and stable input-limit finding codes
+  signatures, export flags, source-anchor navigation metadata, static return metadata, and stable
+  input-limit finding codes
 - `code-symbol-read-report.schema.json`: output of
   `mf script-pack run code/symbol-read read <path> --start-line <line> --json`, containing a
   focused source snippet selected by outline symbol line or explicit line range with file hash,
-  resolved line metadata, optional symbol metadata, and stable range/read finding codes
+  resolved line metadata, optional symbol and static return metadata, and stable range/read finding codes
 - `text-budget-report.schema.json`: output of
   `mf script-pack run core/text-budget check <path...> --json`, containing
   exact text-budget metrics, input content hashes, policy metadata, findings, and JSON Pointer field

package/schemas/code-outline-report.schema.json

@@ -17,6 +17,7 @@
     "policy",
     "input_hash",
     "files",
+    "anchors",
     "symbols",
     "findings",
     "issues"
@@ -37,6 +38,10 @@
       "type": "array",
       "items": { "$ref": "#/$defs/file" }
     },
+    "anchors": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/anchor" }
+    },
     "symbols": {
       "type": "array",
       "items": { "$ref": "#/$defs/symbol" }
@@ -90,6 +95,47 @@
         "symbol_count": { "type": "integer", "minimum": 0 }
       }
     },
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "path",
+        "line_start",
+        "line_end",
+        "purpose",
+        "search",
+        "invariant",
+        "risk",
+        "navigation_only",
+        "can_instruct_agent",
+        "target_symbol_id",
+        "target_kind",
+        "target_name",
+        "target_start_line"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "line_start": { "type": "integer", "minimum": 1 },
+        "line_end": { "type": "integer", "minimum": 1 },
+        "purpose": { "type": ["string", "null"] },
+        "search": { "$ref": "#/$defs/stringArray" },
+        "invariant": { "type": ["string", "null"] },
+        "risk": { "$ref": "#/$defs/stringArray" },
+        "navigation_only": { "const": true },
+        "can_instruct_agent": { "const": false },
+        "target_symbol_id": { "type": ["string", "null"] },
+        "target_kind": {
+          "anyOf": [
+            { "$ref": "#/$defs/symbolKind" },
+            { "type": "null" }
+          ]
+        },
+        "target_name": { "type": ["string", "null"] },
+        "target_start_line": { "type": ["integer", "null"], "minimum": 1 }
+      }
+    },
     "symbol": {
       "type": "object",
       "additionalProperties": false,
@@ -104,6 +150,11 @@
         "signature",
         "exported",
         "async",
+        "return_type",
+        "return_behavior",
+        "return_count",
+        "return_lines",
+        "return_preview",
         "parent",
         "content_sha256"
       ],
@@ -118,6 +169,16 @@
         "signature": { "type": "string" },
         "exported": { "type": "boolean" },
         "async": { "type": "boolean" },
+        "return_type": { "type": ["string", "null"] },
+        "return_behavior": {
+          "enum": ["value", "void", "implicit_undefined", "mixed", "throws_only", "unknown"]
+        },
+        "return_count": { "type": "integer", "minimum": 0 },
+        "return_lines": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "return_preview": { "type": ["string", "null"] },
         "parent": { "type": ["string", "null"] },
         "content_sha256": { "$ref": "#/$defs/sha256" }
       }

package/schemas/code-symbol-read-report.schema.json

@@ -91,6 +91,11 @@
         "signature",
         "exported",
         "async",
+        "return_type",
+        "return_behavior",
+        "return_count",
+        "return_lines",
+        "return_preview",
         "parent",
         "content_sha256"
       ],
@@ -105,6 +110,16 @@
         "signature": { "type": "string" },
         "exported": { "type": "boolean" },
         "async": { "type": "boolean" },
+        "return_type": { "type": ["string", "null"] },
+        "return_behavior": {
+          "enum": ["value", "void", "implicit_undefined", "mixed", "throws_only", "unknown"]
+        },
+        "return_count": { "type": "integer", "minimum": 0 },
+        "return_lines": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "return_preview": { "type": ["string", "null"] },
         "parent": { "type": ["string", "null"] },
         "content_sha256": { "$ref": "#/$defs/sha256" }
       }

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.75.0"
+version = "2.75.2"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"