@stripe/extensibility-sdk 0.22.4

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (C) 2026 Stripe, Inc. (https://stripe.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/config-values/generate.cjs

@@ -0,0 +1,262 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/config-values/generate.ts
+var generate_exports = {};
+__export(generate_exports, {
+  STDLIB_IMPORT_PATH: () => STDLIB_IMPORT_PATH,
+  analyzeConfigType: () => analyzeConfigType,
+  analyzeConfigTypeInProject: () => analyzeConfigTypeInProject,
+  generateConfigDescriptor: () => generateConfigDescriptor
+});
+module.exports = __toCommonJS(generate_exports);
+
+// src/config-values/parse.ts
+var import_ts_morph = require("ts-morph");
+function analyzeConfigType(options) {
+  const project = new import_ts_morph.Project({
+    compilerOptions: { strict: true, skipLibCheck: true },
+    skipAddingFilesFromTsConfig: true
+  });
+  project.addSourceFileAtPath(options.filePath);
+  project.resolveSourceFileDependencies();
+  return analyzeConfigTypeInProject(project, options.filePath, options.typeName);
+}
+function analyzeConfigTypeInProject(project, filePath, typeName) {
+  const sourceFile = project.getSourceFileOrThrow(filePath);
+  const target = sourceFile.getInterface(typeName) ?? sourceFile.getTypeAlias(typeName) ?? sourceFile.getClass(typeName);
+  if (!target) {
+    throw new Error(`Type "${typeName}" not found in "${filePath}"`);
+  }
+  const state = { interfaces: [], enums: [] };
+  const type = target.getType();
+  const fields = walkObjectType(type, typeName, state);
+  state.interfaces.push({ name: typeName, fields });
+  return { rootTypeName: typeName, interfaces: state.interfaces, enums: state.enums };
+}
+function walkObjectType(type, context, state) {
+  const fields = [];
+  for (const sym of type.getProperties()) {
+    const decl = sym.getValueDeclaration();
+    if (!decl || !import_ts_morph.Node.isPropertySignature(decl) && !import_ts_morph.Node.isPropertyDeclaration(decl))
+      continue;
+    const hasQuestionMark = decl.hasQuestionToken();
+    const rawType = decl.getType();
+    const { classification, optional } = classifyType(
+      rawType,
+      `${context}.${sym.getName()}`,
+      state
+    );
+    fields.push({
+      name: sym.getName(),
+      classification,
+      optional: optional || hasQuestionMark
+    });
+  }
+  return fields;
+}
+function classifyType(type, context, state) {
+  if (type.isUnion()) {
+    const members = type.getUnionTypes();
+    const hasNullable = members.some((m) => m.isUndefined() || m.isNull());
+    const nonNullable = members.filter((m) => !m.isUndefined() && !m.isNull());
+    if (nonNullable.length === 0) {
+      throw new Error(
+        `${context}: Type is only null/undefined, which is not a valid config type`
+      );
+    }
+    if (nonNullable.every((m) => m.isBooleanLiteral())) {
+      return { classification: { kind: "primitive" }, optional: hasNullable };
+    }
+    if (nonNullable.every((m) => m.isStringLiteral())) {
+      const aliasSymbol = type.getAliasSymbol();
+      const typeName = aliasSymbol ? aliasSymbol.getName() : context.replace(/\./g, "_");
+      if (!state.enums.some((e) => e.name === typeName)) {
+        const values = nonNullable.map((m) => m.getLiteralValue());
+        state.enums.push({ name: typeName, values });
+      }
+      return { classification: { kind: "enum", typeName }, optional: hasNullable };
+    }
+    if (nonNullable.length === 1) {
+      const [sole] = nonNullable;
+      if (sole) {
+        const { classification } = classifyType(sole, context, state);
+        return { classification, optional: hasNullable };
+      }
+    }
+    throw new Error(
+      `${context}: Union types are not supported in config types (only T | undefined or T | null is allowed)`
+    );
+  }
+  if (type.isStringLiteral()) {
+    const value = type.getLiteralValue();
+    const typeName = context.replace(/\./g, "_");
+    if (!state.enums.some((e) => e.name === typeName)) {
+      state.enums.push({ name: typeName, values: [value] });
+    }
+    return { classification: { kind: "enum", typeName }, optional: false };
+  }
+  if (isStdlibDecimalType(type)) {
+    return { classification: { kind: "decimal" }, optional: false };
+  }
+  const dateSym = type.getSymbol();
+  if (dateSym?.getName() === "Date") {
+    const srcPath = dateSym.getDeclarations()[0]?.getSourceFile().getFilePath() ?? "";
+    const basename = srcPath.slice(srcPath.lastIndexOf("/") + 1);
+    if (basename.startsWith("lib.") && basename.endsWith(".d.ts")) {
+      return { classification: { kind: "datetime" }, optional: false };
+    }
+  }
+  if (type.isString()) return { classification: { kind: "primitive" }, optional: false };
+  if (type.isNumber()) return { classification: { kind: "primitive" }, optional: false };
+  if (type.isBoolean()) return { classification: { kind: "primitive" }, optional: false };
+  if (type.isArray()) {
+    const elementType = type.getArrayElementTypeOrThrow();
+    const { classification: element } = classifyType(elementType, `${context}[]`, state);
+    return { classification: { kind: "array", element }, optional: false };
+  }
+  const stringIndexType = type.getStringIndexType();
+  if (stringIndexType) {
+    const { classification: value } = classifyType(
+      stringIndexType,
+      `${context}[string]`,
+      state
+    );
+    return { classification: { kind: "map", value }, optional: false };
+  }
+  if (type.isObject()) {
+    const typeSym = type.getSymbol();
+    const symName = typeSym?.getName();
+    const typeName = symName && !symName.startsWith("__") ? symName : context.replace(/\./g, "_");
+    if (!state.interfaces.some((i) => i.name === typeName)) {
+      const shapeFields = walkObjectType(type, typeName, state);
+      state.interfaces.push({ name: typeName, fields: shapeFields });
+    }
+    return { classification: { kind: "interface", typeName }, optional: false };
+  }
+  throw new Error(`${context}: Unsupported config field type: ${type.getText()}`);
+}
+function isStdlibDecimalType(type) {
+  return [type.getAliasSymbol(), type.getSymbol()].some((symbol) => {
+    if (symbol?.getName() !== "Decimal") return false;
+    return symbol.getDeclarations().some((declaration) => {
+      const srcPath = declaration.getSourceFile().getFilePath();
+      return srcPath.includes("stdlib/decimal") || srcPath.includes("stdlib/index");
+    });
+  });
+}
+
+// src/config-values/generate.ts
+var STDLIB_IMPORT_PATH = "@stripe/extensibility-sdk/stdlib";
+function generateConfigDescriptor(result) {
+  const usedImports = /* @__PURE__ */ new Set();
+  const usedTypeImports = /* @__PURE__ */ new Set();
+  const lines = [];
+  if (result.enums.length > 0) usedImports.add("_ConfigEnum");
+  for (const enumDesc of result.enums) {
+    const values = enumDesc.values.map((v) => JSON.stringify(v)).join(", ");
+    lines.push(`const ${enumDesc.name}_ConfigValues = new _ConfigEnum([${values}]);`);
+    lines.push("");
+  }
+  usedImports.add("_ShapeDescriptor");
+  usedImports.add("_JsonWireToType");
+  for (const iface of result.interfaces) {
+    const constVarName = `${iface.name}_FromConfig`;
+    const entries = [];
+    for (const field of iface.fields) {
+      const inner = fieldTransformExpr(field.classification, usedImports);
+      const transform = wrapConfigTransform(inner, field.optional, usedImports);
+      entries.push(`  { type: ${JSON.stringify(field.name)}, transform: ${transform} },`);
+    }
+    lines.push(
+      `const ${constVarName} = new _ShapeDescriptor<typeof _JsonWireToType, ${iface.name}>(${JSON.stringify(iface.name)}, [`
+    );
+    lines.push(...entries);
+    lines.push(`]);`);
+    lines.push("");
+  }
+  const rootTypeName = result.rootTypeName;
+  const rootConstVarName = `${rootTypeName}_FromConfig`;
+  usedImports.add("_applyConfig");
+  usedTypeImports.add("_ConfigApplicationContext");
+  lines.push(
+    `export function transform${rootTypeName}(raw: unknown, appCtx?: _ConfigApplicationContext): ${rootTypeName} {`
+  );
+  lines.push(`  return _applyConfig(${rootConstVarName}, raw, appCtx);`);
+  lines.push(`}`);
+  return { lines, requiredImports: usedImports, requiredTypeImports: usedTypeImports };
+}
+function wrapConfigTransform(expr, isOptional, usedImports) {
+  if (isOptional) return expr;
+  if (expr === "_identity") {
+    usedImports.add("_required");
+    return "_required()";
+  }
+  usedImports.add("_required");
+  return `_required(${expr})`;
+}
+function fieldTransformExpr(classification, usedImports) {
+  switch (classification.kind) {
+    case "primitive": {
+      usedImports.add("_identity");
+      return "_identity";
+    }
+    case "decimal": {
+      usedImports.add("_translateDecimal");
+      return "_translateDecimal";
+    }
+    case "datetime": {
+      usedImports.add("_translateDateTime");
+      return "_translateDateTime";
+    }
+    case "enum": {
+      usedImports.add("_translateEnum");
+      return `_translateEnum(${classification.typeName}_ConfigValues)`;
+    }
+    case "array": {
+      usedImports.add("_translateArray");
+      const elemExpr = fieldTransformExpr(classification.element, usedImports);
+      return `_translateArray(${elemExpr})`;
+    }
+    case "map": {
+      usedImports.add("_translateMap");
+      usedImports.add("_identity");
+      const valueExpr = fieldTransformExpr(classification.value, usedImports);
+      return `_translateMap(_identity, ${valueExpr})`;
+    }
+    case "interface": {
+      usedImports.add("_translateShape");
+      const { typeName } = classification;
+      return `_translateShape(() => ${typeName}_FromConfig)`;
+    }
+    case "union":
+      throw new Error(`union types are not supported in config field descriptors`);
+    default: {
+      const _exhaustive = classification;
+      return _exhaustive;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  STDLIB_IMPORT_PATH,
+  analyzeConfigType,
+  analyzeConfigTypeInProject,
+  generateConfigDescriptor
+});

package/dist/config-values/generate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Emits TypeScript code for a config field descriptor constant and its
+ * corresponding `transformX` function.
+ *
+ * @see ./parse.ts — produces the ConfigAnalysisResult input
+ */
+import type { ConfigAnalysisResult } from './parse.js';
+export { analyzeConfigType, analyzeConfigTypeInProject, type ConfigAnalysisResult, type ConfigField, type ConfigInterfaceDescriptor, type ConfigEnumDescriptor, type FieldClassification, type ScalarFieldClassification, type StructuralFieldClassification, } from './parse.js';
+/**
+ * The package specifier for the stdlib module used in generated import lines.
+ *
+ * @internal
+ */
+export declare const STDLIB_IMPORT_PATH = "@stripe/extensibility-sdk/stdlib";
+/**
+ * Generated TypeScript source and imports for a config descriptor.
+ *
+ * @internal
+ */
+export interface GeneratedConfigDescriptor {
+    /** TypeScript code lines for the descriptor constant(s) and transform function */
+    lines: string[];
+    /** Value symbol names required from the stdlib module */
+    requiredImports: ReadonlySet<string>;
+    /** Type-only symbol names required from the stdlib module */
+    requiredTypeImports: ReadonlySet<string>;
+}
+/**
+ * Generates TypeScript code for a config descriptor.
+ *
+ * Emits enum value constants first, then one `_ShapeDescriptor` constant per
+ * interface (in DFS post-order, so inner types appear before their references),
+ * followed by an exported `transformX(raw: unknown): X` function.
+ *
+ * @internal
+ */
+export declare function generateConfigDescriptor(result: ConfigAnalysisResult): GeneratedConfigDescriptor;
+//# sourceMappingURL=generate.d.ts.map

package/dist/config-values/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/config-values/generate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAuB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAMpB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,6DAA6D;IAC7D,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,oBAAoB,GAC3B,yBAAyB,CA8C3B"}

package/dist/config-values/generate.js

@@ -0,0 +1,232 @@
+// src/config-values/parse.ts
+import { Node, Project } from "ts-morph";
+function analyzeConfigType(options) {
+  const project = new Project({
+    compilerOptions: { strict: true, skipLibCheck: true },
+    skipAddingFilesFromTsConfig: true
+  });
+  project.addSourceFileAtPath(options.filePath);
+  project.resolveSourceFileDependencies();
+  return analyzeConfigTypeInProject(project, options.filePath, options.typeName);
+}
+function analyzeConfigTypeInProject(project, filePath, typeName) {
+  const sourceFile = project.getSourceFileOrThrow(filePath);
+  const target = sourceFile.getInterface(typeName) ?? sourceFile.getTypeAlias(typeName) ?? sourceFile.getClass(typeName);
+  if (!target) {
+    throw new Error(`Type "${typeName}" not found in "${filePath}"`);
+  }
+  const state = { interfaces: [], enums: [] };
+  const type = target.getType();
+  const fields = walkObjectType(type, typeName, state);
+  state.interfaces.push({ name: typeName, fields });
+  return { rootTypeName: typeName, interfaces: state.interfaces, enums: state.enums };
+}
+function walkObjectType(type, context, state) {
+  const fields = [];
+  for (const sym of type.getProperties()) {
+    const decl = sym.getValueDeclaration();
+    if (!decl || !Node.isPropertySignature(decl) && !Node.isPropertyDeclaration(decl))
+      continue;
+    const hasQuestionMark = decl.hasQuestionToken();
+    const rawType = decl.getType();
+    const { classification, optional } = classifyType(
+      rawType,
+      `${context}.${sym.getName()}`,
+      state
+    );
+    fields.push({
+      name: sym.getName(),
+      classification,
+      optional: optional || hasQuestionMark
+    });
+  }
+  return fields;
+}
+function classifyType(type, context, state) {
+  if (type.isUnion()) {
+    const members = type.getUnionTypes();
+    const hasNullable = members.some((m) => m.isUndefined() || m.isNull());
+    const nonNullable = members.filter((m) => !m.isUndefined() && !m.isNull());
+    if (nonNullable.length === 0) {
+      throw new Error(
+        `${context}: Type is only null/undefined, which is not a valid config type`
+      );
+    }
+    if (nonNullable.every((m) => m.isBooleanLiteral())) {
+      return { classification: { kind: "primitive" }, optional: hasNullable };
+    }
+    if (nonNullable.every((m) => m.isStringLiteral())) {
+      const aliasSymbol = type.getAliasSymbol();
+      const typeName = aliasSymbol ? aliasSymbol.getName() : context.replace(/\./g, "_");
+      if (!state.enums.some((e) => e.name === typeName)) {
+        const values = nonNullable.map((m) => m.getLiteralValue());
+        state.enums.push({ name: typeName, values });
+      }
+      return { classification: { kind: "enum", typeName }, optional: hasNullable };
+    }
+    if (nonNullable.length === 1) {
+      const [sole] = nonNullable;
+      if (sole) {
+        const { classification } = classifyType(sole, context, state);
+        return { classification, optional: hasNullable };
+      }
+    }
+    throw new Error(
+      `${context}: Union types are not supported in config types (only T | undefined or T | null is allowed)`
+    );
+  }
+  if (type.isStringLiteral()) {
+    const value = type.getLiteralValue();
+    const typeName = context.replace(/\./g, "_");
+    if (!state.enums.some((e) => e.name === typeName)) {
+      state.enums.push({ name: typeName, values: [value] });
+    }
+    return { classification: { kind: "enum", typeName }, optional: false };
+  }
+  if (isStdlibDecimalType(type)) {
+    return { classification: { kind: "decimal" }, optional: false };
+  }
+  const dateSym = type.getSymbol();
+  if (dateSym?.getName() === "Date") {
+    const srcPath = dateSym.getDeclarations()[0]?.getSourceFile().getFilePath() ?? "";
+    const basename = srcPath.slice(srcPath.lastIndexOf("/") + 1);
+    if (basename.startsWith("lib.") && basename.endsWith(".d.ts")) {
+      return { classification: { kind: "datetime" }, optional: false };
+    }
+  }
+  if (type.isString()) return { classification: { kind: "primitive" }, optional: false };
+  if (type.isNumber()) return { classification: { kind: "primitive" }, optional: false };
+  if (type.isBoolean()) return { classification: { kind: "primitive" }, optional: false };
+  if (type.isArray()) {
+    const elementType = type.getArrayElementTypeOrThrow();
+    const { classification: element } = classifyType(elementType, `${context}[]`, state);
+    return { classification: { kind: "array", element }, optional: false };
+  }
+  const stringIndexType = type.getStringIndexType();
+  if (stringIndexType) {
+    const { classification: value } = classifyType(
+      stringIndexType,
+      `${context}[string]`,
+      state
+    );
+    return { classification: { kind: "map", value }, optional: false };
+  }
+  if (type.isObject()) {
+    const typeSym = type.getSymbol();
+    const symName = typeSym?.getName();
+    const typeName = symName && !symName.startsWith("__") ? symName : context.replace(/\./g, "_");
+    if (!state.interfaces.some((i) => i.name === typeName)) {
+      const shapeFields = walkObjectType(type, typeName, state);
+      state.interfaces.push({ name: typeName, fields: shapeFields });
+    }
+    return { classification: { kind: "interface", typeName }, optional: false };
+  }
+  throw new Error(`${context}: Unsupported config field type: ${type.getText()}`);
+}
+function isStdlibDecimalType(type) {
+  return [type.getAliasSymbol(), type.getSymbol()].some((symbol) => {
+    if (symbol?.getName() !== "Decimal") return false;
+    return symbol.getDeclarations().some((declaration) => {
+      const srcPath = declaration.getSourceFile().getFilePath();
+      return srcPath.includes("stdlib/decimal") || srcPath.includes("stdlib/index");
+    });
+  });
+}
+
+// src/config-values/generate.ts
+var STDLIB_IMPORT_PATH = "@stripe/extensibility-sdk/stdlib";
+function generateConfigDescriptor(result) {
+  const usedImports = /* @__PURE__ */ new Set();
+  const usedTypeImports = /* @__PURE__ */ new Set();
+  const lines = [];
+  if (result.enums.length > 0) usedImports.add("_ConfigEnum");
+  for (const enumDesc of result.enums) {
+    const values = enumDesc.values.map((v) => JSON.stringify(v)).join(", ");
+    lines.push(`const ${enumDesc.name}_ConfigValues = new _ConfigEnum([${values}]);`);
+    lines.push("");
+  }
+  usedImports.add("_ShapeDescriptor");
+  usedImports.add("_JsonWireToType");
+  for (const iface of result.interfaces) {
+    const constVarName = `${iface.name}_FromConfig`;
+    const entries = [];
+    for (const field of iface.fields) {
+      const inner = fieldTransformExpr(field.classification, usedImports);
+      const transform = wrapConfigTransform(inner, field.optional, usedImports);
+      entries.push(`  { type: ${JSON.stringify(field.name)}, transform: ${transform} },`);
+    }
+    lines.push(
+      `const ${constVarName} = new _ShapeDescriptor<typeof _JsonWireToType, ${iface.name}>(${JSON.stringify(iface.name)}, [`
+    );
+    lines.push(...entries);
+    lines.push(`]);`);
+    lines.push("");
+  }
+  const rootTypeName = result.rootTypeName;
+  const rootConstVarName = `${rootTypeName}_FromConfig`;
+  usedImports.add("_applyConfig");
+  usedTypeImports.add("_ConfigApplicationContext");
+  lines.push(
+    `export function transform${rootTypeName}(raw: unknown, appCtx?: _ConfigApplicationContext): ${rootTypeName} {`
+  );
+  lines.push(`  return _applyConfig(${rootConstVarName}, raw, appCtx);`);
+  lines.push(`}`);
+  return { lines, requiredImports: usedImports, requiredTypeImports: usedTypeImports };
+}
+function wrapConfigTransform(expr, isOptional, usedImports) {
+  if (isOptional) return expr;
+  if (expr === "_identity") {
+    usedImports.add("_required");
+    return "_required()";
+  }
+  usedImports.add("_required");
+  return `_required(${expr})`;
+}
+function fieldTransformExpr(classification, usedImports) {
+  switch (classification.kind) {
+    case "primitive": {
+      usedImports.add("_identity");
+      return "_identity";
+    }
+    case "decimal": {
+      usedImports.add("_translateDecimal");
+      return "_translateDecimal";
+    }
+    case "datetime": {
+      usedImports.add("_translateDateTime");
+      return "_translateDateTime";
+    }
+    case "enum": {
+      usedImports.add("_translateEnum");
+      return `_translateEnum(${classification.typeName}_ConfigValues)`;
+    }
+    case "array": {
+      usedImports.add("_translateArray");
+      const elemExpr = fieldTransformExpr(classification.element, usedImports);
+      return `_translateArray(${elemExpr})`;
+    }
+    case "map": {
+      usedImports.add("_translateMap");
+      usedImports.add("_identity");
+      const valueExpr = fieldTransformExpr(classification.value, usedImports);
+      return `_translateMap(_identity, ${valueExpr})`;
+    }
+    case "interface": {
+      usedImports.add("_translateShape");
+      const { typeName } = classification;
+      return `_translateShape(() => ${typeName}_FromConfig)`;
+    }
+    case "union":
+      throw new Error(`union types are not supported in config field descriptors`);
+    default: {
+      const _exhaustive = classification;
+      return _exhaustive;
+    }
+  }
+}
+export {
+  STDLIB_IMPORT_PATH,
+  analyzeConfigType,
+  analyzeConfigTypeInProject,
+  generateConfigDescriptor
+};

package/dist/config-values/parse.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Analyzes a config type using ts-morph and produces a field classification
+ * descriptor for runtime transformer generation.
+ *
+ * @see ./generate.ts — converts the descriptor to TypeScript code
+ */
+import type { Project as MorphProject } from 'ts-morph';
+/** @internal */
+export type ScalarFieldClassification = {
+    kind: 'primitive';
+} | {
+    kind: 'decimal';
+} | {
+    kind: 'datetime';
+} | {
+    kind: 'enum';
+    typeName: string;
+};
+/** @internal */
+export type StructuralFieldClassification = {
+    kind: 'interface';
+    typeName: string;
+} | {
+    kind: 'union';
+    typeName: string;
+} | {
+    kind: 'array';
+    element: FieldClassification;
+} | {
+    kind: 'map';
+    value: FieldClassification;
+};
+/** @internal */
+export type FieldClassification = ScalarFieldClassification | StructuralFieldClassification;
+/** @internal */
+export interface ConfigField {
+    name: string;
+    classification: FieldClassification;
+    optional: boolean;
+}
+/** @internal */
+export interface ConfigInterfaceDescriptor {
+    name: string;
+    fields: ConfigField[];
+}
+/** @internal */
+export interface ConfigEnumDescriptor {
+    name: string;
+    values: readonly string[];
+}
+/**
+ * The result of analyzing a config type.
+ *
+ * `interfaces` is in DFS post-order: inner types appear before the types that
+ * reference them, so the root type is always last.
+ * `enums` is in discovery order, deduplicated by name.
+ * @internal
+ */
+export interface ConfigAnalysisResult {
+    rootTypeName: string;
+    interfaces: ConfigInterfaceDescriptor[];
+    enums: ConfigEnumDescriptor[];
+}
+/**
+ * Analyzes a named config type in a source file, producing a descriptor
+ * for runtime transformation.
+ *
+ * Creates a ts-morph Project from the file system. For testing with
+ * in-memory files, use `analyzeConfigTypeInProject` directly.
+ * @internal
+ */
+export declare function analyzeConfigType(options: {
+    filePath: string;
+    typeName: string;
+}): ConfigAnalysisResult;
+/**
+ * Analyzes a named config type using a caller-supplied ts-morph Project.
+ * Use this in tests to pass an in-memory project.
+ * @internal
+ */
+export declare function analyzeConfigTypeInProject(project: MorphProject, filePath: string, typeName: string): ConfigAnalysisResult;
+/** @internal */
+export interface AccumulatorState {
+    interfaces: ConfigInterfaceDescriptor[];
+    enums: ConfigEnumDescriptor[];
+}
+//# sourceMappingURL=parse.d.ts.map

package/dist/config-values/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/config-values/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAQ,OAAO,IAAI,YAAY,EAAE,MAAM,UAAU,CAAC;AAM9D,gBAAgB;AAChB,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,gBAAgB;AAChB,MAAM,MAAM,6BAA6B,GACrC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEhD,gBAAgB;AAChB,MAAM,MAAM,mBAAmB,GAC3B,yBAAyB,GACzB,6BAA6B,CAAC;AAMlC,gBAAgB;AAChB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,mBAAmB,CAAC;IACpC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,gBAAgB;AAChB,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,yBAAyB,EAAE,CAAC;IACxC,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,oBAAoB,CAQvB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,oBAAoB,CAiBtB;AAMD,gBAAgB;AAChB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,yBAAyB,EAAE,CAAC;IACxC,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B"}