deepline 0.3.195 → 0.3.197

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -102,6 +102,16 @@ export type PlayDocflowSubgraph = {
 export type PlayDocflowBinding = {
   nodeId: string;
   line: number;
+  /**
+   * The file this annotation was written in, when it did not come from the play
+   * entry file. A play whose step program lives in a `-core` module has no
+   * statement in its `.play.ts` to annotate, so its boxes could only ever be
+   * sketches; annotations are read from the entry's import closure to fix that.
+   *
+   * `line` is only meaningful together with this: two files both have a line
+   * 42, so any positional comparison must agree on the path first.
+   */
+  sourcePath?: string;
   label?: string;
   kind?: PlayDocflowNodeKind;
   /** Symbolic values read by this business node. Never an arbitrary JS expression. */
@@ -153,6 +163,12 @@ export type ParsePlayDocflowOptions = {
    * both `scalar` and `default`.
    */
   exportName?: string | null;
+  /**
+   * Source of every module the entry imports, keyed by path. Annotations found
+   * here bind to the entry's diagrams exactly like the entry's own — routing is
+   * by node id, which never depended on which file the annotation sat in.
+   */
+  moduleSources?: ReadonlyMap<string, string> | null;
 };
 
 /** One `@mermaid` block, already bound to the export it describes. */
@@ -233,6 +249,8 @@ export function docflowLabelCountFragment(label: string): string | null {
 
 const FLOW_START = /^\s*(?:flowchart|graph)\s+(LR|RL|TB|TD|BT)\s*$/i;
 const MERMAID_NODE = /^\s*\/\/\s*@mermaid-node\s+([A-Za-z][\w-]*)(?:\s+(.*))?$/;
+/** Whole-file pre-filter for {@link MERMAID_NODE}; skips splitting clean files. */
+const MERMAID_NODE_HINT = /@mermaid-node/;
 const ATTRIBUTE = /([A-Za-z][\w-]*)\s*:\s*"([^"\n]*)"/y;
 const MERMAID_NODE_ATTRIBUTES = ['label', 'type', 'in', 'out', 'arm'] as const;
 const MERMAID_NODE_ID = /^[A-Za-z][\w-]*/;
@@ -929,6 +947,7 @@ function materializeDocflow(block: ParsedDocflowBlock): PlayDocflow {
  */
 export function parsePlayDocflowFile(
   sourceCode: string,
+  moduleSources?: ReadonlyMap<string, string> | null,
 ): PlayDocflowFileParseResult {
   const errors: string[] = [];
   const rawBlocks: Array<{
@@ -948,7 +967,19 @@ export function parsePlayDocflowFile(
   // the author already has one actionable error about them, and telling them to
   // "bind it" on the next line is telling them to do what they just did.
   const rejectedNodeIds = new Set<string>();
-  const bindings = parseDocflowBindings(sourceCode, errors, rejectedNodeIds);
+  // The entry first, then the modules it imports. Only files that actually
+  // contain an annotation are split into lines: a play's closure is mostly
+  // helpers and types, and this runs on every publish.
+  const annotationSources: DocflowAnnotationSource[] = [{ sourceCode }];
+  for (const [sourcePath, moduleCode] of moduleSources ?? []) {
+    if (!MERMAID_NODE_HINT.test(moduleCode)) continue;
+    annotationSources.push({ sourceCode: moduleCode, sourcePath });
+  }
+  const bindings = parseDocflowBindings(
+    annotationSources,
+    errors,
+    rejectedNodeIds,
+  );
 
   const parsedBlocks: ParsedDocflowBlock[] = [];
   for (const raw of rawBlocks) {
@@ -1326,7 +1357,7 @@ export function parsePlayDocflow(
   sourceCode: string,
   options: ParsePlayDocflowOptions = {},
 ): PlayDocflowParseResult {
-  const parsed = parsePlayDocflowFile(sourceCode);
+  const parsed = parsePlayDocflowFile(sourceCode, options.moduleSources);
   const requested = options.exportName?.trim() || PLAY_DEFAULT_EXPORT;
   const selected =
     parsed.blocks.find((block) => block.exportName === requested) ??
@@ -1354,10 +1385,32 @@ export function parsePlayDocflow(
  * to themselves afterwards; the annotations themselves are file-scoped text.
  */
 function parseDocflowBindings(
-  sourceCode: string,
+  sources: readonly DocflowAnnotationSource[],
+  errors: string[],
+  rejectedNodeIds: Set<string>,
+): PlayDocflowBinding[] {
+  const bindings: PlayDocflowBinding[] = [];
+  for (const source of sources) {
+    bindings.push(
+      ...parseDocflowBindingsInSource(source, errors, rejectedNodeIds),
+    );
+  }
+  return bindings;
+}
+
+/** One file that may carry `// @mermaid-node` annotations. */
+type DocflowAnnotationSource = {
+  sourceCode: string;
+  /** Omitted for the entry file, whose paths readers already know. */
+  sourcePath?: string;
+};
+
+function parseDocflowBindingsInSource(
+  source: DocflowAnnotationSource,
   errors: string[],
   rejectedNodeIds: Set<string>,
 ): PlayDocflowBinding[] {
+  const { sourceCode, sourcePath } = source;
   const lines = sourceCode.split(/\r?\n/);
   const bindings: PlayDocflowBinding[] = [];
 
@@ -1440,6 +1493,7 @@ function parseDocflowBindings(
     bindings.push({
       nodeId: id,
       line: nextLine + 1,
+      ...(sourcePath ? { sourcePath } : {}),
       ...(attributes.label ? { label: attributes.label } : {}),
       ...(kind ? { kind } : {}),
       // Spread, never `arm: arm ?? undefined` — see `PlayDocflowEdge.arm`. An

package/dist/bundling-sources/shared_libs/plays/share/static-pipeline-summary.ts

@@ -438,6 +438,9 @@ export function buildStaticPipelineSummary(
 // param sources never need to cross the public boundary.
 const SUBSTEP_STRIP_KEYS = new Set([
   'sourceRange',
+  // Same reason as `sourceRange`, and the same shape: it carries the absolute
+  // path of the file the call was made from, which is an author's machine.
+  'callSiteRange',
   'sourcePath',
   'callPath',
   'callDepth',

package/dist/bundling-sources/shared_libs/plays/static-pipeline.ts

@@ -757,6 +757,9 @@ function storageSafeNodeValue(
   if (asStaticRecord(value.sourceRange)) {
     out.sourceRange = { ...(value.sourceRange as Record<string, unknown>) };
   }
+  if (asStaticRecord(value.callSiteRange)) {
+    out.callSiteRange = { ...(value.callSiteRange as Record<string, unknown>) };
+  }
   if (asStaticRecord(value.sheetContract)) {
     out.sheetContract = cloneStorageSafeSheetContract(
       value.sheetContract as PlaySheetContract,
@@ -1224,6 +1227,24 @@ export interface PlayStaticSourceRange {
 type PlayStaticSubstepMetadata = {
   conditional?: boolean;
   disabled?: boolean;
+  /**
+   * Where this substep was REACHED FROM, when the extractor resolved it by
+   * following a call into another function — the range of the call expression
+   * itself, in the file that made the call.
+   *
+   * The extractor hops through `resolveLocalCallable`, which is TypeScript
+   * symbol resolution (`getSymbol()` / `getAliasedSymbol()`), so the callee may
+   * live anywhere in the import closure. Its `sourceRange` then points at the
+   * helper's body, which no annotation in the CALLING file can ever contain.
+   * That is why a binding on `const identity = await resolveCompanyIdentity(…)`
+   * could not reach the `ctx.tools.execute` inside it.
+   *
+   * Recorded as the OUTERMOST hop: unwinding stamps each level, so a tool three
+   * helpers deep ends up carrying the call site in the annotated function
+   * rather than an intermediate one. Absent whenever the substep was found
+   * directly in the function being analyzed.
+   */
+  callSiteRange?: PlayStaticSourceRange;
 };
 
 /**