@soda-gql/common 0.0.1

package/LICENSE

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

package/dist/canonical-id/index.cjs

@@ -0,0 +1,9 @@
+require('../utils-NBAPoMgh.cjs');
+const require_canonical_id = require('../canonical-id-CE4Xjo2C.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;

package/dist/canonical-id/index.d.cts

@@ -0,0 +1,2 @@
+import { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker } from "../index-C8yyrGd7.cjs";
+export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };

package/dist/canonical-id/index.d.ts

@@ -0,0 +1,2 @@
+import { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker } from "../index-D6Lx478n.js";
+export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };

package/dist/canonical-id/index.js

@@ -0,0 +1,4 @@
+import "../utils-DxBnV8tL.js";
+import { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker } from "../canonical-id-Bn6ZPdZl.js";
+
+export { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };

package/dist/canonical-id-Bn6ZPdZl.js

@@ -0,0 +1,155 @@
+import { normalizePath } from "./utils-DxBnV8tL.js";
+import { isAbsolute, resolve } from "node:path";
+import z$1 from "zod";
+
+//#region packages/common/src/canonical-id/canonical-id.ts
+const canonicalIdSeparator = "::";
+const CanonicalIdSchema = z$1.string();
+const createCanonicalId = (filePath, astPath) => {
+	if (!isAbsolute(filePath)) {
+		throw new Error("[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH");
+	}
+	const resolved = resolve(filePath);
+	const normalized = normalizePath(resolved);
+	const idParts = [normalized, astPath];
+	return idParts.join(canonicalIdSeparator);
+};
+
+//#endregion
+//#region packages/common/src/canonical-id/path-tracker.ts
+/**
+* Build AST path from scope stack (internal helper)
+*/
+const _buildAstPath = (stack) => {
+	return stack.map((frame) => frame.nameSegment).join(".");
+};
+/**
+* Create a canonical path tracker
+*
+* @param options Configuration options
+* @returns Tracker instance
+*
+* @example
+* ```typescript
+* // In a Babel plugin
+* const tracker = createCanonicalTracker({ filePath: state.filename });
+*
+* const visitor = {
+*   FunctionDeclaration: {
+*     enter(path) {
+*       const handle = tracker.enterScope({
+*         segment: path.node.id.name,
+*         kind: 'function'
+*       });
+*     },
+*     exit(path) {
+*       tracker.exitScope(handle);
+*     }
+*   }
+* };
+* ```
+*/
+const createCanonicalTracker = (options) => {
+	const { filePath, getExportName } = options;
+	const scopeStack = [];
+	const occurrenceCounters = new Map();
+	const usedPaths = new Set();
+	const exportBindings = new Map();
+	const getNextOccurrence = (key) => {
+		const current = occurrenceCounters.get(key) ?? 0;
+		occurrenceCounters.set(key, current + 1);
+		return current;
+	};
+	const ensureUniquePath = (basePath) => {
+		let path = basePath;
+		let suffix = 0;
+		while (usedPaths.has(path)) {
+			suffix++;
+			path = `${basePath}$${suffix}`;
+		}
+		usedPaths.add(path);
+		return path;
+	};
+	return {
+		enterScope({ segment, kind, stableKey }) {
+			const key = stableKey ?? `${kind}:${segment}`;
+			const occurrence = getNextOccurrence(key);
+			const frame = {
+				nameSegment: segment,
+				kind,
+				occurrence
+			};
+			scopeStack.push(frame);
+			return {
+				__brand: "ScopeHandle",
+				depth: scopeStack.length - 1
+			};
+		},
+		exitScope(handle) {
+			if (handle.depth !== scopeStack.length - 1) {
+				throw new Error(`[INTERNAL] Invalid scope exit: expected depth ${scopeStack.length - 1}, got ${handle.depth}`);
+			}
+			scopeStack.pop();
+		},
+		registerDefinition() {
+			const basePath = _buildAstPath(scopeStack);
+			const astPath = ensureUniquePath(basePath);
+			const isTopLevel = scopeStack.length === 0;
+			let exportBinding;
+			if (getExportName && isTopLevel) {
+				exportBinding = undefined;
+			}
+			return {
+				astPath,
+				isTopLevel,
+				exportBinding
+			};
+		},
+		resolveCanonicalId(astPath) {
+			return createCanonicalId(filePath, astPath);
+		},
+		registerExportBinding(local, exported) {
+			exportBindings.set(local, exported);
+		},
+		currentDepth() {
+			return scopeStack.length;
+		}
+	};
+};
+/**
+* Helper to create occurrence tracker (for backward compatibility)
+*/
+const createOccurrenceTracker = () => {
+	const occurrenceCounters = new Map();
+	return { getNextOccurrence(key) {
+		const current = occurrenceCounters.get(key) ?? 0;
+		occurrenceCounters.set(key, current + 1);
+		return current;
+	} };
+};
+/**
+* Helper to create path tracker (for backward compatibility)
+*/
+const createPathTracker = () => {
+	const usedPaths = new Set();
+	return { ensureUniquePath(basePath) {
+		let path = basePath;
+		let suffix = 0;
+		while (usedPaths.has(path)) {
+			suffix++;
+			path = `${basePath}$${suffix}`;
+		}
+		usedPaths.add(path);
+		return path;
+	} };
+};
+/**
+* Build AST path from scope stack (for backward compatibility)
+*/
+const buildAstPath = (stack) => {
+	return stack.map((frame) => frame.nameSegment).join(".");
+};
+
+//#endregion
+export { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };
+//# sourceMappingURL=canonical-id-Bn6ZPdZl.js.map

package/dist/canonical-id-Bn6ZPdZl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-id-Bn6ZPdZl.js","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/canonical-id-CE4Xjo2C.cjs

@@ -0,0 +1,192 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const require_utils = require('./utils-NBAPoMgh.cjs');
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+let zod = require("zod");
+zod = require_chunk.__toESM(zod);
+
+//#region packages/common/src/canonical-id/canonical-id.ts
+const canonicalIdSeparator = "::";
+const CanonicalIdSchema = zod.default.string();
+const createCanonicalId = (filePath, astPath) => {
+	if (!(0, node_path.isAbsolute)(filePath)) {
+		throw new Error("[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH");
+	}
+	const resolved = (0, node_path.resolve)(filePath);
+	const normalized = require_utils.normalizePath(resolved);
+	const idParts = [normalized, astPath];
+	return idParts.join(canonicalIdSeparator);
+};
+
+//#endregion
+//#region packages/common/src/canonical-id/path-tracker.ts
+/**
+* Build AST path from scope stack (internal helper)
+*/
+const _buildAstPath = (stack) => {
+	return stack.map((frame) => frame.nameSegment).join(".");
+};
+/**
+* Create a canonical path tracker
+*
+* @param options Configuration options
+* @returns Tracker instance
+*
+* @example
+* ```typescript
+* // In a Babel plugin
+* const tracker = createCanonicalTracker({ filePath: state.filename });
+*
+* const visitor = {
+*   FunctionDeclaration: {
+*     enter(path) {
+*       const handle = tracker.enterScope({
+*         segment: path.node.id.name,
+*         kind: 'function'
+*       });
+*     },
+*     exit(path) {
+*       tracker.exitScope(handle);
+*     }
+*   }
+* };
+* ```
+*/
+const createCanonicalTracker = (options) => {
+	const { filePath, getExportName } = options;
+	const scopeStack = [];
+	const occurrenceCounters = new Map();
+	const usedPaths = new Set();
+	const exportBindings = new Map();
+	const getNextOccurrence = (key) => {
+		const current = occurrenceCounters.get(key) ?? 0;
+		occurrenceCounters.set(key, current + 1);
+		return current;
+	};
+	const ensureUniquePath = (basePath) => {
+		let path = basePath;
+		let suffix = 0;
+		while (usedPaths.has(path)) {
+			suffix++;
+			path = `${basePath}$${suffix}`;
+		}
+		usedPaths.add(path);
+		return path;
+	};
+	return {
+		enterScope({ segment, kind, stableKey }) {
+			const key = stableKey ?? `${kind}:${segment}`;
+			const occurrence = getNextOccurrence(key);
+			const frame = {
+				nameSegment: segment,
+				kind,
+				occurrence
+			};
+			scopeStack.push(frame);
+			return {
+				__brand: "ScopeHandle",
+				depth: scopeStack.length - 1
+			};
+		},
+		exitScope(handle) {
+			if (handle.depth !== scopeStack.length - 1) {
+				throw new Error(`[INTERNAL] Invalid scope exit: expected depth ${scopeStack.length - 1}, got ${handle.depth}`);
+			}
+			scopeStack.pop();
+		},
+		registerDefinition() {
+			const basePath = _buildAstPath(scopeStack);
+			const astPath = ensureUniquePath(basePath);
+			const isTopLevel = scopeStack.length === 0;
+			let exportBinding;
+			if (getExportName && isTopLevel) {
+				exportBinding = undefined;
+			}
+			return {
+				astPath,
+				isTopLevel,
+				exportBinding
+			};
+		},
+		resolveCanonicalId(astPath) {
+			return createCanonicalId(filePath, astPath);
+		},
+		registerExportBinding(local, exported) {
+			exportBindings.set(local, exported);
+		},
+		currentDepth() {
+			return scopeStack.length;
+		}
+	};
+};
+/**
+* Helper to create occurrence tracker (for backward compatibility)
+*/
+const createOccurrenceTracker = () => {
+	const occurrenceCounters = new Map();
+	return { getNextOccurrence(key) {
+		const current = occurrenceCounters.get(key) ?? 0;
+		occurrenceCounters.set(key, current + 1);
+		return current;
+	} };
+};
+/**
+* Helper to create path tracker (for backward compatibility)
+*/
+const createPathTracker = () => {
+	const usedPaths = new Set();
+	return { ensureUniquePath(basePath) {
+		let path = basePath;
+		let suffix = 0;
+		while (usedPaths.has(path)) {
+			suffix++;
+			path = `${basePath}$${suffix}`;
+		}
+		usedPaths.add(path);
+		return path;
+	} };
+};
+/**
+* Build AST path from scope stack (for backward compatibility)
+*/
+const buildAstPath = (stack) => {
+	return stack.map((frame) => frame.nameSegment).join(".");
+};
+
+//#endregion
+Object.defineProperty(exports, 'CanonicalIdSchema', {
+  enumerable: true,
+  get: function () {
+    return CanonicalIdSchema;
+  }
+});
+Object.defineProperty(exports, 'buildAstPath', {
+  enumerable: true,
+  get: function () {
+    return buildAstPath;
+  }
+});
+Object.defineProperty(exports, 'createCanonicalId', {
+  enumerable: true,
+  get: function () {
+    return createCanonicalId;
+  }
+});
+Object.defineProperty(exports, 'createCanonicalTracker', {
+  enumerable: true,
+  get: function () {
+    return createCanonicalTracker;
+  }
+});
+Object.defineProperty(exports, 'createOccurrenceTracker', {
+  enumerable: true,
+  get: function () {
+    return createOccurrenceTracker;
+  }
+});
+Object.defineProperty(exports, 'createPathTracker', {
+  enumerable: true,
+  get: function () {
+    return createPathTracker;
+  }
+});

package/dist/chunk-CUT6urMc.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/index-B_QJzQA2.d.cts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+//#region packages/common/src/zod/schema-helper.d.ts
+type SchemaFor<TOutput> = z.ZodType<TOutput, any, any>;
+type ShapeFor<TOutput extends object> = { [K in keyof TOutput]-?: SchemaFor<TOutput[K]> };
+declare function defineSchemaFor<TOutput extends object>(): <TShape extends ShapeFor<NoInfer<TOutput>>>(shape: TShape & { [K in Exclude<keyof TShape, keyof TOutput>]: never }) => z.ZodObject<TShape & { [K in Exclude<keyof TShape, keyof TOutput>]: never } extends infer T ? { -readonly [P in keyof T]: T[P] } : never, z.core.$strict>;
+//#endregion
+export { SchemaFor, ShapeFor, defineSchemaFor };
+//# sourceMappingURL=index-B_QJzQA2.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-B_QJzQA2.d.cts","names":[],"sources":["../src/zod/schema-helper.ts"],"sourcesContent":[],"mappings":";;;KAGY,qBAAqB,CAAA,CAAE,QAAQ;KAE/B,2CAFA,MAEiD,OAFxC,KAEoD,SAFpD,CAE8D,OAF9D,CAEsE,CAFtE,CAAA,CAAA,EAAA;AAAsB,iBAI3B,eAJ2B,CAAA,gBAAA,MAAA,CAAA,CAAA,CAAA,EAAA,CAAA,eAKlB,QALkB,CAKT,OALS,CAKD,OALC,CAAA,CAAA,CAAA,CAAA,KAAA,EAKiB,MALjB,GAAA,QAKkC,OALlC,CAAA,MAKgD,MALhD,EAAA,MAK8D,OAL9D,CAAA,GAAA,KAAA,EAAA,EAAA,GAKgF,CAAA,CAAA,SALhF,CAKgF,MALhF,GAAA,QAK8B,OAL9B,CAAA,MAK8B,MAL9B,EAAA,MAK8B,OAL9B,CAAA,GAAA,KAAA,EAAA,SAAA,KAAA,EAAA,GAAA,kBAAA,MAK8B,CAL9B,GAK8B,CAL9B,CAK8B,CAL9B,CAAA,EAAA,GAAA,KAAA,EAK8B,CAAA,CAAA,IAAA,CAAA,OAL9B,CAAA"}

package/dist/index-C0n5gWc3.d.cts

@@ -0,0 +1,88 @@
+//#region packages/common/src/portable/fs.d.ts
+/**
+ * Portable filesystem API that works on both Bun and Node.js
+ */
+interface PortableFS {
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<{
+    mtime: Date;
+    size: number;
+  }>;
+  rename(oldPath: string, newPath: string): Promise<void>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+}
+declare function createPortableFS(): PortableFS;
+declare function getPortableFS(): PortableFS;
+/**
+ * Reset the filesystem singleton for testing
+ * @internal
+ */
+declare function __resetPortableFSForTests(): void;
+//#endregion
+//#region packages/common/src/portable/hash.d.ts
+/**
+ * Portable hashing API that works on both Bun and Node.js
+ */
+type HashAlgorithm = "sha256" | "xxhash";
+interface PortableHasher {
+  hash(content: string, algorithm?: HashAlgorithm): string;
+}
+declare function createPortableHasher(): PortableHasher;
+declare function getPortableHasher(): PortableHasher;
+/**
+ * Reset the hasher singleton for testing
+ * @internal
+ */
+declare function __resetPortableHasherForTests(): void;
+//#endregion
+//#region packages/common/src/portable/id.d.ts
+/**
+ * Portable ID generation that works on both Bun and Node.js
+ */
+/**
+ * Generate a unique ID
+ * Uses UUIDv7 on Bun (monotonic), falls back to randomUUID on Node.js
+ */
+declare function generateId(): string;
+//#endregion
+//#region packages/common/src/portable/runtime.d.ts
+/**
+ * Runtime detection utilities for portable API implementation
+ */
+declare const runtime: {
+  readonly isBun: boolean;
+  readonly isNode: boolean;
+  readonly supportsWebCrypto: boolean;
+};
+/**
+ * Helper to cache module imports to avoid repeated dynamic imports
+ */
+declare function once<T>(fn: () => T): () => T;
+/**
+ * Reset runtime state for testing purposes only
+ * @internal
+ */
+declare function resetPortableForTests(): void;
+//#endregion
+//#region packages/common/src/portable/spawn.d.ts
+/**
+ * Portable subprocess spawning that works on both Bun and Node.js
+ */
+interface SpawnOptions {
+  cmd: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+}
+interface SpawnResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+declare function spawn(options: SpawnOptions): Promise<SpawnResult>;
+//#endregion
+export { type HashAlgorithm, type PortableFS, type PortableHasher, type SpawnOptions, type SpawnResult, __resetPortableFSForTests, __resetPortableHasherForTests, createPortableFS, createPortableHasher, generateId, getPortableFS, getPortableHasher, once, resetPortableForTests, runtime, spawn };
+//# sourceMappingURL=index-C0n5gWc3.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-C0n5gWc3.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;;AAC0B,UADT,UAAA,CACS;UACkB,CAAA,IAAA,EAAA,MAAA,CAAA,EADlB,OACkB,CAAA,MAAA,CAAA;WACpB,CAAA,IAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,CAAA,EADoB,OACpB,CAAA,IAAA,CAAA;QACe,CAAA,IAAA,EAAA,MAAA,CAAA,EADf,OACe,CAAA,OAAA,CAAA;MAAjB,CAAA,IAAA,EAAA,MAAA,CAAA,EAAA,OAAA,CAAA;IACsB,KAAA,EADL,IACK;IACc,IAAA,EAAA,MAAA;EAAO,CAAA,CAAA;EAsBjD,MAAA,CAAA,OAAA,EAAA,MAAgB,EAAA,OAAI,EAAA,MAAA,CAAA,EAvBQ,OAuBE,CAAA,IAAA,CAAA;EA4F9B,KAAA,CAAA,IAAA,EAAA,MAAa,EAAA,QAAI,EAAA;IAWjB,SAAA,CAAA,EAAA,OAAA;MA7H0C;;iBAsB1C,gBAAA,CAAA,GAAoB;AC5BxB,iBDwHI,aAAA,CAAA,CCxHS,EDwHQ,UCxHR;AAEzB;AAWA;AAqCA;AAWA;iBDsEgB,yBAAA,CAAA;;;;AAnIhB;;AAC0B,KCDd,aAAA,GDCc,QAAA,GAAA,QAAA;AACkB,UCA3B,cAAA,CDA2B;MACpB,CAAA,OAAA,EAAA,MAAA,EAAA,SAAA,CAAA,ECAY,aDAZ,CAAA,EAAA,MAAA;;AACF,iBCSN,oBAAA,CAAA,CDTM,ECSkB,cDTlB;AACsB,iBC6C5B,iBAAA,CAAA,CD7C4B,EC6CP,cD7CO;;;AAuB5C;AA4FA;AAWgB,iBCtEA,6BAAA,CAAA,CDsEyB,EAAA,IAAA;;;;AAnIzC;;;;;;AAIsB,iBEAN,UAAA,CAAA,CFAM,EAAA,MAAA;;;;AAJtB;;AAC0B,cGHb,OHGa,EAAA;WACkB,KAAA,EAAA,OAAA;WACpB,MAAA,EAAA,OAAA;WACe,iBAAA,EAAA,OAAA;;;;;AAwBvB,iBGrBA,IHqBgB,CAAA,CAAA,CAAA,CAAA,EAAI,EAAA,GAAA,GGrBF,CHqBE,CAAA,EAAU,GAAA,GGrBF,CHqBE;AA4F9C;AAWA;;;iBG3GgB,qBAAA,CAAA;;;;AHxBhB;;AAC0B,UIDT,YAAA,CJCS;KACkB,EAAA,MAAA,EAAA;KACpB,CAAA,EAAA,MAAA;KACe,CAAA,EID/B,MJC+B,CAAA,MAAA,EAAA,MAAA,CAAA;;AACK,UIC3B,WAAA,CJD2B;QACc,EAAA,MAAA;EAAO,MAAA,EAAA,MAAA;EAsBjD,QAAA,EAAA,MAAA;AA4FhB;AAWgB,iBIvHM,KAAA,CJuHN,OAAyB,EIvHJ,YJuHI,CAAA,EIvHW,OJuHX,CIvHmB,WJuHnB,CAAA"}

package/dist/index-C8yyrGd7.d.cts

@@ -0,0 +1,124 @@
+import z$1 from "zod";
+
+//#region packages/common/src/canonical-id/canonical-id.d.ts
+type CanonicalId = string & {
+  readonly __brand: "CanonicalId";
+};
+declare const CanonicalIdSchema: z$1.ZodType<CanonicalId>;
+declare const createCanonicalId: (filePath: string, astPath: string) => CanonicalId;
+//#endregion
+//#region packages/common/src/canonical-id/path-tracker.d.ts
+
+/**
+ * Scope frame for tracking AST path segments
+ */
+type ScopeFrame = {
+  /** Name segment (e.g., "MyComponent", "useQuery", "arrow#1") */
+  readonly nameSegment: string;
+  /** Kind of scope */
+  readonly kind: "function" | "class" | "variable" | "property" | "method" | "expression";
+  /** Occurrence index for disambiguation */
+  readonly occurrence: number;
+};
+/**
+ * Opaque handle for scope tracking
+ */
+type ScopeHandle = {
+  readonly __brand: "ScopeHandle";
+  readonly depth: number;
+};
+/**
+ * Canonical path tracker interface
+ */
+interface CanonicalPathTracker {
+  /**
+   * Enter a new scope during traversal
+   * @param options Scope information
+   * @returns Handle to use when exiting the scope
+   */
+  enterScope(options: {
+    segment: string;
+    kind: ScopeFrame["kind"];
+    stableKey?: string;
+  }): ScopeHandle;
+  /**
+   * Exit a scope during traversal
+   * @param handle Handle returned from enterScope
+   */
+  exitScope(handle: ScopeHandle): void;
+  /**
+   * Register a definition discovered during traversal
+   * @returns Definition metadata including astPath and canonical ID information
+   */
+  registerDefinition(): {
+    astPath: string;
+    isTopLevel: boolean;
+    exportBinding?: string;
+  };
+  /**
+   * Resolve a canonical ID from an astPath
+   * @param astPath AST path string
+   * @returns Canonical ID
+   */
+  resolveCanonicalId(astPath: string): CanonicalId;
+  /**
+   * Register an export binding
+   * @param local Local variable name
+   * @param exported Exported name
+   */
+  registerExportBinding(local: string, exported: string): void;
+  /**
+   * Get current scope depth
+   * @returns Current depth (0 = top level)
+   */
+  currentDepth(): number;
+}
+/**
+ * Create a canonical path tracker
+ *
+ * @param options Configuration options
+ * @returns Tracker instance
+ *
+ * @example
+ * ```typescript
+ * // In a Babel plugin
+ * const tracker = createCanonicalTracker({ filePath: state.filename });
+ *
+ * const visitor = {
+ *   FunctionDeclaration: {
+ *     enter(path) {
+ *       const handle = tracker.enterScope({
+ *         segment: path.node.id.name,
+ *         kind: 'function'
+ *       });
+ *     },
+ *     exit(path) {
+ *       tracker.exitScope(handle);
+ *     }
+ *   }
+ * };
+ * ```
+ */
+declare const createCanonicalTracker: (options: {
+  filePath: string;
+  getExportName?: (localName: string) => string | undefined;
+}) => CanonicalPathTracker;
+/**
+ * Helper to create occurrence tracker (for backward compatibility)
+ */
+declare const createOccurrenceTracker: () => {
+  getNextOccurrence: (key: string) => number;
+};
+/**
+ * Helper to create path tracker (for backward compatibility)
+ */
+declare const createPathTracker: () => {
+  ensureUniquePath: (basePath: string) => string;
+};
+/**
+ * Build AST path from scope stack (for backward compatibility)
+ */
+declare const buildAstPath: (stack: readonly ScopeFrame[]) => string;
+//#endregion
+export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker };
+//# sourceMappingURL=index-C8yyrGd7.d.cts.map