graphddb 0.6.0 → 0.7.0

package/dist/transform/index.js

@@ -0,0 +1,719 @@
+// src/transform/prepared-transform.ts
+import ts from "typescript";
+var HOIST_SLOT_PREFIX = "__gddbPrepared";
+var SLOT_NAME_RE = /^__gddbPrepared\d+$/;
+function collectModuleBindings(sf) {
+  const out = /* @__PURE__ */ new Map();
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+      const clause = stmt.importClause;
+      if (clause.name) {
+        out.set(clause.name.text, {
+          kind: "import",
+          importedName: void 0,
+          namespace: false
+        });
+      }
+      const bindings = clause.namedBindings;
+      if (bindings) {
+        if (ts.isNamespaceImport(bindings)) {
+          out.set(bindings.name.text, {
+            kind: "import",
+            importedName: void 0,
+            namespace: true
+          });
+        } else {
+          for (const spec of bindings.elements) {
+            out.set(spec.name.text, {
+              kind: "import",
+              importedName: (spec.propertyName ?? spec.name).text,
+              namespace: false
+            });
+          }
+        }
+      }
+    } else if (ts.isVariableStatement(stmt)) {
+      const isConst = (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0;
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) {
+          out.set(
+            decl.name.text,
+            isConst ? { kind: "const", initializer: decl.initializer } : { kind: "mutable" }
+          );
+        } else {
+          for (const name of bindingNames(decl.name)) {
+            out.set(
+              name,
+              isConst ? { kind: "const", initializer: void 0 } : { kind: "mutable" }
+            );
+          }
+        }
+      }
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      out.set(stmt.name.text, { kind: "class", node: stmt });
+    } else if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      out.set(stmt.name.text, { kind: "function", node: stmt });
+    } else if (ts.isEnumDeclaration(stmt)) {
+      out.set(stmt.name.text, { kind: "enum" });
+    }
+  }
+  return out;
+}
+function bindingNames(name) {
+  if (ts.isIdentifier(name)) return [name.text];
+  const out = [];
+  for (const el of name.elements) {
+    if (ts.isBindingElement(el)) out.push(...bindingNames(el.name));
+  }
+  return out;
+}
+function isDDBModelRef(expr, bindings, seen = /* @__PURE__ */ new Set()) {
+  const e = unwrapExpr(expr);
+  if (ts.isIdentifier(e)) {
+    const name = e.text;
+    if (seen.has(name)) return false;
+    seen.add(name);
+    const b = bindings.get(name);
+    if (!b) return false;
+    if (b.kind === "import") return b.importedName === "DDBModel";
+    if (b.kind === "const" && b.initializer)
+      return isDDBModelRef(b.initializer, bindings, seen);
+    if (b.kind === "class") {
+      const heritage = b.node.heritageClauses?.find(
+        (h) => h.token === ts.SyntaxKind.ExtendsKeyword
+      );
+      const base = heritage?.types[0]?.expression;
+      return base !== void 0 && isDDBModelRef(base, bindings, seen);
+    }
+    return false;
+  }
+  if (ts.isPropertyAccessExpression(e) && e.name.text === "DDBModel") {
+    const root = unwrapExpr(e.expression);
+    if (ts.isIdentifier(root)) {
+      const b = bindings.get(root.text);
+      return b?.kind === "import" && b.namespace;
+    }
+  }
+  return false;
+}
+function unwrapExpr(e) {
+  let cur = e;
+  for (; ; ) {
+    if (ts.isParenthesizedExpression(cur)) cur = cur.expression;
+    else if (ts.isAsExpression(cur)) cur = cur.expression;
+    else if (ts.isSatisfiesExpression(cur)) cur = cur.expression;
+    else if (ts.isNonNullExpression(cur)) cur = cur.expression;
+    else if (ts.isTypeAssertionExpression(cur)) cur = cur.expression;
+    else return cur;
+  }
+}
+function isFunctionLikeScope(n) {
+  return ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n) || ts.isMethodDeclaration(n) || ts.isConstructorDeclaration(n) || ts.isGetAccessorDeclaration(n) || ts.isSetAccessorDeclaration(n);
+}
+function scopeDeclares(scope, name) {
+  if (isFunctionLikeScope(scope)) {
+    const fn = scope;
+    for (const p of fn.parameters) {
+      if (bindingNames(p.name).includes(name)) return true;
+    }
+    if (fn.body && ts.isBlock(fn.body) && blockDeclares(fn.body, name)) return true;
+    if ((ts.isFunctionExpression(scope) || ts.isFunctionDeclaration(scope)) && scope.name?.text === name) {
+      return true;
+    }
+    return false;
+  }
+  if (ts.isBlock(scope)) return blockDeclares(scope, name);
+  if (ts.isCatchClause(scope)) {
+    return scope.variableDeclaration !== void 0 && bindingNames(scope.variableDeclaration.name).includes(name);
+  }
+  if (ts.isForStatement(scope) || ts.isForOfStatement(scope) || ts.isForInStatement(scope)) {
+    const init = scope.initializer;
+    if (init && ts.isVariableDeclarationList(init)) {
+      for (const d of init.declarations) {
+        if (bindingNames(d.name).includes(name)) return true;
+      }
+    }
+    return false;
+  }
+  return false;
+}
+function blockDeclares(block, name) {
+  for (const stmt of block.statements) {
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (bindingNames(d.name).includes(name)) return true;
+      }
+    } else if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) && stmt.name?.text === name) {
+      return true;
+    }
+  }
+  return false;
+}
+function resolveIdentifier(id, bodyFn, bindings) {
+  const name = id.text;
+  let node = id;
+  while (node.parent) {
+    const parent = node.parent;
+    if (isFunctionLikeScope(parent) || ts.isBlock(parent) || ts.isCatchClause(parent) || ts.isForStatement(parent) || ts.isForOfStatement(parent) || ts.isForInStatement(parent)) {
+      if (scopeDeclares(parent, name)) {
+        if (bodyFn && isInside(parent, bodyFn)) return { at: "body-local" };
+        if (isFunctionLikeScope(parent) || hasFunctionAncestorBelowModule(parent)) {
+          return { at: "enclosing-function" };
+        }
+        return { at: "module", binding: { kind: "const", initializer: void 0 } };
+      }
+    }
+    node = parent;
+  }
+  const b = bindings.get(name);
+  if (b) return { at: "module", binding: b };
+  return { at: "unresolved" };
+}
+function isInside(node, ancestor) {
+  let cur = node;
+  while (cur) {
+    if (cur === ancestor) return true;
+    cur = cur.parent;
+  }
+  return false;
+}
+function hasFunctionAncestorBelowModule(node) {
+  let cur = node.parent;
+  while (cur && !ts.isSourceFile(cur)) {
+    if (isFunctionLikeScope(cur)) return true;
+    cur = cur.parent;
+  }
+  return false;
+}
+function report(ctx, node, code, message, category = "error") {
+  const { line, character } = ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf));
+  ctx.diagnostics.push({
+    code,
+    category,
+    message,
+    file: ctx.fileName,
+    line: line + 1,
+    column: character + 1
+  });
+}
+function lintPreparedBody(ctx, fn) {
+  const before = countErrors(ctx.diagnostics);
+  if (fn.parameters.length > 1) {
+    report(
+      ctx,
+      fn.parameters[1],
+      "impure-expression",
+      "A prepared body takes exactly one parameter (the `$` placeholder)."
+    );
+    return countErrors(ctx.diagnostics) - before;
+  }
+  const paramNames = /* @__PURE__ */ new Set();
+  const destructured = /* @__PURE__ */ new Set();
+  const param = fn.parameters[0];
+  if (param) {
+    if (ts.isIdentifier(param.name)) {
+      paramNames.add(param.name.text);
+    } else if (ts.isObjectBindingPattern(param.name)) {
+      for (const el of param.name.elements) {
+        if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name) || el.initializer !== void 0 || el.dotDotDotToken !== void 0 || el.propertyName !== void 0 && !ts.isIdentifier(el.propertyName)) {
+          report(
+            ctx,
+            el,
+            "impure-expression",
+            "Only a plain, single-level destructuring of the `$` placeholder is supported (no nesting, defaults, or rest)."
+          );
+        } else {
+          destructured.add(el.name.text);
+        }
+      }
+    } else {
+      report(
+        ctx,
+        param,
+        "impure-expression",
+        "The `$` parameter must be a plain identifier or a single-level object destructuring."
+      );
+    }
+  }
+  const env = { bodyFn: fn, paramNames, destructuredParamNames: destructured };
+  const body = fn.body;
+  if (body !== void 0) {
+    if (ts.isBlock(body)) lintBodyBlock(ctx, body, env);
+    else checkExpr(ctx, body, env);
+  }
+  return countErrors(ctx.diagnostics) - before;
+}
+function countErrors(diags) {
+  return diags.reduce((n, d) => n + (d.category === "error" ? 1 : 0), 0);
+}
+function lintBodyBlock(ctx, block, env) {
+  for (const stmt of block.statements) {
+    if (ts.isReturnStatement(stmt)) {
+      if (stmt.expression) checkExpr(ctx, stmt.expression, env);
+      continue;
+    }
+    if (ts.isVariableStatement(stmt) && (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0) {
+      for (const d of stmt.declarationList.declarations) {
+        if (d.initializer) checkExpr(ctx, d.initializer, env);
+      }
+      continue;
+    }
+    report(
+      ctx,
+      stmt,
+      "impure-expression",
+      "A prepared body block may contain only `const` declarations and `return` statements \u2014 any other statement is per-call control flow, which breaks compile-time hoisting."
+    );
+  }
+}
+function checkExpr(ctx, node, env) {
+  const e = unwrapExpr(node);
+  if (ts.isStringLiteral(e) || ts.isNumericLiteral(e) || ts.isBigIntLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e) || e.kind === ts.SyntaxKind.TrueKeyword || e.kind === ts.SyntaxKind.FalseKeyword || e.kind === ts.SyntaxKind.NullKeyword) {
+    return;
+  }
+  if (ts.isPrefixUnaryExpression(e) && (e.operator === ts.SyntaxKind.MinusToken || e.operator === ts.SyntaxKind.PlusToken) && ts.isNumericLiteral(e.operand)) {
+    return;
+  }
+  if (ts.isObjectLiteralExpression(e)) {
+    for (const prop of e.properties) {
+      if (ts.isPropertyAssignment(prop)) {
+        if (ts.isComputedPropertyName(prop.name)) {
+          report(
+            ctx,
+            prop.name,
+            "impure-expression",
+            "A computed property name is per-call control flow \u2014 a prepared template needs statically known keys."
+          );
+        }
+        checkExpr(ctx, prop.initializer, env);
+      } else if (ts.isShorthandPropertyAssignment(prop)) {
+        checkIdentifierRef(ctx, prop.name, env);
+      } else if (ts.isSpreadAssignment(prop)) {
+        checkExpr(ctx, prop.expression, env);
+      } else {
+        report(
+          ctx,
+          prop,
+          "impure-expression",
+          "Only plain property assignments are supported in a prepared template."
+        );
+      }
+    }
+    return;
+  }
+  if (ts.isArrayLiteralExpression(e)) {
+    for (const el of e.elements) {
+      if (ts.isSpreadElement(el)) checkExpr(ctx, el.expression, env);
+      else checkExpr(ctx, el, env);
+    }
+    return;
+  }
+  if (ts.isArrowFunction(e) || ts.isFunctionExpression(e)) {
+    if (e.parameters.length !== 0) {
+      report(
+        ctx,
+        e,
+        "impure-expression",
+        "A function inside a prepared template is only valid as a zero-parameter model ref (`() => Model`)."
+      );
+      return;
+    }
+    const refExpr = thunkResultExpression(e);
+    if (refExpr === void 0) {
+      report(
+        ctx,
+        e,
+        "impure-expression",
+        "A model-ref thunk must be a single expression (or single `return`) referencing a module-static model."
+      );
+      return;
+    }
+    checkStaticRefChain(ctx, refExpr, env);
+    return;
+  }
+  if (ts.isIdentifier(e)) {
+    checkIdentifierRef(ctx, e, env);
+    return;
+  }
+  if (ts.isPropertyAccessExpression(e)) {
+    checkPropertyChain(ctx, e, env);
+    return;
+  }
+  if (ts.isCallExpression(e) || ts.isNewExpression(e)) {
+    report(
+      ctx,
+      e,
+      "call-in-body",
+      "A call inside a prepared body is an indirect runtime-capture channel (the lint cannot see through it, and even a global like `Date.now()` is a fresh per-call value). Inline the result as a static literal, bind it via `$`, or extract a module-scope `const` template."
+    );
+    return;
+  }
+  if (e.kind === ts.SyntaxKind.ThisKeyword) {
+    report(
+      ctx,
+      e,
+      "runtime-capture",
+      "`this` inside a prepared body captures the per-call receiver. Bind the value via `$` instead."
+    );
+    return;
+  }
+  if (ts.isTemplateExpression(e)) {
+    report(
+      ctx,
+      e,
+      "impure-expression",
+      "A template literal with substitutions embeds a runtime value into the template. Bind the value via `$` (the runtime binds whole fields, never string fragments)."
+    );
+    return;
+  }
+  report(
+    ctx,
+    e,
+    "impure-expression",
+    `Unsupported expression (${ts.SyntaxKind[e.kind]}) in a prepared body \u2014 only object/array literals, static literals, \`$.<name>\` refs, module-static references, and \`() => Model\` thunks are declarative.`
+  );
+}
+function thunkResultExpression(fn) {
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) return fn.body;
+  const body = fn.body;
+  if (body && ts.isBlock(body) && body.statements.length === 1) {
+    const only = body.statements[0];
+    if (ts.isReturnStatement(only) && only.expression) return only.expression;
+  }
+  return void 0;
+}
+function checkStaticRefChain(ctx, expr, env) {
+  const e = unwrapExpr(expr);
+  if (ts.isIdentifier(e)) {
+    checkIdentifierRef(
+      ctx,
+      e,
+      env,
+      /* refOnly */
+      true
+    );
+    return;
+  }
+  if (ts.isPropertyAccessExpression(e)) {
+    checkPropertyChain(
+      ctx,
+      e,
+      env,
+      /* refOnly */
+      true
+    );
+    return;
+  }
+  report(
+    ctx,
+    e,
+    "impure-expression",
+    "A model ref must be a plain reference to a module-static model (`() => Model` / `() => ns.Model`)."
+  );
+}
+function checkIdentifierRef(ctx, id, env, refOnly = false) {
+  const name = id.text;
+  if (name === "undefined") {
+    report(
+      ctx,
+      id,
+      "non-static-reference",
+      "`undefined` is not a bindable template value \u2014 omit the field or bind it via `$`."
+    );
+    return;
+  }
+  if (env.paramNames.has(name)) {
+    report(
+      ctx,
+      id,
+      "impure-expression",
+      "The `$` placeholder itself is not a value \u2014 bind a specific param via `$.<name>`."
+    );
+    return;
+  }
+  if (env.destructuredParamNames.has(name)) return;
+  const res = resolveIdentifier(id, env.bodyFn, ctx.bindings);
+  switch (res.at) {
+    case "body-local":
+      return;
+    case "enclosing-function":
+      report(
+        ctx,
+        id,
+        "runtime-capture",
+        `'${name}' is declared in an enclosing function \u2014 a per-call runtime value captured into the prepared body. Bind it via \`$\` (a per-call param) or move it to a module-scope \`const\`.`
+      );
+      return;
+    case "unresolved":
+      report(
+        ctx,
+        id,
+        "non-static-reference",
+        `'${name}' does not resolve to \`$\` or a module-static binding in this file. Globals are per-call runtime state; a prepared body may reference only \`$\` and module-static values.`
+      );
+      return;
+    case "module":
+      checkModuleBindingUse(ctx, id, name, res.binding, refOnly);
+      return;
+  }
+}
+function checkModuleBindingUse(ctx, at, name, binding, refOnly) {
+  switch (binding.kind) {
+    case "mutable":
+      report(
+        ctx,
+        at,
+        "mutable-module-state",
+        `'${name}' is module-scope \`let\`/\`var\` \u2014 mutable module state. A hoisted body would freeze its value while an unhoisted one would not; results must not depend on placement. Make it a \`const\` or bind it via \`$\`.`
+      );
+      return;
+    case "import":
+    case "class":
+    case "enum":
+      return;
+    // module-static by construction (see the documented limits).
+    case "function":
+      if (binding.node.parameters.length === 0) {
+        const result = binding.node.body ? functionSingleReturn(binding.node) : void 0;
+        if (result !== void 0) {
+          checkStaticRefChain(
+            ctx,
+            result,
+            // Module context: no `$`, no body scope.
+            { bodyFn: void 0, paramNames: /* @__PURE__ */ new Set(), destructuredParamNames: /* @__PURE__ */ new Set() }
+          );
+          return;
+        }
+      }
+      if (!refOnly) return;
+      report(
+        ctx,
+        at,
+        "impure-expression",
+        `'${name}' is not a zero-parameter thunk returning a module-static reference \u2014 a model ref must be statically resolvable.`
+      );
+      return;
+    case "const": {
+      if (binding.initializer === void 0) return;
+      if (ctx.visitedConsts.has(name)) return;
+      ctx.visitedConsts.add(name);
+      checkExpr(ctx, binding.initializer, {
+        bodyFn: void 0,
+        paramNames: /* @__PURE__ */ new Set(),
+        destructuredParamNames: /* @__PURE__ */ new Set()
+      });
+      return;
+    }
+  }
+}
+function functionSingleReturn(fn) {
+  const body = fn.body;
+  if (body && body.statements.length === 1) {
+    const only = body.statements[0];
+    if (ts.isReturnStatement(only) && only.expression) return only.expression;
+  }
+  return void 0;
+}
+function checkPropertyChain(ctx, e, env, refOnly = false) {
+  let levels = 0;
+  let cur = e;
+  while (ts.isPropertyAccessExpression(cur)) {
+    levels += 1;
+    cur = unwrapExpr(cur.expression);
+  }
+  if (ts.isIdentifier(cur)) {
+    const rootName = cur.text;
+    if (env.paramNames.has(rootName)) {
+      if (levels > 1) {
+        report(
+          ctx,
+          e,
+          "param-deep-access",
+          "Only a direct `$.<name>` read is supported \u2014 nested access on a param is a per-call transform the runtime rejects too."
+        );
+      }
+      return;
+    }
+    if (env.destructuredParamNames.has(rootName)) {
+      report(
+        ctx,
+        e,
+        "param-deep-access",
+        "A destructured `$` param is already the bound value \u2014 nested access on it is a per-call transform."
+      );
+      return;
+    }
+    checkIdentifierRef(ctx, cur, env, refOnly);
+    return;
+  }
+  if (cur.kind === ts.SyntaxKind.ThisKeyword) {
+    report(
+      ctx,
+      e,
+      "runtime-capture",
+      "`this` inside a prepared body captures the per-call receiver. Bind the value via `$` instead."
+    );
+    return;
+  }
+  report(
+    ctx,
+    e,
+    "impure-expression",
+    "A property chain in a prepared body must be rooted at `$` or a module-static reference."
+  );
+}
+function isPerCallSite(call) {
+  let cur = call.parent;
+  while (cur && !ts.isSourceFile(cur)) {
+    if (isFunctionLikeScope(cur)) return true;
+    if (ts.isPropertyDeclaration(cur) && !cur.modifiers?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword)) {
+      return true;
+    }
+    cur = cur.parent;
+  }
+  return false;
+}
+function isAlreadyHoisted(call) {
+  const parent = call.parent;
+  return parent !== void 0 && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionEqualsToken && ts.isIdentifier(parent.left) && SLOT_NAME_RE.test(parent.left.text) && parent.right === call;
+}
+function transformPreparedSource(fileName, sourceText, options = {}) {
+  const mode = options.mode ?? "transform";
+  const scriptKind = fileName.endsWith(".tsx") ? ts.ScriptKind.TSX : fileName.endsWith(".jsx") ? ts.ScriptKind.JSX : ts.ScriptKind.TS;
+  const sf = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */
+    true,
+    scriptKind
+  );
+  const bindings = collectModuleBindings(sf);
+  const ctx = {
+    sf,
+    fileName,
+    bindings,
+    diagnostics: [],
+    visitedConsts: /* @__PURE__ */ new Set()
+  };
+  const calls = [];
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "prepare" && isDDBModelRef(node.expression.expression, bindings)) {
+      let bodyFn;
+      let indirect = false;
+      const arg = node.arguments.length === 1 ? unwrapExpr(node.arguments[0]) : void 0;
+      if (arg && (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg))) {
+        bodyFn = arg;
+      } else if (arg && ts.isIdentifier(arg)) {
+        const res = resolveIdentifier(arg, void 0, bindings);
+        if (res.at === "module") {
+          const b = res.binding;
+          if (b.kind === "const" && b.initializer) {
+            const init = unwrapExpr(b.initializer);
+            if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+              bodyFn = init;
+              indirect = true;
+            }
+          } else if (b.kind === "function") {
+            bodyFn = b.node;
+            indirect = true;
+          }
+        }
+      }
+      calls.push({ call: node, bodyFn, bodyIsIndirect: indirect });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  const edits = [];
+  const slotNames = [];
+  let hoistedCount = 0;
+  let moduleScopeCount = 0;
+  let alreadyHoistedCount = 0;
+  let slotIndex = 0;
+  for (const m of sourceText.matchAll(/__gddbPrepared(\d+)\b/g)) {
+    slotIndex = Math.max(slotIndex, Number(m[1]));
+  }
+  for (const { call, bodyFn } of calls) {
+    if (bodyFn === void 0) {
+      report(
+        ctx,
+        call,
+        "unverifiable-body",
+        "The `prepare` argument is not a statically visible function (an inline arrow/function or a module-scope `const` body). The no-runtime-capture lint cannot verify it \u2014 pass the body inline or as a module-scope const."
+      );
+      continue;
+    }
+    const bodyErrors = lintPreparedBody(ctx, bodyFn);
+    if (bodyErrors > 0) continue;
+    if (isAlreadyHoisted(call)) {
+      alreadyHoistedCount += 1;
+      continue;
+    }
+    if (!isPerCallSite(call)) {
+      moduleScopeCount += 1;
+      continue;
+    }
+    if (mode === "lint") {
+      report(
+        ctx,
+        call,
+        "hoistable",
+        "Inline `DDBModel.prepare` call site \u2014 `graphddb transform prepared --write` normalizes it to a module-scope prepared slot (zero per-op overhead). Untransformed it falls back to the runtime structural-memoization path.",
+        "note"
+      );
+      continue;
+    }
+    slotIndex += 1;
+    const slot = `${HOIST_SLOT_PREFIX}${slotIndex}`;
+    slotNames.push(slot);
+    edits.push({ pos: call.getStart(sf), insert: `(${slot} ??= ` });
+    edits.push({ pos: call.getEnd(), insert: `)` });
+    hoistedCount += 1;
+  }
+  const errorCount = countErrors(ctx.diagnostics);
+  if (errorCount > 0) {
+    return {
+      fileName,
+      text: sourceText,
+      changed: false,
+      hoistedCount: 0,
+      moduleScopeCount,
+      alreadyHoistedCount,
+      diagnostics: ctx.diagnostics,
+      errorCount
+    };
+  }
+  let text = sourceText;
+  if (hoistedCount > 0) {
+    let declPos = 0;
+    for (const stmt of sf.statements) {
+      if (ts.isImportDeclaration(stmt)) declPos = stmt.getEnd();
+    }
+    const nl = sourceText.includes("\r\n") ? "\r\n" : "\n";
+    const header = `${nl}${nl}// graphddb transform prepared (#206): module-scope lazy slots \u2014 each${nl}// prepared statement compiles once per module and every later call is a${nl}// plain \`.execute\` (zero per-op planning / hashing).` + slotNames.map((s) => `${nl}let ${s};`).join("");
+    edits.push({ pos: declPos, insert: declPos === 0 ? header.trimStart() + nl : header });
+    edits.sort((a, b) => b.pos - a.pos);
+    for (const e of edits) {
+      text = text.slice(0, e.pos) + e.insert + text.slice(e.pos);
+    }
+  }
+  return {
+    fileName,
+    text,
+    changed: text !== sourceText,
+    hoistedCount,
+    moduleScopeCount,
+    alreadyHoistedCount,
+    diagnostics: ctx.diagnostics,
+    errorCount: 0
+  };
+}
+function lintPreparedSource(fileName, sourceText) {
+  return transformPreparedSource(fileName, sourceText, { mode: "lint" }).diagnostics;
+}
+export {
+  HOIST_SLOT_PREFIX,
+  lintPreparedSource,
+  transformPreparedSource
+};