@forge-kit/plugin-source-map-prase 0.0.1 → 0.0.3

package/src/{utils/source-map → node/trace/core}/domain/source-content.ts

@@ -9,6 +9,11 @@ interface SourceCodeMatch {
     location: TraceLocation
 }
 
+interface ResolveSourceCodeOptions {
+    onlyLastMap?: boolean
+    lastMapFileName?: string
+}
+
 const findSourceCodeMatch = (hop: TraceHop, sourceMapRecord: SourceMapRecord): SourceCodeMatch | null => {
     if (!hop.output) return null
 
@@ -42,14 +47,22 @@ const findSourceCodeMatch = (hop: TraceHop, sourceMapRecord: SourceMapRecord): S
     }
 }
 
-export const resolveSourceCodeFromTrace = (traceHops: TraceHop[], sourceMaps: SourceMapRegistry) => {
+export const resolveSourceCodeFromTrace = (
+    traceHops: TraceHop[],
+    sourceMaps: SourceMapRegistry,
+    options: ResolveSourceCodeOptions = {},
+) => {
     const sourceMapRecords = listSourceMapRecords(sourceMaps)
+    const sourceMapRecordByName = new Map(sourceMapRecords.map((record) => [record.mapFileName, record] as const))
+    const {onlyLastMap = false, lastMapFileName} = options
 
     for (let index = traceHops.length - 1; index >= 0; index--) {
         const hop = traceHops[index]
         if (!hop.output || !hop.mapFileName) continue
+        // 仅允许链路最后一个 map 返回 sourcesContent，控制传输体积和性能开销。
+        if (onlyLastMap && lastMapFileName && hop.mapFileName !== lastMapFileName) continue
 
-        const sourceMapRecord = sourceMapRecords.find((item) => item.mapFileName === hop.mapFileName)
+        const sourceMapRecord = sourceMapRecordByName.get(hop.mapFileName)
         if (!sourceMapRecord) continue
 
         const match = findSourceCodeMatch(hop, sourceMapRecord)

package/src/node/trace/core/domain/trace-resolver.ts

@@ -0,0 +1,179 @@
+import {SourceMapConsumer, type RawSourceMap} from "source-map-js";
+import {MAX_TRACE_DEPTH} from "../base/constants";
+import {getSourceMapByFileName, getSourceMapByMapFileName} from "../base/registry";
+import type {ResolveTraceOptions, SourceMapRecord, SourceMapRegistry, TraceHop, TraceLocation} from "../base/types";
+
+interface ResolvedTraceHop extends TraceHop {
+    output: TraceLocation
+}
+
+const toLocationCursor = (location: TraceLocation) => {
+    return `${location.fileName}:${location.lineNumber}:${location.columnNumber}`
+}
+
+const isSameLocation = (left: TraceLocation, right: TraceLocation) => {
+    return (
+        left.fileName === right.fileName
+        && left.lineNumber === right.lineNumber
+        && left.columnNumber === right.columnNumber
+    )
+}
+
+const resolveOriginalLocation = (
+    rawSourceMap: RawSourceMap,
+    position: { line: number; column: number },
+): TraceLocation | null => {
+    const consumer = new SourceMapConsumer(rawSourceMap)
+
+    try {
+        // 回退策略：
+        // 1) 优先按目标列号查询；
+        // 2) 再回退到列号 0 的行级查询；
+        // 同时组合 GLB/LUB 两种 bias，提高稀疏映射和压缩代码场景下的命中率。
+        const attempts = [
+            {line: position.line, column: position.column, bias: SourceMapConsumer.GREATEST_LOWER_BOUND},
+            {line: position.line, column: 0, bias: SourceMapConsumer.GREATEST_LOWER_BOUND},
+            {line: position.line, column: position.column, bias: SourceMapConsumer.LEAST_UPPER_BOUND},
+            {line: position.line, column: 0, bias: SourceMapConsumer.LEAST_UPPER_BOUND},
+        ]
+
+        for (const attempt of attempts) {
+            const found = consumer.originalPositionFor(attempt)
+            if (found.source && found.line != null && found.column != null) {
+                return {
+                    fileName: found.source,
+                    lineNumber: found.line,
+                    columnNumber: found.column,
+                }
+            }
+        }
+    } finally {
+        const maybeDestroy = (consumer as { destroy?: () => void }).destroy
+        maybeDestroy?.()
+    }
+
+    return null
+}
+
+const resolveHopFromRecord = (sourceMapRecord: SourceMapRecord, input: TraceLocation): ResolvedTraceHop | null => {
+    try {
+        const {lineNumber: line, columnNumber: column} = input
+        const output = resolveOriginalLocation(sourceMapRecord.rawSourceMap, {line, column})
+        if (!output) return null
+        return {input, output, mapFileName: sourceMapRecord.mapFileName}
+    } catch {
+        return null
+    }
+}
+
+interface AppendUnresolvedHopInput {
+    traceHops: TraceHop[]
+    input: TraceLocation
+    mapFileName?: string
+}
+
+const appendUnresolvedHop = (input: AppendUnresolvedHopInput) => {
+    const {traceHops, input: location, mapFileName} = input
+    traceHops.push({input: location, mapFileName})
+}
+
+interface ResolveTraceWithOrderedMapsInput {
+    entry: TraceLocation
+    sourceMaps: SourceMapRegistry
+    orderedMapFileNames: string[]
+    maxDepth: number
+}
+
+const resolveTraceWithOrderedMaps = (input: ResolveTraceWithOrderedMapsInput) => {
+    const {entry, sourceMaps, orderedMapFileNames, maxDepth} = input
+    const traceHops: TraceHop[] = []
+    const visited = new Set<string>()
+    let current = entry
+
+    for (let depth = 0; depth < orderedMapFileNames.length && depth < maxDepth; depth++) {
+        const mapFileName = orderedMapFileNames[depth]
+        const cursor = toLocationCursor(current)
+
+        if (visited.has(cursor)) {
+            appendUnresolvedHop({traceHops, input: current, mapFileName})
+            continue
+        }
+        visited.add(cursor)
+
+        const sourceMapRecord = getSourceMapByMapFileName(sourceMaps, mapFileName)
+        if (!sourceMapRecord) {
+            appendUnresolvedHop({traceHops, input: current, mapFileName})
+            continue
+        }
+
+        const hop = resolveHopFromRecord(sourceMapRecord, current)
+        if (!hop) {
+            appendUnresolvedHop({traceHops, input: current, mapFileName: sourceMapRecord.mapFileName})
+            continue
+        }
+
+        traceHops.push(hop)
+        current = hop.output
+    }
+
+    return traceHops
+}
+
+interface ResolveTraceByFileLookupInput {
+    entry: TraceLocation
+    sourceMaps: SourceMapRegistry
+    maxDepth: number
+}
+
+const resolveTraceByFileLookup = (input: ResolveTraceByFileLookupInput) => {
+    const {entry, sourceMaps, maxDepth} = input
+    const traceHops: TraceHop[] = []
+    const visited = new Set<string>()
+    let current = entry
+
+    for (let depth = 0; depth < maxDepth; depth++) {
+        const cursor = toLocationCursor(current)
+
+        if (visited.has(cursor)) {
+            appendUnresolvedHop({traceHops, input: current})
+            break
+        }
+        visited.add(cursor)
+
+        const sourceMapRecord = getSourceMapByFileName(sourceMaps, current.fileName)
+        if (!sourceMapRecord) {
+            if (traceHops.length === 0) appendUnresolvedHop({traceHops, input: current})
+            break
+        }
+
+        const hop = resolveHopFromRecord(sourceMapRecord, current)
+        if (!hop) {
+            appendUnresolvedHop({traceHops, input: current, mapFileName: sourceMapRecord.mapFileName})
+            break
+        }
+
+        traceHops.push(hop)
+
+        if (isSameLocation(hop.output, current)) break
+
+        current = hop.output
+    }
+
+    return traceHops
+}
+
+interface ResolveTraceBySourceMapsInput {
+    entry: TraceLocation
+    sourceMaps: SourceMapRegistry
+    orderedMapFileNames?: string[]
+    options?: ResolveTraceOptions
+}
+
+export const resolveTraceBySourceMaps = async (input: ResolveTraceBySourceMapsInput): Promise<TraceHop[]> => {
+    const {entry, sourceMaps, orderedMapFileNames = [], options = {}} = input
+    const maxDepth = options.maxDepth ?? MAX_TRACE_DEPTH
+
+    if (orderedMapFileNames.length > 0) return resolveTraceWithOrderedMaps({entry, sourceMaps, orderedMapFileNames, maxDepth})
+
+    return resolveTraceByFileLookup({entry, sourceMaps, maxDepth})
+}

package/src/node/trace/core/domain/view-model.ts

@@ -0,0 +1,57 @@
+import {DEFAULT_CONTEXT_LINE_RADIUS} from "../base/constants";
+import type {TraceLocation} from "../base/types";
+
+export const toDisplayLocation = (location: TraceLocation): TraceLocation => ({...location})
+
+const MAX_EXCERPT_CHARS = 12000
+const COLUMN_WINDOW_CHARS = 4000
+
+const truncateLineByColumn = (line: string, targetColumn = 0) => {
+    if (line.length <= MAX_EXCERPT_CHARS) return line
+    const halfWindow = Math.floor(COLUMN_WINDOW_CHARS / 2)
+    const start = Math.max(0, targetColumn - halfWindow)
+    const end = Math.min(line.length, start + COLUMN_WINDOW_CHARS)
+    const head = start > 0 ? "…[truncated]…" : ""
+    const tail = end < line.length ? "…[truncated]…" : ""
+    return `${head}${line.slice(start, end)}${tail}`
+}
+
+const truncateExcerpt = (code: string) => {
+    if (code.length <= MAX_EXCERPT_CHARS) return code
+    return `${code.slice(0, MAX_EXCERPT_CHARS)}\n...[truncated ${code.length - MAX_EXCERPT_CHARS} chars]...`
+}
+
+interface CreateCodeExcerptInput {
+    fullCode: string
+    targetLine: number
+    radius?: number
+    targetColumn?: number
+}
+
+export const createCodeExcerpt = (input: CreateCodeExcerptInput) => {
+    const {
+        fullCode,
+        targetLine,
+        radius = DEFAULT_CONTEXT_LINE_RADIUS,
+        targetColumn = 0,
+    } = input
+    const lines = fullCode.split(/\r?\n/)
+    if (lines.length === 0) {
+        return {code: truncateExcerpt(fullCode), highlightLine: targetLine}
+    }
+
+    const safeTarget = Math.min(Math.max(targetLine, 1), lines.length)
+
+    // 压缩后的单行源码可能非常大，仅截取目标列附近窗口。
+    if (lines.length === 1) {
+        return {code: truncateLineByColumn(lines[0], targetColumn), highlightLine: 1}
+    }
+
+    const start = Math.max(1, safeTarget - radius)
+    const end = Math.min(lines.length, safeTarget + radius)
+
+    return {
+        code: truncateExcerpt(lines.slice(start - 1, end).join("\n")),
+        highlightLine: safeTarget - start + 1,
+    }
+}

package/src/node/trace/resolve/context.ts

@@ -0,0 +1,59 @@
+import {readFile} from "node:fs/promises";
+import {basename} from "node:path";
+import {homedir} from "node:os";
+import type {ChainMapSlot} from "@/node/trace/core/base/types";
+import {
+    DEFAULT_CONTEXT_LINE_RADIUS,
+    buildChainStateFromSlots,
+    validateResolveInput,
+} from "../runner";
+import type {ResolveTaskContext, ResolveTraceInput} from "./types";
+
+const createChainSlotFromPath = async (filePath: string): Promise<ChainMapSlot> => {
+    const resolvedPath = filePath.startsWith("~/") ? `${homedir()}/${filePath.slice(2)}` : filePath
+    const mapFileName = basename(resolvedPath)
+    const slotId = `${mapFileName}-${Math.random().toString(36).slice(2, 8)}`
+
+    try {
+        const fileText = await readFile(resolvedPath, "utf8")
+        const rawSourceMap = JSON.parse(fileText)
+        if (!rawSourceMap || typeof rawSourceMap !== "object" || typeof rawSourceMap.mappings !== "string") {
+            throw new Error("invalid source-map json")
+        }
+        return {
+            id: slotId,
+            mapFileName,
+            mapFilePath: resolvedPath,
+            sourceMapRecord: {rawSourceMap, mapFileName},
+        }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error"
+        return {
+            id: slotId,
+            mapFileName,
+            mapFilePath: resolvedPath,
+            error: `${mapFileName}: ${message}`,
+        }
+    }
+}
+
+export const createResolveContext = async (parsed: ResolveTraceInput): Promise<ResolveTaskContext> => {
+    // 单次请求内统一读取并校验 map 文件，避免重复 IO。
+    const chainSlots = await Promise.all(parsed.mapFilePaths.map(createChainSlotFromPath))
+    const chainState = buildChainStateFromSlots(chainSlots)
+    const validated = validateResolveInput({
+        entryFileName: parsed.entryFileName,
+        entryLine: parsed.entryLine,
+        entryColumn: parsed.entryColumn,
+        contextLineRadius: parsed.contextLineRadius || String(DEFAULT_CONTEXT_LINE_RADIUS),
+        mapCount: chainState.sourceMapFileNames.length,
+    })
+    if (!validated.ok) throw new Error(validated.message)
+
+    return {
+        entry: validated.entry,
+        contextLineRadius: validated.contextLineRadius,
+        sourceMaps: chainState.sourceMaps,
+        sourceMapFileNames: chainState.sourceMapFileNames,
+    }
+}

package/src/node/trace/resolve/index.ts

@@ -0,0 +1,97 @@
+import {performance} from "node:perf_hooks";
+import {
+    buildTraceMetaOutput,
+    buildTraceSnippetOutput,
+    resolveTraceContextTask,
+} from "../runner";
+import {createResolveContext} from "./context";
+import {
+    createValidationMetaOutput,
+    isInputValidationMessage,
+    parseResolveInput,
+    toFallbackEntry,
+} from "./input";
+import {
+    assertSnippetPayloadWithinLimit,
+    estimateSnippetPayloadBytes,
+    parseMaxSnippetPayloadBytes,
+} from "./snippet-limit";
+import type {ProfileResolveTraceOutput, TraceProfilePhase} from "./types";
+
+const pushProfilePhase = (phases: TraceProfilePhase[], name: string, startedAt: number) => {
+    phases.push({name, durationMs: Number((performance.now() - startedAt).toFixed(2))})
+}
+
+export const resolveTrace = async (payloadText: string) => {
+    const parsed = parseResolveInput(payloadText)
+    try {
+        const resolveContext = await createResolveContext(parsed)
+        const resolved = await resolveTraceContextTask(resolveContext)
+        return buildTraceMetaOutput(resolved)
+    } catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error"
+        if (isInputValidationMessage(message)) return createValidationMetaOutput(message)
+        return {
+            traceData: [{input: toFallbackEntry(parsed)}],
+            resolvedSourceMeta: null,
+            canFetchSourceSnippet: false,
+            message: `source-map trace failed: ${message}`,
+        }
+    }
+}
+
+export const getSourceSnippet = async (payloadText: string) => {
+    // 两阶段接口在无进程缓存模式下，第二阶段使用同一入参重新计算。
+    const parsed = parseResolveInput(payloadText)
+    const resolveContext = await createResolveContext(parsed)
+    const resolved = await resolveTraceContextTask(resolveContext)
+    const snippetOutput = buildTraceSnippetOutput({
+        contextLineRadius: resolveContext.contextLineRadius,
+        resolved,
+    })
+    assertSnippetPayloadWithinLimit(snippetOutput, parsed)
+    return snippetOutput
+}
+
+export const profileResolveTracePhases = async (payloadText: string): Promise<ProfileResolveTraceOutput> => {
+    const phases: TraceProfilePhase[] = []
+    const totalStart = performance.now()
+
+    const parseStart = performance.now()
+    const parsed = parseResolveInput(payloadText)
+    pushProfilePhase(phases, "parseResolveInput", parseStart)
+
+    const createContextStart = performance.now()
+    const resolveContext = await createResolveContext(parsed)
+    pushProfilePhase(phases, "createResolveContext", createContextStart)
+
+    const resolveTraceStart = performance.now()
+    const resolved = await resolveTraceContextTask(resolveContext)
+    pushProfilePhase(phases, "resolveTraceContextTask", resolveTraceStart)
+
+    const buildMetaStart = performance.now()
+    const metaOutput = buildTraceMetaOutput(resolved)
+    pushProfilePhase(phases, "buildTraceMetaOutput", buildMetaStart)
+
+    const buildSnippetStart = performance.now()
+    const snippetOutput = buildTraceSnippetOutput({
+        contextLineRadius: resolveContext.contextLineRadius,
+        resolved,
+    })
+    pushProfilePhase(phases, "buildTraceSnippetOutput", buildSnippetStart)
+
+    const estimateStart = performance.now()
+    const maxSnippetPayloadBytes = parseMaxSnippetPayloadBytes(parsed)
+    const snippetPayloadBytes = estimateSnippetPayloadBytes(snippetOutput)
+    pushProfilePhase(phases, "estimateSnippetPayloadBytes", estimateStart)
+
+    return {
+        phases,
+        totalMs: Number((performance.now() - totalStart).toFixed(2)),
+        traceHopCount: metaOutput.traceData.length,
+        resolvedSourceMetaExists: Boolean(metaOutput.resolvedSourceMeta),
+        snippetPayloadBytes,
+        maxSnippetPayloadBytes,
+        snippetPayloadWouldExceedLimit: snippetPayloadBytes > maxSnippetPayloadBytes,
+    }
+}

package/src/node/trace/resolve/input.ts

@@ -0,0 +1,35 @@
+import {DEFAULT_CONTEXT_LINE_RADIUS, type TraceMetaOutputState} from "../runner";
+import type {ResolveTraceInput} from "./types";
+
+const INPUT_VALIDATION_PATTERNS = ["请输入", "必须是", "未加载"]
+
+export const parseResolveInput = (payloadText: string): ResolveTraceInput => {
+    const parsed = JSON.parse(payloadText) as ResolveTraceInput
+    if (!parsed || typeof parsed !== "object") throw new Error("invalid resolveTrace payload")
+    if (!parsed.entryFileName) throw new Error("missing argument: entryFileName")
+    if (!parsed.entryLine) throw new Error("missing argument: entryLine")
+    if (!parsed.entryColumn) throw new Error("missing argument: entryColumn")
+    if (!Array.isArray(parsed.mapFilePaths) || parsed.mapFilePaths.length === 0) {
+        throw new Error("missing argument: mapFilePaths")
+    }
+    return {
+        ...parsed,
+        contextLineRadius: parsed.contextLineRadius || String(DEFAULT_CONTEXT_LINE_RADIUS),
+    }
+}
+
+export const isInputValidationMessage = (message: string) =>
+    INPUT_VALIDATION_PATTERNS.some((pattern) => message.includes(pattern))
+
+export const toFallbackEntry = (parsed: ResolveTraceInput) => ({
+    fileName: parsed.entryFileName,
+    lineNumber: Number(parsed.entryLine) || 1,
+    columnNumber: Number(parsed.entryColumn) || 0,
+})
+
+export const createValidationMetaOutput = (message: string): TraceMetaOutputState => ({
+    traceData: [],
+    resolvedSourceMeta: null,
+    canFetchSourceSnippet: false,
+    message,
+})

package/src/node/trace/resolve/snippet-limit.ts

@@ -0,0 +1,35 @@
+import type {TraceSnippetState} from "@/shared/trace-common";
+import type {ResolveTraceInput} from "./types";
+
+export const DEFAULT_MAX_SNIPPET_PAYLOAD_BYTES = 32 * 1024
+export const SNIPPET_PAYLOAD_EXCEEDED_ERROR = "SOURCE_SNIPPET_PAYLOAD_EXCEEDED: 返回体超出限制"
+const SNIPPET_PAYLOAD_OVERHEAD_BYTES = 512
+
+export const parseMaxSnippetPayloadBytes = (input: ResolveTraceInput) => {
+    if (!input.maxSnippetPayloadBytes?.trim()) return DEFAULT_MAX_SNIPPET_PAYLOAD_BYTES
+    const parsed = Number(input.maxSnippetPayloadBytes)
+    if (!Number.isInteger(parsed) || parsed <= 0) throw new Error("maxSnippetPayloadBytes 必须是大于 0 的整数。")
+    return parsed
+}
+
+export const estimateSnippetPayloadBytes = (snippet: TraceSnippetState) => {
+    const codeBytes = Buffer.byteLength(snippet.traceCode, "utf8")
+    const sourceFileBytes = snippet.resolvedSourceMeta?.sourceFile
+        ? Buffer.byteLength(snippet.resolvedSourceMeta.sourceFile, "utf8")
+        : 0
+    const highlightBytes = snippet.traceHighlightLines.reduce((total, line) => {
+        return total + Buffer.byteLength(String(line), "utf8") + 1
+    }, 0)
+    return codeBytes + sourceFileBytes + highlightBytes + SNIPPET_PAYLOAD_OVERHEAD_BYTES
+}
+
+export const assertSnippetPayloadWithinLimit = (
+    snippet: TraceSnippetState,
+    input: ResolveTraceInput,
+) => {
+    const maxSnippetPayloadBytes = parseMaxSnippetPayloadBytes(input)
+    const payloadBytes = estimateSnippetPayloadBytes(snippet)
+    if (payloadBytes > maxSnippetPayloadBytes) throw new Error(
+        `${SNIPPET_PAYLOAD_EXCEEDED_ERROR} (${payloadBytes} bytes > ${maxSnippetPayloadBytes} bytes)`,
+    )
+}

package/src/node/trace/resolve/types.ts

@@ -0,0 +1,37 @@
+import type {SourceMapRegistry, TraceHop} from "@/node/trace/core/base/types";
+import type {TraceLocation} from "@/shared/trace-common";
+import type {ResolveTraceInput} from "@/shared/trace-contract";
+export type {ResolveTraceInput};
+
+export interface ResolveTaskContext {
+    entry: TraceLocation
+    contextLineRadius: number
+    sourceMaps: SourceMapRegistry
+    sourceMapFileNames: string[]
+}
+
+export interface ResolvedTraceContext {
+    traceChain: TraceHop[]
+    sourceCode: {
+        code: string
+        sourceFile: string
+        lineNumber: number
+        columnNumber: number
+    } | null
+    lastResolved: TraceLocation | null
+}
+
+export interface TraceProfilePhase {
+    name: string
+    durationMs: number
+}
+
+export interface ProfileResolveTraceOutput {
+    phases: TraceProfilePhase[]
+    totalMs: number
+    traceHopCount: number
+    resolvedSourceMetaExists: boolean
+    snippetPayloadBytes: number
+    maxSnippetPayloadBytes: number
+    snippetPayloadWouldExceedLimit: boolean
+}

package/src/node/trace/runner.ts

@@ -0,0 +1,149 @@
+import {MAX_TRACE_DEPTH} from "@/node/trace/core/base/constants";
+import {buildRegistryFromChainSlots, getAutoEntryFileNameFromSlots} from "@/node/trace/core/domain/chain-slots";
+import {resolveSourceCodeFromTrace, getLastResolvedOutput} from "@/node/trace/core/domain/source-content";
+import {resolveTraceBySourceMaps} from "@/node/trace/core/domain/trace-resolver";
+import {toDisplayLocation, createCodeExcerpt} from "@/node/trace/core/domain/view-model";
+import type {
+    ChainMapSlot,
+    SourceMapRegistry,
+    TraceHop,
+} from "@/node/trace/core/base/types";
+import {
+    DEFAULT_CONTEXT_LINE_RADIUS,
+    createInitialOutputState,
+    patchOutputMessage,
+    validateResolveInput,
+} from "@/shared/trace-common";
+import type {
+    TraceMetaOutputState as SharedTraceMetaOutputState,
+    TraceOutputState as SharedTraceOutputState,
+    TraceSnippetState,
+} from "@/shared/trace-common";
+import type {ResolvedTraceContext, ResolveTaskContext} from "./resolve/types";
+
+export type TraceOutputState = SharedTraceOutputState<TraceHop>
+export type TraceMetaOutputState = SharedTraceMetaOutputState<TraceHop>
+
+export interface SourceMapChainState {
+    sourceMaps: SourceMapRegistry
+    sourceMapFileNames: string[]
+    chainMapSlots: ChainMapSlot[]
+    entryFileName: string
+}
+
+interface BuildTraceSnippetOutputInput {
+    contextLineRadius: number
+    resolved: ResolvedTraceContext
+}
+
+export const buildChainStateFromSlots = (slots: ChainMapSlot[]): SourceMapChainState => {
+    const {registry, orderedMapFileNames} = buildRegistryFromChainSlots(slots)
+    return {
+        sourceMaps: registry,
+        sourceMapFileNames: orderedMapFileNames,
+        chainMapSlots: slots,
+        entryFileName: getAutoEntryFileNameFromSlots(slots),
+    }
+}
+
+export const resolveTraceContextTask = async (context: ResolveTaskContext): Promise<ResolvedTraceContext> => {
+    const traceChain = await resolveTraceBySourceMaps({
+        entry: context.entry,
+        sourceMaps: context.sourceMaps,
+        orderedMapFileNames: context.sourceMapFileNames,
+        options: {maxDepth: MAX_TRACE_DEPTH},
+    })
+
+    const sourceCode = resolveSourceCodeFromTrace(traceChain, context.sourceMaps, {
+        onlyLastMap: true,
+        lastMapFileName: context.sourceMapFileNames[context.sourceMapFileNames.length - 1],
+    })
+
+    return {
+        traceChain,
+        sourceCode,
+        lastResolved: getLastResolvedOutput(traceChain),
+    }
+}
+
+export const buildTraceMetaOutput = (resolved: ResolvedTraceContext): TraceMetaOutputState => {
+    if (resolved.sourceCode) {
+        // 第一阶段只返回元信息；大段源码由第二阶段接口按需获取。
+        return {
+            traceData: resolved.traceChain,
+            resolvedSourceMeta: {
+                sourceFile: resolved.sourceCode.sourceFile,
+                lineNumber: resolved.sourceCode.lineNumber,
+                columnNumber: resolved.sourceCode.columnNumber,
+            },
+            canFetchSourceSnippet: true,
+            message: "已定位到源码位置，开始加载源码片段。",
+        }
+    }
+
+    if (resolved.lastResolved) {
+        const display = toDisplayLocation(resolved.lastResolved)
+        return {
+            traceData: resolved.traceChain,
+            resolvedSourceMeta: {
+                sourceFile: display.fileName,
+                lineNumber: display.lineNumber,
+                columnNumber: display.columnNumber,
+            },
+            canFetchSourceSnippet: false,
+            message: "当前 map 不包含 sourcesContent，无法直接渲染源码内容。",
+        }
+    }
+
+    return {
+        traceData: resolved.traceChain,
+        resolvedSourceMeta: null,
+        canFetchSourceSnippet: false,
+        message: "未命中映射，未定位到源码位置。",
+    }
+}
+
+export const buildTraceSnippetOutput = (input: BuildTraceSnippetOutputInput): TraceSnippetState => {
+    const {contextLineRadius, resolved} = input
+    if (resolved.sourceCode) {
+        const excerpt = createCodeExcerpt({
+            fullCode: resolved.sourceCode.code,
+            targetLine: resolved.sourceCode.lineNumber,
+            radius: contextLineRadius,
+            targetColumn: resolved.sourceCode.columnNumber,
+        })
+        return {
+            traceCode: excerpt.code,
+            resolvedSourceMeta: {
+                sourceFile: resolved.sourceCode.sourceFile,
+                lineNumber: resolved.sourceCode.lineNumber,
+                columnNumber: resolved.sourceCode.columnNumber,
+            },
+            traceHighlightLines: [excerpt.highlightLine],
+        }
+    }
+
+    if (resolved.lastResolved) {
+        const display = toDisplayLocation(resolved.lastResolved)
+        return {
+            traceCode: [
+                `已定位到源码位置：${display.fileName}:${display.lineNumber}:${display.columnNumber}`,
+                "当前 map 不包含 sourcesContent，无法直接渲染源码内容。",
+            ].join("\n"),
+            resolvedSourceMeta: {
+                sourceFile: display.fileName,
+                lineNumber: display.lineNumber,
+                columnNumber: display.columnNumber,
+            },
+            traceHighlightLines: [],
+        }
+    }
+
+    return {
+        traceCode: "未命中映射，未定位到源码位置。",
+        resolvedSourceMeta: null,
+        traceHighlightLines: [],
+    }
+}
+
+export {DEFAULT_CONTEXT_LINE_RADIUS, createInitialOutputState, patchOutputMessage, validateResolveInput}