mustflow 2.75.1 → 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}`;
@@ -455,7 +456,60 @@ function extractSymbols(relativePath, language, contentSha256, text) {
     }
     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) => ({
@@ -464,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 })),
@@ -486,6 +547,7 @@ export function inspectCodeOutline(projectRoot, options) {
         ignored_directories: [...IGNORED_DIRECTORIES],
     };
     const files = [];
+    const anchors = [];
     const symbols = [];
     const findings = [];
     const issues = [];
@@ -506,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,
         });
     }
@@ -530,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.1",
+  "version": "2.75.2",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -67,7 +67,8 @@ 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, static return metadata, 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,

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,

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.75.1"
+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"