deepline 0.3.90 → 0.3.92

package/dist/bundling-sources/shared_libs/plays/transform-factor-structure.ts

@@ -0,0 +1,377 @@
+/**
+ * Factor structure of a code transform — the descriptive shape a trace UI needs
+ * to render an authored lambda as readable factors instead of raw code.
+ *
+ * A cell produced by a provider call explains itself: there is a tool, an
+ * input, a response. A cell produced by CODE does not. The trace can show the
+ * lambda verbatim, and most readers cannot read it. This module's types
+ * describe the one thing that IS mechanically recoverable from the source: the
+ * named intermediate steps, what each one reads, and how they combine.
+ *
+ * Three properties are load-bearing:
+ *
+ * 1. **Static, never evaluated.** Nothing here says which branch fired. The
+ *    structure states "40 when employees >= 1000, else 25 when >= 200, else
+ *    10"; the UI juxtaposes the row's actual values beside it so a human draws
+ *    the conclusion. An extractor that evaluated would be a second, silently
+ *    divergent implementation of the runtime.
+ * 2. **Whole or nothing.** A lambda outside the supported shape yields no
+ *    structure at all, with a reason. A structure that quietly dropped a
+ *    statement would read as complete and be a lie, which is worse for a
+ *    provenance surface than showing the code.
+ * 3. **Partial only when marked.** Where a sub-expression cannot be structured,
+ *    it is carried verbatim and flagged (`opaque`), so the renderer shows the
+ *    author's own text rather than a paraphrase it cannot justify.
+ *
+ * These types are deliberately dependency-free: the extractor (which needs the
+ * TypeScript compiler) and the renderer model (which runs in the browser) both
+ * import them, and only the extractor may pay for the compiler.
+ */
+
+/** A column read off the transform's row parameter. */
+export type TransformInputRef = {
+  /** Dataset column, e.g. `company_profile` for `row.company_profile`. */
+  column: string;
+  /** Property path under the column, e.g. `['basic_info','name']`. */
+  path?: string[];
+};
+
+/**
+ * Everything an expression reaches for.
+ *
+ * `externals` are identifiers resolved outside the lambda that are not calls —
+ * a module constant, say. They are named rather than inlined: the extractor
+ * reads one lambda, and claiming to know an external's value would be a guess.
+ */
+export type TransformRefs = {
+  inputs: TransformInputRef[];
+  factors: string[];
+  /** Called functions, by written name (`employeeFloor`, `Number`, `Math.max`). */
+  calls: string[];
+  externals: string[];
+};
+
+/** A value position: a leaf of the structure. `text` is always the authored text. */
+export type TransformValue =
+  | { kind: 'literal'; text: string }
+  | { kind: 'input'; text: string; input: TransformInputRef }
+  | { kind: 'factor'; text: string; name: string }
+  | {
+      kind: 'call';
+      text: string;
+      /**
+       * The name at the call position. WITHOUT `receiver` it is a function a
+       * reader can look up (`employeeFloor`, `Number`, `Math.max`). WITH
+       * `receiver` it is a METHOD name and means nothing on its own: `trim` is
+       * not a function anybody can find, it is what was done to the receiver.
+       */
+      callee: string;
+      args: TransformValue[];
+      /**
+       * The value the method was reached THROUGH, when the call is a method
+       * call — `String(row.domain)` in `String(row.domain).trim()`.
+       *
+       * Absent for a plain named call, and the absence is load-bearing: a
+       * consumer that evaluates the language's own coercions (`Number`,
+       * `String`, `Boolean`) must not fire on `x.Number(y)`, which is somebody
+       * else's method that happens to share a name.
+       */
+      receiver?: TransformValue;
+    }
+  /**
+   * A property reached through another value — `profile.company.name`,
+   * `parts[0]`, `String(row.domain).length`.
+   *
+   * Only a STATIC key: a name, or a literal index. `row[key]` names a property
+   * nobody can read off the source, and it stays verbatim rather than being
+   * described as a property called `key`.
+   *
+   * `optional` is the author's `?.`, and it is carried because it changes what
+   * happens on a missing object: with it the read yields undefined, without it
+   * the run threw. A consumer that flattened the two would state a value for a
+   * row whose run never got this far.
+   */
+  | {
+      kind: 'member';
+      text: string;
+      object: TransformValue;
+      property: string;
+      optional: boolean;
+    }
+  /**
+   * A fallback chain — `row.name ?? row.legal_name ?? null`.
+   *
+   * The operands are in the order the author wrote them, which is the order
+   * they are tried in. Nothing here says which one won: that depends on the
+   * row, and deciding it is the consumer's job over recorded values, exactly as
+   * it is for a conditional's arms.
+   */
+  | {
+      kind: 'coalesce';
+      operator: TransformCoalesceOperator;
+      text: string;
+      operands: TransformValue[];
+    }
+  /**
+   * A template literal, as the described parts it joins —
+   * `` `${row.first_name} ${row.last_name}` `` is three parts, the middle one a
+   * literal space.
+   *
+   * Only an UNTAGGED template. A tagged one runs the tag's body over the parts,
+   * and that body is not in this structure, so it stays verbatim.
+   */
+  | { kind: 'concat'; text: string; parts: TransformValue[] }
+  /**
+   * An identifier bound outside the transform — a module constant, an import.
+   *
+   * NAMED, never valued. The extractor reads one lambda; what a module constant
+   * holds at run time is not in it, and a leaf that claimed to know would be
+   * guessing. Distinct from `expression` because there IS something to say
+   * here: a reader can go and look this name up.
+   */
+  | { kind: 'external'; text: string; name: string }
+  /** Anything else, carried verbatim. Never paraphrased. */
+  | { kind: 'expression'; text: string };
+
+export type TransformComparisonOperator =
+  | '==='
+  | '!=='
+  | '=='
+  | '!='
+  | '>='
+  | '>'
+  | '<='
+  | '<';
+
+/**
+ * A test in a conditional.
+ *
+ * `truthiness` is the bare `row.headquarters ? 15 : 0` shape — the author asked
+ * whether a value is there at all, and the renderer says exactly that rather
+ * than inventing a comparison the code does not make.
+ */
+export type TransformCondition =
+  | {
+      kind: 'comparison';
+      text: string;
+      left: TransformValue;
+      operator: TransformComparisonOperator;
+      right: TransformValue;
+    }
+  | {
+      kind: 'truthiness';
+      text: string;
+      subject: TransformValue;
+      negated: boolean;
+    }
+  | { kind: 'all'; text: string; parts: TransformCondition[] }
+  | { kind: 'any'; text: string; parts: TransformCondition[] }
+  /** Structurally unreadable, carried verbatim. */
+  | { kind: 'opaque'; text: string };
+
+/** One arm of a ternary chain: this condition selects this value. */
+export type TransformConditionArm = {
+  condition: TransformCondition;
+  value: TransformValue;
+  /** What this arm's test and value read. */
+  refs: TransformRefs;
+};
+
+/** Arithmetic operators the extractor will flatten into an operand list. */
+export type TransformCombinationOperator = '+' | '-' | '*' | '/' | '%';
+
+/**
+ * The two fallback operators, kept APART because they ask different questions.
+ *
+ * `??` takes the first operand that is neither null nor undefined. `||` takes
+ * the first TRUTHY one, so it also steps over `0`, `''` and `false` — values an
+ * author may well have meant to keep. Describing both as "first present of"
+ * would state the wrong rule for half the corpus, so the operator travels with
+ * the structure and every renderer says which one it is looking at.
+ */
+export type TransformCoalesceOperator = '??' | '||';
+
+/**
+ * How a factor (or the transform's result) gets its value.
+ *
+ * `value` with an `expression` leaf is the marked-partial case: the rule was
+ * not structurable, and the factor carries `opaque: true` so the renderer
+ * prints the author's text instead of a description of it.
+ */
+export type TransformRule =
+  | { kind: 'value'; value: TransformValue }
+  | {
+      kind: 'conditional';
+      arms: TransformConditionArm[];
+      otherwise: TransformValue;
+    }
+  | {
+      kind: 'combination';
+      operator: TransformCombinationOperator;
+      operands: TransformValue[];
+    };
+
+/** One named intermediate step: a `const` in the transform body. */
+export type TransformFactor = {
+  name: string;
+  /** The authored initializer, whitespace-normalized. Always renderable. */
+  expression: string;
+  rule: TransformRule;
+  /** Union of everything the initializer reads. */
+  refs: TransformRefs;
+  /** True when the rule is verbatim text rather than a described structure. */
+  opaque?: true;
+};
+
+/** The transform's returned value. */
+export type TransformResult = {
+  expression: string;
+  rule: TransformRule;
+  refs: TransformRefs;
+  opaque?: true;
+};
+
+/**
+ * The extracted structure of one column's transform.
+ *
+ * `inputColumns` is the join key for the UI: the columns this transform reads,
+ * in first-appearance order, so factor lines can be sat beside the trace's own
+ * input hops without the renderer re-deriving them.
+ */
+export type TransformFactorStructure = {
+  /** Dataset column this transform produces. */
+  column: string;
+  /** Dataset the column belongs to, when the extractor could name it. */
+  dataset?: string;
+  /** The transform's row parameter name, as authored. */
+  rowParam: string;
+  factors: TransformFactor[];
+  result: TransformResult;
+  inputColumns: string[];
+  /** Functions called by the transform, by written name. */
+  helpers: string[];
+};
+
+/**
+ * A structure, addressed the way a trace addresses cells.
+ *
+ * The structure alone says what a transform IS; it does not say which cell it
+ * explains. A consumer holding a chain of hops needs both, so the address
+ * travels with it — table and column, verbatim as the trace reported them, so
+ * the join is a string match and never a guess about namespacing.
+ */
+export type TransformFactorEntry = {
+  table: string;
+  column: string;
+  structure: TransformFactorStructure;
+};
+
+/**
+ * Why no structure was produced.
+ *
+ * Each value names a shape the extractor refuses to describe rather than
+ * describe badly. `unsupported_statement` covers loops, branches, mutation and
+ * try/catch in one: the supported body is a run of `const` declarations
+ * followed by a `return`, and anything else in it means the description would
+ * omit real behavior.
+ *
+ * The last two are about the extractor rather than the code.
+ * `expression_too_deep` is a nesting budget: a described value that nests past
+ * it is refused instead of risking the stack. `extraction_failed` is the net
+ * under everything — any error the extractor did not anticipate arrives here
+ * with its message, so a surface reports "cannot read this" instead of failing
+ * the request. Either one appearing on an authored play is a bug worth chasing.
+ */
+export type TransformUnstructurableReason =
+  | 'column_not_found'
+  | 'ambiguous_column'
+  | 'not_a_function'
+  /**
+   * The column is filled by a `steps()` program — a provider cascade — and not
+   * by code. There are no factors to describe because there is no arithmetic:
+   * the trace explains such a cell with its hops, which is a better answer than
+   * anything this module could say about it.
+   */
+  | 'step_program_column'
+  | 'async_transform'
+  | 'destructured_row_param'
+  | 'row_context_used'
+  | 'row_index_used'
+  /**
+   * The transform read `previousCell` — the value this cell held before the
+   * rerun — which the object column form hands its `run` alongside the row.
+   *
+   * Not a column, and named separately from the row context and the row index
+   * for the same reason those two are named separately from each other: a
+   * refusal that misnames what it refused sends the next reader looking in the
+   * wrong place.
+   */
+  | 'previous_cell_used'
+  /**
+   * An object column's `run` was handed its input WHOLE — `(input) =>
+   * input.row.domain` rather than `({ row }) => row.domain`.
+   *
+   * The contract passes `run` one argument, `{ row, ctx, index, previousCell }`,
+   * so the row is a property of the parameter rather than the parameter. This
+   * module names a row PARAMETER and reads properties off it; a row one level
+   * further in is a shape it cannot describe, and describing the envelope
+   * instead would report `row` and `ctx` as if they were dataset columns.
+   */
+  | 'run_input_not_destructured'
+  | 'nested_function'
+  | 'unsupported_statement'
+  | 'unsupported_declaration'
+  | 'missing_return'
+  | 'dynamic_row_access'
+  | 'expression_too_deep'
+  | 'extraction_failed';
+
+/** Extraction outcome. A failure is a fact with a reason, never an exception. */
+export type TransformFactorExtraction =
+  | { structure: TransformFactorStructure; reason: null }
+  | { structure: null; reason: TransformUnstructurableReason; detail?: string };
+
+/** Empty ref set. Callers merge into a copy; this value is never mutated. */
+export function emptyTransformRefs(): TransformRefs {
+  return { inputs: [], factors: [], calls: [], externals: [] };
+}
+
+/** Merge ref sets, preserving first-appearance order and deduping. */
+export function mergeTransformRefs(
+  ...sets: readonly TransformRefs[]
+): TransformRefs {
+  const merged = emptyTransformRefs();
+  const seenInputs = new Set<string>();
+  const seenFactors = new Set<string>();
+  const seenCalls = new Set<string>();
+  const seenExternals = new Set<string>();
+  for (const set of sets) {
+    for (const input of set.inputs) {
+      const key = transformInputKey(input);
+      if (seenInputs.has(key)) continue;
+      seenInputs.add(key);
+      merged.inputs.push(input);
+    }
+    for (const factor of set.factors) {
+      if (seenFactors.has(factor)) continue;
+      seenFactors.add(factor);
+      merged.factors.push(factor);
+    }
+    for (const call of set.calls) {
+      if (seenCalls.has(call)) continue;
+      seenCalls.add(call);
+      merged.calls.push(call);
+    }
+    for (const external of set.externals) {
+      if (seenExternals.has(external)) continue;
+      seenExternals.add(external);
+      merged.externals.push(external);
+    }
+  }
+  return merged;
+}
+
+/** Stable identity for an input ref, column plus path. */
+export function transformInputKey(input: TransformInputRef): string {
+  return [input.column, ...(input.path ?? [])].join('.');
+}

package/dist/bundling-sources/shared_libs/plays/webhook-payload.ts

@@ -0,0 +1,113 @@
+const WEBHOOK_KEY_PREFIX = '__deepline_webhook_key_v1_';
+/**
+ * Play inputs are objects or arrays. Rather than acknowledge a scalar JSON or
+ * non-JSON delivery and silently replace it with `{}`, retain the exact body
+ * in a namespaced input envelope. This name is only introduced for payloads
+ * which cannot themselves be a Play input, so it cannot collide with a key in
+ * a caller-provided object.
+ */
+export const WEBHOOK_RAW_INPUT_KEY = '__deepline_webhook_raw_v1';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+export type PlayWebhookPayload = Record<string, unknown> | unknown[];
+
+export type RetainedWebhookPayload = {
+  rawBody: string;
+  contentType: string | null;
+  encoding: 'utf-8';
+  /** Present when the body was valid JSON but not an object or array. */
+  jsonValue?: string | number | boolean | null;
+};
+
+/**
+ * Convert an arbitrary HTTP body into a valid Play input without losing it.
+ * Object and array JSON remain byte-for-byte equivalent at the JSON value
+ * level; scalar JSON and non-JSON use a deliberately explicit envelope.
+ */
+export function parsePlayWebhookPayload(input: {
+  rawBody: string;
+  contentType?: string | null;
+}): PlayWebhookPayload {
+  const contentType = input.contentType?.trim() || null;
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && typeof parsed === 'object') {
+      return parsed as Record<string, unknown>;
+    }
+    if (
+      parsed === null ||
+      typeof parsed === 'string' ||
+      typeof parsed === 'number' ||
+      typeof parsed === 'boolean'
+    ) {
+      return {
+        [WEBHOOK_RAW_INPUT_KEY]: {
+          rawBody: input.rawBody,
+          contentType,
+          encoding: 'utf-8',
+          jsonValue: parsed,
+        } satisfies RetainedWebhookPayload,
+      };
+    }
+  } catch {
+    // The raw body below is the durable, user-visible value for non-JSON.
+  }
+  return {
+    [WEBHOOK_RAW_INPUT_KEY]: {
+      rawBody: input.rawBody,
+      contentType,
+      encoding: 'utf-8',
+    } satisfies RetainedWebhookPayload,
+  };
+}
+
+function encodeKey(key: string): string {
+  return (
+    WEBHOOK_KEY_PREFIX +
+    Array.from(encoder.encode(key), (byte) =>
+      byte.toString(16).padStart(2, '0'),
+    ).join('')
+  );
+}
+
+function decodeKey(key: string): string | null {
+  if (!key.startsWith(WEBHOOK_KEY_PREFIX)) return null;
+  const encoded = key.slice(WEBHOOK_KEY_PREFIX.length);
+  if (!encoded || encoded.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(encoded)) {
+    return null;
+  }
+  try {
+    const bytes = new Uint8Array(
+      encoded.match(/.{2}/g)!.map((pair) => Number.parseInt(pair, 16)),
+    );
+    const decoded = decoder.decode(bytes);
+    return encodeKey(decoded) === key ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+
+function mapKeys(value: unknown, mapKey: (key: string) => string): unknown {
+  if (Array.isArray(value)) return value.map((item) => mapKeys(item, mapKey));
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).map(
+      ([key, nestedValue]) => [mapKey(key), mapKeys(nestedValue, mapKey)],
+    ),
+  );
+}
+
+/**
+ * Convex only accepts ASCII object keys. Webhook bodies are external JSON, so
+ * encode every key losslessly before crossing its client or persistence boundary.
+ */
+export function encodeWebhookPayloadForConvex(value: unknown): unknown {
+  return mapKeys(value, encodeKey);
+}
+
+/** Restores webhook payload keys before they are made available to a Play. */
+export function decodeWebhookPayloadFromConvex(value: unknown): unknown {
+  return mapKeys(value, (key) => decodeKey(key) ?? key);
+}