npm - @emeryld/rrroutes-contract - Versions diffs - 2.7.4 → 2.7.6 - Mend

@emeryld/rrroutes-contract 2.7.4 → 2.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +19 -1
package/bin/rrroutes-export-finalized-leaves.mjs +14 -0
package/dist/export/defaultViewerTemplate.d.ts +1 -1
package/dist/export/exportFinalizedLeaves.cli.d.ts +2 -0
package/dist/export/exportFinalizedLeaves.d.ts +14 -0
package/dist/export/extractLeafSourceByAst.d.ts +30 -0
package/dist/export/index.d.ts +1 -0
package/dist/index.cjs +540 -38
package/dist/index.cjs.map +1 -1
package/dist/index.mjs +539 -38
package/dist/index.mjs.map +1 -1
package/package.json +7 -2
package/tools/finalized-leaves-viewer.html +272 -138

package/dist/index.mjs CHANGED Viewed

@@ -42,9 +42,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);
@@ -119,8 +119,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;
 };
@@ -296,8 +296,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];
@@ -617,45 +617,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) {
@@ -676,7 +676,7 @@ function flattenLeafSchemas(leaf) {
 // src/export/exportFinalizedLeaves.ts
 import fs from "fs/promises";
-import path from "path";
+import path2 from "path";
 import { spawn } from "child_process";
 // src/export/defaultViewerTemplate.ts
@@ -731,6 +731,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')
@@ -739,7 +746,63 @@ 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: ' +
+                source.definition.file +
+                ':' +
+                source.definition.line +
+                ':' +
+                source.definition.column
+              label.appendChild(link)
+              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>') +
+                    ' (' +
+                    schema.file +
+                    ':' +
+                    schema.line +
+                    ':' +
+                    schema.column +
+                    ')'
+                  row.appendChild(link)
+                } 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)
         })
@@ -749,6 +812,393 @@ var DEFAULT_VIEWER_TEMPLATE = `<!doctype html>
 </html>
 `;
+// src/export/extractLeafSourceByAst.ts
+import path from "path";
+import ts from "typescript";
+var SCHEMA_KEYS = [
+  "bodySchema",
+  "querySchema",
+  "paramsSchema",
+  "outputSchema",
+  "outputMetaSchema",
+  "queryExtensionSchema"
+];
+var HTTP_METHODS = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete"]);
+function toLocation(node) {
+  const sourceFile = node.getSourceFile();
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+    node.getStart(sourceFile)
+  );
+  return {
+    file: path.resolve(sourceFile.fileName),
+    line: line + 1,
+    column: character + 1
+  };
+}
+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 (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current) || ts.isSatisfiesExpression(current)) {
+      current = current.expression;
+      continue;
+    }
+    break;
+  }
+  return current;
+}
+function getTextName(name) {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.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 & ts.SymbolFlags.Alias) !== 0) {
+    try {
+      return checker.getAliasedSymbol(symbol);
+    } catch {
+      return symbol;
+    }
+  }
+  return symbol;
+}
+function findSourceFile(program, filePath) {
+  const wanted = path.resolve(filePath);
+  const normalizedWanted = path.normalize(wanted);
+  return program.getSourceFiles().find((file) => path.normalize(path.resolve(file.fileName)) === normalizedWanted);
+}
+function expressionFromDeclaration(declaration) {
+  if (!declaration) return void 0;
+  if (ts.isVariableDeclaration(declaration)) {
+    return declaration.initializer;
+  }
+  if (ts.isExportAssignment(declaration)) {
+    return declaration.expression;
+  }
+  if (ts.isPropertyAssignment(declaration)) {
+    return declaration.initializer;
+  }
+  if (ts.isShorthandPropertyAssignment(declaration)) {
+    return declaration.name;
+  }
+  if (ts.isBindingElement(declaration)) {
+    return declaration.initializer;
+  }
+  return void 0;
+}
+function resolveIdentifierExpression(identifier, ctx) {
+  const symbol = ctx.checker.getSymbolAtLocation(identifier);
+  if (!symbol) return void 0;
+  const target = getAliasedSymbolIfNeeded(ctx.checker, symbol);
+  const declaration = target.declarations?.[0];
+  return expressionFromDeclaration(declaration);
+}
+function resolveExportExpression(sourceFile, exportName, checker) {
+  const moduleSymbol = getModuleSymbol(checker, sourceFile);
+  if (!moduleSymbol) return void 0;
+  const exports = checker.getExportsOfModule(moduleSymbol);
+  const explicit = exports.find((entry) => entry.getName() === exportName);
+  if (explicit) {
+    const declaration = getAliasedSymbolIfNeeded(checker, explicit).declarations?.[0];
+    return expressionFromDeclaration(declaration);
+  }
+  const defaultExport = exports.find((entry) => entry.getName() === "default");
+  if (!defaultExport) return void 0;
+  const defaultDecl = getAliasedSymbolIfNeeded(checker, defaultExport).declarations?.[0];
+  const defaultExpr = expressionFromDeclaration(defaultDecl);
+  if (!defaultExpr) return void 0;
+  const resolved = unwrapExpression(defaultExpr);
+  if (!ts.isObjectLiteralExpression(resolved)) return void 0;
+  for (const property of resolved.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const propertyName = getTextName(property.name);
+    if (propertyName !== exportName) continue;
+    return property.initializer;
+  }
+  return void 0;
+}
+function maybeObjectLiteral(expression, ctx) {
+  if (!expression) return void 0;
+  const resolved = unwrapExpression(expression);
+  if (ts.isObjectLiteralExpression(resolved)) return resolved;
+  if (ts.isIdentifier(resolved)) {
+    const target = resolveIdentifierExpression(resolved, ctx);
+    if (!target) return void 0;
+    return maybeObjectLiteral(target, ctx);
+  }
+  return void 0;
+}
+function collectSchemaExpressionsFromObject(objectLiteral, ctx) {
+  const schemas = {};
+  for (const property of objectLiteral.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      const spreadObject = maybeObjectLiteral(property.expression, ctx);
+      if (!spreadObject) continue;
+      Object.assign(schemas, collectSchemaExpressionsFromObject(spreadObject, ctx));
+      continue;
+    }
+    if (ts.isPropertyAssignment(property)) {
+      const key = getTextName(property.name);
+      if (!key || !SCHEMA_KEYS.includes(key)) continue;
+      schemas[key] = property.initializer;
+      continue;
+    }
+    if (ts.isShorthandPropertyAssignment(property)) {
+      const key = property.name.text;
+      if (!SCHEMA_KEYS.includes(key)) continue;
+      schemas[key] = property.name;
+    }
+  }
+  return schemas;
+}
+function extractSchemaExpressions(cfgExpression, ctx) {
+  const objectLiteral = maybeObjectLiteral(cfgExpression, ctx);
+  if (!objectLiteral) return {};
+  return collectSchemaExpressionsFromObject(objectLiteral, ctx);
+}
+function getNearestVariableName(node) {
+  let current = node;
+  while (current) {
+    if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name)) {
+      return current.name.text;
+    }
+    current = current.parent;
+  }
+  return void 0;
+}
+function evaluateBranchExpression(expression, ctx) {
+  const resolved = unwrapExpression(expression);
+  if (ts.isIdentifier(resolved)) {
+    const valueExpr = resolveIdentifierExpression(resolved, ctx);
+    if (!valueExpr) return void 0;
+    return evaluateBranchExpression(valueExpr, ctx);
+  }
+  if (!ts.isCallExpression(resolved)) return void 0;
+  const call = resolved;
+  if (ts.isIdentifier(call.expression) && call.expression.text === "resource") {
+    const firstArg = call.arguments[0];
+    if (!firstArg || !ts.isStringLiteralLike(firstArg)) return void 0;
+    return { base: normalizeResourceBase(firstArg.text), leaves: [] };
+  }
+  if (!ts.isPropertyAccessExpression(call.expression)) return void 0;
+  const owner = call.expression.expression;
+  const method = call.expression.name.text;
+  const branch = evaluateBranchExpression(owner, ctx);
+  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);
+    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)
+    );
+    const prefixed = mountedLeaves.map((leaf) => ({
+      ...leaf,
+      path: joinPaths2(branch.base, leaf.path)
+    }));
+    return {
+      ...branch,
+      leaves: [...branch.leaves, ...prefixed]
+    };
+  }
+  return void 0;
+}
+function evaluateLeavesFromExpression(expression, ctx) {
+  const resolved = unwrapExpression(expression);
+  const key = resolved.getStart(resolved.getSourceFile());
+  if (ctx.visitedExpressionStarts.has(key)) {
+    return [];
+  }
+  ctx.visitedExpressionStarts.add(key);
+  try {
+    if (ts.isIdentifier(resolved)) {
+      const valueExpr = resolveIdentifierExpression(resolved, ctx);
+      if (!valueExpr) return [];
+      return evaluateLeavesFromExpression(valueExpr, ctx);
+    }
+    if (ts.isArrayLiteralExpression(resolved)) {
+      const leaves = [];
+      for (const element of resolved.elements) {
+        if (ts.isSpreadElement(element)) {
+          leaves.push(...evaluateLeavesFromExpression(element.expression, ctx));
+          continue;
+        }
+        leaves.push(...evaluateLeavesFromExpression(element, ctx));
+      }
+      return leaves;
+    }
+    if (ts.isCallExpression(resolved)) {
+      if (ts.isIdentifier(resolved.expression)) {
+        const callName = resolved.expression.text;
+        if (callName === "finalize") {
+          const arg = resolved.arguments[0];
+          if (!arg) return [];
+          return evaluateLeavesFromExpression(arg, ctx);
+        }
+        if (callName === "mergeArrays") {
+          return resolved.arguments.flatMap(
+            (arg) => evaluateLeavesFromExpression(arg, ctx)
+          );
+        }
+      }
+      if (ts.isPropertyAccessExpression(resolved.expression)) {
+        const prop = resolved.expression.name.text;
+        if (prop === "done") {
+          const branch2 = evaluateBranchExpression(resolved.expression.expression, ctx);
+          return branch2?.leaves ?? [];
+        }
+      }
+    }
+    const branch = evaluateBranchExpression(resolved, ctx);
+    return branch?.leaves ?? [];
+  } finally {
+    ctx.visitedExpressionStarts.delete(key);
+  }
+}
+function resolveSchemaMetadata(expression, ctx) {
+  const resolved = unwrapExpression(expression);
+  if (ts.isIdentifier(resolved)) {
+    const symbol = ctx.checker.getSymbolAtLocation(resolved);
+    const target = symbol ? getAliasedSymbolIfNeeded(ctx.checker, symbol) : void 0;
+    const declaration = target?.declarations?.[0];
+    const locationNode = declaration ? ts.isVariableDeclaration(declaration) ? declaration.name : declaration : resolved;
+    const sourceName = declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) ? declaration.name.text : resolved.text;
+    return {
+      ...toLocation(locationNode),
+      sourceName,
+      tag: declaration ? void 0 : "<anonymous>"
+    };
+  }
+  if (ts.isPropertyAccessExpression(resolved) || ts.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 ? path.resolve(cwd, tsconfigPath) : ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json");
+  if (!resolvedTsconfig) {
+    return void 0;
+  }
+  const read = ts.readConfigFile(resolvedTsconfig, ts.sys.readFile);
+  if (read.error) {
+    throw new Error(ts.flattenDiagnosticMessageText(read.error.messageText, "\n"));
+  }
+  const parsed = ts.parseJsonConfigFileContent(
+    read.config,
+    ts.sys,
+    path.dirname(resolvedTsconfig),
+    void 0,
+    resolvedTsconfig
+  );
+  if (parsed.errors.length > 0) {
+    throw new Error(
+      parsed.errors.map((entry) => ts.flattenDiagnosticMessageText(entry.messageText, "\n")).join("\n")
+    );
+  }
+  return { resolvedTsconfig, parsed };
+}
+function extractLeafSourceByAst({
+  modulePath,
+  exportName,
+  tsconfigPath,
+  cwd = process.cwd()
+}) {
+  const parsedConfig = parseTsConfig(cwd, tsconfigPath);
+  if (!parsedConfig) {
+    return { sourceByLeaf: {} };
+  }
+  const program = ts.createProgram({
+    rootNames: parsedConfig.parsed.fileNames,
+    options: parsedConfig.parsed.options
+  });
+  const checker = program.getTypeChecker();
+  const moduleFile = findSourceFile(program, path.resolve(cwd, modulePath));
+  if (!moduleFile) {
+    return {
+      sourceByLeaf: {},
+      tsconfigPath: parsedConfig.resolvedTsconfig
+    };
+  }
+  const exportedExpression = resolveExportExpression(moduleFile, exportName, checker);
+  if (!exportedExpression) {
+    return {
+      sourceByLeaf: {},
+      tsconfigPath: parsedConfig.resolvedTsconfig
+    };
+  }
+  const ctx = {
+    checker,
+    visitedExpressionStarts: /* @__PURE__ */ new Set()
+  };
+  const evaluatedLeaves = evaluateLeavesFromExpression(exportedExpression, ctx);
+  const sourceByLeaf = {};
+  for (const leaf of evaluatedLeaves) {
+    const key = buildLeafKey(leaf.method, leaf.path);
+    const definition = {
+      ...toLocation(leaf.definitionNode),
+      symbolName: getNearestVariableName(leaf.definitionNode)
+    };
+    const schemas = {};
+    for (const schemaKey of SCHEMA_KEYS) {
+      const schemaExpression = leaf.schemas[schemaKey];
+      if (!schemaExpression) continue;
+      schemas[schemaKey] = resolveSchemaMetadata(schemaExpression, ctx);
+    }
+    sourceByLeaf[key] = { definition, schemas };
+  }
+  return {
+    sourceByLeaf,
+    tsconfigPath: parsedConfig.resolvedTsconfig
+  };
+}
 // src/export/exportFinalizedLeaves.ts
 function isRegistry(value) {
   return typeof value === "object" && value !== null && "all" in value && "byKey" in value;
@@ -756,10 +1206,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: [
@@ -816,20 +1267,20 @@ ${htmlTemplate}`;
 }
 async function resolveViewerTemplatePath(viewerTemplateFile) {
   if (viewerTemplateFile) {
-    const resolved = path.resolve(viewerTemplateFile);
+    const resolved = path2.resolve(viewerTemplateFile);
     await fs.access(resolved);
     return resolved;
   }
   const candidates = [
-    path.resolve(
+    path2.resolve(
       process.cwd(),
       "node_modules/@emeryld/rrroutes-contract/tools/finalized-leaves-viewer.html"
     ),
-    path.resolve(
+    path2.resolve(
       process.cwd(),
       "tools/finalized-leaves-viewer.html"
     ),
-    path.resolve(
+    path2.resolve(
       process.cwd(),
       "packages/contract/tools/finalized-leaves-viewer.html"
     )
@@ -844,8 +1295,8 @@ async function resolveViewerTemplatePath(viewerTemplateFile) {
   return void 0;
 }
 async function writeJsonExport(payload, outFile) {
-  const resolved = path.resolve(outFile);
-  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  const resolved = path2.resolve(outFile);
+  await fs.mkdir(path2.dirname(resolved), { recursive: true });
   await fs.writeFile(resolved, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
   return resolved;
@@ -854,13 +1305,13 @@ async function writeBakedHtmlExport(payload, htmlFile, viewerTemplateFile) {
   const templatePath = await resolveViewerTemplatePath(viewerTemplateFile);
   const template = templatePath ? await fs.readFile(templatePath, "utf8") : DEFAULT_VIEWER_TEMPLATE;
   const baked = injectPayloadIntoViewerHtml(template, payload);
-  const resolved = path.resolve(htmlFile);
-  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  const resolved = path2.resolve(htmlFile);
+  await fs.mkdir(path2.dirname(resolved), { recursive: true });
   await fs.writeFile(resolved, baked, "utf8");
   return resolved;
 }
 async function openHtmlInBrowser(filePath) {
-  const resolved = path.resolve(filePath);
+  const resolved = path2.resolve(filePath);
   const platform = process.platform;
   if (platform === "darwin") {
     spawn("open", [resolved], { detached: true, stdio: "ignore" }).unref();
@@ -904,10 +1355,46 @@ 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: path2.resolve(modulePath),
+        exportName,
+        tsconfigPath: extracted.tsconfigPath,
+        resolvedLeafCount: Object.keys(sourceByLeaf).length
+      };
+    } else {
+      sourceExtraction = {
+        mode: "ast",
+        enabled: false,
+        exportName,
+        tsconfigPath: options.tsconfigPath ? path2.resolve(options.tsconfigPath) : void 0,
+        resolvedLeafCount: 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, {
@@ -921,14 +1408,19 @@ async function exportFinalizedLeaves(input, options = {}) {
 }
 // src/export/exportFinalizedLeaves.cli.ts
-import path2 from "path";
+import path3 from "path";
 import { pathToFileURL } from "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}`);
@@ -943,14 +1435,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 = path2.resolve(process.cwd(), modulePath);
+  const resolvedModule = path3.resolve(process.cwd(), modulePath);
   const mod = await import(pathToFileURL(resolvedModule).href);
   const value = mod[exportName] ?? (mod.default && mod.default[exportName]);
   if (!value) {
@@ -961,10 +1455,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: path2.resolve(args.outFile)
+    outFile: path3.resolve(args.outFile)
   };
 }
 export {
@@ -977,6 +1477,7 @@ export {
   createSchemaIntrospector,
   defineSocketEvents,
   exportFinalizedLeaves,
+  extractLeafSourceByAst,
   finalize,
   flattenLeafSchemas,
   flattenSerializableSchema,