@emeryld/rrroutes-contract 2.7.5 → 2.7.7

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   createSchemaIntrospector: () => createSchemaIntrospector,
   defineSocketEvents: () => defineSocketEvents,
   exportFinalizedLeaves: () => exportFinalizedLeaves,
+  extractLeafSourceByAst: () => extractLeafSourceByAst,
   finalize: () => finalize,
   flattenLeafSchemas: () => flattenLeafSchemas,
   flattenSerializableSchema: () => flattenSerializableSchema,
@@ -107,9 +108,9 @@ function collectNestedFieldSuggestions(shape, prefix = []) {
   }
   return suggestions;
 }
-function compilePath(path3, params) {
-  if (!params) return path3;
-  const withParams = path3.replace(/:([A-Za-z0-9_]+)/g, (_, k) => {
+function compilePath(path4, params) {
+  if (!params) return path4;
+  const withParams = path4.replace(/:([A-Za-z0-9_]+)/g, (_, k) => {
     const v = params[k];
     if (v === void 0 || v === null) throw new Error(`Missing param :${k}`);
     return String(v);
@@ -184,8 +185,8 @@ function buildLowProfileLeaf(leaf) {
     }
   };
 }
-var keyOf = (method, path3, encodeSafe) => {
-  const key = `${method.toUpperCase()} ${path3}`;
+var keyOf = (method, path4, encodeSafe) => {
+  const key = `${method.toUpperCase()} ${path4}`;
   return encodeSafe ? encodeURIComponent(key) : key;
 };
 
@@ -361,8 +362,8 @@ function joinPaths(parent, child) {
   if (!trimmedChild) return trimmedParent;
   return `${trimmedParent}/${trimmedChild}`;
 }
-function assertDynamicLayerUniqueness(path3, dynamicLayerMap) {
-  const segments = path3.split("/").filter(Boolean);
+function assertDynamicLayerUniqueness(path4, dynamicLayerMap) {
+  const segments = path4.split("/").filter(Boolean);
   if (segments.length === 0) return;
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i];
@@ -682,45 +683,45 @@ function normalizeType(schema) {
       return "unknown";
   }
 }
-function isNonEmptyPath(path3) {
-  return typeof path3 === "string" && path3.length > 0;
+function isNonEmptyPath(path4) {
+  return typeof path4 === "string" && path4.length > 0;
 }
-function setNode(out, path3, schema, inherited) {
-  if (!isNonEmptyPath(path3)) return;
-  out[path3] = {
+function setNode(out, path4, schema, inherited) {
+  if (!isNonEmptyPath(path4)) return;
+  out[path4] = {
     type: normalizeType(schema),
     nullable: inherited.nullable || Boolean(schema.nullable),
     optional: inherited.optional || Boolean(schema.optional)
   };
 }
-function flattenInto(out, schema, path3, inherited) {
-  if (!schema || !isNonEmptyPath(path3)) return;
+function flattenInto(out, schema, path4, inherited) {
+  if (!schema || !isNonEmptyPath(path4)) return;
   const nextInherited = {
     optional: inherited.optional || Boolean(schema.optional),
     nullable: inherited.nullable || Boolean(schema.nullable)
   };
   if (schema.kind === "union" && Array.isArray(schema.union) && schema.union.length > 0) {
     schema.union.forEach((option, index) => {
-      const optionPath = `${path3}-${index + 1}`;
+      const optionPath = `${path4}-${index + 1}`;
       flattenInto(out, option, optionPath, inherited);
     });
     return;
   }
-  setNode(out, path3, schema, inherited);
+  setNode(out, path4, schema, inherited);
   if (schema.kind === "object" && schema.properties) {
     for (const [key, child] of Object.entries(schema.properties)) {
-      const childPath = `${path3}.${key}`;
+      const childPath = `${path4}.${key}`;
       flattenInto(out, child, childPath, nextInherited);
     }
     return;
   }
   if (schema.kind === "array" && schema.element) {
-    flattenInto(out, schema.element, `${path3}[]`, nextInherited);
+    flattenInto(out, schema.element, `${path4}[]`, nextInherited);
   }
 }
-function flattenSerializableSchema(schema, path3) {
+function flattenSerializableSchema(schema, path4) {
   const out = {};
-  flattenInto(out, schema, path3, { optional: false, nullable: false });
+  flattenInto(out, schema, path4, { optional: false, nullable: false });
   return out;
 }
 function isSerializedLeaf(value) {
@@ -741,7 +742,7 @@ function flattenLeafSchemas(leaf) {
 
 // src/export/exportFinalizedLeaves.ts
 var import_promises = __toESM(require("fs/promises"), 1);
-var import_node_path = __toESM(require("path"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
 var import_node_child_process = require("child_process");
 
 // src/export/defaultViewerTemplate.ts
@@ -796,6 +797,13 @@ var DEFAULT_VIEWER_TEMPLATE = `<!doctype html>
       } else {
         statusEl.textContent =           'Loaded baked payload with ' + payload.leaves.length + ' routes.'
 
+        const toHref = (source) => {
+          if (!source || !source.file) return null
+          const normalizedPath = String(source.file).replace(/\\\\/g, '/')
+          const prefix = normalizedPath.startsWith('/') ? 'file://' : 'file:///'
+          return prefix + encodeURI(normalizedPath)
+        }
+
         payload.leaves.forEach((leaf) => {
           const details = document.createElement('details')
           const summary = document.createElement('summary')
@@ -804,7 +812,62 @@ var DEFAULT_VIEWER_TEMPLATE = `<!doctype html>
           const pre = document.createElement('pre')
           pre.textContent = JSON.stringify(leaf, null, 2)
 
+          const source = payload.sourceByLeaf && payload.sourceByLeaf[leaf.key]
+          let sourceWrap = null
+          if (source) {
+            sourceWrap = document.createElement('div')
+            sourceWrap.className = 'meta'
+
+            const definitionHref = toHref(source.definition)
+            if (definitionHref) {
+              const label = document.createElement('div')
+              const link = document.createElement('a')
+              link.href = definitionHref
+              link.target = '_blank'
+              link.rel = 'noopener noreferrer'
+              link.textContent = 'definition'
+              label.appendChild(link)
+              const location = document.createElement('span')
+              location.textContent =
+                ' (' +
+                source.definition.file +
+                ':' +
+                source.definition.line +
+                ':' +
+                source.definition.column +
+                ')'
+              label.appendChild(location)
+              sourceWrap.appendChild(label)
+            }
+
+            if (source.schemas && typeof source.schemas === 'object') {
+              Object.entries(source.schemas).forEach(([name, schema]) => {
+                if (!schema) return
+                const href = toHref(schema)
+                const row = document.createElement('div')
+                if (href) {
+                  const link = document.createElement('a')
+                  link.href = href
+                  link.target = '_blank'
+                  link.rel = 'noopener noreferrer'
+                  link.textContent =
+                    name + ': ' + (schema.sourceName || schema.tag || '<anonymous>')
+                  row.appendChild(link)
+                  const location = document.createElement('span')
+                  location.textContent =
+                    ' (' + schema.file + ':' + schema.line + ':' + schema.column + ')'
+                  row.appendChild(location)
+                } else {
+                  row.textContent = name + ': ' + (schema.sourceName || schema.tag || '<anonymous>')
+                }
+                sourceWrap.appendChild(row)
+              })
+            }
+
+          }
+
           details.appendChild(summary)
+          if (sourceWrap) details.appendChild(sourceWrap)
           details.appendChild(pre)
           resultsEl.appendChild(details)
         })
@@ -814,6 +877,551 @@ var DEFAULT_VIEWER_TEMPLATE = `<!doctype html>
 </html>
 `;
 
+// src/export/extractLeafSourceByAst.ts
+var import_node_path = __toESM(require("path"), 1);
+var import_typescript = __toESM(require("typescript"), 1);
+var SCHEMA_KEYS = [
+  "bodySchema",
+  "querySchema",
+  "paramsSchema",
+  "outputSchema",
+  "outputMetaSchema",
+  "queryExtensionSchema"
+];
+var HTTP_METHODS = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete"]);
+var MAX_RECURSION_DEPTH = 120;
+function toLocation(node) {
+  const sourceFile = node.getSourceFile();
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+    node.getStart(sourceFile)
+  );
+  return {
+    file: import_node_path.default.resolve(sourceFile.fileName),
+    line: line + 1,
+    column: character + 1
+  };
+}
+function markFile(ctx, sourceFile) {
+  if (!sourceFile) return;
+  ctx.visitedFilePaths.add(import_node_path.default.resolve(sourceFile.fileName));
+}
+function trimPreview(text, max = 80) {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length > max ? `${normalized.slice(0, max)}...` : normalized;
+}
+function unwrapExpression(expression) {
+  let current = expression;
+  while (true) {
+    if (import_typescript.default.isParenthesizedExpression(current) || import_typescript.default.isAsExpression(current) || import_typescript.default.isTypeAssertionExpression(current) || import_typescript.default.isNonNullExpression(current) || import_typescript.default.isSatisfiesExpression(current)) {
+      current = current.expression;
+      continue;
+    }
+    break;
+  }
+  return current;
+}
+function getTextName(name) {
+  if (import_typescript.default.isIdentifier(name) || import_typescript.default.isStringLiteral(name) || import_typescript.default.isNumericLiteral(name)) {
+    return name.text;
+  }
+  return void 0;
+}
+function joinPaths2(parent, child) {
+  if (!parent) return child;
+  if (!child) return parent;
+  const trimmedParent = parent.endsWith("/") ? parent.replace(/\/+$/, "") : parent;
+  const trimmedChild = child.startsWith("/") ? child.replace(/^\/+/, "") : child;
+  if (!trimmedChild) return trimmedParent;
+  return `${trimmedParent}/${trimmedChild}`;
+}
+function buildLeafKey(method, leafPath) {
+  return `${method.toUpperCase()} ${leafPath}`;
+}
+function normalizeResourceBase(raw) {
+  if (raw === "") return "";
+  if (raw.startsWith("/") || raw.startsWith(":") || raw.startsWith("*")) {
+    return raw;
+  }
+  return `/${raw}`;
+}
+function getModuleSymbol(checker, sourceFile) {
+  return checker.getSymbolAtLocation(sourceFile);
+}
+function getAliasedSymbolIfNeeded(checker, symbol) {
+  if ((symbol.flags & import_typescript.default.SymbolFlags.Alias) !== 0) {
+    try {
+      return checker.getAliasedSymbol(symbol);
+    } catch {
+      return symbol;
+    }
+  }
+  return symbol;
+}
+function findSourceFile(program, filePath) {
+  const wanted = import_node_path.default.resolve(filePath);
+  const normalizedWanted = import_node_path.default.normalize(wanted);
+  return program.getSourceFiles().find((file) => import_node_path.default.normalize(import_node_path.default.resolve(file.fileName)) === normalizedWanted);
+}
+function declarationToExpression(declaration) {
+  if (!declaration) return void 0;
+  if (import_typescript.default.isVariableDeclaration(declaration)) {
+    return declaration.initializer;
+  }
+  if (import_typescript.default.isExportAssignment(declaration)) {
+    return declaration.expression;
+  }
+  if (import_typescript.default.isPropertyAssignment(declaration)) {
+    return declaration.initializer;
+  }
+  if (import_typescript.default.isShorthandPropertyAssignment(declaration)) {
+    return declaration.name;
+  }
+  if (import_typescript.default.isBindingElement(declaration)) {
+    return declaration.initializer;
+  }
+  if (import_typescript.default.isEnumMember(declaration)) {
+    return declaration.initializer;
+  }
+  return void 0;
+}
+function symbolKey(symbol) {
+  const decl = symbol.declarations?.[0];
+  if (!decl) return `${symbol.getName()}#${symbol.flags}`;
+  const file = import_node_path.default.resolve(decl.getSourceFile().fileName);
+  return `${file}:${decl.getStart()}:${symbol.getName()}`;
+}
+function resolveSymbolFromNode(node, ctx) {
+  const symbol = ctx.checker.getSymbolAtLocation(node);
+  if (!symbol) {
+    ctx.unresolvedReferences += 1;
+    return void 0;
+  }
+  const target = getAliasedSymbolIfNeeded(ctx.checker, symbol);
+  const key = symbolKey(target);
+  ctx.visitedSymbolKeys.add(key);
+  return target;
+}
+function getExpressionFromSymbol(symbol, ctx, depth) {
+  const key = symbolKey(symbol);
+  if (ctx.activeSymbols.has(key)) return void 0;
+  if (depth > MAX_RECURSION_DEPTH) return void 0;
+  ctx.activeSymbols.add(key);
+  try {
+    const declaration = symbol.declarations?.[0];
+    markFile(ctx, declaration?.getSourceFile());
+    const direct = declarationToExpression(declaration);
+    if (direct) return direct;
+    if (declaration && import_typescript.default.isImportSpecifier(declaration)) {
+      const target = getAliasedSymbolIfNeeded(ctx.checker, symbol);
+      if (target !== symbol) {
+        return getExpressionFromSymbol(target, ctx, depth + 1);
+      }
+    }
+    return void 0;
+  } finally {
+    ctx.activeSymbols.delete(key);
+  }
+}
+function resolveIdentifierExpression(identifier, ctx, depth) {
+  const symbol = resolveSymbolFromNode(identifier, ctx);
+  if (!symbol) return void 0;
+  return getExpressionFromSymbol(symbol, ctx, depth);
+}
+function resolvePropertyExpression(expression, ctx, depth) {
+  if (depth > MAX_RECURSION_DEPTH) return void 0;
+  if (import_typescript.default.isPropertyAccessExpression(expression)) {
+    const symbol = resolveSymbolFromNode(expression.name, ctx);
+    if (symbol) {
+      const fromSymbol = getExpressionFromSymbol(symbol, ctx, depth + 1);
+      if (fromSymbol) return fromSymbol;
+    }
+  } else if (expression.argumentExpression) {
+    const symbol = resolveSymbolFromNode(expression.argumentExpression, ctx);
+    if (symbol) {
+      const fromSymbol = getExpressionFromSymbol(symbol, ctx, depth + 1);
+      if (fromSymbol) return fromSymbol;
+    }
+  }
+  const ownerExpr = evaluateExpressionReference(expression.expression, ctx, depth + 1);
+  const owner = ownerExpr ? maybeObjectLiteral(ownerExpr, ctx, depth + 1) : void 0;
+  if (!owner) return void 0;
+  const propName = import_typescript.default.isPropertyAccessExpression(expression) ? expression.name.text : expression.argumentExpression && import_typescript.default.isStringLiteralLike(expression.argumentExpression) ? expression.argumentExpression.text : void 0;
+  if (!propName) return void 0;
+  for (const property of owner.properties) {
+    if (import_typescript.default.isPropertyAssignment(property) && getTextName(property.name) === propName) {
+      return property.initializer;
+    }
+    if (import_typescript.default.isShorthandPropertyAssignment(property) && property.name.text === propName) {
+      return property.name;
+    }
+  }
+  return void 0;
+}
+function evaluateExpressionReference(expression, ctx, depth) {
+  const resolved = unwrapExpression(expression);
+  markFile(ctx, resolved.getSourceFile());
+  if (depth > MAX_RECURSION_DEPTH) return void 0;
+  if (import_typescript.default.isIdentifier(resolved)) {
+    return resolveIdentifierExpression(resolved, ctx, depth + 1);
+  }
+  if (import_typescript.default.isPropertyAccessExpression(resolved) || import_typescript.default.isElementAccessExpression(resolved)) {
+    return resolvePropertyExpression(resolved, ctx, depth + 1);
+  }
+  return void 0;
+}
+function resolveExportExpression(sourceFile, exportName, checker) {
+  const moduleSymbol = getModuleSymbol(checker, sourceFile);
+  if (!moduleSymbol) return void 0;
+  const exports2 = checker.getExportsOfModule(moduleSymbol);
+  const explicit = exports2.find((entry) => entry.getName() === exportName);
+  if (explicit) {
+    const declaration = getAliasedSymbolIfNeeded(checker, explicit).declarations?.[0];
+    return declarationToExpression(declaration);
+  }
+  const defaultExport = exports2.find((entry) => entry.getName() === "default");
+  if (!defaultExport) return void 0;
+  const defaultDecl = getAliasedSymbolIfNeeded(checker, defaultExport).declarations?.[0];
+  const defaultExpr = declarationToExpression(defaultDecl);
+  if (!defaultExpr) return void 0;
+  const resolved = unwrapExpression(defaultExpr);
+  if (!import_typescript.default.isObjectLiteralExpression(resolved)) return void 0;
+  for (const property of resolved.properties) {
+    if (!import_typescript.default.isPropertyAssignment(property)) continue;
+    const propertyName = getTextName(property.name);
+    if (propertyName !== exportName) continue;
+    return property.initializer;
+  }
+  return void 0;
+}
+function maybeObjectLiteral(expression, ctx, depth = 0) {
+  if (!expression || depth > MAX_RECURSION_DEPTH) return void 0;
+  const resolved = unwrapExpression(expression);
+  markFile(ctx, resolved.getSourceFile());
+  if (import_typescript.default.isObjectLiteralExpression(resolved)) return resolved;
+  const referenced = evaluateExpressionReference(resolved, ctx, depth + 1);
+  if (!referenced) return void 0;
+  return maybeObjectLiteral(referenced, ctx, depth + 1);
+}
+function collectSchemaExpressionsFromObject(objectLiteral, ctx, depth) {
+  const schemas = {};
+  for (const property of objectLiteral.properties) {
+    if (import_typescript.default.isSpreadAssignment(property)) {
+      const spreadObject = maybeObjectLiteral(property.expression, ctx, depth + 1);
+      if (!spreadObject) continue;
+      Object.assign(
+        schemas,
+        collectSchemaExpressionsFromObject(spreadObject, ctx, depth + 1)
+      );
+      continue;
+    }
+    if (import_typescript.default.isPropertyAssignment(property)) {
+      const key = getTextName(property.name);
+      if (!key || !SCHEMA_KEYS.includes(key)) continue;
+      schemas[key] = property.initializer;
+      continue;
+    }
+    if (import_typescript.default.isShorthandPropertyAssignment(property)) {
+      const key = property.name.text;
+      if (!SCHEMA_KEYS.includes(key)) continue;
+      schemas[key] = property.name;
+    }
+  }
+  return schemas;
+}
+function extractSchemaExpressions(cfgExpression, ctx, depth) {
+  const objectLiteral = maybeObjectLiteral(cfgExpression, ctx, depth);
+  if (!objectLiteral) return {};
+  return collectSchemaExpressionsFromObject(objectLiteral, ctx, depth);
+}
+function getNearestVariableName(node) {
+  let current = node;
+  while (current) {
+    if (import_typescript.default.isVariableDeclaration(current) && import_typescript.default.isIdentifier(current.name)) {
+      return current.name.text;
+    }
+    current = current.parent;
+  }
+  return void 0;
+}
+function isAllAccess(expression) {
+  if (import_typescript.default.isPropertyAccessExpression(expression)) {
+    return expression.name.text === "all";
+  }
+  return Boolean(
+    expression.argumentExpression && import_typescript.default.isStringLiteralLike(expression.argumentExpression) && expression.argumentExpression.text === "all"
+  );
+}
+function evaluateBranchExpression(expression, ctx, depth) {
+  const resolved = unwrapExpression(expression);
+  markFile(ctx, resolved.getSourceFile());
+  if (depth > MAX_RECURSION_DEPTH) return void 0;
+  if (import_typescript.default.isIdentifier(resolved)) {
+    const valueExpr = resolveIdentifierExpression(resolved, ctx, depth + 1);
+    if (!valueExpr) return void 0;
+    return evaluateBranchExpression(valueExpr, ctx, depth + 1);
+  }
+  if (!import_typescript.default.isCallExpression(resolved)) return void 0;
+  const call = resolved;
+  if (import_typescript.default.isIdentifier(call.expression) && call.expression.text === "resource") {
+    const firstArg = call.arguments[0];
+    if (!firstArg || !import_typescript.default.isStringLiteralLike(firstArg)) {
+      ctx.unsupportedShapeSeen = true;
+      return void 0;
+    }
+    return { base: normalizeResourceBase(firstArg.text), leaves: [] };
+  }
+  if (!import_typescript.default.isPropertyAccessExpression(call.expression)) {
+    ctx.unsupportedShapeSeen = true;
+    return void 0;
+  }
+  const owner = call.expression.expression;
+  const method = call.expression.name.text;
+  const branch = evaluateBranchExpression(owner, ctx, depth + 1);
+  if (!branch) return void 0;
+  if (method === "with") return branch;
+  if (HTTP_METHODS.has(method)) {
+    const cfgExpression = call.arguments[0];
+    const schemas = extractSchemaExpressions(cfgExpression, ctx, depth + 1);
+    const nextLeaf = {
+      method,
+      path: branch.base,
+      definitionNode: call.expression.name,
+      schemas
+    };
+    return {
+      ...branch,
+      leaves: [...branch.leaves, nextLeaf]
+    };
+  }
+  if (method === "sub") {
+    const mountedLeaves = call.arguments.flatMap(
+      (arg) => evaluateLeavesFromExpression(arg, ctx, depth + 1)
+    );
+    const prefixed = mountedLeaves.map((leaf) => ({
+      ...leaf,
+      path: joinPaths2(branch.base, leaf.path)
+    }));
+    return {
+      ...branch,
+      leaves: [...branch.leaves, ...prefixed]
+    };
+  }
+  ctx.unsupportedShapeSeen = true;
+  return void 0;
+}
+function expressionKey(expression) {
+  const source = expression.getSourceFile();
+  return `${import_node_path.default.resolve(source.fileName)}:${expression.getStart(source)}:${expression.getEnd()}:${expression.kind}`;
+}
+function evaluateLeavesFromExpression(expression, ctx, depth = 0) {
+  const resolved = unwrapExpression(expression);
+  markFile(ctx, resolved.getSourceFile());
+  const key = expressionKey(resolved);
+  if (ctx.activeExpressionKeys.has(key)) return [];
+  if (depth > MAX_RECURSION_DEPTH) return [];
+  ctx.activeExpressionKeys.add(key);
+  try {
+    if (import_typescript.default.isIdentifier(resolved)) {
+      const valueExpr = resolveIdentifierExpression(resolved, ctx, depth + 1);
+      if (!valueExpr) return [];
+      return evaluateLeavesFromExpression(valueExpr, ctx, depth + 1);
+    }
+    if (import_typescript.default.isPropertyAccessExpression(resolved) || import_typescript.default.isElementAccessExpression(resolved)) {
+      if (isAllAccess(resolved)) {
+        return evaluateLeavesFromExpression(resolved.expression, ctx, depth + 1);
+      }
+      const refExpr = resolvePropertyExpression(resolved, ctx, depth + 1);
+      if (refExpr) {
+        return evaluateLeavesFromExpression(refExpr, ctx, depth + 1);
+      }
+      return [];
+    }
+    if (import_typescript.default.isArrayLiteralExpression(resolved)) {
+      const leaves = [];
+      for (const element of resolved.elements) {
+        if (import_typescript.default.isSpreadElement(element)) {
+          leaves.push(...evaluateLeavesFromExpression(element.expression, ctx, depth + 1));
+          continue;
+        }
+        leaves.push(...evaluateLeavesFromExpression(element, ctx, depth + 1));
+      }
+      return leaves;
+    }
+    if (import_typescript.default.isCallExpression(resolved)) {
+      if (import_typescript.default.isIdentifier(resolved.expression)) {
+        const callName = resolved.expression.text;
+        if (callName === "finalize") {
+          const arg = resolved.arguments[0];
+          if (!arg) return [];
+          return evaluateLeavesFromExpression(arg, ctx, depth + 1);
+        }
+        if (callName === "mergeArrays") {
+          return resolved.arguments.flatMap(
+            (arg) => evaluateLeavesFromExpression(arg, ctx, depth + 1)
+          );
+        }
+      }
+      if (import_typescript.default.isPropertyAccessExpression(resolved.expression)) {
+        const prop = resolved.expression.name.text;
+        if (prop === "done") {
+          const branch2 = evaluateBranchExpression(
+            resolved.expression.expression,
+            ctx,
+            depth + 1
+          );
+          return branch2?.leaves ?? [];
+        }
+      }
+      const refExpr = evaluateExpressionReference(resolved, ctx, depth + 1);
+      if (refExpr) return evaluateLeavesFromExpression(refExpr, ctx, depth + 1);
+      ctx.unsupportedShapeSeen = true;
+      return [];
+    }
+    const branch = evaluateBranchExpression(resolved, ctx, depth + 1);
+    if (branch) return branch.leaves;
+    ctx.unsupportedShapeSeen = true;
+    return [];
+  } finally {
+    ctx.activeExpressionKeys.delete(key);
+  }
+}
+function resolveSchemaMetadata(expression, ctx) {
+  const resolved = unwrapExpression(expression);
+  if (import_typescript.default.isIdentifier(resolved)) {
+    const symbol = resolveSymbolFromNode(resolved, ctx);
+    const declaration = symbol?.declarations?.[0];
+    const locationNode = declaration ? import_typescript.default.isVariableDeclaration(declaration) ? declaration.name : declaration : resolved;
+    const sourceName = declaration && import_typescript.default.isVariableDeclaration(declaration) && import_typescript.default.isIdentifier(declaration.name) ? declaration.name.text : resolved.text;
+    return {
+      ...toLocation(locationNode),
+      sourceName,
+      tag: declaration ? void 0 : "<anonymous>"
+    };
+  }
+  if (import_typescript.default.isPropertyAccessExpression(resolved) || import_typescript.default.isElementAccessExpression(resolved)) {
+    return {
+      ...toLocation(resolved),
+      sourceName: trimPreview(resolved.getText()),
+      tag: "<expression>"
+    };
+  }
+  return {
+    ...toLocation(resolved),
+    sourceName: trimPreview(resolved.getText()),
+    tag: "<inline>"
+  };
+}
+function parseTsConfig(cwd, tsconfigPath) {
+  const resolvedTsconfig = tsconfigPath ? import_node_path.default.resolve(cwd, tsconfigPath) : import_typescript.default.findConfigFile(cwd, import_typescript.default.sys.fileExists, "tsconfig.json");
+  if (!resolvedTsconfig) {
+    return void 0;
+  }
+  const read = import_typescript.default.readConfigFile(resolvedTsconfig, import_typescript.default.sys.readFile);
+  if (read.error) {
+    throw new Error(import_typescript.default.flattenDiagnosticMessageText(read.error.messageText, "\n"));
+  }
+  const parsed = import_typescript.default.parseJsonConfigFileContent(
+    read.config,
+    import_typescript.default.sys,
+    import_node_path.default.dirname(resolvedTsconfig),
+    void 0,
+    resolvedTsconfig
+  );
+  const nonEmptyInputErrors = parsed.errors.filter((entry) => entry.code !== 18003);
+  if (nonEmptyInputErrors.length > 0) {
+    throw new Error(
+      nonEmptyInputErrors.map((entry) => import_typescript.default.flattenDiagnosticMessageText(entry.messageText, "\n")).join("\n")
+    );
+  }
+  return { resolvedTsconfig, parsed };
+}
+function createProgramWithFallback(parsed, moduleFileAbs) {
+  const base = import_typescript.default.createProgram({
+    rootNames: parsed.fileNames,
+    options: parsed.options
+  });
+  if (findSourceFile(base, moduleFileAbs)) {
+    return base;
+  }
+  const rootNames = Array.from(/* @__PURE__ */ new Set([...parsed.fileNames, moduleFileAbs]));
+  return import_typescript.default.createProgram({ rootNames, options: parsed.options });
+}
+function extractLeafSourceByAst({
+  modulePath,
+  exportName,
+  tsconfigPath,
+  cwd = process.cwd()
+}) {
+  const parsedConfig = parseTsConfig(cwd, tsconfigPath);
+  if (!parsedConfig) {
+    return {
+      sourceByLeaf: {},
+      reason: "module_not_in_program",
+      stats: { visitedSymbols: 0, visitedFiles: 0, unresolvedReferences: 0 }
+    };
+  }
+  const moduleAbs = import_node_path.default.resolve(cwd, modulePath);
+  const program = createProgramWithFallback(parsedConfig.parsed, moduleAbs);
+  const checker = program.getTypeChecker();
+  const moduleFile = findSourceFile(program, moduleAbs);
+  if (!moduleFile) {
+    return {
+      sourceByLeaf: {},
+      tsconfigPath: parsedConfig.resolvedTsconfig,
+      reason: "module_not_in_program",
+      stats: { visitedSymbols: 0, visitedFiles: 0, unresolvedReferences: 0 }
+    };
+  }
+  const exportedExpression = resolveExportExpression(moduleFile, exportName, checker);
+  if (!exportedExpression) {
+    return {
+      sourceByLeaf: {},
+      tsconfigPath: parsedConfig.resolvedTsconfig,
+      reason: "export_not_found",
+      stats: { visitedSymbols: 0, visitedFiles: 1, unresolvedReferences: 0 }
+    };
+  }
+  const ctx = {
+    checker,
+    activeExpressionKeys: /* @__PURE__ */ new Set(),
+    activeSymbols: /* @__PURE__ */ new Set(),
+    visitedSymbolKeys: /* @__PURE__ */ new Set(),
+    visitedFilePaths: /* @__PURE__ */ new Set([import_node_path.default.resolve(moduleFile.fileName)]),
+    unresolvedReferences: 0,
+    unsupportedShapeSeen: false
+  };
+  const evaluatedLeaves = evaluateLeavesFromExpression(exportedExpression, ctx, 0);
+  const sourceByLeaf = {};
+  for (const leaf of evaluatedLeaves) {
+    const key = buildLeafKey(leaf.method, leaf.path);
+    const definition = {
+      ...toLocation(leaf.definitionNode),
+      symbolName: getNearestVariableName(leaf.definitionNode)
+    };
+    ctx.visitedFilePaths.add(definition.file);
+    const schemas = {};
+    for (const schemaKey of SCHEMA_KEYS) {
+      const schemaExpression = leaf.schemas[schemaKey];
+      if (!schemaExpression) continue;
+      const schemaMeta = resolveSchemaMetadata(schemaExpression, ctx);
+      ctx.visitedFilePaths.add(schemaMeta.file);
+      schemas[schemaKey] = schemaMeta;
+    }
+    sourceByLeaf[key] = { definition, schemas };
+  }
+  const reason = Object.keys(sourceByLeaf).length > 0 ? void 0 : ctx.unsupportedShapeSeen ? "unsupported_expression_shape" : "resolved_zero_leaves";
+  return {
+    sourceByLeaf,
+    tsconfigPath: parsedConfig.resolvedTsconfig,
+    reason,
+    stats: {
+      visitedSymbols: ctx.visitedSymbolKeys.size,
+      visitedFiles: ctx.visitedFilePaths.size,
+      unresolvedReferences: ctx.unresolvedReferences
+    }
+  };
+}
+
 // src/export/exportFinalizedLeaves.ts
 function isRegistry(value) {
   return typeof value === "object" && value !== null && "all" in value && "byKey" in value;
@@ -821,10 +1429,11 @@ function isRegistry(value) {
 function getLeaves(input) {
   return isRegistry(input) ? input.all : input;
 }
-function buildMeta() {
+function buildMeta(sourceExtraction) {
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     description: "Finalized RRRoutes leaves export with serialized schemas and flattened schema paths for downstream processing.",
+    sourceExtraction,
     fieldCatalog: {
       leaf: ["key", "method", "path", "cfg"],
       cfg: [
@@ -881,20 +1490,20 @@ ${htmlTemplate}`;
 }
 async function resolveViewerTemplatePath(viewerTemplateFile) {
   if (viewerTemplateFile) {
-    const resolved = import_node_path.default.resolve(viewerTemplateFile);
+    const resolved = import_node_path2.default.resolve(viewerTemplateFile);
     await import_promises.default.access(resolved);
     return resolved;
   }
   const candidates = [
-    import_node_path.default.resolve(
+    import_node_path2.default.resolve(
       process.cwd(),
       "node_modules/@emeryld/rrroutes-contract/tools/finalized-leaves-viewer.html"
     ),
-    import_node_path.default.resolve(
+    import_node_path2.default.resolve(
       process.cwd(),
       "tools/finalized-leaves-viewer.html"
     ),
-    import_node_path.default.resolve(
+    import_node_path2.default.resolve(
       process.cwd(),
       "packages/contract/tools/finalized-leaves-viewer.html"
     )
@@ -909,8 +1518,8 @@ async function resolveViewerTemplatePath(viewerTemplateFile) {
   return void 0;
 }
 async function writeJsonExport(payload, outFile) {
-  const resolved = import_node_path.default.resolve(outFile);
-  await import_promises.default.mkdir(import_node_path.default.dirname(resolved), { recursive: true });
+  const resolved = import_node_path2.default.resolve(outFile);
+  await import_promises.default.mkdir(import_node_path2.default.dirname(resolved), { recursive: true });
   await import_promises.default.writeFile(resolved, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
   return resolved;
@@ -919,13 +1528,13 @@ async function writeBakedHtmlExport(payload, htmlFile, viewerTemplateFile) {
   const templatePath = await resolveViewerTemplatePath(viewerTemplateFile);
   const template = templatePath ? await import_promises.default.readFile(templatePath, "utf8") : DEFAULT_VIEWER_TEMPLATE;
   const baked = injectPayloadIntoViewerHtml(template, payload);
-  const resolved = import_node_path.default.resolve(htmlFile);
-  await import_promises.default.mkdir(import_node_path.default.dirname(resolved), { recursive: true });
+  const resolved = import_node_path2.default.resolve(htmlFile);
+  await import_promises.default.mkdir(import_node_path2.default.dirname(resolved), { recursive: true });
   await import_promises.default.writeFile(resolved, baked, "utf8");
   return resolved;
 }
 async function openHtmlInBrowser(filePath) {
-  const resolved = import_node_path.default.resolve(filePath);
+  const resolved = import_node_path2.default.resolve(filePath);
   const platform = process.platform;
   if (platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [resolved], { detached: true, stdio: "ignore" }).unref();
@@ -969,10 +1578,54 @@ async function exportFinalizedLeaves(input, options = {}) {
   const schemaFlatByLeaf = Object.fromEntries(
     serializedLeaves.map((leaf) => [leaf.key, flattenLeafSchemas(leaf)])
   );
+  const sourceByLeaf = {};
+  let sourceExtraction;
+  if (options.includeSource) {
+    const modulePath = options.sourceModulePath;
+    const exportName = options.sourceExportName ?? "leaves";
+    if (modulePath) {
+      const extracted = extractLeafSourceByAst({
+        modulePath,
+        exportName,
+        tsconfigPath: options.tsconfigPath
+      });
+      const allowedLeafKeys = new Set(serializedLeaves.map((leaf) => leaf.key));
+      for (const [key, source] of Object.entries(extracted.sourceByLeaf)) {
+        if (allowedLeafKeys.has(key)) {
+          sourceByLeaf[key] = source;
+        }
+      }
+      sourceExtraction = {
+        mode: "ast",
+        enabled: true,
+        modulePath: import_node_path2.default.resolve(modulePath),
+        exportName,
+        tsconfigPath: extracted.tsconfigPath,
+        resolvedLeafCount: Object.keys(sourceByLeaf).length,
+        reason: extracted.reason,
+        stats: extracted.stats
+      };
+    } else {
+      sourceExtraction = {
+        mode: "ast",
+        enabled: false,
+        exportName,
+        tsconfigPath: options.tsconfigPath ? import_node_path2.default.resolve(options.tsconfigPath) : void 0,
+        resolvedLeafCount: 0,
+        reason: "resolved_zero_leaves",
+        stats: {
+          visitedSymbols: 0,
+          visitedFiles: 0,
+          unresolvedReferences: 0
+        }
+      };
+    }
+  }
   const payload = {
-    _meta: buildMeta(),
+    _meta: buildMeta(sourceExtraction),
     leaves: serializedLeaves,
-    schemaFlatByLeaf
+    schemaFlatByLeaf,
+    sourceByLeaf: options.includeSource && Object.keys(sourceByLeaf).length > 0 ? sourceByLeaf : void 0
   };
   if (options.outFile || options.htmlFile) {
     await writeFinalizedLeavesExport(payload, {
@@ -986,14 +1639,19 @@ async function exportFinalizedLeaves(input, options = {}) {
 }
 
 // src/export/exportFinalizedLeaves.cli.ts
-var import_node_path2 = __toESM(require("path"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 function parseFinalizedLeavesCliArgs(argv) {
   const args = /* @__PURE__ */ new Map();
+  let withSource = false;
   for (let i = 0; i < argv.length; i += 1) {
     const key = argv[i];
     if (key === "--") continue;
     if (!key.startsWith("--")) continue;
+    if (key === "--with-source") {
+      withSource = true;
+      continue;
+    }
     const value = argv[i + 1];
     if (!value || value.startsWith("--")) {
       throw new Error(`Missing value for ${key}`);
@@ -1008,14 +1666,16 @@ function parseFinalizedLeavesCliArgs(argv) {
   return {
     modulePath,
     exportName: args.get("--export") ?? "leaves",
-    outFile: args.get("--out") ?? "finalized-leaves.export.json"
+    outFile: args.get("--out") ?? "finalized-leaves.export.json",
+    withSource,
+    tsconfigPath: args.get("--tsconfig") ?? void 0
   };
 }
 async function loadFinalizedLeavesInput({
   modulePath,
   exportName
 }) {
-  const resolvedModule = import_node_path2.default.resolve(process.cwd(), modulePath);
+  const resolvedModule = import_node_path3.default.resolve(process.cwd(), modulePath);
   const mod = await import((0, import_node_url.pathToFileURL)(resolvedModule).href);
   const value = mod[exportName] ?? (mod.default && mod.default[exportName]);
   if (!value) {
@@ -1026,10 +1686,16 @@ async function loadFinalizedLeavesInput({
 async function runExportFinalizedLeavesCli(argv) {
   const args = parseFinalizedLeavesCliArgs(argv);
   const input = await loadFinalizedLeavesInput(args);
-  const payload = await exportFinalizedLeaves(input, { outFile: args.outFile });
+  const payload = await exportFinalizedLeaves(input, {
+    outFile: args.outFile,
+    includeSource: args.withSource,
+    tsconfigPath: args.tsconfigPath,
+    sourceModulePath: args.modulePath,
+    sourceExportName: args.exportName
+  });
   return {
     payload,
-    outFile: import_node_path2.default.resolve(args.outFile)
+    outFile: import_node_path3.default.resolve(args.outFile)
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1043,6 +1709,7 @@ async function runExportFinalizedLeavesCli(argv) {
   createSchemaIntrospector,
   defineSocketEvents,
   exportFinalizedLeaves,
+  extractLeafSourceByAst,
   finalize,
   flattenLeafSchemas,
   flattenSerializableSchema,