deepline 0.3.258 → 0.3.259

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

@@ -1444,34 +1444,116 @@ function sourceLoaderForPath(path: string): Loader {
   return 'ts';
 }
 
-function docflowContextIdentifierFromCall(call: AstNode): string | null {
+function isFunctionNode(node: AstNode | null | undefined): node is AstNode {
+  return (
+    !!node &&
+    (node.type === 'ArrowFunctionExpression' ||
+      node.type === 'FunctionExpression')
+  );
+}
+
+/**
+ * The run function a definePlay call declares inline: the positional callback
+ * of `definePlay(name, run, options?)`, or the `run` property (arrow, function
+ * expression, or method shorthand) of the object form `definePlay({ id, run })`.
+ */
+function definePlayRunFunction(call: AstNode): AstNode | null {
   if (!isDefinePlayCallExpression(call)) return null;
   const args = astArray(call.arguments);
-  const callback = args.find(
-    (argument) =>
-      argument.type === 'ArrowFunctionExpression' ||
-      argument.type === 'FunctionExpression',
-  );
-  if (!callback) return null;
-  return getIdentifierName(astArray(callback.params)[0]);
+  const positional = args.find((argument) => isFunctionNode(argument));
+  if (positional) return positional;
+  const config = unwrapStaticExpression(args[0] ?? null);
+  if (!config || config.type !== 'ObjectExpression') return null;
+  let run: AstNode | null = null;
+  for (const property of astArray(config.properties)) {
+    if (property.type !== 'Property') continue;
+    if (propertyNameFromKey(property) !== 'run') continue;
+    const value = unwrapStaticExpression(
+      isAstNode(property.value) ? property.value : null,
+    );
+    run = isFunctionNode(value) ? value : null;
+  }
+  return run;
+}
+
+/** Context parameter name injected into a run function that declares none. */
+const DOCFLOW_INJECTED_CONTEXT_NAME = '__deeplineDocflowContext';
+
+type DocflowContextResolution =
+  /** The run function's first parameter is a plain identifier. */
+  | { kind: 'named'; name: string }
+  /** The run function declares no parameters; one is injected at `at`. */
+  | { kind: 'inject'; name: string; at: number }
+  /** The run function exists but its context cannot be addressed. */
+  | { kind: 'unsupported'; reason: string };
+
+function docflowContextFromCall(
+  call: AstNode,
+  sourceCode: string,
+): DocflowContextResolution | null {
+  if (!isDefinePlayCallExpression(call)) return null;
+  const run = definePlayRunFunction(call);
+  if (!run) {
+    return {
+      kind: 'unsupported',
+      reason:
+        'its definePlay call does not declare the run function inline (pass `definePlay(name, async (ctx, input) => …)` or `definePlay({ id, run: async (ctx, input) => … })`)',
+    };
+  }
+  const params = astArray(run.params);
+  const first = params[0];
+  if (first) {
+    const name = getIdentifierName(first);
+    return name
+      ? { kind: 'named', name }
+      : {
+          kind: 'unsupported',
+          reason: `its run function's first parameter is not a plain identifier (found ${first.type}; declare the context as \`ctx\` and destructure inside the body)`,
+        };
+  }
+  const runBounds = astNodeBounds(run);
+  const body = isAstNode(run.body) ? astNodeBounds(run.body) : null;
+  if (!runBounds || !body) {
+    return {
+      kind: 'unsupported',
+      reason: 'its run function has no source span',
+    };
+  }
+  const signature = sourceCode.slice(runBounds.start, body.start);
+  const emptyParams = /\(\s*\)/.exec(signature);
+  if (!emptyParams) {
+    return {
+      kind: 'unsupported',
+      reason: 'its parameterless run function has no `()` parameter list',
+    };
+  }
+  return {
+    kind: 'inject',
+    name: DOCFLOW_INJECTED_CONTEXT_NAME,
+    at: runBounds.start + emptyParams.index + 1,
+  };
 }
 
 /**
  * Finds the context parameter for the definePlay call that owns one binding.
  * A file may export several plays with different parameter names, so a single
  * file-global context identifier is not safe for instrumentation.
+ *
+ * `null` means no definePlay call owns the binding: it sits in a module-level
+ * helper the run function calls, which has no context in scope.
  */
-function findDocflowContextIdentifier(input: {
+function findDocflowContext(input: {
   ast: AstNode;
+  sourceCode: string;
   statement: AstNode | null;
   bindingLine: number;
   lineStarts: readonly number[];
   parents: ReadonlyMap<AstNode, AstNode>;
-}): string | null {
+}): DocflowContextResolution | null {
   let owner: AstNode | null = input.statement;
   while (owner) {
-    const contextName = docflowContextIdentifierFromCall(owner);
-    if (contextName) return contextName;
+    const context = docflowContextFromCall(owner, input.sourceCode);
+    if (context) return context;
     owner = input.parents.get(owner) ?? null;
   }
 
@@ -1504,7 +1586,7 @@ function findDocflowContextIdentifier(input: {
       else if (isAstNode(child)) pending.push(child);
     }
   }
-  return best ? docflowContextIdentifierFromCall(best) : null;
+  return best ? docflowContextFromCall(best, input.sourceCode) : null;
 }
 
 type DocflowInstrumentationReplacement = {
@@ -1530,6 +1612,14 @@ function docflowObservationTarget(
   end: number;
   awaitsResult: boolean;
   expression: AstNode;
+  /**
+   * The statement is a `throw`: its node is observed FAILING, not completing.
+   * The observed span is the thrown value, and the observation itself throws
+   * it — so the node settles as failed with the authored error, and the outer
+   * `throw` it replaces is never reached. A hit marker before the statement
+   * used to record the node completed an instant before the run failed there.
+   */
+  throws: boolean;
 } | null {
   if (!statement) return null;
   let expression: AstNode | null = null;
@@ -1550,6 +1640,11 @@ function docflowObservationTarget(
     expression = statement.expression;
   } else if (statement.type === 'IfStatement' && isAstNode(statement.test)) {
     expression = statement.test;
+  } else if (
+    statement.type === 'ThrowStatement' &&
+    isAstNode(statement.argument)
+  ) {
+    expression = statement.argument;
   }
   if (!expression) return null;
   const bounds = astNodeBounds(expression);
@@ -1558,6 +1653,7 @@ function docflowObservationTarget(
     ...bounds,
     awaitsResult: expressionContainsTopLevelAwait(expression),
     expression,
+    throws: statement.type === 'ThrowStatement',
   };
 }
 
@@ -1568,10 +1664,13 @@ function docflowObservedExpression(input: {
   outputs: readonly string[];
   expression: string;
   awaitsResult: boolean;
+  /** Observe the expression as the value a `throw` raises (see `throws`). */
+  throws?: boolean;
 }): string {
-  const callback = input.awaitsResult
-    ? `async()=>(${input.expression})`
-    : `()=>(${input.expression})`;
+  const body = input.throws
+    ? `{throw (${input.expression})}`
+    : `(${input.expression})`;
+  const callback = input.awaitsResult ? `async()=>${body}` : `()=>${body}`;
   const observation = `((runtimeContext,inputCaptures,execute)=>typeof runtimeContext.__deeplineObserveDocflowNode==="function"?runtimeContext.__deeplineObserveDocflowNode(${JSON.stringify(input.nodeId)},inputCaptures,${JSON.stringify(input.outputs)},execute):execute())(${input.contextName},${docflowInputCaptureSource(input.inputs)},${callback})`;
   // Parenthesize the awaited form so it is self-delimiting at every source
   // boundary, including compact `return{...}` syntax. This avoids relying on
@@ -1627,10 +1726,13 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
     start: number;
     end: number;
     awaitsResult: boolean;
+    throws: boolean;
     contextName: string;
     binding: PlayDocflowBinding;
   };
   const targets: ObservationTarget[] = [];
+  /** Parameterless run functions that receive an injected context param. */
+  const injectedContextAt = new Set<number>();
 
   // Build the parent index once so every binding's symbol resolution reuses it.
   const parents = buildDocflowParentIndex(ast);
@@ -1639,14 +1741,27 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
     // to positional resolution. Instrumentation and `plays check` share this
     // resolver, so the observed statement and the lint agree.
     const resolution = resolveDocflowBinding(ast, binding, lineStarts, parents);
-    const contextName = findDocflowContextIdentifier({
+    const context = findDocflowContext({
       ast,
+      sourceCode,
       statement: resolution.statement,
       bindingLine: binding.line,
       lineStarts,
       parents,
     });
-    if (!contextName) continue;
+    // No owning definePlay: the binding is in a module-level helper with no
+    // context in scope, so it is observed through its caller's bindings.
+    if (!context) continue;
+    if (context.kind === 'unsupported') {
+      throw new Error(
+        `@mermaid-node ${binding.nodeId} (line ${binding.line}) cannot be observed at runtime: ${context.reason}.`,
+      );
+    }
+    if (context.kind === 'inject') injectedContextAt.add(context.at);
+    // An injected parameter is undefined when the run function is invoked
+    // directly (outside the runtime), so its reads stay null-safe.
+    const contextName =
+      context.kind === 'inject' ? `(${context.name}??{})` : context.name;
     const target = docflowObservationTarget(resolution.statement);
     // A binding naming a `.step('<leg>', …)` leg of a waterfall is NOT
     // instrumented, and the omission is deliberate rather than a gap.
@@ -1706,6 +1821,7 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
     start: number;
     end: number;
     awaitsResult: boolean;
+    throws: boolean;
     contextName: string;
     bindings: PlayDocflowBinding[];
   };
@@ -1719,6 +1835,7 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
         start: target.start,
         end: target.end,
         awaitsResult: target.awaitsResult,
+        throws: target.throws,
         contextName: target.contextName,
         bindings: [target.binding],
       });
@@ -1728,6 +1845,9 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
   for (const group of groups) {
     // Wrap in reverse order so the first-listed annotation observes outermost.
     let expression = sourceCode.slice(group.start, group.end);
+    // Only the innermost observation raises a thrown value; every annotation
+    // wrapped around it sees that raise as its own failure.
+    let innermost = true;
     for (const binding of [...group.bindings].reverse()) {
       expression = docflowObservedExpression({
         contextName: group.contextName,
@@ -1736,7 +1856,9 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
         outputs: binding.outputs ?? [],
         expression,
         awaitsResult: group.awaitsResult,
+        throws: group.throws && innermost,
       });
+      innermost = false;
     }
     replacements.push({
       start: group.start,
@@ -1745,6 +1867,14 @@ export function instrumentPlayDocflowRuntimeHits(sourceCode: string): string {
     });
   }
 
+  for (const at of injectedContextAt) {
+    replacements.push({
+      start: at,
+      end: at,
+      value: DOCFLOW_INJECTED_CONTEXT_NAME,
+    });
+  }
+
   return replacements
     .sort((left, right) => right.start - left.start)
     .reduce(

package/dist/bundling-sources/shared_libs/plays/cascade-falloff.ts

@@ -0,0 +1,86 @@
+// A cascade's falloff on one run: how many rows reached each attempt, how many
+// it answered, and how many were left for the next — derived from the run
+// summary's leg-hit patterns (`SheetSummary.cascades`) and the cascade's
+// declared attempt order.
+//
+// A row is answered by the FIRST attempt, in declared order, whose leg holds a
+// value. That is the waterfall's meaning even when later attempts also ran
+// (a `steps()` chain without `runIf` runs every leg), so a later attempt never
+// gets credit for a row an earlier one already answered.
+//
+// PURE — shared by the dashboard and the CLI so both state the same numbers.
+
+export type CascadeFillPattern = {
+  /** The leg columns that held a value on these rows. */
+  filled: readonly string[];
+  rows: number;
+};
+
+export type CascadeFalloffStep = {
+  leg: string;
+  /** Rows no earlier attempt answered. */
+  entering: number;
+  /** Rows this attempt answered first. */
+  hits: number;
+  /** Rows still unanswered after this attempt. */
+  remaining: number;
+};
+
+export type CascadeFalloff = {
+  /** The rows the cascade worked on. */
+  total: number;
+  steps: CascadeFalloffStep[];
+  /** Rows no attempt answered. */
+  noResult: number;
+};
+
+export function cascadeFalloff(input: {
+  /** Leg columns in the cascade's declared order. */
+  legs: readonly string[];
+  patterns: readonly CascadeFillPattern[];
+  /** Rows the cascade worked on (the run's rows in its table). */
+  total: number;
+}): CascadeFalloff {
+  const order = new Map(input.legs.map((leg, index) => [leg, index]));
+  const firstHits = input.legs.map(() => 0);
+  for (const pattern of input.patterns) {
+    let first = -1;
+    for (const leg of pattern.filled) {
+      const index = order.get(leg);
+      if (index !== undefined && (first === -1 || index < first)) first = index;
+    }
+    if (first !== -1) firstHits[first] += pattern.rows;
+  }
+  const answered = firstHits.reduce((sum, hits) => sum + hits, 0);
+  const total = Math.max(input.total, answered);
+  let entering = total;
+  const steps = input.legs.map((leg, index) => {
+    const hits = firstHits[index]!;
+    const step = { leg, entering, hits, remaining: entering - hits };
+    entering -= hits;
+    return step;
+  });
+  return { total, steps, noResult: total - answered };
+}
+
+/** `x%` — a count's share of `total`, never rounding a partial share up to a
+ *  whole one or down to nothing. */
+export function formatHitRate(count: number, total: number): string {
+  if (total <= 0) return '—';
+  const share = (count / total) * 100;
+  const percent =
+    share === 0 || share === 100
+      ? share.toString()
+      : share >= 10
+        ? Math.min(99, Math.round(share)).toString()
+        : share < 1
+          ? '<1'
+          : share.toFixed(1).replace(/\.0$/, '');
+  return `${percent}%`;
+}
+
+/** `n · x%` — a count and its share of `total`, for a dense surface. */
+export function formatHitShare(count: number, total: number): string {
+  if (total <= 0) return count.toLocaleString('en-US');
+  return `${count.toLocaleString('en-US')} · ${formatHitRate(count, total)}`;
+}