@soda-gql/common 0.7.0 → 0.8.0

package/dist/{canonical-id-BFnyQGST.mjs → canonical-id-BJahCcrS.mjs}

@@ -14,6 +14,24 @@ const createCanonicalId = (filePath, astPath) => {
 	const idParts = [normalized, astPath];
 	return idParts.join(canonicalIdSeparator);
 };
+/**
+* Parse a canonical ID into its components.
+* @param canonicalId - The canonical ID to parse (e.g., "/app/src/user.ts::userFragment")
+* @returns An object with filePath and astPath
+*/
+const parseCanonicalId = (canonicalId) => {
+	const idx = canonicalId.indexOf(canonicalIdSeparator);
+	if (idx === -1) {
+		return {
+			filePath: canonicalId,
+			astPath: ""
+		};
+	}
+	return {
+		filePath: canonicalId.slice(0, idx),
+		astPath: canonicalId.slice(idx + canonicalIdSeparator.length)
+	};
+};
 
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.ts
@@ -151,5 +169,5 @@ const buildAstPath = (stack) => {
 };
 
 //#endregion
-export { CanonicalIdSchema as a, createPathTracker as i, createCanonicalTracker as n, createCanonicalId as o, createOccurrenceTracker as r, buildAstPath as t };
-//# sourceMappingURL=canonical-id-BFnyQGST.mjs.map
+export { CanonicalIdSchema as a, createPathTracker as i, createCanonicalTracker as n, createCanonicalId as o, createOccurrenceTracker as r, parseCanonicalId as s, buildAstPath as t };
+//# sourceMappingURL=canonical-id-BJahCcrS.mjs.map

package/dist/canonical-id-BJahCcrS.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-id-BJahCcrS.mjs","names":["CanonicalIdSchema: z.ZodType<CanonicalId>","z","scopeStack: ScopeFrame[]","frame: ScopeFrame","exportBinding: string | undefined"],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":["import { isAbsolute, resolve } from \"node:path\";\nimport z from \"zod\";\nimport { normalizePath } from \"../utils\";\n\nexport type CanonicalId = string & { readonly __brand: \"CanonicalId\" };\n\nconst canonicalIdSeparator = \"::\" as const;\n\nexport const CanonicalIdSchema: z.ZodType<CanonicalId> = z.string() as unknown as z.ZodType<CanonicalId>;\n\n// Type-safe schema for CanonicalId - validates as string but types as branded\nexport const createCanonicalId = (filePath: string, astPath: string): CanonicalId => {\n  if (!isAbsolute(filePath)) {\n    throw new Error(\"[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH\");\n  }\n\n  const resolved = resolve(filePath);\n  const normalized = normalizePath(resolved);\n\n  // Create a 2-part ID: {absPath}::{astPath}\n  // astPath uniquely identifies the definition's location in the AST (e.g., \"MyComponent.useQuery.def\")\n  const idParts = [normalized, astPath];\n\n  return idParts.join(canonicalIdSeparator) as CanonicalId;\n};\n\n/**\n * Parse a canonical ID into its components.\n * @param canonicalId - The canonical ID to parse (e.g., \"/app/src/user.ts::userFragment\")\n * @returns An object with filePath and astPath\n */\nexport const parseCanonicalId = (\n  canonicalId: CanonicalId | string,\n): {\n  filePath: string;\n  astPath: string;\n} => {\n  const idx = canonicalId.indexOf(canonicalIdSeparator);\n  if (idx === -1) {\n    return { filePath: canonicalId, astPath: \"\" };\n  }\n  return {\n    filePath: canonicalId.slice(0, idx),\n    astPath: canonicalId.slice(idx + canonicalIdSeparator.length),\n  };\n};\n","/**\n * Canonical path tracker for AST traversal.\n *\n * This module provides a stateful helper that tracks scope information during\n * AST traversal to generate canonical IDs. It's designed to integrate with\n * existing plugin visitor patterns (Babel, SWC, TypeScript) without requiring\n * a separate AST traversal.\n *\n * Usage pattern:\n * 1. Plugin creates tracker at file/program entry\n * 2. Plugin calls enterScope/exitScope during its traversal\n * 3. Plugin calls registerDefinition when discovering GQL definitions\n * 4. Tracker provides canonical ID information\n */\n\nimport type { CanonicalId } from \"./canonical-id\";\nimport { createCanonicalId } from \"./canonical-id\";\n\n/**\n * Scope frame for tracking AST path segments\n */\nexport type ScopeFrame = {\n  /** Name segment (e.g., \"MyComponent\", \"useQuery\", \"arrow#1\") */\n  readonly nameSegment: string;\n  /** Kind of scope */\n  readonly kind: \"function\" | \"class\" | \"variable\" | \"property\" | \"method\" | \"expression\";\n  /** Occurrence index for disambiguation */\n  readonly occurrence: number;\n};\n\n/**\n * Opaque handle for scope tracking\n */\nexport type ScopeHandle = {\n  readonly __brand: \"ScopeHandle\";\n  readonly depth: number;\n};\n\n/**\n * Canonical path tracker interface\n */\nexport interface CanonicalPathTracker {\n  /**\n   * Enter a new scope during traversal\n   * @param options Scope information\n   * @returns Handle to use when exiting the scope\n   */\n  enterScope(options: { segment: string; kind: ScopeFrame[\"kind\"]; stableKey?: string }): ScopeHandle;\n\n  /**\n   * Exit a scope during traversal\n   * @param handle Handle returned from enterScope\n   */\n  exitScope(handle: ScopeHandle): void;\n\n  /**\n   * Register a definition discovered during traversal\n   * @returns Definition metadata including astPath and canonical ID information\n   */\n  registerDefinition(): {\n    astPath: string;\n    isTopLevel: boolean;\n    exportBinding?: string;\n  };\n\n  /**\n   * Resolve a canonical ID from an astPath\n   * @param astPath AST path string\n   * @returns Canonical ID\n   */\n  resolveCanonicalId(astPath: string): CanonicalId;\n\n  /**\n   * Register an export binding\n   * @param local Local variable name\n   * @param exported Exported name\n   */\n  registerExportBinding(local: string, exported: string): void;\n\n  /**\n   * Get current scope depth\n   * @returns Current depth (0 = top level)\n   */\n  currentDepth(): number;\n}\n\n/**\n * Build AST path from scope stack (internal helper)\n */\nconst _buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n\n/**\n * Create a canonical path tracker\n *\n * @param options Configuration options\n * @returns Tracker instance\n *\n * @example\n * ```typescript\n * // In a Babel plugin\n * const tracker = createCanonicalTracker({ filePath: state.filename });\n *\n * const visitor = {\n *   FunctionDeclaration: {\n *     enter(path) {\n *       const handle = tracker.enterScope({\n *         segment: path.node.id.name,\n *         kind: 'function'\n *       });\n *     },\n *     exit(path) {\n *       tracker.exitScope(handle);\n *     }\n *   }\n * };\n * ```\n */\nexport const createCanonicalTracker = (options: {\n  filePath: string;\n  getExportName?: (localName: string) => string | undefined;\n}): CanonicalPathTracker => {\n  const { filePath, getExportName } = options;\n\n  // Scope stack\n  const scopeStack: ScopeFrame[] = [];\n\n  // Occurrence counters for disambiguating duplicate names\n  const occurrenceCounters = new Map<string, number>();\n\n  // Used paths for ensuring uniqueness\n  const usedPaths = new Set<string>();\n\n  // Export bindings map\n  const exportBindings = new Map<string, string>();\n\n  const getNextOccurrence = (key: string): number => {\n    const current = occurrenceCounters.get(key) ?? 0;\n    occurrenceCounters.set(key, current + 1);\n    return current;\n  };\n\n  const ensureUniquePath = (basePath: string): string => {\n    let path = basePath;\n    let suffix = 0;\n    while (usedPaths.has(path)) {\n      suffix++;\n      path = `${basePath}$${suffix}`;\n    }\n    usedPaths.add(path);\n    return path;\n  };\n\n  return {\n    enterScope({ segment, kind, stableKey }): ScopeHandle {\n      const key = stableKey ?? `${kind}:${segment}`;\n      const occurrence = getNextOccurrence(key);\n\n      const frame: ScopeFrame = {\n        nameSegment: segment,\n        kind,\n        occurrence,\n      };\n\n      scopeStack.push(frame);\n\n      return {\n        __brand: \"ScopeHandle\",\n        depth: scopeStack.length - 1,\n      } as ScopeHandle;\n    },\n\n    exitScope(handle: ScopeHandle): void {\n      // Validate handle depth matches current stack\n      if (handle.depth !== scopeStack.length - 1) {\n        throw new Error(`[INTERNAL] Invalid scope exit: expected depth ${scopeStack.length - 1}, got ${handle.depth}`);\n      }\n      scopeStack.pop();\n    },\n\n    registerDefinition(): {\n      astPath: string;\n      isTopLevel: boolean;\n      exportBinding?: string;\n    } {\n      const basePath = _buildAstPath(scopeStack);\n      const astPath = ensureUniquePath(basePath);\n      const isTopLevel = scopeStack.length === 0;\n\n      // Check export binding if provided\n      let exportBinding: string | undefined;\n      if (getExportName && isTopLevel) {\n        // For top-level definitions, try to get export name\n        // This is a simplified version - real logic depends on how the definition is bound\n        exportBinding = undefined;\n      }\n\n      return {\n        astPath,\n        isTopLevel,\n        exportBinding,\n      };\n    },\n\n    resolveCanonicalId(astPath: string): CanonicalId {\n      return createCanonicalId(filePath, astPath);\n    },\n\n    registerExportBinding(local: string, exported: string): void {\n      exportBindings.set(local, exported);\n    },\n\n    currentDepth(): number {\n      return scopeStack.length;\n    },\n  };\n};\n\n/**\n * Helper to create occurrence tracker (for backward compatibility)\n */\nexport const createOccurrenceTracker = (): {\n  getNextOccurrence: (key: string) => number;\n} => {\n  const occurrenceCounters = new Map<string, number>();\n\n  return {\n    getNextOccurrence(key: string): number {\n      const current = occurrenceCounters.get(key) ?? 0;\n      occurrenceCounters.set(key, current + 1);\n      return current;\n    },\n  };\n};\n\n/**\n * Helper to create path tracker (for backward compatibility)\n */\nexport const createPathTracker = (): {\n  ensureUniquePath: (basePath: string) => string;\n} => {\n  const usedPaths = new Set<string>();\n\n  return {\n    ensureUniquePath(basePath: string): string {\n      let path = basePath;\n      let suffix = 0;\n      while (usedPaths.has(path)) {\n        suffix++;\n        path = `${basePath}$${suffix}`;\n      }\n      usedPaths.add(path);\n      return path;\n    },\n  };\n};\n\n/**\n * Build AST path from scope stack (for backward compatibility)\n */\nexport const buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n"],"mappings":"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"}

package/dist/{canonical-id-BFcryTw5.cjs → canonical-id-CgMNOZyn.cjs}

@@ -25,7 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_utils = require('./utils-CmLf7LU5.cjs');
+const require_utils = require('./utils-CsTwS1dw.cjs');
 let node_path = require("node:path");
 let zod = require("zod");
 zod = __toESM(zod);
@@ -42,6 +42,24 @@ const createCanonicalId = (filePath, astPath) => {
 	const idParts = [normalized, astPath];
 	return idParts.join(canonicalIdSeparator);
 };
+/**
+* Parse a canonical ID into its components.
+* @param canonicalId - The canonical ID to parse (e.g., "/app/src/user.ts::userFragment")
+* @returns An object with filePath and astPath
+*/
+const parseCanonicalId = (canonicalId) => {
+	const idx = canonicalId.indexOf(canonicalIdSeparator);
+	if (idx === -1) {
+		return {
+			filePath: canonicalId,
+			astPath: ""
+		};
+	}
+	return {
+		filePath: canonicalId.slice(0, idx),
+		astPath: canonicalId.slice(idx + canonicalIdSeparator.length)
+	};
+};
 
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.ts
@@ -221,4 +239,10 @@ Object.defineProperty(exports, 'createPathTracker', {
     return createPathTracker;
   }
 });
-//# sourceMappingURL=canonical-id-BFcryTw5.cjs.map
+Object.defineProperty(exports, 'parseCanonicalId', {
+  enumerable: true,
+  get: function () {
+    return parseCanonicalId;
+  }
+});
+//# sourceMappingURL=canonical-id-CgMNOZyn.cjs.map

package/dist/canonical-id-CgMNOZyn.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-id-CgMNOZyn.cjs","names":["CanonicalIdSchema: z.ZodType<CanonicalId>","z","normalizePath","scopeStack: ScopeFrame[]","frame: ScopeFrame","exportBinding: string | undefined"],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":["import { isAbsolute, resolve } from \"node:path\";\nimport z from \"zod\";\nimport { normalizePath } from \"../utils\";\n\nexport type CanonicalId = string & { readonly __brand: \"CanonicalId\" };\n\nconst canonicalIdSeparator = \"::\" as const;\n\nexport const CanonicalIdSchema: z.ZodType<CanonicalId> = z.string() as unknown as z.ZodType<CanonicalId>;\n\n// Type-safe schema for CanonicalId - validates as string but types as branded\nexport const createCanonicalId = (filePath: string, astPath: string): CanonicalId => {\n  if (!isAbsolute(filePath)) {\n    throw new Error(\"[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH\");\n  }\n\n  const resolved = resolve(filePath);\n  const normalized = normalizePath(resolved);\n\n  // Create a 2-part ID: {absPath}::{astPath}\n  // astPath uniquely identifies the definition's location in the AST (e.g., \"MyComponent.useQuery.def\")\n  const idParts = [normalized, astPath];\n\n  return idParts.join(canonicalIdSeparator) as CanonicalId;\n};\n\n/**\n * Parse a canonical ID into its components.\n * @param canonicalId - The canonical ID to parse (e.g., \"/app/src/user.ts::userFragment\")\n * @returns An object with filePath and astPath\n */\nexport const parseCanonicalId = (\n  canonicalId: CanonicalId | string,\n): {\n  filePath: string;\n  astPath: string;\n} => {\n  const idx = canonicalId.indexOf(canonicalIdSeparator);\n  if (idx === -1) {\n    return { filePath: canonicalId, astPath: \"\" };\n  }\n  return {\n    filePath: canonicalId.slice(0, idx),\n    astPath: canonicalId.slice(idx + canonicalIdSeparator.length),\n  };\n};\n","/**\n * Canonical path tracker for AST traversal.\n *\n * This module provides a stateful helper that tracks scope information during\n * AST traversal to generate canonical IDs. It's designed to integrate with\n * existing plugin visitor patterns (Babel, SWC, TypeScript) without requiring\n * a separate AST traversal.\n *\n * Usage pattern:\n * 1. Plugin creates tracker at file/program entry\n * 2. Plugin calls enterScope/exitScope during its traversal\n * 3. Plugin calls registerDefinition when discovering GQL definitions\n * 4. Tracker provides canonical ID information\n */\n\nimport type { CanonicalId } from \"./canonical-id\";\nimport { createCanonicalId } from \"./canonical-id\";\n\n/**\n * Scope frame for tracking AST path segments\n */\nexport type ScopeFrame = {\n  /** Name segment (e.g., \"MyComponent\", \"useQuery\", \"arrow#1\") */\n  readonly nameSegment: string;\n  /** Kind of scope */\n  readonly kind: \"function\" | \"class\" | \"variable\" | \"property\" | \"method\" | \"expression\";\n  /** Occurrence index for disambiguation */\n  readonly occurrence: number;\n};\n\n/**\n * Opaque handle for scope tracking\n */\nexport type ScopeHandle = {\n  readonly __brand: \"ScopeHandle\";\n  readonly depth: number;\n};\n\n/**\n * Canonical path tracker interface\n */\nexport interface CanonicalPathTracker {\n  /**\n   * Enter a new scope during traversal\n   * @param options Scope information\n   * @returns Handle to use when exiting the scope\n   */\n  enterScope(options: { segment: string; kind: ScopeFrame[\"kind\"]; stableKey?: string }): ScopeHandle;\n\n  /**\n   * Exit a scope during traversal\n   * @param handle Handle returned from enterScope\n   */\n  exitScope(handle: ScopeHandle): void;\n\n  /**\n   * Register a definition discovered during traversal\n   * @returns Definition metadata including astPath and canonical ID information\n   */\n  registerDefinition(): {\n    astPath: string;\n    isTopLevel: boolean;\n    exportBinding?: string;\n  };\n\n  /**\n   * Resolve a canonical ID from an astPath\n   * @param astPath AST path string\n   * @returns Canonical ID\n   */\n  resolveCanonicalId(astPath: string): CanonicalId;\n\n  /**\n   * Register an export binding\n   * @param local Local variable name\n   * @param exported Exported name\n   */\n  registerExportBinding(local: string, exported: string): void;\n\n  /**\n   * Get current scope depth\n   * @returns Current depth (0 = top level)\n   */\n  currentDepth(): number;\n}\n\n/**\n * Build AST path from scope stack (internal helper)\n */\nconst _buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n\n/**\n * Create a canonical path tracker\n *\n * @param options Configuration options\n * @returns Tracker instance\n *\n * @example\n * ```typescript\n * // In a Babel plugin\n * const tracker = createCanonicalTracker({ filePath: state.filename });\n *\n * const visitor = {\n *   FunctionDeclaration: {\n *     enter(path) {\n *       const handle = tracker.enterScope({\n *         segment: path.node.id.name,\n *         kind: 'function'\n *       });\n *     },\n *     exit(path) {\n *       tracker.exitScope(handle);\n *     }\n *   }\n * };\n * ```\n */\nexport const createCanonicalTracker = (options: {\n  filePath: string;\n  getExportName?: (localName: string) => string | undefined;\n}): CanonicalPathTracker => {\n  const { filePath, getExportName } = options;\n\n  // Scope stack\n  const scopeStack: ScopeFrame[] = [];\n\n  // Occurrence counters for disambiguating duplicate names\n  const occurrenceCounters = new Map<string, number>();\n\n  // Used paths for ensuring uniqueness\n  const usedPaths = new Set<string>();\n\n  // Export bindings map\n  const exportBindings = new Map<string, string>();\n\n  const getNextOccurrence = (key: string): number => {\n    const current = occurrenceCounters.get(key) ?? 0;\n    occurrenceCounters.set(key, current + 1);\n    return current;\n  };\n\n  const ensureUniquePath = (basePath: string): string => {\n    let path = basePath;\n    let suffix = 0;\n    while (usedPaths.has(path)) {\n      suffix++;\n      path = `${basePath}$${suffix}`;\n    }\n    usedPaths.add(path);\n    return path;\n  };\n\n  return {\n    enterScope({ segment, kind, stableKey }): ScopeHandle {\n      const key = stableKey ?? `${kind}:${segment}`;\n      const occurrence = getNextOccurrence(key);\n\n      const frame: ScopeFrame = {\n        nameSegment: segment,\n        kind,\n        occurrence,\n      };\n\n      scopeStack.push(frame);\n\n      return {\n        __brand: \"ScopeHandle\",\n        depth: scopeStack.length - 1,\n      } as ScopeHandle;\n    },\n\n    exitScope(handle: ScopeHandle): void {\n      // Validate handle depth matches current stack\n      if (handle.depth !== scopeStack.length - 1) {\n        throw new Error(`[INTERNAL] Invalid scope exit: expected depth ${scopeStack.length - 1}, got ${handle.depth}`);\n      }\n      scopeStack.pop();\n    },\n\n    registerDefinition(): {\n      astPath: string;\n      isTopLevel: boolean;\n      exportBinding?: string;\n    } {\n      const basePath = _buildAstPath(scopeStack);\n      const astPath = ensureUniquePath(basePath);\n      const isTopLevel = scopeStack.length === 0;\n\n      // Check export binding if provided\n      let exportBinding: string | undefined;\n      if (getExportName && isTopLevel) {\n        // For top-level definitions, try to get export name\n        // This is a simplified version - real logic depends on how the definition is bound\n        exportBinding = undefined;\n      }\n\n      return {\n        astPath,\n        isTopLevel,\n        exportBinding,\n      };\n    },\n\n    resolveCanonicalId(astPath: string): CanonicalId {\n      return createCanonicalId(filePath, astPath);\n    },\n\n    registerExportBinding(local: string, exported: string): void {\n      exportBindings.set(local, exported);\n    },\n\n    currentDepth(): number {\n      return scopeStack.length;\n    },\n  };\n};\n\n/**\n * Helper to create occurrence tracker (for backward compatibility)\n */\nexport const createOccurrenceTracker = (): {\n  getNextOccurrence: (key: string) => number;\n} => {\n  const occurrenceCounters = new Map<string, number>();\n\n  return {\n    getNextOccurrence(key: string): number {\n      const current = occurrenceCounters.get(key) ?? 0;\n      occurrenceCounters.set(key, current + 1);\n      return current;\n    },\n  };\n};\n\n/**\n * Helper to create path tracker (for backward compatibility)\n */\nexport const createPathTracker = (): {\n  ensureUniquePath: (basePath: string) => string;\n} => {\n  const usedPaths = new Set<string>();\n\n  return {\n    ensureUniquePath(basePath: string): string {\n      let path = basePath;\n      let suffix = 0;\n      while (usedPaths.has(path)) {\n        suffix++;\n        path = `${basePath}$${suffix}`;\n      }\n      usedPaths.add(path);\n      return path;\n    },\n  };\n};\n\n/**\n * Build AST path from scope stack (for backward compatibility)\n */\nexport const buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n"],"mappings":"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"}

package/dist/canonical-id.cjs

@@ -1,9 +1,10 @@
-const require_canonical_id = require('./canonical-id-BFcryTw5.cjs');
-require('./utils-CmLf7LU5.cjs');
+const require_canonical_id = require('./canonical-id-CgMNOZyn.cjs');
+require('./utils-CsTwS1dw.cjs');
 
 exports.CanonicalIdSchema = require_canonical_id.CanonicalIdSchema;
 exports.buildAstPath = require_canonical_id.buildAstPath;
 exports.createCanonicalId = require_canonical_id.createCanonicalId;
 exports.createCanonicalTracker = require_canonical_id.createCanonicalTracker;
 exports.createOccurrenceTracker = require_canonical_id.createOccurrenceTracker;
-exports.createPathTracker = require_canonical_id.createPathTracker;
+exports.createPathTracker = require_canonical_id.createPathTracker;
+exports.parseCanonicalId = require_canonical_id.parseCanonicalId;

package/dist/canonical-id.d.cts

@@ -1,2 +1,2 @@
-import { a as createCanonicalTracker, c as CanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-BG7Aiges.cjs";
-export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };
+import { a as createCanonicalTracker, c as CanonicalId, d as parseCanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-Cm2Zwk9m.cjs";
+export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, parseCanonicalId };

package/dist/canonical-id.d.mts

@@ -1,2 +1,2 @@
-import { a as createCanonicalTracker, c as CanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-C4t2Wbzs.mjs";
-export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };
+import { a as createCanonicalTracker, c as CanonicalId, d as parseCanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-CPpVc8Id.mjs";
+export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, parseCanonicalId };

package/dist/canonical-id.mjs

@@ -1,4 +1,4 @@
 import "./utils-DLEgAn7q.mjs";
-import { a as CanonicalIdSchema, i as createPathTracker, n as createCanonicalTracker, o as createCanonicalId, r as createOccurrenceTracker, t as buildAstPath } from "./canonical-id-BFnyQGST.mjs";
+import { a as CanonicalIdSchema, i as createPathTracker, n as createCanonicalTracker, o as createCanonicalId, r as createOccurrenceTracker, s as parseCanonicalId, t as buildAstPath } from "./canonical-id-BJahCcrS.mjs";
 
-export { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };
+export { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, parseCanonicalId };

package/dist/{index-BG7Aiges.d.cts → index-CPpVc8Id.d.mts}

@@ -6,6 +6,15 @@ type CanonicalId = string & {
 };
 declare const CanonicalIdSchema: z$1.ZodType<CanonicalId>;
 declare const createCanonicalId: (filePath: string, astPath: string) => CanonicalId;
+/**
+ * Parse a canonical ID into its components.
+ * @param canonicalId - The canonical ID to parse (e.g., "/app/src/user.ts::userFragment")
+ * @returns An object with filePath and astPath
+ */
+declare const parseCanonicalId: (canonicalId: CanonicalId | string) => {
+  filePath: string;
+  astPath: string;
+};
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.d.ts
 
@@ -120,5 +129,5 @@ declare const createPathTracker: () => {
  */
 declare const buildAstPath: (stack: readonly ScopeFrame[]) => string;
 //#endregion
-export { createCanonicalTracker as a, CanonicalId as c, buildAstPath as i, CanonicalIdSchema as l, ScopeFrame as n, createOccurrenceTracker as o, ScopeHandle as r, createPathTracker as s, CanonicalPathTracker as t, createCanonicalId as u };
-//# sourceMappingURL=index-BG7Aiges.d.cts.map
+export { createCanonicalTracker as a, CanonicalId as c, parseCanonicalId as d, buildAstPath as i, CanonicalIdSchema as l, ScopeFrame as n, createOccurrenceTracker as o, ScopeHandle as r, createPathTracker as s, CanonicalPathTracker as t, createCanonicalId as u };
+//# sourceMappingURL=index-CPpVc8Id.d.mts.map

package/dist/index-CPpVc8Id.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CPpVc8Id.d.mts","names":[],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":[],"mappings":";;;KAIY,WAAA;;AAAZ,CAAA;AAIa,cAAA,iBAA6B,EAAV,GAAA,CAAE,OAAF,CAAU,WAAD,CAAA;AAG5B,cAAA,iBAAyD,EAAA,CAAA,QAarE,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,GAbqE,WAarE;AAOD;;;;ACVA;AAYY,cDFC,gBCEU,EAAA,CAAA,WAAA,EDDR,WCCQ,GAAA,MAAA,EAAA,GAAA;EAQN,QAAA,EAAA,MAAA;EAM8B,OAAA,EAAA,MAAA;CAA2C;;;;;;;AAwE7E,KAlGD,UAAA,GAkGC;EAuGA;EAiBA,SAAA,WAiBZ,EAAA,MAAA;EAKY;;;;;;;;KApOD,WAAA;;;;;;;UAQK,oBAAA;;;;;;;;UAM8B;;MAA2C;;;;;oBAMtE;;;;;;;;;;;;;;;uCAiBmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiD1B;;;MAGT;;;;cAoGS;;;;;;cAiBA;;;;;;cAsBA,+BAAgC"}

package/dist/{index-C4t2Wbzs.d.mts → index-Cm2Zwk9m.d.cts}

@@ -6,6 +6,15 @@ type CanonicalId = string & {
 };
 declare const CanonicalIdSchema: z$1.ZodType<CanonicalId>;
 declare const createCanonicalId: (filePath: string, astPath: string) => CanonicalId;
+/**
+ * Parse a canonical ID into its components.
+ * @param canonicalId - The canonical ID to parse (e.g., "/app/src/user.ts::userFragment")
+ * @returns An object with filePath and astPath
+ */
+declare const parseCanonicalId: (canonicalId: CanonicalId | string) => {
+  filePath: string;
+  astPath: string;
+};
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.d.ts
 
@@ -120,5 +129,5 @@ declare const createPathTracker: () => {
  */
 declare const buildAstPath: (stack: readonly ScopeFrame[]) => string;
 //#endregion
-export { createCanonicalTracker as a, CanonicalId as c, buildAstPath as i, CanonicalIdSchema as l, ScopeFrame as n, createOccurrenceTracker as o, ScopeHandle as r, createPathTracker as s, CanonicalPathTracker as t, createCanonicalId as u };
-//# sourceMappingURL=index-C4t2Wbzs.d.mts.map
+export { createCanonicalTracker as a, CanonicalId as c, parseCanonicalId as d, buildAstPath as i, CanonicalIdSchema as l, ScopeFrame as n, createOccurrenceTracker as o, ScopeHandle as r, createPathTracker as s, CanonicalPathTracker as t, createCanonicalId as u };
+//# sourceMappingURL=index-Cm2Zwk9m.d.cts.map

package/dist/index-Cm2Zwk9m.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-Cm2Zwk9m.d.cts","names":[],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":[],"mappings":";;;KAIY,WAAA;;AAAZ,CAAA;AAIa,cAAA,iBAA6B,EAAV,GAAA,CAAE,OAAF,CAAU,WAAD,CAAA;AAG5B,cAAA,iBAAyD,EAAA,CAAA,QAarE,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,GAbqE,WAarE;AAOD;;;;ACVA;AAYY,cDFC,gBCEU,EAAA,CAAA,WAAA,EDDR,WCCQ,GAAA,MAAA,EAAA,GAAA;EAQN,QAAA,EAAA,MAAA;EAM8B,OAAA,EAAA,MAAA;CAA2C;;;;;;;AAwE7E,KAlGD,UAAA,GAkGC;EAuGA;EAiBA,SAAA,WAiBZ,EAAA,MAAA;EAKY;;;;;;;;KApOD,WAAA;;;;;;;UAQK,oBAAA;;;;;;;;UAM8B;;MAA2C;;;;;oBAMtE;;;;;;;;;;;;;;;uCAiBmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiD1B;;;MAGT;;;;cAoGS;;;;;;cAiBA;;;;;;cAsBA,+BAAgC"}

package/dist/index-DaAp2rNj.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index-DaAp2rNj.d.cts","names":[],"sources":["../src/portable/fs.ts","../src/portable/hash.ts","../src/portable/id.ts","../src/portable/runtime.ts","../src/portable/spawn.ts"],"sourcesContent":[],"mappings":";;AAMA;;AAE4C,UAF3B,UAAA,CAE2B;EACpB,QAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAFE,OAEF,CAAA,MAAA,CAAA;EACe,SAAA,CAAA,IAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,EAFK,OAEL,CAAA,IAAA,CAAA;EAAjB,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EADE,OACF,CAAA,OAAA,CAAA;EACsB,IAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EADtB,OACsB,CAAA;IACc,KAAA,EAFnB,IAEmB;IAAO,IAAA,EAAA,MAAA;EAsBjD,CAAA,CAAA;EA4FA,MAAA,CAAA,OAAA,EAAa,MAAA,EAAA,OAAI,EAAA,MAAU,CAAA,EAnHC,OAmHD,CAAA,IAAA,CAAA;EAW3B,KAAA,CAAA,IAAA,EAAA,MAAA,EAAA,QAAyB,EAAA;;MA7HiB;;ACN9C,iBD4BI,gBAAA,CAAA,CC5BS,ED4BW,UC5BX;AAER,iBDsHD,aAAA,CAAA,CCrHoB,EDqHH,UCrHgB;AAUjD;AAqCA;AAWA;;iBDsEgB,yBAAA,CAAA;;;;AAnIhB;;AAE4C,KCFhC,aAAA,GDEgC,QAAA,GAAA,QAAA;AACpB,UCDP,cAAA,CDCO;EACe,IAAA,CAAA,OAAA,EAAA,MAAA,EAAA,SAAA,CAAA,ECDH,aDCG,CAAA,EAAA,MAAA;;AACK,iBCQ5B,oBAAA,CAAA,CDR4B,ECQJ,cDRI;AACc,iBC4C1C,iBAAA,CAAA,CD5C0C,EC4CrB,cD5CqB;;AAsB1D;AA4FA;AAWA;iBCtEgB,6BAAA,CAAA;;;;AD7DhB;;;;;;AAK4C,iBED5B,UAAA,CAAA,CFC4B,EAAA,MAAA;;;;AAL5C;;AAE4C,cGJ/B,OHI+B,EAAA;EACpB,SAAA,KAAA,EAAA,OAAA;EACe,SAAA,MAAA,EAAA,OAAA;EAAjB,SAAA,iBAAA,EAAA,OAAA;CACsB;;;AAuB5C;AA4FgB,iBGjHA,IHiHa,CAAA,CAAA,CAAI,CAAA,EAAA,EAAA,GAAA,GGjHC,CHiHS,CAAA,EAAA,GAAA,GGjHC,CHiHD;AAW3C;;;;ACnIY,iBEwBI,qBAAA,CAAA,CFxBS,EAAA,IAAA;;;;ADAzB;;AAE4C,UIF3B,YAAA,CJE2B;EACpB,GAAA,EAAA,MAAA,EAAA;EACe,GAAA,CAAA,EAAA,MAAA;EAAjB,GAAA,CAAA,EIDd,MJCc,CAAA,MAAA,EAAA,MAAA,CAAA;;AAEoC,UIAzC,WAAA,CJAyC;EAAO,MAAA,EAAA,MAAA;EAsBjD,MAAA,EAAA,MAAA;EA4FA,QAAA,EAAA,MAAa;AAW7B;iBIvHsB,KAAA,UAAe,eAAe,QAAQ"}
+{"version":3,"file":"index-DaAp2rNj.d.cts","names":[],"sources":["../src/portable/fs.ts","../src/portable/hash.ts","../src/portable/id.ts","../src/portable/runtime.ts","../src/portable/spawn.ts"],"sourcesContent":[],"mappings":";;AAMA;;AAE4C,UAF3B,UAAA,CAE2B;EACpB,QAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAFE,OAEF,CAAA,MAAA,CAAA;EACe,SAAA,CAAA,IAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,EAFK,OAEL,CAAA,IAAA,CAAA;EAAjB,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EADE,OACF,CAAA,OAAA,CAAA;EACsB,IAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EADtB,OACsB,CAAA;IACc,KAAA,EAFnB,IAEmB;IAAO,IAAA,EAAA,MAAA;EAsBjD,CAAA,CAAA;EA4FA,MAAA,CAAA,OAAA,EAAa,MAAA,EAAA,OAAI,EAAA,MAAU,CAAA,EAnHC,OAmHD,CAAA,IAAA,CAAA;EAW3B,KAAA,CAAA,IAAA,EAAA,MAAA,EAAA,QAAyB,EAAA;;MA7HiB;;ACN9C,iBD4BI,gBAAA,CAAA,CC5BS,ED4BW,UC5BX;AAER,iBDsHD,aAAA,CAAA,CCrHoB,EDqHH,UCrHgB;AAUjD;AAqCA;AAWA;;iBDsEgB,yBAAA,CAAA;;;;AAnIhB;;AAE4C,KCFhC,aAAA,GDEgC,QAAA,GAAA,QAAA;AACpB,UCDP,cAAA,CDCO;EACe,IAAA,CAAA,OAAA,EAAA,MAAA,EAAA,SAAA,CAAA,ECDH,aDCG,CAAA,EAAA,MAAA;;AACK,iBCQ5B,oBAAA,CAAA,CDR4B,ECQJ,cDRI;AACc,iBC4C1C,iBAAA,CAAA,CD5C0C,EC4CrB,cD5CqB;;AAsB1D;AA4FA;AAWA;iBCtEgB,6BAAA,CAAA;;;;AD7DhB;;;;;;AAK4C,iBED5B,UAAA,CAAA,CFC4B,EAAA,MAAA;;;;AAL5C;;AAE4C,cGJ/B,OHI+B,EAAA;EACpB,SAAA,KAAA,EAAA,OAAA;EACe,SAAA,MAAA,EAAA,OAAA;EAAjB,SAAA,iBAAA,EAAA,OAAA;CACsB;;;AAuB5C;AA4FgB,iBGjHA,IHiHa,CAAA,CAAA,CAAA,CAAI,EAAA,EAAA,GAAA,GGjHC,CHiHS,CAAA,EAAA,GAAA,GGjHC,CHiHD;AAW3C;;;;ACnIY,iBEwBI,qBAAA,CAAA,CFxBS,EAAA,IAAA;;;;ADAzB;;AAE4C,UIF3B,YAAA,CJE2B;EACpB,GAAA,EAAA,MAAA,EAAA;EACe,GAAA,CAAA,EAAA,MAAA;EAAjB,GAAA,CAAA,EIDd,MJCc,CAAA,MAAA,EAAA,MAAA,CAAA;;AAEoC,UIAzC,WAAA,CJAyC;EAAO,MAAA,EAAA,MAAA;EAsBjD,MAAA,EAAA,MAAA;EA4FA,QAAA,EAAA,MAAa;AAW7B;iBIvHsB,KAAA,UAAe,eAAe,QAAQ"}

package/dist/index-Dit86qkX.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index-Dit86qkX.d.mts","names":[],"sources":["../src/zod/schema-helper.ts"],"sourcesContent":[],"mappings":";;;KAGY,qBAAqB,CAAA,CAAE,QAAQ;KAE/B,2CAFA,MAEiD,OAFxC,KAEoD,SAF9B,CAEwC,OAFhD,CAEwD,CAFxD,CAAA,CAAA,EAEnC;AAA6D,iBAE7C,eAF6C,CAAA,gBAAA,MAAA,CAAA,CAAA,CAAA,EAAA,CAAA,eAGpC,QAHoC,CAG3B,OAH2B,CAGnB,OAHmB,CAAA,CAAA,CAAA,CAAA,KAAA,EAGD,MAHC,GAAA,QAGgB,OAHhB,CAAA,MAG8B,MAH9B,EAAA,MAG4C,OAH5C,CAAA,GAAA,KAAA,EAAA,EAAA,GAG8D,CAAA,CAAA,SAH9D,CAG8D,MAH9D,GAAA,QAGY,OAHZ,CAAA,MAGY,MAHZ,EAAA,MAGY,OAHZ,CAAA,GAAA,KAAA,EAAA,SAAA,KAAA,EAAA,GAAA,kBAAA,MAGY,CAHZ,GAGY,CAHZ,CAGY,CAHZ,CAAA,EAAA,GAAA,KAAA,EAGY,CAAA,CAAA,IAAA,CAAA,OAHZ,CAAA"}
+{"version":3,"file":"index-Dit86qkX.d.mts","names":[],"sources":["../src/zod/schema-helper.ts"],"sourcesContent":[],"mappings":";;;KAGY,qBAAqB,CAAA,CAAE,QAAQ;KAE/B,2CAFA,MAEiD,OAFxC,KAEoD,SAF9B,CAEwC,OAFlD,CAE0D,CAFxD,CAAA,CAAA,EAEnC;AAA6D,iBAE7C,eAF6C,CAAA,gBAAA,MAAA,CAAA,CAAA,CAAA,EAAA,CAAA,eAGpC,QAHoC,CAG3B,OAH2B,CAGnB,OAHmB,CAAA,CAAA,CAAA,CAAA,KAAA,EAGD,MAHC,GAAA,QAGgB,OAHhB,CAAA,MAG8B,MAH9B,EAAA,MAG4C,OAH5C,CAAA,GAAA,KAAA,EAAA,EAAA,GAG8D,CAAA,CAAA,SAH9D,CAG8D,MAH9D,GAAA,QAGY,OAHZ,CAAA,MAGY,MAHZ,EAAA,MAGY,OAHZ,CAAA,GAAA,KAAA,EAAA,SAAA,KAAA,EAAA,GAAA,kBAAA,MAGY,CAHZ,GAGY,CAHZ,CAGY,CAHZ,CAAA,EAAA,GAAA,KAAA,EAGY,CAAA,CAAA,IAAA,CAAA,OAHZ,CAAA"}

package/dist/index.cjs

@@ -1,7 +1,7 @@
-const require_canonical_id = require('./canonical-id-BFcryTw5.cjs');
-const require_utils = require('./utils-CmLf7LU5.cjs');
+const require_canonical_id = require('./canonical-id-CgMNOZyn.cjs');
+const require_utils = require('./utils-CsTwS1dw.cjs');
 const require_portable = require('./portable-C_7gJWmz.cjs');
-const require_zod = require('./zod-CynYgOoN.cjs');
+const require_zod = require('./zod-C_6JfuYV.cjs');
 let neverthrow = require("neverthrow");
 
 //#region packages/common/src/scheduler/types.ts
@@ -286,6 +286,7 @@ exports.isExternalSpecifier = require_utils.isExternalSpecifier;
 exports.isRelativeSpecifier = require_utils.isRelativeSpecifier;
 exports.normalizePath = require_utils.normalizePath;
 exports.once = require_portable.once;
+exports.parseCanonicalId = require_canonical_id.parseCanonicalId;
 exports.resetPortableForTests = require_portable.resetPortableForTests;
 exports.resolveRelativeImportWithExistenceCheck = require_utils.resolveRelativeImportWithExistenceCheck;
 exports.resolveRelativeImportWithReferences = require_utils.resolveRelativeImportWithReferences;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as createCanonicalTracker, c as CanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-BG7Aiges.cjs";
+import { a as createCanonicalTracker, c as CanonicalId, d as parseCanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-Cm2Zwk9m.cjs";
 import { a as resetPortableForTests, c as HashAlgorithm, d as createPortableHasher, f as getPortableHasher, g as getPortableFS, h as createPortableFS, i as once, l as PortableHasher, m as __resetPortableFSForTests, n as SpawnResult, o as runtime, p as PortableFS, r as spawn, s as generateId, t as SpawnOptions, u as __resetPortableHasherForTests } from "./index-DaAp2rNj.cjs";
 import { a as resolveRelativeImportWithExistenceCheck, i as normalizePath, n as isExternalSpecifier, o as resolveRelativeImportWithReferences, r as isRelativeSpecifier, s as cachedFn, t as MODULE_EXTENSION_CANDIDATES } from "./index-LaXfl_e_.cjs";
 import { n as ShapeFor, r as defineSchemaFor, t as SchemaFor } from "./index-LHYortIn.cjs";
@@ -216,5 +216,5 @@ declare const Effects: {
  */
 declare const createSyncScheduler: () => SyncScheduler;
 //#endregion
-export { type AsyncScheduler, CanonicalId, CanonicalIdSchema, CanonicalPathTracker, DeferEffect, Effect, type EffectGenerator, type EffectGeneratorFn, type EffectResult, Effects, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PortableFS, PortableHasher, PureEffect, type SchedulerError, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, type SyncScheduler, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+export { type AsyncScheduler, CanonicalId, CanonicalIdSchema, CanonicalPathTracker, DeferEffect, Effect, type EffectGenerator, type EffectGeneratorFn, type EffectResult, Effects, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PortableFS, PortableHasher, PureEffect, type SchedulerError, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, type SyncScheduler, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, parseCanonicalId, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as createCanonicalTracker, c as CanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-C4t2Wbzs.mjs";
+import { a as createCanonicalTracker, c as CanonicalId, d as parseCanonicalId, i as buildAstPath, l as CanonicalIdSchema, n as ScopeFrame, o as createOccurrenceTracker, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as createCanonicalId } from "./index-CPpVc8Id.mjs";
 import { a as resetPortableForTests, c as HashAlgorithm, d as createPortableHasher, f as getPortableHasher, g as getPortableFS, h as createPortableFS, i as once, l as PortableHasher, m as __resetPortableFSForTests, n as SpawnResult, o as runtime, p as PortableFS, r as spawn, s as generateId, t as SpawnOptions, u as __resetPortableHasherForTests } from "./index-BedBpKbv.mjs";
 import { a as resolveRelativeImportWithExistenceCheck, i as normalizePath, n as isExternalSpecifier, o as resolveRelativeImportWithReferences, r as isRelativeSpecifier, s as cachedFn, t as MODULE_EXTENSION_CANDIDATES } from "./index-Dv8spPt0.mjs";
 import { n as ShapeFor, r as defineSchemaFor, t as SchemaFor } from "./index-Dit86qkX.mjs";
@@ -216,5 +216,5 @@ declare const Effects: {
  */
 declare const createSyncScheduler: () => SyncScheduler;
 //#endregion
-export { type AsyncScheduler, CanonicalId, CanonicalIdSchema, CanonicalPathTracker, DeferEffect, Effect, type EffectGenerator, type EffectGeneratorFn, type EffectResult, Effects, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PortableFS, PortableHasher, PureEffect, type SchedulerError, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, type SyncScheduler, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+export { type AsyncScheduler, CanonicalId, CanonicalIdSchema, CanonicalPathTracker, DeferEffect, Effect, type EffectGenerator, type EffectGeneratorFn, type EffectResult, Effects, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PortableFS, PortableHasher, PureEffect, type SchedulerError, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, type SyncScheduler, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, parseCanonicalId, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { a as getPortableHasher, c as getPortableFS, d as runtime, i as createPortableHasher, l as once, n as generateId, o as __resetPortableFSForTests, r as __resetPortableHasherForTests, s as createPortableFS, t as spawn, u as resetPortableForTests } from "./portable-Dbo3u2CQ.mjs";
 import { a as resolveRelativeImportWithExistenceCheck, i as normalizePath, n as isExternalSpecifier, o as resolveRelativeImportWithReferences, r as isRelativeSpecifier, s as cachedFn, t as MODULE_EXTENSION_CANDIDATES } from "./utils-DLEgAn7q.mjs";
-import { a as CanonicalIdSchema, i as createPathTracker, n as createCanonicalTracker, o as createCanonicalId, r as createOccurrenceTracker, t as buildAstPath } from "./canonical-id-BFnyQGST.mjs";
+import { a as CanonicalIdSchema, i as createPathTracker, n as createCanonicalTracker, o as createCanonicalId, r as createOccurrenceTracker, s as parseCanonicalId, t as buildAstPath } from "./canonical-id-BJahCcrS.mjs";
 import { t as defineSchemaFor } from "./zod-DeSimXdI.mjs";
 import { err, ok } from "neverthrow";
 
@@ -257,5 +257,5 @@ const isSchedulerError = (error) => {
 };
 
 //#endregion
-export { CanonicalIdSchema, DeferEffect, Effect, Effects, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PureEffect, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+export { CanonicalIdSchema, DeferEffect, Effect, Effects, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PureEffect, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, parseCanonicalId, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
 //# sourceMappingURL=index.mjs.map

package/dist/{utils-CmLf7LU5.cjs → utils-CsTwS1dw.cjs}

@@ -1,4 +1,4 @@
-const require_canonical_id = require('./canonical-id-BFcryTw5.cjs');
+const require_canonical_id = require('./canonical-id-CgMNOZyn.cjs');
 let node_path = require("node:path");
 let node_fs = require("node:fs");
 
@@ -145,4 +145,4 @@ Object.defineProperty(exports, 'resolveRelativeImportWithReferences', {
     return resolveRelativeImportWithReferences;
   }
 });
-//# sourceMappingURL=utils-CmLf7LU5.cjs.map
+//# sourceMappingURL=utils-CsTwS1dw.cjs.map

package/dist/{utils-CmLf7LU5.cjs.map → utils-CsTwS1dw.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"utils-CmLf7LU5.cjs","names":["cached: { value: T } | null"],"sources":["../src/utils/cached-fn.ts","../src/utils/path.ts"],"sourcesContent":["export const cachedFn = <T>(fn: () => T) => {\n  let cached: { value: T } | null = null;\n\n  const ensure = () => (cached ??= { value: fn() }).value;\n  ensure.clear = () => {\n    cached = null;\n  };\n\n  return ensure;\n};\n","import { existsSync, statSync } from \"node:fs\";\nimport { dirname, join, normalize, resolve } from \"node:path\";\n\n/**\n * File extensions to try when resolving module specifiers.\n * Ordered to match TypeScript's module resolution order.\n * @see https://www.typescriptlang.org/docs/handbook/module-resolution.html\n */\nexport const MODULE_EXTENSION_CANDIDATES = [\".ts\", \".tsx\", \".mts\", \".cts\", \".js\", \".mjs\", \".cjs\", \".jsx\"] as const;\n\n/**\n * Normalize path to use forward slashes (cross-platform).\n * Ensures consistent path handling across platforms.\n */\nexport const normalizePath = (value: string): string => normalize(value).replace(/\\\\/g, \"/\");\n\n/**\n * Resolve a relative import specifier to an absolute file path.\n * Tries the specifier as-is, with extensions, and as a directory with index files.\n *\n * @param from - Absolute path to the importing file\n * @param specifier - Relative module specifier (must start with '.')\n * @returns Absolute POSIX path to the resolved file, or null if not found\n */\nexport const resolveRelativeImportWithExistenceCheck = ({\n  filePath,\n  specifier,\n}: {\n  filePath: string;\n  specifier: string;\n}): string | null => {\n  const base = resolve(dirname(filePath), specifier);\n\n  // Try with extensions first (most common case)\n  // This handles cases like \"./constants\" resolving to \"./constants.ts\"\n  // even when a \"./constants\" directory exists\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = `${base}${ext}`;\n    if (existsSync(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  // Try as directory with index files\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = join(base, `index${ext}`);\n    if (existsSync(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  // Try exact path last (only if it's a file, not directory)\n  if (existsSync(base)) {\n    try {\n      const stat = statSync(base);\n      if (stat.isFile()) {\n        return normalizePath(base);\n      }\n    } catch {\n      // Ignore stat errors\n    }\n  }\n\n  return null;\n};\n\n/**\n * Resolve a relative import specifier to an absolute file path.\n * Tries the specifier as-is, with extensions, and as a directory with index files.\n *\n * @param from - Absolute path to the importing file\n * @param specifier - Relative module specifier (must start with '.')\n * @returns Absolute POSIX path to the resolved file, or null if not found\n */\nexport const resolveRelativeImportWithReferences = <_>({\n  filePath,\n  specifier,\n  references,\n}: {\n  filePath: string;\n  specifier: string;\n  references: Map<string, _> | Set<string>;\n}): string | null => {\n  const base = resolve(dirname(filePath), specifier);\n\n  // Try exact path first\n  if (references.has(base)) {\n    return normalizePath(base);\n  }\n\n  // Try with extensions\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = `${base}${ext}`;\n    if (references.has(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  // Try as directory with index files\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = join(base, `index${ext}`);\n    if (references.has(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  return null;\n};\n\n/**\n * Check if a module specifier is relative (starts with '.' or '..')\n */\nexport const isRelativeSpecifier = (specifier: string): boolean => specifier.startsWith(\"./\") || specifier.startsWith(\"../\");\n\n/**\n * Check if a module specifier is external (package name, not relative)\n */\nexport const isExternalSpecifier = (specifier: string): boolean => !isRelativeSpecifier(specifier);\n"],"mappings":";;;;;AAAA,MAAa,YAAe,OAAgB;CAC1C,IAAIA,SAA8B;CAElC,MAAM,gBAAgB,WAAW,EAAE,OAAO,IAAI,EAAE,EAAE;AAClD,QAAO,cAAc;AACnB,WAAS;;AAGX,QAAO;;;;;;;;;;ACAT,MAAa,8BAA8B;CAAC;CAAO;CAAQ;CAAQ;CAAQ;CAAO;CAAQ;CAAQ;CAAO;;;;;AAMzG,MAAa,iBAAiB,mCAAoC,MAAM,CAAC,QAAQ,OAAO,IAAI;;;;;;;;;AAU5F,MAAa,2CAA2C,EACtD,UACA,gBAImB;CACnB,MAAM,qDAAuB,SAAS,EAAE,UAAU;AAKlD,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,YAAY,GAAG,OAAO;AAC5B,8BAAe,UAAU,EAAE;AACzB,UAAO,cAAc,UAAU;;;AAKnC,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,gCAAiB,MAAM,QAAQ,MAAM;AAC3C,8BAAe,UAAU,EAAE;AACzB,UAAO,cAAc,UAAU;;;AAKnC,6BAAe,KAAK,EAAE;AACpB,MAAI;GACF,MAAM,6BAAgB,KAAK;AAC3B,OAAI,KAAK,QAAQ,EAAE;AACjB,WAAO,cAAc,KAAK;;UAEtB;;AAKV,QAAO;;;;;;;;;;AAWT,MAAa,uCAA0C,EACrD,UACA,WACA,iBAKmB;CACnB,MAAM,qDAAuB,SAAS,EAAE,UAAU;AAGlD,KAAI,WAAW,IAAI,KAAK,EAAE;AACxB,SAAO,cAAc,KAAK;;AAI5B,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,YAAY,GAAG,OAAO;AAC5B,MAAI,WAAW,IAAI,UAAU,EAAE;AAC7B,UAAO,cAAc,UAAU;;;AAKnC,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,gCAAiB,MAAM,QAAQ,MAAM;AAC3C,MAAI,WAAW,IAAI,UAAU,EAAE;AAC7B,UAAO,cAAc,UAAU;;;AAInC,QAAO;;;;;AAMT,MAAa,uBAAuB,cAA+B,UAAU,WAAW,KAAK,IAAI,UAAU,WAAW,MAAM;;;;AAK5H,MAAa,uBAAuB,cAA+B,CAAC,oBAAoB,UAAU"}
+{"version":3,"file":"utils-CsTwS1dw.cjs","names":["cached: { value: T } | null"],"sources":["../src/utils/cached-fn.ts","../src/utils/path.ts"],"sourcesContent":["export const cachedFn = <T>(fn: () => T) => {\n  let cached: { value: T } | null = null;\n\n  const ensure = () => (cached ??= { value: fn() }).value;\n  ensure.clear = () => {\n    cached = null;\n  };\n\n  return ensure;\n};\n","import { existsSync, statSync } from \"node:fs\";\nimport { dirname, join, normalize, resolve } from \"node:path\";\n\n/**\n * File extensions to try when resolving module specifiers.\n * Ordered to match TypeScript's module resolution order.\n * @see https://www.typescriptlang.org/docs/handbook/module-resolution.html\n */\nexport const MODULE_EXTENSION_CANDIDATES = [\".ts\", \".tsx\", \".mts\", \".cts\", \".js\", \".mjs\", \".cjs\", \".jsx\"] as const;\n\n/**\n * Normalize path to use forward slashes (cross-platform).\n * Ensures consistent path handling across platforms.\n */\nexport const normalizePath = (value: string): string => normalize(value).replace(/\\\\/g, \"/\");\n\n/**\n * Resolve a relative import specifier to an absolute file path.\n * Tries the specifier as-is, with extensions, and as a directory with index files.\n *\n * @param from - Absolute path to the importing file\n * @param specifier - Relative module specifier (must start with '.')\n * @returns Absolute POSIX path to the resolved file, or null if not found\n */\nexport const resolveRelativeImportWithExistenceCheck = ({\n  filePath,\n  specifier,\n}: {\n  filePath: string;\n  specifier: string;\n}): string | null => {\n  const base = resolve(dirname(filePath), specifier);\n\n  // Try with extensions first (most common case)\n  // This handles cases like \"./constants\" resolving to \"./constants.ts\"\n  // even when a \"./constants\" directory exists\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = `${base}${ext}`;\n    if (existsSync(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  // Try as directory with index files\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = join(base, `index${ext}`);\n    if (existsSync(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  // Try exact path last (only if it's a file, not directory)\n  if (existsSync(base)) {\n    try {\n      const stat = statSync(base);\n      if (stat.isFile()) {\n        return normalizePath(base);\n      }\n    } catch {\n      // Ignore stat errors\n    }\n  }\n\n  return null;\n};\n\n/**\n * Resolve a relative import specifier to an absolute file path.\n * Tries the specifier as-is, with extensions, and as a directory with index files.\n *\n * @param from - Absolute path to the importing file\n * @param specifier - Relative module specifier (must start with '.')\n * @returns Absolute POSIX path to the resolved file, or null if not found\n */\nexport const resolveRelativeImportWithReferences = <_>({\n  filePath,\n  specifier,\n  references,\n}: {\n  filePath: string;\n  specifier: string;\n  references: Map<string, _> | Set<string>;\n}): string | null => {\n  const base = resolve(dirname(filePath), specifier);\n\n  // Try exact path first\n  if (references.has(base)) {\n    return normalizePath(base);\n  }\n\n  // Try with extensions\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = `${base}${ext}`;\n    if (references.has(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  // Try as directory with index files\n  for (const ext of MODULE_EXTENSION_CANDIDATES) {\n    const candidate = join(base, `index${ext}`);\n    if (references.has(candidate)) {\n      return normalizePath(candidate);\n    }\n  }\n\n  return null;\n};\n\n/**\n * Check if a module specifier is relative (starts with '.' or '..')\n */\nexport const isRelativeSpecifier = (specifier: string): boolean => specifier.startsWith(\"./\") || specifier.startsWith(\"../\");\n\n/**\n * Check if a module specifier is external (package name, not relative)\n */\nexport const isExternalSpecifier = (specifier: string): boolean => !isRelativeSpecifier(specifier);\n"],"mappings":";;;;;AAAA,MAAa,YAAe,OAAgB;CAC1C,IAAIA,SAA8B;CAElC,MAAM,gBAAgB,WAAW,EAAE,OAAO,IAAI,EAAE,EAAE;AAClD,QAAO,cAAc;AACnB,WAAS;;AAGX,QAAO;;;;;;;;;;ACAT,MAAa,8BAA8B;CAAC;CAAO;CAAQ;CAAQ;CAAQ;CAAO;CAAQ;CAAQ;CAAO;;;;;AAMzG,MAAa,iBAAiB,mCAAoC,MAAM,CAAC,QAAQ,OAAO,IAAI;;;;;;;;;AAU5F,MAAa,2CAA2C,EACtD,UACA,gBAImB;CACnB,MAAM,qDAAuB,SAAS,EAAE,UAAU;AAKlD,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,YAAY,GAAG,OAAO;AAC5B,8BAAe,UAAU,EAAE;AACzB,UAAO,cAAc,UAAU;;;AAKnC,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,gCAAiB,MAAM,QAAQ,MAAM;AAC3C,8BAAe,UAAU,EAAE;AACzB,UAAO,cAAc,UAAU;;;AAKnC,6BAAe,KAAK,EAAE;AACpB,MAAI;GACF,MAAM,6BAAgB,KAAK;AAC3B,OAAI,KAAK,QAAQ,EAAE;AACjB,WAAO,cAAc,KAAK;;UAEtB;;AAKV,QAAO;;;;;;;;;;AAWT,MAAa,uCAA0C,EACrD,UACA,WACA,iBAKmB;CACnB,MAAM,qDAAuB,SAAS,EAAE,UAAU;AAGlD,KAAI,WAAW,IAAI,KAAK,EAAE;AACxB,SAAO,cAAc,KAAK;;AAI5B,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,YAAY,GAAG,OAAO;AAC5B,MAAI,WAAW,IAAI,UAAU,EAAE;AAC7B,UAAO,cAAc,UAAU;;;AAKnC,MAAK,MAAM,OAAO,6BAA6B;EAC7C,MAAM,gCAAiB,MAAM,QAAQ,MAAM;AAC3C,MAAI,WAAW,IAAI,UAAU,EAAE;AAC7B,UAAO,cAAc,UAAU;;;AAInC,QAAO;;;;;AAMT,MAAa,uBAAuB,cAA+B,UAAU,WAAW,KAAK,IAAI,UAAU,WAAW,MAAM;;;;AAK5H,MAAa,uBAAuB,cAA+B,CAAC,oBAAoB,UAAU"}

package/dist/utils.cjs

@@ -1,4 +1,4 @@
-const require_utils = require('./utils-CmLf7LU5.cjs');
+const require_utils = require('./utils-CsTwS1dw.cjs');
 
 exports.MODULE_EXTENSION_CANDIDATES = require_utils.MODULE_EXTENSION_CANDIDATES;
 exports.cachedFn = require_utils.cachedFn;

package/dist/{zod-CynYgOoN.cjs → zod-C_6JfuYV.cjs}

@@ -1,4 +1,4 @@
-const require_canonical_id = require('./canonical-id-BFcryTw5.cjs');
+const require_canonical_id = require('./canonical-id-CgMNOZyn.cjs');
 let zod = require("zod");
 
 //#region packages/common/src/zod/schema-helper.ts
@@ -13,4 +13,4 @@ Object.defineProperty(exports, 'defineSchemaFor', {
     return defineSchemaFor;
   }
 });
-//# sourceMappingURL=zod-CynYgOoN.cjs.map
+//# sourceMappingURL=zod-C_6JfuYV.cjs.map

package/dist/{zod-CynYgOoN.cjs.map → zod-C_6JfuYV.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"zod-CynYgOoN.cjs","names":["z"],"sources":["../src/zod/schema-helper.ts"],"sourcesContent":["import { z } from \"zod\";\n\n// biome-ignore lint/suspicious/noExplicitAny: abstract type\nexport type SchemaFor<TOutput> = z.ZodType<TOutput, any, any>;\n\nexport type ShapeFor<TOutput extends object> = { [K in keyof TOutput]-?: SchemaFor<TOutput[K]> };\n\nexport function defineSchemaFor<TOutput extends object>() {\n  return <TShape extends ShapeFor<NoInfer<TOutput>>>(shape: TShape & { [K in Exclude<keyof TShape, keyof TOutput>]: never }) =>\n    z.object(shape).strict();\n}\n"],"mappings":";;;;AAOA,SAAgB,kBAA0C;AACxD,SAAmD,UACjDA,MAAE,OAAO,MAAM,CAAC,QAAQ"}
+{"version":3,"file":"zod-C_6JfuYV.cjs","names":["z"],"sources":["../src/zod/schema-helper.ts"],"sourcesContent":["import { z } from \"zod\";\n\n// biome-ignore lint/suspicious/noExplicitAny: abstract type\nexport type SchemaFor<TOutput> = z.ZodType<TOutput, any, any>;\n\nexport type ShapeFor<TOutput extends object> = { [K in keyof TOutput]-?: SchemaFor<TOutput[K]> };\n\nexport function defineSchemaFor<TOutput extends object>() {\n  return <TShape extends ShapeFor<NoInfer<TOutput>>>(shape: TShape & { [K in Exclude<keyof TShape, keyof TOutput>]: never }) =>\n    z.object(shape).strict();\n}\n"],"mappings":";;;;AAOA,SAAgB,kBAA0C;AACxD,SAAmD,UACjDA,MAAE,OAAO,MAAM,CAAC,QAAQ"}

package/dist/zod.cjs

@@ -1,3 +1,3 @@
-const require_zod = require('./zod-CynYgOoN.cjs');
+const require_zod = require('./zod-C_6JfuYV.cjs');
 
 exports.defineSchemaFor = require_zod.defineSchemaFor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soda-gql/common",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Shared utilities for soda-gql packages",
   "type": "module",
   "private": false,

package/dist/canonical-id-BFcryTw5.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonical-id-BFcryTw5.cjs","names":["CanonicalIdSchema: z.ZodType<CanonicalId>","z","normalizePath","scopeStack: ScopeFrame[]","frame: ScopeFrame","exportBinding: string | undefined"],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":["import { isAbsolute, resolve } from \"node:path\";\nimport z from \"zod\";\nimport { normalizePath } from \"../utils\";\n\nexport type CanonicalId = string & { readonly __brand: \"CanonicalId\" };\n\nconst canonicalIdSeparator = \"::\" as const;\n\nexport const CanonicalIdSchema: z.ZodType<CanonicalId> = z.string() as unknown as z.ZodType<CanonicalId>;\n\n// Type-safe schema for CanonicalId - validates as string but types as branded\nexport const createCanonicalId = (filePath: string, astPath: string): CanonicalId => {\n  if (!isAbsolute(filePath)) {\n    throw new Error(\"[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH\");\n  }\n\n  const resolved = resolve(filePath);\n  const normalized = normalizePath(resolved);\n\n  // Create a 2-part ID: {absPath}::{astPath}\n  // astPath uniquely identifies the definition's location in the AST (e.g., \"MyComponent.useQuery.def\")\n  const idParts = [normalized, astPath];\n\n  return idParts.join(canonicalIdSeparator) as CanonicalId;\n};\n","/**\n * Canonical path tracker for AST traversal.\n *\n * This module provides a stateful helper that tracks scope information during\n * AST traversal to generate canonical IDs. It's designed to integrate with\n * existing plugin visitor patterns (Babel, SWC, TypeScript) without requiring\n * a separate AST traversal.\n *\n * Usage pattern:\n * 1. Plugin creates tracker at file/program entry\n * 2. Plugin calls enterScope/exitScope during its traversal\n * 3. Plugin calls registerDefinition when discovering GQL definitions\n * 4. Tracker provides canonical ID information\n */\n\nimport type { CanonicalId } from \"./canonical-id\";\nimport { createCanonicalId } from \"./canonical-id\";\n\n/**\n * Scope frame for tracking AST path segments\n */\nexport type ScopeFrame = {\n  /** Name segment (e.g., \"MyComponent\", \"useQuery\", \"arrow#1\") */\n  readonly nameSegment: string;\n  /** Kind of scope */\n  readonly kind: \"function\" | \"class\" | \"variable\" | \"property\" | \"method\" | \"expression\";\n  /** Occurrence index for disambiguation */\n  readonly occurrence: number;\n};\n\n/**\n * Opaque handle for scope tracking\n */\nexport type ScopeHandle = {\n  readonly __brand: \"ScopeHandle\";\n  readonly depth: number;\n};\n\n/**\n * Canonical path tracker interface\n */\nexport interface CanonicalPathTracker {\n  /**\n   * Enter a new scope during traversal\n   * @param options Scope information\n   * @returns Handle to use when exiting the scope\n   */\n  enterScope(options: { segment: string; kind: ScopeFrame[\"kind\"]; stableKey?: string }): ScopeHandle;\n\n  /**\n   * Exit a scope during traversal\n   * @param handle Handle returned from enterScope\n   */\n  exitScope(handle: ScopeHandle): void;\n\n  /**\n   * Register a definition discovered during traversal\n   * @returns Definition metadata including astPath and canonical ID information\n   */\n  registerDefinition(): {\n    astPath: string;\n    isTopLevel: boolean;\n    exportBinding?: string;\n  };\n\n  /**\n   * Resolve a canonical ID from an astPath\n   * @param astPath AST path string\n   * @returns Canonical ID\n   */\n  resolveCanonicalId(astPath: string): CanonicalId;\n\n  /**\n   * Register an export binding\n   * @param local Local variable name\n   * @param exported Exported name\n   */\n  registerExportBinding(local: string, exported: string): void;\n\n  /**\n   * Get current scope depth\n   * @returns Current depth (0 = top level)\n   */\n  currentDepth(): number;\n}\n\n/**\n * Build AST path from scope stack (internal helper)\n */\nconst _buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n\n/**\n * Create a canonical path tracker\n *\n * @param options Configuration options\n * @returns Tracker instance\n *\n * @example\n * ```typescript\n * // In a Babel plugin\n * const tracker = createCanonicalTracker({ filePath: state.filename });\n *\n * const visitor = {\n *   FunctionDeclaration: {\n *     enter(path) {\n *       const handle = tracker.enterScope({\n *         segment: path.node.id.name,\n *         kind: 'function'\n *       });\n *     },\n *     exit(path) {\n *       tracker.exitScope(handle);\n *     }\n *   }\n * };\n * ```\n */\nexport const createCanonicalTracker = (options: {\n  filePath: string;\n  getExportName?: (localName: string) => string | undefined;\n}): CanonicalPathTracker => {\n  const { filePath, getExportName } = options;\n\n  // Scope stack\n  const scopeStack: ScopeFrame[] = [];\n\n  // Occurrence counters for disambiguating duplicate names\n  const occurrenceCounters = new Map<string, number>();\n\n  // Used paths for ensuring uniqueness\n  const usedPaths = new Set<string>();\n\n  // Export bindings map\n  const exportBindings = new Map<string, string>();\n\n  const getNextOccurrence = (key: string): number => {\n    const current = occurrenceCounters.get(key) ?? 0;\n    occurrenceCounters.set(key, current + 1);\n    return current;\n  };\n\n  const ensureUniquePath = (basePath: string): string => {\n    let path = basePath;\n    let suffix = 0;\n    while (usedPaths.has(path)) {\n      suffix++;\n      path = `${basePath}$${suffix}`;\n    }\n    usedPaths.add(path);\n    return path;\n  };\n\n  return {\n    enterScope({ segment, kind, stableKey }): ScopeHandle {\n      const key = stableKey ?? `${kind}:${segment}`;\n      const occurrence = getNextOccurrence(key);\n\n      const frame: ScopeFrame = {\n        nameSegment: segment,\n        kind,\n        occurrence,\n      };\n\n      scopeStack.push(frame);\n\n      return {\n        __brand: \"ScopeHandle\",\n        depth: scopeStack.length - 1,\n      } as ScopeHandle;\n    },\n\n    exitScope(handle: ScopeHandle): void {\n      // Validate handle depth matches current stack\n      if (handle.depth !== scopeStack.length - 1) {\n        throw new Error(`[INTERNAL] Invalid scope exit: expected depth ${scopeStack.length - 1}, got ${handle.depth}`);\n      }\n      scopeStack.pop();\n    },\n\n    registerDefinition(): {\n      astPath: string;\n      isTopLevel: boolean;\n      exportBinding?: string;\n    } {\n      const basePath = _buildAstPath(scopeStack);\n      const astPath = ensureUniquePath(basePath);\n      const isTopLevel = scopeStack.length === 0;\n\n      // Check export binding if provided\n      let exportBinding: string | undefined;\n      if (getExportName && isTopLevel) {\n        // For top-level definitions, try to get export name\n        // This is a simplified version - real logic depends on how the definition is bound\n        exportBinding = undefined;\n      }\n\n      return {\n        astPath,\n        isTopLevel,\n        exportBinding,\n      };\n    },\n\n    resolveCanonicalId(astPath: string): CanonicalId {\n      return createCanonicalId(filePath, astPath);\n    },\n\n    registerExportBinding(local: string, exported: string): void {\n      exportBindings.set(local, exported);\n    },\n\n    currentDepth(): number {\n      return scopeStack.length;\n    },\n  };\n};\n\n/**\n * Helper to create occurrence tracker (for backward compatibility)\n */\nexport const createOccurrenceTracker = (): {\n  getNextOccurrence: (key: string) => number;\n} => {\n  const occurrenceCounters = new Map<string, number>();\n\n  return {\n    getNextOccurrence(key: string): number {\n      const current = occurrenceCounters.get(key) ?? 0;\n      occurrenceCounters.set(key, current + 1);\n      return current;\n    },\n  };\n};\n\n/**\n * Helper to create path tracker (for backward compatibility)\n */\nexport const createPathTracker = (): {\n  ensureUniquePath: (basePath: string) => string;\n} => {\n  const usedPaths = new Set<string>();\n\n  return {\n    ensureUniquePath(basePath: string): string {\n      let path = basePath;\n      let suffix = 0;\n      while (usedPaths.has(path)) {\n        suffix++;\n        path = `${basePath}$${suffix}`;\n      }\n      usedPaths.add(path);\n      return path;\n    },\n  };\n};\n\n/**\n * Build AST path from scope stack (for backward compatibility)\n */\nexport const buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMA,MAAM,uBAAuB;AAE7B,MAAaA,oBAA4CC,YAAE,QAAQ;AAGnE,MAAa,qBAAqB,UAAkB,YAAiC;AACnF,KAAI,2BAAY,SAAS,EAAE;AACzB,QAAM,IAAI,MAAM,iDAAiD;;CAGnE,MAAM,kCAAmB,SAAS;CAClC,MAAM,aAAaC,4BAAc,SAAS;CAI1C,MAAM,UAAU,CAAC,YAAY,QAAQ;AAErC,QAAO,QAAQ,KAAK,qBAAqB;;;;;;;;ACkE3C,MAAM,iBAAiB,UAAyC;AAC9D,QAAO,MAAM,KAAK,UAAU,MAAM,YAAY,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6B1D,MAAa,0BAA0B,YAGX;CAC1B,MAAM,EAAE,UAAU,kBAAkB;CAGpC,MAAMC,aAA2B,EAAE;CAGnC,MAAM,qBAAqB,IAAI,KAAqB;CAGpD,MAAM,YAAY,IAAI,KAAa;CAGnC,MAAM,iBAAiB,IAAI,KAAqB;CAEhD,MAAM,qBAAqB,QAAwB;EACjD,MAAM,UAAU,mBAAmB,IAAI,IAAI,IAAI;AAC/C,qBAAmB,IAAI,KAAK,UAAU,EAAE;AACxC,SAAO;;CAGT,MAAM,oBAAoB,aAA6B;EACrD,IAAI,OAAO;EACX,IAAI,SAAS;AACb,SAAO,UAAU,IAAI,KAAK,EAAE;AAC1B;AACA,UAAO,GAAG,SAAS,GAAG;;AAExB,YAAU,IAAI,KAAK;AACnB,SAAO;;AAGT,QAAO;EACL,WAAW,EAAE,SAAS,MAAM,aAA0B;GACpD,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG;GACpC,MAAM,aAAa,kBAAkB,IAAI;GAEzC,MAAMC,QAAoB;IACxB,aAAa;IACb;IACA;IACD;AAED,cAAW,KAAK,MAAM;AAEtB,UAAO;IACL,SAAS;IACT,OAAO,WAAW,SAAS;IAC5B;;EAGH,UAAU,QAA2B;AAEnC,OAAI,OAAO,UAAU,WAAW,SAAS,GAAG;AAC1C,UAAM,IAAI,MAAM,iDAAiD,WAAW,SAAS,EAAE,QAAQ,OAAO,QAAQ;;AAEhH,cAAW,KAAK;;EAGlB,qBAIE;GACA,MAAM,WAAW,cAAc,WAAW;GAC1C,MAAM,UAAU,iBAAiB,SAAS;GAC1C,MAAM,aAAa,WAAW,WAAW;GAGzC,IAAIC;AACJ,OAAI,iBAAiB,YAAY;AAG/B,oBAAgB;;AAGlB,UAAO;IACL;IACA;IACA;IACD;;EAGH,mBAAmB,SAA8B;AAC/C,UAAO,kBAAkB,UAAU,QAAQ;;EAG7C,sBAAsB,OAAe,UAAwB;AAC3D,kBAAe,IAAI,OAAO,SAAS;;EAGrC,eAAuB;AACrB,UAAO,WAAW;;EAErB;;;;;AAMH,MAAa,gCAER;CACH,MAAM,qBAAqB,IAAI,KAAqB;AAEpD,QAAO,EACL,kBAAkB,KAAqB;EACrC,MAAM,UAAU,mBAAmB,IAAI,IAAI,IAAI;AAC/C,qBAAmB,IAAI,KAAK,UAAU,EAAE;AACxC,SAAO;IAEV;;;;;AAMH,MAAa,0BAER;CACH,MAAM,YAAY,IAAI,KAAa;AAEnC,QAAO,EACL,iBAAiB,UAA0B;EACzC,IAAI,OAAO;EACX,IAAI,SAAS;AACb,SAAO,UAAU,IAAI,KAAK,EAAE;AAC1B;AACA,UAAO,GAAG,SAAS,GAAG;;AAExB,YAAU,IAAI,KAAK;AACnB,SAAO;IAEV;;;;;AAMH,MAAa,gBAAgB,UAAyC;AACpE,QAAO,MAAM,KAAK,UAAU,MAAM,YAAY,CAAC,KAAK,IAAI"}

package/dist/canonical-id-BFnyQGST.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonical-id-BFnyQGST.mjs","names":["CanonicalIdSchema: z.ZodType<CanonicalId>","z","scopeStack: ScopeFrame[]","frame: ScopeFrame","exportBinding: string | undefined"],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":["import { isAbsolute, resolve } from \"node:path\";\nimport z from \"zod\";\nimport { normalizePath } from \"../utils\";\n\nexport type CanonicalId = string & { readonly __brand: \"CanonicalId\" };\n\nconst canonicalIdSeparator = \"::\" as const;\n\nexport const CanonicalIdSchema: z.ZodType<CanonicalId> = z.string() as unknown as z.ZodType<CanonicalId>;\n\n// Type-safe schema for CanonicalId - validates as string but types as branded\nexport const createCanonicalId = (filePath: string, astPath: string): CanonicalId => {\n  if (!isAbsolute(filePath)) {\n    throw new Error(\"[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH\");\n  }\n\n  const resolved = resolve(filePath);\n  const normalized = normalizePath(resolved);\n\n  // Create a 2-part ID: {absPath}::{astPath}\n  // astPath uniquely identifies the definition's location in the AST (e.g., \"MyComponent.useQuery.def\")\n  const idParts = [normalized, astPath];\n\n  return idParts.join(canonicalIdSeparator) as CanonicalId;\n};\n","/**\n * Canonical path tracker for AST traversal.\n *\n * This module provides a stateful helper that tracks scope information during\n * AST traversal to generate canonical IDs. It's designed to integrate with\n * existing plugin visitor patterns (Babel, SWC, TypeScript) without requiring\n * a separate AST traversal.\n *\n * Usage pattern:\n * 1. Plugin creates tracker at file/program entry\n * 2. Plugin calls enterScope/exitScope during its traversal\n * 3. Plugin calls registerDefinition when discovering GQL definitions\n * 4. Tracker provides canonical ID information\n */\n\nimport type { CanonicalId } from \"./canonical-id\";\nimport { createCanonicalId } from \"./canonical-id\";\n\n/**\n * Scope frame for tracking AST path segments\n */\nexport type ScopeFrame = {\n  /** Name segment (e.g., \"MyComponent\", \"useQuery\", \"arrow#1\") */\n  readonly nameSegment: string;\n  /** Kind of scope */\n  readonly kind: \"function\" | \"class\" | \"variable\" | \"property\" | \"method\" | \"expression\";\n  /** Occurrence index for disambiguation */\n  readonly occurrence: number;\n};\n\n/**\n * Opaque handle for scope tracking\n */\nexport type ScopeHandle = {\n  readonly __brand: \"ScopeHandle\";\n  readonly depth: number;\n};\n\n/**\n * Canonical path tracker interface\n */\nexport interface CanonicalPathTracker {\n  /**\n   * Enter a new scope during traversal\n   * @param options Scope information\n   * @returns Handle to use when exiting the scope\n   */\n  enterScope(options: { segment: string; kind: ScopeFrame[\"kind\"]; stableKey?: string }): ScopeHandle;\n\n  /**\n   * Exit a scope during traversal\n   * @param handle Handle returned from enterScope\n   */\n  exitScope(handle: ScopeHandle): void;\n\n  /**\n   * Register a definition discovered during traversal\n   * @returns Definition metadata including astPath and canonical ID information\n   */\n  registerDefinition(): {\n    astPath: string;\n    isTopLevel: boolean;\n    exportBinding?: string;\n  };\n\n  /**\n   * Resolve a canonical ID from an astPath\n   * @param astPath AST path string\n   * @returns Canonical ID\n   */\n  resolveCanonicalId(astPath: string): CanonicalId;\n\n  /**\n   * Register an export binding\n   * @param local Local variable name\n   * @param exported Exported name\n   */\n  registerExportBinding(local: string, exported: string): void;\n\n  /**\n   * Get current scope depth\n   * @returns Current depth (0 = top level)\n   */\n  currentDepth(): number;\n}\n\n/**\n * Build AST path from scope stack (internal helper)\n */\nconst _buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n\n/**\n * Create a canonical path tracker\n *\n * @param options Configuration options\n * @returns Tracker instance\n *\n * @example\n * ```typescript\n * // In a Babel plugin\n * const tracker = createCanonicalTracker({ filePath: state.filename });\n *\n * const visitor = {\n *   FunctionDeclaration: {\n *     enter(path) {\n *       const handle = tracker.enterScope({\n *         segment: path.node.id.name,\n *         kind: 'function'\n *       });\n *     },\n *     exit(path) {\n *       tracker.exitScope(handle);\n *     }\n *   }\n * };\n * ```\n */\nexport const createCanonicalTracker = (options: {\n  filePath: string;\n  getExportName?: (localName: string) => string | undefined;\n}): CanonicalPathTracker => {\n  const { filePath, getExportName } = options;\n\n  // Scope stack\n  const scopeStack: ScopeFrame[] = [];\n\n  // Occurrence counters for disambiguating duplicate names\n  const occurrenceCounters = new Map<string, number>();\n\n  // Used paths for ensuring uniqueness\n  const usedPaths = new Set<string>();\n\n  // Export bindings map\n  const exportBindings = new Map<string, string>();\n\n  const getNextOccurrence = (key: string): number => {\n    const current = occurrenceCounters.get(key) ?? 0;\n    occurrenceCounters.set(key, current + 1);\n    return current;\n  };\n\n  const ensureUniquePath = (basePath: string): string => {\n    let path = basePath;\n    let suffix = 0;\n    while (usedPaths.has(path)) {\n      suffix++;\n      path = `${basePath}$${suffix}`;\n    }\n    usedPaths.add(path);\n    return path;\n  };\n\n  return {\n    enterScope({ segment, kind, stableKey }): ScopeHandle {\n      const key = stableKey ?? `${kind}:${segment}`;\n      const occurrence = getNextOccurrence(key);\n\n      const frame: ScopeFrame = {\n        nameSegment: segment,\n        kind,\n        occurrence,\n      };\n\n      scopeStack.push(frame);\n\n      return {\n        __brand: \"ScopeHandle\",\n        depth: scopeStack.length - 1,\n      } as ScopeHandle;\n    },\n\n    exitScope(handle: ScopeHandle): void {\n      // Validate handle depth matches current stack\n      if (handle.depth !== scopeStack.length - 1) {\n        throw new Error(`[INTERNAL] Invalid scope exit: expected depth ${scopeStack.length - 1}, got ${handle.depth}`);\n      }\n      scopeStack.pop();\n    },\n\n    registerDefinition(): {\n      astPath: string;\n      isTopLevel: boolean;\n      exportBinding?: string;\n    } {\n      const basePath = _buildAstPath(scopeStack);\n      const astPath = ensureUniquePath(basePath);\n      const isTopLevel = scopeStack.length === 0;\n\n      // Check export binding if provided\n      let exportBinding: string | undefined;\n      if (getExportName && isTopLevel) {\n        // For top-level definitions, try to get export name\n        // This is a simplified version - real logic depends on how the definition is bound\n        exportBinding = undefined;\n      }\n\n      return {\n        astPath,\n        isTopLevel,\n        exportBinding,\n      };\n    },\n\n    resolveCanonicalId(astPath: string): CanonicalId {\n      return createCanonicalId(filePath, astPath);\n    },\n\n    registerExportBinding(local: string, exported: string): void {\n      exportBindings.set(local, exported);\n    },\n\n    currentDepth(): number {\n      return scopeStack.length;\n    },\n  };\n};\n\n/**\n * Helper to create occurrence tracker (for backward compatibility)\n */\nexport const createOccurrenceTracker = (): {\n  getNextOccurrence: (key: string) => number;\n} => {\n  const occurrenceCounters = new Map<string, number>();\n\n  return {\n    getNextOccurrence(key: string): number {\n      const current = occurrenceCounters.get(key) ?? 0;\n      occurrenceCounters.set(key, current + 1);\n      return current;\n    },\n  };\n};\n\n/**\n * Helper to create path tracker (for backward compatibility)\n */\nexport const createPathTracker = (): {\n  ensureUniquePath: (basePath: string) => string;\n} => {\n  const usedPaths = new Set<string>();\n\n  return {\n    ensureUniquePath(basePath: string): string {\n      let path = basePath;\n      let suffix = 0;\n      while (usedPaths.has(path)) {\n        suffix++;\n        path = `${basePath}$${suffix}`;\n      }\n      usedPaths.add(path);\n      return path;\n    },\n  };\n};\n\n/**\n * Build AST path from scope stack (for backward compatibility)\n */\nexport const buildAstPath = (stack: readonly ScopeFrame[]): string => {\n  return stack.map((frame) => frame.nameSegment).join(\".\");\n};\n"],"mappings":";;;;;AAMA,MAAM,uBAAuB;AAE7B,MAAaA,oBAA4CC,IAAE,QAAQ;AAGnE,MAAa,qBAAqB,UAAkB,YAAiC;AACnF,KAAI,CAAC,WAAW,SAAS,EAAE;AACzB,QAAM,IAAI,MAAM,iDAAiD;;CAGnE,MAAM,WAAW,QAAQ,SAAS;CAClC,MAAM,aAAa,cAAc,SAAS;CAI1C,MAAM,UAAU,CAAC,YAAY,QAAQ;AAErC,QAAO,QAAQ,KAAK,qBAAqB;;;;;;;;ACkE3C,MAAM,iBAAiB,UAAyC;AAC9D,QAAO,MAAM,KAAK,UAAU,MAAM,YAAY,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6B1D,MAAa,0BAA0B,YAGX;CAC1B,MAAM,EAAE,UAAU,kBAAkB;CAGpC,MAAMC,aAA2B,EAAE;CAGnC,MAAM,qBAAqB,IAAI,KAAqB;CAGpD,MAAM,YAAY,IAAI,KAAa;CAGnC,MAAM,iBAAiB,IAAI,KAAqB;CAEhD,MAAM,qBAAqB,QAAwB;EACjD,MAAM,UAAU,mBAAmB,IAAI,IAAI,IAAI;AAC/C,qBAAmB,IAAI,KAAK,UAAU,EAAE;AACxC,SAAO;;CAGT,MAAM,oBAAoB,aAA6B;EACrD,IAAI,OAAO;EACX,IAAI,SAAS;AACb,SAAO,UAAU,IAAI,KAAK,EAAE;AAC1B;AACA,UAAO,GAAG,SAAS,GAAG;;AAExB,YAAU,IAAI,KAAK;AACnB,SAAO;;AAGT,QAAO;EACL,WAAW,EAAE,SAAS,MAAM,aAA0B;GACpD,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG;GACpC,MAAM,aAAa,kBAAkB,IAAI;GAEzC,MAAMC,QAAoB;IACxB,aAAa;IACb;IACA;IACD;AAED,cAAW,KAAK,MAAM;AAEtB,UAAO;IACL,SAAS;IACT,OAAO,WAAW,SAAS;IAC5B;;EAGH,UAAU,QAA2B;AAEnC,OAAI,OAAO,UAAU,WAAW,SAAS,GAAG;AAC1C,UAAM,IAAI,MAAM,iDAAiD,WAAW,SAAS,EAAE,QAAQ,OAAO,QAAQ;;AAEhH,cAAW,KAAK;;EAGlB,qBAIE;GACA,MAAM,WAAW,cAAc,WAAW;GAC1C,MAAM,UAAU,iBAAiB,SAAS;GAC1C,MAAM,aAAa,WAAW,WAAW;GAGzC,IAAIC;AACJ,OAAI,iBAAiB,YAAY;AAG/B,oBAAgB;;AAGlB,UAAO;IACL;IACA;IACA;IACD;;EAGH,mBAAmB,SAA8B;AAC/C,UAAO,kBAAkB,UAAU,QAAQ;;EAG7C,sBAAsB,OAAe,UAAwB;AAC3D,kBAAe,IAAI,OAAO,SAAS;;EAGrC,eAAuB;AACrB,UAAO,WAAW;;EAErB;;;;;AAMH,MAAa,gCAER;CACH,MAAM,qBAAqB,IAAI,KAAqB;AAEpD,QAAO,EACL,kBAAkB,KAAqB;EACrC,MAAM,UAAU,mBAAmB,IAAI,IAAI,IAAI;AAC/C,qBAAmB,IAAI,KAAK,UAAU,EAAE;AACxC,SAAO;IAEV;;;;;AAMH,MAAa,0BAER;CACH,MAAM,YAAY,IAAI,KAAa;AAEnC,QAAO,EACL,iBAAiB,UAA0B;EACzC,IAAI,OAAO;EACX,IAAI,SAAS;AACb,SAAO,UAAU,IAAI,KAAK,EAAE;AAC1B;AACA,UAAO,GAAG,SAAS,GAAG;;AAExB,YAAU,IAAI,KAAK;AACnB,SAAO;IAEV;;;;;AAMH,MAAa,gBAAgB,UAAyC;AACpE,QAAO,MAAM,KAAK,UAAU,MAAM,YAAY,CAAC,KAAK,IAAI"}

package/dist/index-BG7Aiges.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-BG7Aiges.d.cts","names":[],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":[],"mappings":";;;KAIY,WAAA;;AAAZ,CAAA;AAIa,cAAA,iBAA6B,EAAV,GAAA,CAAE,OAAF,CAAU,WAAD,CAAA;AAG5B,cAAA,iBAAyD,EAAA,CAAA,QAarE,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,GAbqE,WAarE;;;;;;AC+FD;AAuGa,KAzMD,UAAA,GAyMC;EAiBA;EAsBA,SAAA,WAEZ,EAAA,MAF4C;;;;;;;;;KApOjC,WAAA;;;;;;;UAQK,oBAAA;;;;;;;;UAM8B;;MAA2C;;;;;oBAMtE;;;;;;;;;;;;;;;uCAiBmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiD1B;;;MAGT;;;;cAoGS;;;;;;cAiBA;;;;;;cAsBA,+BAAgC"}

package/dist/index-C4t2Wbzs.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-C4t2Wbzs.d.mts","names":[],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":[],"mappings":";;;KAIY,WAAA;;AAAZ,CAAA;AAIa,cAAA,iBAA6B,EAAV,GAAA,CAAE,OAAF,CAAU,WAAD,CAAA;AAG5B,cAAA,iBAAyD,EAAA,CAAA,QAarE,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,GAbqE,WAarE;;;;;;AC+FD;AAuGa,KAzMD,UAAA,GAyMC;EAiBA;EAsBA,SAAA,WAEZ,EAAA,MAF4C;;;;;;;;;KApOjC,WAAA;;;;;;;UAQK,oBAAA;;;;;;;;UAM8B;;MAA2C;;;;;oBAMtE;;;;;;;;;;;;;;;uCAiBmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiD1B;;;MAGT;;;;cAoGS;;;;;;cAiBA;;;;;;cAsBA,+BAAgC"}