@soda-gql/common 0.14.0 → 0.14.2

package/dist/template-extraction.d.cts

@@ -9,19 +9,30 @@ import { ArrowFunctionExpression, CallExpression, Node, TaggedTemplateExpression
  */
 /** Operation kind extracted from tagged template tag name. */
 type OperationKind = "query" | "mutation" | "subscription" | "fragment";
-/** A single tagged template extracted from a TypeScript source file. */
+/** A single template extracted from a TypeScript source file. */
 type ExtractedTemplate = {
   /** Resolved schema name from gql.{schemaName}. */
   readonly schemaName: string;
   /** Operation kind from tag name. */
   readonly kind: OperationKind;
-  /** Raw GraphQL content between backticks (may contain __FRAG_SPREAD_N__ placeholders). */
+  /**
+   * Raw content extracted from template.
+   * For tagged templates: GraphQL body (e.g., "{ user { id } }").
+   * For callback-variables: variable definition string (e.g., "($id: ID!)").
+   * When source is "callback-variables", content is NOT standalone valid GraphQL —
+   * consumers must wrap it in a dummy operation before parsing.
+   */
   readonly content: string;
   /** Element name from curried tag call (e.g., "GetUser" from query("GetUser")). */
   readonly elementName?: string;
   /** Type name from curried fragment call (e.g., "User" from fragment("UserFields", "User")). */
   readonly typeName?: string;
-  /** Character offset range of GraphQL content within TS source (excludes backticks). */
+  /** Character offset range of typeName within TS source (excludes quotes). */
+  readonly typeNameSpan?: {
+    readonly start: number;
+    readonly end: number;
+  };
+  /** Character offset range of content within TS source (excludes backticks/quotes). */
   readonly contentRange?: {
     readonly start: number;
     readonly end: number;
@@ -31,6 +42,11 @@ type ExtractedTemplate = {
     readonly start: number;
     readonly end: number;
   }[];
+  /**
+   * Extraction source discriminator. Undefined for tagged template (default).
+   * "callback-variables" for variables property extracted from callback builder options object.
+   */
+  readonly source?: "tagged-template" | "callback-variables";
 };
 /** ExtractedTemplate with guaranteed position information (when positionCtx is provided). */
 type ExtractedTemplateWithPosition = ExtractedTemplate & {
@@ -45,9 +61,61 @@ type TemplateFormatEdit = {
   readonly end: number;
   readonly newText: string;
 };
+/**
+ * A single f("fieldName") call in a callback builder field selection.
+ * Schema-independent — extracted purely from SWC AST.
+ */
+type FieldCallNode = {
+  readonly fieldName: string;
+  readonly fieldNameSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly callSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly nested: FieldCallNested | null;
+};
+type FieldCallNested = {
+  readonly kind: "object";
+  readonly span: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly children: readonly FieldCallNode[];
+} | {
+  readonly kind: "union";
+  readonly span: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly branches: readonly UnionBranchNode[];
+};
+type UnionBranchNode = {
+  readonly typeName: string;
+  readonly typeNameSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly branchSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly children: readonly FieldCallNode[];
+};
+type ExtractedFieldTree = {
+  readonly schemaName: string;
+  readonly kind: OperationKind;
+  readonly elementName?: string;
+  readonly rootSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly children: readonly FieldCallNode[];
+};
 //#endregion
 //#region packages/common/src/template-extraction/extract.d.ts
-
 declare const OPERATION_KINDS: Set<string>;
 declare const isOperationKind: (value: string) => value is OperationKind;
 /** Optional position tracking context for extraction. */
@@ -60,9 +128,18 @@ type PositionTrackingContext = {
  * Returns the schema name if it is, null otherwise.
  */
 declare const getGqlCallSchemaName: (identifiers: ReadonlySet<string>, call: CallExpression) => string | null;
+/**
+ * Extract variables template from a callback builder options object.
+ * Handles patterns like:
+ * - `query("Name")({ variables: \`($id: ID!)\`, fields: ... })({})`
+ * - `query("Name")({ variables: "($id: ID!)", fields: ... })`
+ *
+ * Returns true if a callback builder pattern was detected (even if no variables property found).
+ */
+declare const extractVariablesFromCallbackBuilder: (expr: Node, schemaName: string, templates: ExtractedTemplate[], positionCtx?: PositionTrackingContext) => boolean;
 /**
  * Extract templates from a gql callback's arrow function body.
- * Handles both expression bodies and block bodies with return statements.
+ * Handles tagged templates, metadata chaining, and callback builder variables.
  */
 declare const extractTemplatesFromCallback: (arrow: ArrowFunctionExpression, schemaName: string, positionCtx?: PositionTrackingContext) => ExtractedTemplate[];
 /**
@@ -79,6 +156,24 @@ declare const findGqlCall: (identifiers: ReadonlySet<string>, node: Node) => Cal
  */
 declare function walkAndExtract(node: Node, identifiers: ReadonlySet<string>, positionCtx: PositionTrackingContext): ExtractedTemplateWithPosition[];
 declare function walkAndExtract(node: Node, identifiers: ReadonlySet<string>, positionCtx?: PositionTrackingContext): ExtractedTemplate[];
+/**
+ * Walk AST to find gql callback builder calls and extract field call trees.
+ * Companion to walkAndExtract — collects ExtractedFieldTree instead of ExtractedTemplate.
+ */
+declare const walkAndExtractFieldTrees: (node: Node, identifiers: ReadonlySet<string>, positionCtx?: PositionTrackingContext) => ExtractedFieldTree[];
+/**
+ * Extract a field call tree from a callback builder expression.
+ *
+ * Expects a top-level expression of the callback builder pattern:
+ *   `query("Name")({ fields: ({ f }) => ({ ...f("id")(), ...f("name")() }) })({})`
+ *
+ * Returns an `ExtractedFieldTree` describing the root children (fields on the root selection set),
+ * or `null` if the expression is not a callback builder or has no `fields` property.
+ *
+ * The `positionCtx` is optional — when provided, all span values will be character offsets
+ * in the original TypeScript source. When omitted, spans are raw SWC byte positions.
+ */
+declare const extractFieldCallTree: (expr: Node, schemaName: string, positionCtx?: PositionTrackingContext) => ExtractedFieldTree | null;
 //#endregion
 //#region packages/common/src/template-extraction/format.d.ts
 /** A function that formats GraphQL source text. */
@@ -140,5 +235,5 @@ declare const unwrapFormattedContent: (formatted: string, prefixPattern: RegExp
  */
 declare const formatTemplatesInSource: (templates: readonly ExtractedTemplate[], tsSource: string, formatGraphql: FormatGraphqlFn) => readonly TemplateFormatEdit[];
 //#endregion
-export { ExtractedTemplate, ExtractedTemplateWithPosition, FormatGraphqlFn, OPERATION_KINDS, OperationKind, PositionTrackingContext, TemplateFormatEdit, buildGraphqlWrapper, detectBaseIndent, detectIndentUnit, extractFromTaggedTemplate, extractTemplatesFromCallback, findGqlCall, formatTemplatesInSource, getGqlCallSchemaName, isOperationKind, reindent, unwrapFormattedContent, walkAndExtract };
+export { ExtractedFieldTree, ExtractedTemplate, ExtractedTemplateWithPosition, FieldCallNested, FieldCallNode, FormatGraphqlFn, OPERATION_KINDS, OperationKind, PositionTrackingContext, TemplateFormatEdit, UnionBranchNode, buildGraphqlWrapper, detectBaseIndent, detectIndentUnit, extractFieldCallTree, extractFromTaggedTemplate, extractTemplatesFromCallback, extractVariablesFromCallbackBuilder, findGqlCall, formatTemplatesInSource, getGqlCallSchemaName, isOperationKind, reindent, unwrapFormattedContent, walkAndExtract, walkAndExtractFieldTrees };
 //# sourceMappingURL=template-extraction.d.cts.map

package/dist/template-extraction.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"template-extraction.d.cts","names":[],"sources":["../src/template-extraction/types.ts","../src/template-extraction/extract.ts","../src/template-extraction/format.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAMA;AAGY,KAHA,aAAA,GAGiB,OAAA,GAIZ,UAAA,GAAa,cAAA,GAAA,UAAA;AAc9B;AAKY,KAvBA,iBAAA,GAuBkB;;;;ECfjB,SAAA,IAAA,EDJI,aCIgF;EAEpF;EAGD,SAAA,OAAA,EAAA,MAAA;EASC;EA2BA,SAAA,WAAA,CAAA,EAAA,MAAA;EACJ;EAEO,SAAA,QAAA,CAAA,EAAA,MAAA;EACb;EAAiB,SAAA,YAAA,CAAA,EAAA;IAwCP,SAAA,KAAA,EAAA,MAAA;IACH,SAAA,GAAA,EAAA,MAAA;EAEG,CAAA;EACG;EAAuB,SAAA,gBAAA,CAAA,EAAA,SAAA;IA+F1B,SAAA,KAgBZ,EAAA,MAAA;IAhBwC,SAAA,GAAA,EAAA,MAAA;EAA2B,CAAA,EAAA;CAAO;;AAqB3D,KDnMJ,6BAAA,GAAgC,iBCmMd,GAAA;EACtB,SAAA,YAAA,EAAA;IACO,SAAA,KAAA,EAAA,MAAA;IACA,SAAA,GAAA,EAAA,MAAA;EACZ,CAAA;CAA6B;AAChC;AACQ,KDpMI,kBAAA,GCoMJ;EACO,SAAA,KAAA,EAAA,MAAA;EACC,SAAA,GAAA,EAAA,MAAA;EACb,SAAA,OAAA,EAAA,MAAA;CAAiB;;;;AAxMP,cAdA,eAmCZ,EAnC2B,GAcsB,CAAA,MAAA,CAAA;AA2BrC,cAvCA,eA6EZ,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,KAAA,IA7EwD,aA6ExD;;AAnCe,KAvCJ,uBAAA,GAuCI;EACb,SAAA,UAAA,EAAA,MAAA;EAAiB,SAAA,SAAA,EAtCE,gBAsCF;AAwCpB,CAAA;;;;;AAmGa,cA1KA,oBA0LZ,EAAA,CAAA,WAAA,EA1LiD,WA0LjD,CAAA,MAAA,CAAA,EAAA,IAAA,EA1L4E,cA0L5E,EAAA,GAAA,MAAA,GAAA,IAAA;;;;;AAKe,cApKH,4BAoKiB,EAAA,CAAA,KAAA,EAnKrB,uBAmKqB,EAAA,UAAA,EAAA,MAAA,EAAA,WAAA,CAAA,EAjKd,uBAiKc,EAAA,GAhK3B,iBAgK2B,EAAA;;;;;AAIE,cA5HnB,yBA4HmB,EAAA,CAAA,MAAA,EA3HtB,wBA2HsB,EAAA,UAAA,EAAA,MAAA,EAAA,SAAA,EAzHnB,iBAyHmB,EAAA,EAAA,WAAA,CAAA,EAxHhB,uBAwHgB,EAAA,GAAA,IAAA;AAChC;;;AAGgB,cA7BH,WA6BG,EAAA,CAAA,WAAA,EA7ByB,WA6BzB,CAAA,MAAA,CAAA,EAAA,IAAA,EA7BoD,IA6BpD,EAAA,GA7B2D,cA6B3D,GAAA,IAAA;;;;iBARA,cAAA,OACR,mBACO,kCACA,0BACZ;iBACa,cAAA,OACR,mBACO,mCACC,0BACb;;;;KC3NS,eAAA;ADKZ;AAEA;AAGA;AASA;AA2Ba,cCxCA,gBD8EZ,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,kBAAA,EAAA,MAAA,EAAA,GAAA,MAAA;;;;;AAMD;;;;;AAmGA;;AAAoE,cC5IvD,QD4IuD,EAAA,CAAA,SAAA,EAAA,MAAA,EAAA,UAAA,EAAA,MAAA,EAAA,eAAA,EAAA,MAAA,EAAA,UAAA,CAAA,EAAA,MAAA,EAAA,GAAA,MAAA;;;AAqBpE;;;;;;AAKgB,cCtHH,gBDsHiB,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,GAAA,MAAA;;;;;;;;;ACvN9B;AAMA;AA2Ca,cAwEA,mBAlCZ,EAAA,CAAA,QAAA,EAkC6C,iBAlC7C,EAAA,GAAA;EAUY,OAAA,EAAA,MAAA;EAwBA,aAAA,EAAuF,MAAvF,GAyBZ,IAAA;AAOD,CAAA;AAgBA;;;;;cAhBa,2DAA4D;;;;;;;;;;cAgB5D,8CACS,sDAEL,6BACL"}
+{"version":3,"file":"template-extraction.d.cts","names":[],"sources":["../src/template-extraction/types.ts","../src/template-extraction/extract.ts","../src/template-extraction/format.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/template-extraction.d.mts

@@ -9,19 +9,30 @@ import { ArrowFunctionExpression, CallExpression, Node, TaggedTemplateExpression
  */
 /** Operation kind extracted from tagged template tag name. */
 type OperationKind = "query" | "mutation" | "subscription" | "fragment";
-/** A single tagged template extracted from a TypeScript source file. */
+/** A single template extracted from a TypeScript source file. */
 type ExtractedTemplate = {
   /** Resolved schema name from gql.{schemaName}. */
   readonly schemaName: string;
   /** Operation kind from tag name. */
   readonly kind: OperationKind;
-  /** Raw GraphQL content between backticks (may contain __FRAG_SPREAD_N__ placeholders). */
+  /**
+   * Raw content extracted from template.
+   * For tagged templates: GraphQL body (e.g., "{ user { id } }").
+   * For callback-variables: variable definition string (e.g., "($id: ID!)").
+   * When source is "callback-variables", content is NOT standalone valid GraphQL —
+   * consumers must wrap it in a dummy operation before parsing.
+   */
   readonly content: string;
   /** Element name from curried tag call (e.g., "GetUser" from query("GetUser")). */
   readonly elementName?: string;
   /** Type name from curried fragment call (e.g., "User" from fragment("UserFields", "User")). */
   readonly typeName?: string;
-  /** Character offset range of GraphQL content within TS source (excludes backticks). */
+  /** Character offset range of typeName within TS source (excludes quotes). */
+  readonly typeNameSpan?: {
+    readonly start: number;
+    readonly end: number;
+  };
+  /** Character offset range of content within TS source (excludes backticks/quotes). */
   readonly contentRange?: {
     readonly start: number;
     readonly end: number;
@@ -31,6 +42,11 @@ type ExtractedTemplate = {
     readonly start: number;
     readonly end: number;
   }[];
+  /**
+   * Extraction source discriminator. Undefined for tagged template (default).
+   * "callback-variables" for variables property extracted from callback builder options object.
+   */
+  readonly source?: "tagged-template" | "callback-variables";
 };
 /** ExtractedTemplate with guaranteed position information (when positionCtx is provided). */
 type ExtractedTemplateWithPosition = ExtractedTemplate & {
@@ -45,9 +61,61 @@ type TemplateFormatEdit = {
   readonly end: number;
   readonly newText: string;
 };
+/**
+ * A single f("fieldName") call in a callback builder field selection.
+ * Schema-independent — extracted purely from SWC AST.
+ */
+type FieldCallNode = {
+  readonly fieldName: string;
+  readonly fieldNameSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly callSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly nested: FieldCallNested | null;
+};
+type FieldCallNested = {
+  readonly kind: "object";
+  readonly span: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly children: readonly FieldCallNode[];
+} | {
+  readonly kind: "union";
+  readonly span: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly branches: readonly UnionBranchNode[];
+};
+type UnionBranchNode = {
+  readonly typeName: string;
+  readonly typeNameSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly branchSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly children: readonly FieldCallNode[];
+};
+type ExtractedFieldTree = {
+  readonly schemaName: string;
+  readonly kind: OperationKind;
+  readonly elementName?: string;
+  readonly rootSpan: {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly children: readonly FieldCallNode[];
+};
 //#endregion
 //#region packages/common/src/template-extraction/extract.d.ts
-
 declare const OPERATION_KINDS: Set<string>;
 declare const isOperationKind: (value: string) => value is OperationKind;
 /** Optional position tracking context for extraction. */
@@ -60,9 +128,18 @@ type PositionTrackingContext = {
  * Returns the schema name if it is, null otherwise.
  */
 declare const getGqlCallSchemaName: (identifiers: ReadonlySet<string>, call: CallExpression) => string | null;
+/**
+ * Extract variables template from a callback builder options object.
+ * Handles patterns like:
+ * - `query("Name")({ variables: \`($id: ID!)\`, fields: ... })({})`
+ * - `query("Name")({ variables: "($id: ID!)", fields: ... })`
+ *
+ * Returns true if a callback builder pattern was detected (even if no variables property found).
+ */
+declare const extractVariablesFromCallbackBuilder: (expr: Node, schemaName: string, templates: ExtractedTemplate[], positionCtx?: PositionTrackingContext) => boolean;
 /**
  * Extract templates from a gql callback's arrow function body.
- * Handles both expression bodies and block bodies with return statements.
+ * Handles tagged templates, metadata chaining, and callback builder variables.
  */
 declare const extractTemplatesFromCallback: (arrow: ArrowFunctionExpression, schemaName: string, positionCtx?: PositionTrackingContext) => ExtractedTemplate[];
 /**
@@ -79,6 +156,24 @@ declare const findGqlCall: (identifiers: ReadonlySet<string>, node: Node) => Cal
  */
 declare function walkAndExtract(node: Node, identifiers: ReadonlySet<string>, positionCtx: PositionTrackingContext): ExtractedTemplateWithPosition[];
 declare function walkAndExtract(node: Node, identifiers: ReadonlySet<string>, positionCtx?: PositionTrackingContext): ExtractedTemplate[];
+/**
+ * Walk AST to find gql callback builder calls and extract field call trees.
+ * Companion to walkAndExtract — collects ExtractedFieldTree instead of ExtractedTemplate.
+ */
+declare const walkAndExtractFieldTrees: (node: Node, identifiers: ReadonlySet<string>, positionCtx?: PositionTrackingContext) => ExtractedFieldTree[];
+/**
+ * Extract a field call tree from a callback builder expression.
+ *
+ * Expects a top-level expression of the callback builder pattern:
+ *   `query("Name")({ fields: ({ f }) => ({ ...f("id")(), ...f("name")() }) })({})`
+ *
+ * Returns an `ExtractedFieldTree` describing the root children (fields on the root selection set),
+ * or `null` if the expression is not a callback builder or has no `fields` property.
+ *
+ * The `positionCtx` is optional — when provided, all span values will be character offsets
+ * in the original TypeScript source. When omitted, spans are raw SWC byte positions.
+ */
+declare const extractFieldCallTree: (expr: Node, schemaName: string, positionCtx?: PositionTrackingContext) => ExtractedFieldTree | null;
 //#endregion
 //#region packages/common/src/template-extraction/format.d.ts
 /** A function that formats GraphQL source text. */
@@ -140,5 +235,5 @@ declare const unwrapFormattedContent: (formatted: string, prefixPattern: RegExp
  */
 declare const formatTemplatesInSource: (templates: readonly ExtractedTemplate[], tsSource: string, formatGraphql: FormatGraphqlFn) => readonly TemplateFormatEdit[];
 //#endregion
-export { ExtractedTemplate, ExtractedTemplateWithPosition, FormatGraphqlFn, OPERATION_KINDS, OperationKind, PositionTrackingContext, TemplateFormatEdit, buildGraphqlWrapper, detectBaseIndent, detectIndentUnit, extractFromTaggedTemplate, extractTemplatesFromCallback, findGqlCall, formatTemplatesInSource, getGqlCallSchemaName, isOperationKind, reindent, unwrapFormattedContent, walkAndExtract };
+export { ExtractedFieldTree, ExtractedTemplate, ExtractedTemplateWithPosition, FieldCallNested, FieldCallNode, FormatGraphqlFn, OPERATION_KINDS, OperationKind, PositionTrackingContext, TemplateFormatEdit, UnionBranchNode, buildGraphqlWrapper, detectBaseIndent, detectIndentUnit, extractFieldCallTree, extractFromTaggedTemplate, extractTemplatesFromCallback, extractVariablesFromCallbackBuilder, findGqlCall, formatTemplatesInSource, getGqlCallSchemaName, isOperationKind, reindent, unwrapFormattedContent, walkAndExtract, walkAndExtractFieldTrees };
 //# sourceMappingURL=template-extraction.d.mts.map

package/dist/template-extraction.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"template-extraction.d.mts","names":[],"sources":["../src/template-extraction/types.ts","../src/template-extraction/extract.ts","../src/template-extraction/format.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAMA;AAGY,KAHA,aAAA,GAGiB,OAAA,GAIZ,UAAA,GAAa,cAAA,GAAA,UAAA;AAc9B;AAKY,KAvBA,iBAAA,GAuBkB;;;;ECfjB,SAAA,IAAA,EDJI,aCIgF;EAEpF;EAGD,SAAA,OAAA,EAAA,MAAA;EASC;EA2BA,SAAA,WAAA,CAAA,EAAA,MAAA;EACJ;EAEO,SAAA,QAAA,CAAA,EAAA,MAAA;EACb;EAAiB,SAAA,YAAA,CAAA,EAAA;IAwCP,SAAA,KAAA,EAAA,MAAA;IACH,SAAA,GAAA,EAAA,MAAA;EAEG,CAAA;EACG;EAAuB,SAAA,gBAAA,CAAA,EAAA,SAAA;IA+F1B,SAAA,KAgBZ,EAAA,MAAA;IAhBwC,SAAA,GAAA,EAAA,MAAA;EAA2B,CAAA,EAAA;CAAO;;AAqB3D,KDnMJ,6BAAA,GAAgC,iBCmMd,GAAA;EACtB,SAAA,YAAA,EAAA;IACO,SAAA,KAAA,EAAA,MAAA;IACA,SAAA,GAAA,EAAA,MAAA;EACZ,CAAA;CAA6B;AAChC;AACQ,KDpMI,kBAAA,GCoMJ;EACO,SAAA,KAAA,EAAA,MAAA;EACC,SAAA,GAAA,EAAA,MAAA;EACb,SAAA,OAAA,EAAA,MAAA;CAAiB;;;;AAxMP,cAdA,eAmCZ,EAnC2B,GAcsB,CAAA,MAAA,CAAA;AA2BrC,cAvCA,eA6EZ,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,KAAA,IA7EwD,aA6ExD;;AAnCe,KAvCJ,uBAAA,GAuCI;EACb,SAAA,UAAA,EAAA,MAAA;EAAiB,SAAA,SAAA,EAtCE,gBAsCF;AAwCpB,CAAA;;;;;AAmGa,cA1KA,oBA0LZ,EAAA,CAAA,WAAA,EA1LiD,WA0LjD,CAAA,MAAA,CAAA,EAAA,IAAA,EA1L4E,cA0L5E,EAAA,GAAA,MAAA,GAAA,IAAA;;;;;AAKe,cApKH,4BAoKiB,EAAA,CAAA,KAAA,EAnKrB,uBAmKqB,EAAA,UAAA,EAAA,MAAA,EAAA,WAAA,CAAA,EAjKd,uBAiKc,EAAA,GAhK3B,iBAgK2B,EAAA;;;;;AAIE,cA5HnB,yBA4HmB,EAAA,CAAA,MAAA,EA3HtB,wBA2HsB,EAAA,UAAA,EAAA,MAAA,EAAA,SAAA,EAzHnB,iBAyHmB,EAAA,EAAA,WAAA,CAAA,EAxHhB,uBAwHgB,EAAA,GAAA,IAAA;AAChC;;;AAGgB,cA7BH,WA6BG,EAAA,CAAA,WAAA,EA7ByB,WA6BzB,CAAA,MAAA,CAAA,EAAA,IAAA,EA7BoD,IA6BpD,EAAA,GA7B2D,cA6B3D,GAAA,IAAA;;;;iBARA,cAAA,OACR,mBACO,kCACA,0BACZ;iBACa,cAAA,OACR,mBACO,mCACC,0BACb;;;;KC3NS,eAAA;ADKZ;AAEA;AAGA;AASA;AA2Ba,cCxCA,gBD8EZ,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,kBAAA,EAAA,MAAA,EAAA,GAAA,MAAA;;;;;AAMD;;;;;AAmGA;;AAAoE,cC5IvD,QD4IuD,EAAA,CAAA,SAAA,EAAA,MAAA,EAAA,UAAA,EAAA,MAAA,EAAA,eAAA,EAAA,MAAA,EAAA,UAAA,CAAA,EAAA,MAAA,EAAA,GAAA,MAAA;;;AAqBpE;;;;;;AAKgB,cCtHH,gBDsHiB,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,GAAA,MAAA;;;;;;;;;ACvN9B;AAMA;AA2Ca,cAwEA,mBAlCZ,EAAA,CAAA,QAAA,EAkC6C,iBAlC7C,EAAA,GAAA;EAUY,OAAA,EAAA,MAAA;EAwBA,aAAA,EAAuF,MAAvF,GAyBZ,IAAA;AAOD,CAAA;AAgBA;;;;;cAhBa,2DAA4D;;;;;;;;;;cAgB5D,8CACS,sDAEL,6BACL"}
+{"version":3,"file":"template-extraction.d.mts","names":[],"sources":["../src/template-extraction/types.ts","../src/template-extraction/extract.ts","../src/template-extraction/format.ts"],"sourcesContent":[],"mappings":"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"}