mustflow 2.75.0 → 2.75.1

package/dist/core/code-outline.js

@@ -11,6 +11,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 +262,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 +435,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,9 +445,10 @@ 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,
         });

package/package.json

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

package/schemas/README.md

@@ -67,11 +67,11 @@ 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, 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

@@ -104,6 +104,11 @@
         "signature",
         "exported",
         "async",
+        "return_type",
+        "return_behavior",
+        "return_count",
+        "return_lines",
+        "return_preview",
         "parent",
         "content_sha256"
       ],
@@ -118,6 +123,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.1"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"