deepline 0.2.53 → 0.2.55

package/dist/bundling-sources/shared_libs/plays/play-exports.ts

@@ -0,0 +1,202 @@
+/**
+ * Which plays a source file exports, esbuild-free.
+ *
+ * A `.play.ts` file may export more than one play — the shipped prebuilts pair
+ * `export const scalar` with `export const batch` and end `export default
+ * scalar`. Two callers need that list and neither can reach esbuild:
+ * `plays check` (which must check every exported play, not only the default)
+ * and the docflow parser (which must decide which `@mermaid` block belongs to
+ * which export). The bundler owns the same knowledge behind its esbuild
+ * fallback parse; this is the acorn-only subset both can share.
+ *
+ * Abstains (returns `null`) rather than guessing: source acorn cannot parse, or
+ * a file with no recognizable `definePlay` export, leaves the caller on its
+ * existing default-export behaviour.
+ */
+import {
+  astArray,
+  isAstNode,
+  parsePlaySourceForAnalysis,
+  type AstNode,
+} from './ts-ast';
+
+/** The export name the runtime, the registry and the CLI all use for a file's
+ *  default play. Aliases resolve to it, never the other way round. */
+export const PLAY_DEFAULT_EXPORT = 'default';
+
+export type PlayFileExport = {
+  /**
+   * The canonical name this play is addressed by. `default` wins whenever the
+   * play is the file's default export, even when the same value also has a
+   * named export — `export const scalar = definePlay(…); export default scalar`
+   * is ONE play, canonically `default`.
+   */
+  name: string;
+  /** Other export names that resolve to the same `definePlay` call. */
+  aliases: string[];
+};
+
+function getIdentifierName(node: unknown): string | null {
+  return isAstNode(node) && node.type === 'Identifier'
+    ? typeof node.name === 'string'
+      ? node.name
+      : null
+    : null;
+}
+
+function unwrapStaticExpression(node: AstNode | null): AstNode | null {
+  let current = node;
+  while (
+    current &&
+    (current.type === 'TSAsExpression' ||
+      current.type === 'TSSatisfiesExpression' ||
+      current.type === 'TSTypeAssertion' ||
+      current.type === 'TSNonNullExpression' ||
+      current.type === 'ParenthesizedExpression')
+  ) {
+    current = isAstNode(current.expression) ? current.expression : null;
+  }
+  return current;
+}
+
+/** `definePlay(…)` / `defineWorkflow(…)`, bare or as a member call. Mirrors the
+ *  bundler's recognizer so both agree on what counts as a play. */
+export function isDefinePlayCall(node: AstNode | null): boolean {
+  const expression = unwrapStaticExpression(node);
+  if (!expression || expression.type !== 'CallExpression') return false;
+  const callee = isAstNode(expression.callee) ? expression.callee : null;
+  if (!callee) return false;
+  if (callee.type === 'Identifier') {
+    return callee.name === 'definePlay' || callee.name === 'defineWorkflow';
+  }
+  if (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    isAstNode(callee.property) &&
+    callee.property.type === 'Identifier'
+  ) {
+    return (
+      callee.property.name === 'definePlay' ||
+      callee.property.name === 'defineWorkflow'
+    );
+  }
+  return false;
+}
+
+/**
+ * The plays `sourceCode` exports, default first, then named exports in source
+ * order. `null` means acorn could not parse the file — the caller abstains and
+ * the TypeScript diagnostics own the syntax error. An EMPTY array is a real
+ * answer: the file parses and exports no `definePlay`.
+ */
+export function listPlayFileExports(
+  sourceCode: string,
+): PlayFileExport[] | null {
+  const ast = parsePlaySourceForAnalysis(sourceCode);
+  if (!ast) return null;
+
+  /** Local const/let/var name -> its initializer, for resolving `export { x }`
+   *  and `export default x` back to the `definePlay` call they name. */
+  const declarations = new Map<string, AstNode | null>();
+  /** Exported name -> local name, in source order. */
+  const namedExports = new Map<string, string>();
+  let defaultExpression: AstNode | null = null;
+
+  const recordDeclarations = (declaration: AstNode, exported: boolean) => {
+    for (const declarator of astArray(declaration.declarations)) {
+      const name = getIdentifierName(declarator.id);
+      if (!name) continue;
+      declarations.set(
+        name,
+        isAstNode(declarator.init) ? declarator.init : null,
+      );
+      if (exported) namedExports.set(name, name);
+    }
+  };
+
+  for (const statement of astArray(ast.body)) {
+    if (statement.type === 'VariableDeclaration') {
+      recordDeclarations(statement, false);
+      continue;
+    }
+    if (statement.type === 'ExportDefaultDeclaration') {
+      defaultExpression = isAstNode(statement.declaration)
+        ? statement.declaration
+        : null;
+      continue;
+    }
+    if (statement.type === 'TSExportAssignment') {
+      defaultExpression = isAstNode(statement.expression)
+        ? statement.expression
+        : null;
+      continue;
+    }
+    if (statement.type !== 'ExportNamedDeclaration') continue;
+    if (
+      isAstNode(statement.declaration) &&
+      statement.declaration.type === 'VariableDeclaration'
+    ) {
+      recordDeclarations(statement.declaration, true);
+    }
+    for (const specifier of astArray(statement.specifiers)) {
+      const localName = getIdentifierName(specifier.local);
+      const exportedName = getIdentifierName(specifier.exported);
+      if (localName && exportedName) namedExports.set(exportedName, localName);
+    }
+  }
+
+  // The default export's local name, when it is `export default <identifier>`.
+  // That identifier is an ALIAS of `default`, not a second play.
+  const defaultLocalName = getIdentifierName(
+    unwrapStaticExpression(defaultExpression),
+  );
+  const defaultIsPlay = defaultLocalName
+    ? isDefinePlayCall(declarations.get(defaultLocalName) ?? null)
+    : isDefinePlayCall(defaultExpression);
+
+  const exports: PlayFileExport[] = [];
+  const aliasedLocals = new Set<string>();
+  if (defaultIsPlay) {
+    const aliases = defaultLocalName
+      ? [...namedExports.entries()]
+          .filter(([, local]) => local === defaultLocalName)
+          .map(([exported]) => exported)
+      : [];
+    if (defaultLocalName) aliasedLocals.add(defaultLocalName);
+    exports.push({ name: PLAY_DEFAULT_EXPORT, aliases });
+  }
+  for (const [exportedName, localName] of namedExports) {
+    if (exportedName === PLAY_DEFAULT_EXPORT) continue;
+    if (aliasedLocals.has(localName)) continue;
+    if (!isDefinePlayCall(declarations.get(localName) ?? null)) continue;
+    exports.push({ name: exportedName, aliases: [] });
+  }
+
+  return exports;
+}
+
+/**
+ * Resolves an export name a caller or an `@mermaid <name>` header wrote to its
+ * canonical name. `scalar` in `export default scalar` resolves to `default`;
+ * an unknown name resolves to `null` so the caller can fail loudly with the
+ * available set rather than silently binding nothing.
+ */
+export function canonicalPlayExportName(
+  exportName: string | null | undefined,
+  exports: readonly PlayFileExport[],
+): string | null {
+  const requested = exportName?.trim() || PLAY_DEFAULT_EXPORT;
+  for (const entry of exports) {
+    if (entry.name === requested || entry.aliases.includes(requested)) {
+      return entry.name;
+    }
+  }
+  return null;
+}
+
+/** Every name an author may legally write, for a "valid names are …" message. */
+export function playExportNamesForMessage(
+  exports: readonly PlayFileExport[],
+): string[] {
+  return exports.flatMap((entry) => [entry.name, ...entry.aliases]);
+}

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

@@ -1,5 +1,6 @@
 import { normalizeTableNamespace } from './row-identity';
 import { sqlSafePlayColumnName } from '../play-data-plane/column-names';
+import type { PlayDocflow } from './docflow';
 
 export { sqlSafePlayColumnName };
 
@@ -23,6 +24,8 @@ export interface PlayStaticReturnField {
 }
 
 export interface PlayStaticPipeline {
+  /** Authored business flow. Static analysis is used only when this is absent. */
+  docflow?: PlayDocflow;
   tableNamespace?: string;
   inputFields?: string[];
   rowKeyFields?: string[];
@@ -138,7 +141,10 @@ export function deriveStaticPipelineEntryInputFields(
 }
 
 export type PlaySheetColumnSource =
-  'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
+  | 'input'
+  | 'datasetColumn'
+  | 'waterfallStep'
+  | 'childPlayColumn';
 
 export interface PlaySheetColumnContract {
   id: string;
@@ -444,6 +450,9 @@ function truncateStaticSubstepsForStorage(
             }))
           : undefined,
         waterfallIds: base.waterfallIds ? [...base.waterfallIds] : undefined,
+        undrawnColumns: base.undrawnColumns
+          ? [...base.undrawnColumns]
+          : undefined,
         steps: truncateStaticSubstepsForStorage(base.steps, nestedInput),
         sheetContract: cloneStorageSafeSheetContract(base.sheetContract),
       });
@@ -1146,6 +1155,12 @@ export type PlayStaticSubstep = PlayStaticSubstepMetadata &
         waterfallIds?: string[];
         steps?: PlayStaticSubstep[];
         sheetContract?: PlaySheetContract | null;
+        /**
+         * Columns the author declared as deliberately absent from the `@mermaid`
+         * diagram via `.run({ undrawnColumns: [...] })`. The docflow column
+         * coverage gate reads this; nothing about execution does.
+         */
+        undrawnColumns?: string[];
         description?: string;
         sourceRange?: PlayStaticSourceRange;
         callDepth?: number;

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

@@ -0,0 +1,48 @@
+/**
+ * The acorn TypeScript parser and the two guards every play-source analyzer
+ * needs, in one dependency-free module.
+ *
+ * Extracted so modules that must not import each other can still share one
+ * parser configuration: `docflow-binding` (binding resolution) and
+ * `play-exports` (which plays a file exports) both parse the same source, and
+ * a second parser config would be a silent divergence rather than a loud one.
+ */
+import { Parser } from 'acorn';
+import { tsPlugin } from 'acorn-typescript';
+
+export type AstNode = {
+  type: string;
+  [key: string]: unknown;
+};
+
+export const TypeScriptParser = Parser.extend(
+  tsPlugin({
+    allowSatisfies: true,
+    jsx: {
+      allowNamespaces: true,
+      allowNamespacedObjects: true,
+    },
+  }) as unknown as (BaseParser: typeof Parser) => typeof Parser,
+);
+
+export function isAstNode(value: unknown): value is AstNode {
+  return value !== null && typeof value === 'object' && 'type' in value;
+}
+
+export function astArray(value: unknown): AstNode[] {
+  return Array.isArray(value) ? value.filter(isAstNode) : [];
+}
+
+/** Parses play source for analysis. `null` when acorn cannot: the caller
+ *  abstains, and the TypeScript diagnostics own the syntax error. */
+export function parsePlaySourceForAnalysis(sourceCode: string): AstNode | null {
+  try {
+    return TypeScriptParser.parse(sourceCode, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      allowHashBang: true,
+    }) as unknown as AstNode;
+  } catch {
+    return null;
+  }
+}