@soda-gql/common 0.11.10 → 0.11.12

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

@@ -1,11 +1,28 @@
-import { i as normalizePath } from "./utils-DLEgAn7q.mjs";
-import { isAbsolute, resolve } from "node:path";
+import { s as normalizePath } from "./utils-ZCE_eqCf.mjs";
+import { isAbsolute, relative, 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) => {
+/**
+* Create a canonical ID from a file path and AST path.
+*
+* @param filePath - The file path (absolute, or relative if baseDir is provided)
+* @param astPath - The AST path identifying the definition within the file
+* @param options - Optional configuration including baseDir for relative path support
+* @returns A canonical ID in the format "{path}::{astPath}"
+*/
+const createCanonicalId = (filePath, astPath, options) => {
+	const { baseDir } = options ?? {};
+	if (baseDir) {
+		const absolutePath = isAbsolute(filePath) ? filePath : resolve(baseDir, filePath);
+		const resolved$1 = resolve(absolutePath);
+		const relativePath = relative(baseDir, resolved$1);
+		const normalized$1 = normalizePath(relativePath);
+		const idParts$1 = [normalized$1, astPath];
+		return idParts$1.join(canonicalIdSeparator);
+	}
 	if (!isAbsolute(filePath)) {
 		throw new Error("[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH");
 	}
@@ -15,6 +32,16 @@ const createCanonicalId = (filePath, astPath) => {
 	return idParts.join(canonicalIdSeparator);
 };
 /**
+* Check if a canonical ID uses a relative path.
+* Relative canonical IDs do not start with '/'.
+*
+* @param canonicalId - The canonical ID to check
+* @returns true if the canonical ID uses a relative path
+*/
+const isRelativeCanonicalId = (canonicalId) => {
+	return !canonicalId.startsWith("/");
+};
+/**
 * 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
@@ -32,6 +59,38 @@ const parseCanonicalId = (canonicalId) => {
 		astPath: canonicalId.slice(idx + canonicalIdSeparator.length)
 	};
 };
+/**
+* Validate a canonical ID format.
+* A valid canonical ID has format: "{filePath}::{astPath}"
+* where both filePath and astPath are non-empty.
+*
+* @param canonicalId - The canonical ID to validate
+* @returns Validation result with isValid boolean and optional error reason
+*/
+const validateCanonicalId = (canonicalId) => {
+	const idx = canonicalId.indexOf(canonicalIdSeparator);
+	if (idx === -1) {
+		return {
+			isValid: false,
+			reason: "missing '::' separator"
+		};
+	}
+	const filePath = canonicalId.slice(0, idx);
+	const astPath = canonicalId.slice(idx + canonicalIdSeparator.length);
+	if (filePath === "") {
+		return {
+			isValid: false,
+			reason: "empty file path"
+		};
+	}
+	if (astPath === "") {
+		return {
+			isValid: false,
+			reason: "empty AST path"
+		};
+	}
+	return { isValid: true };
+};
 
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.ts
@@ -68,7 +127,7 @@ const _buildAstPath = (stack) => {
 * ```
 */
 const createCanonicalTracker = (options) => {
-	const { filePath, getExportName } = options;
+	const { filePath, baseDir, getExportName } = options;
 	const scopeStack = [];
 	const occurrenceCounters = new Map();
 	const usedPaths = new Set();
@@ -124,7 +183,7 @@ const createCanonicalTracker = (options) => {
 			};
 		},
 		resolveCanonicalId(astPath) {
-			return createCanonicalId(filePath, astPath);
+			return createCanonicalId(filePath, astPath, { baseDir });
 		},
 		registerExportBinding(local, exported) {
 			exportBindings.set(local, exported);
@@ -169,5 +228,5 @@ const buildAstPath = (stack) => {
 };
 
 //#endregion
-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
+export { CanonicalIdSchema as a, parseCanonicalId as c, createPathTracker as i, validateCanonicalId as l, createCanonicalTracker as n, createCanonicalId as o, createOccurrenceTracker as r, isRelativeCanonicalId as s, buildAstPath as t };
+//# sourceMappingURL=canonical-id-9alor9gv.mjs.map

package/dist/canonical-id-9alor9gv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-id-9alor9gv.mjs","names":["CanonicalIdSchema: z.ZodType<CanonicalId>","z","resolved","normalized","idParts","scopeStack: ScopeFrame[]","frame: ScopeFrame","exportBinding: string | undefined"],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":["import { isAbsolute, relative, 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/**\n * Options for creating a canonical ID.\n */\nexport type CreateCanonicalIdOptions = {\n  /**\n   * Base directory for relative path computation.\n   * When provided, the canonical ID will use a relative path from baseDir.\n   * When undefined, an absolute path is required and used as-is.\n   */\n  readonly baseDir?: string;\n};\n\n/**\n * Create a canonical ID from a file path and AST path.\n *\n * @param filePath - The file path (absolute, or relative if baseDir is provided)\n * @param astPath - The AST path identifying the definition within the file\n * @param options - Optional configuration including baseDir for relative path support\n * @returns A canonical ID in the format \"{path}::{astPath}\"\n */\nexport const createCanonicalId = (filePath: string, astPath: string, options?: CreateCanonicalIdOptions): CanonicalId => {\n  const { baseDir } = options ?? {};\n\n  if (baseDir) {\n    // With baseDir, compute relative path\n    const absolutePath = isAbsolute(filePath) ? filePath : resolve(baseDir, filePath);\n    const resolved = resolve(absolutePath);\n    const relativePath = relative(baseDir, resolved);\n    const normalized = normalizePath(relativePath);\n\n    const idParts = [normalized, astPath];\n    return idParts.join(canonicalIdSeparator) as CanonicalId;\n  }\n\n  // Without baseDir, require absolute path (legacy behavior)\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 * Check if a canonical ID uses a relative path.\n * Relative canonical IDs do not start with '/'.\n *\n * @param canonicalId - The canonical ID to check\n * @returns true if the canonical ID uses a relative path\n */\nexport const isRelativeCanonicalId = (canonicalId: CanonicalId | string): boolean => {\n  return !canonicalId.startsWith(\"/\");\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/**\n * Validation result for canonical ID format.\n */\nexport type CanonicalIdValidationResult = { readonly isValid: true } | { readonly isValid: false; readonly reason: string };\n\n/**\n * Validate a canonical ID format.\n * A valid canonical ID has format: \"{filePath}::{astPath}\"\n * where both filePath and astPath are non-empty.\n *\n * @param canonicalId - The canonical ID to validate\n * @returns Validation result with isValid boolean and optional error reason\n */\nexport const validateCanonicalId = (canonicalId: string): CanonicalIdValidationResult => {\n  const idx = canonicalId.indexOf(canonicalIdSeparator);\n\n  if (idx === -1) {\n    return { isValid: false, reason: \"missing '::' separator\" };\n  }\n\n  const filePath = canonicalId.slice(0, idx);\n  const astPath = canonicalId.slice(idx + canonicalIdSeparator.length);\n\n  if (filePath === \"\") {\n    return { isValid: false, reason: \"empty file path\" };\n  }\n\n  if (astPath === \"\") {\n    return { isValid: false, reason: \"empty AST path\" };\n  }\n\n  return { isValid: true };\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  /**\n   * Base directory for relative path computation in canonical IDs.\n   * When provided, canonical IDs will use relative paths from baseDir.\n   */\n  baseDir?: string;\n  getExportName?: (localName: string) => string | undefined;\n}): CanonicalPathTracker => {\n  const { filePath, baseDir, 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, { baseDir });\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-CgMNOZyn.cjs → canonical-id-DHdeYIsT.cjs}

@@ -25,7 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_utils = require('./utils-CsTwS1dw.cjs');
+const require_utils = require('./utils-Rs7YbafF.cjs');
 let node_path = require("node:path");
 let zod = require("zod");
 zod = __toESM(zod);
@@ -33,7 +33,24 @@ zod = __toESM(zod);
 //#region packages/common/src/canonical-id/canonical-id.ts
 const canonicalIdSeparator = "::";
 const CanonicalIdSchema = zod.default.string();
-const createCanonicalId = (filePath, astPath) => {
+/**
+* Create a canonical ID from a file path and AST path.
+*
+* @param filePath - The file path (absolute, or relative if baseDir is provided)
+* @param astPath - The AST path identifying the definition within the file
+* @param options - Optional configuration including baseDir for relative path support
+* @returns A canonical ID in the format "{path}::{astPath}"
+*/
+const createCanonicalId = (filePath, astPath, options) => {
+	const { baseDir } = options ?? {};
+	if (baseDir) {
+		const absolutePath = (0, node_path.isAbsolute)(filePath) ? filePath : (0, node_path.resolve)(baseDir, filePath);
+		const resolved$1 = (0, node_path.resolve)(absolutePath);
+		const relativePath = (0, node_path.relative)(baseDir, resolved$1);
+		const normalized$1 = require_utils.normalizePath(relativePath);
+		const idParts$1 = [normalized$1, astPath];
+		return idParts$1.join(canonicalIdSeparator);
+	}
 	if (!(0, node_path.isAbsolute)(filePath)) {
 		throw new Error("[INTERNAL] CANONICAL_ID_REQUIRES_ABSOLUTE_PATH");
 	}
@@ -43,6 +60,16 @@ const createCanonicalId = (filePath, astPath) => {
 	return idParts.join(canonicalIdSeparator);
 };
 /**
+* Check if a canonical ID uses a relative path.
+* Relative canonical IDs do not start with '/'.
+*
+* @param canonicalId - The canonical ID to check
+* @returns true if the canonical ID uses a relative path
+*/
+const isRelativeCanonicalId = (canonicalId) => {
+	return !canonicalId.startsWith("/");
+};
+/**
 * 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
@@ -60,6 +87,38 @@ const parseCanonicalId = (canonicalId) => {
 		astPath: canonicalId.slice(idx + canonicalIdSeparator.length)
 	};
 };
+/**
+* Validate a canonical ID format.
+* A valid canonical ID has format: "{filePath}::{astPath}"
+* where both filePath and astPath are non-empty.
+*
+* @param canonicalId - The canonical ID to validate
+* @returns Validation result with isValid boolean and optional error reason
+*/
+const validateCanonicalId = (canonicalId) => {
+	const idx = canonicalId.indexOf(canonicalIdSeparator);
+	if (idx === -1) {
+		return {
+			isValid: false,
+			reason: "missing '::' separator"
+		};
+	}
+	const filePath = canonicalId.slice(0, idx);
+	const astPath = canonicalId.slice(idx + canonicalIdSeparator.length);
+	if (filePath === "") {
+		return {
+			isValid: false,
+			reason: "empty file path"
+		};
+	}
+	if (astPath === "") {
+		return {
+			isValid: false,
+			reason: "empty AST path"
+		};
+	}
+	return { isValid: true };
+};
 
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.ts
@@ -96,7 +155,7 @@ const _buildAstPath = (stack) => {
 * ```
 */
 const createCanonicalTracker = (options) => {
-	const { filePath, getExportName } = options;
+	const { filePath, baseDir, getExportName } = options;
 	const scopeStack = [];
 	const occurrenceCounters = new Map();
 	const usedPaths = new Set();
@@ -152,7 +211,7 @@ const createCanonicalTracker = (options) => {
 			};
 		},
 		resolveCanonicalId(astPath) {
-			return createCanonicalId(filePath, astPath);
+			return createCanonicalId(filePath, astPath, { baseDir });
 		},
 		registerExportBinding(local, exported) {
 			exportBindings.set(local, exported);
@@ -239,10 +298,22 @@ Object.defineProperty(exports, 'createPathTracker', {
     return createPathTracker;
   }
 });
+Object.defineProperty(exports, 'isRelativeCanonicalId', {
+  enumerable: true,
+  get: function () {
+    return isRelativeCanonicalId;
+  }
+});
 Object.defineProperty(exports, 'parseCanonicalId', {
   enumerable: true,
   get: function () {
     return parseCanonicalId;
   }
 });
-//# sourceMappingURL=canonical-id-CgMNOZyn.cjs.map
+Object.defineProperty(exports, 'validateCanonicalId', {
+  enumerable: true,
+  get: function () {
+    return validateCanonicalId;
+  }
+});
+//# sourceMappingURL=canonical-id-DHdeYIsT.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-id-DHdeYIsT.cjs","names":["CanonicalIdSchema: z.ZodType<CanonicalId>","z","resolved","normalized","normalizePath","idParts","scopeStack: ScopeFrame[]","frame: ScopeFrame","exportBinding: string | undefined"],"sources":["../src/canonical-id/canonical-id.ts","../src/canonical-id/path-tracker.ts"],"sourcesContent":["import { isAbsolute, relative, 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/**\n * Options for creating a canonical ID.\n */\nexport type CreateCanonicalIdOptions = {\n  /**\n   * Base directory for relative path computation.\n   * When provided, the canonical ID will use a relative path from baseDir.\n   * When undefined, an absolute path is required and used as-is.\n   */\n  readonly baseDir?: string;\n};\n\n/**\n * Create a canonical ID from a file path and AST path.\n *\n * @param filePath - The file path (absolute, or relative if baseDir is provided)\n * @param astPath - The AST path identifying the definition within the file\n * @param options - Optional configuration including baseDir for relative path support\n * @returns A canonical ID in the format \"{path}::{astPath}\"\n */\nexport const createCanonicalId = (filePath: string, astPath: string, options?: CreateCanonicalIdOptions): CanonicalId => {\n  const { baseDir } = options ?? {};\n\n  if (baseDir) {\n    // With baseDir, compute relative path\n    const absolutePath = isAbsolute(filePath) ? filePath : resolve(baseDir, filePath);\n    const resolved = resolve(absolutePath);\n    const relativePath = relative(baseDir, resolved);\n    const normalized = normalizePath(relativePath);\n\n    const idParts = [normalized, astPath];\n    return idParts.join(canonicalIdSeparator) as CanonicalId;\n  }\n\n  // Without baseDir, require absolute path (legacy behavior)\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 * Check if a canonical ID uses a relative path.\n * Relative canonical IDs do not start with '/'.\n *\n * @param canonicalId - The canonical ID to check\n * @returns true if the canonical ID uses a relative path\n */\nexport const isRelativeCanonicalId = (canonicalId: CanonicalId | string): boolean => {\n  return !canonicalId.startsWith(\"/\");\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/**\n * Validation result for canonical ID format.\n */\nexport type CanonicalIdValidationResult = { readonly isValid: true } | { readonly isValid: false; readonly reason: string };\n\n/**\n * Validate a canonical ID format.\n * A valid canonical ID has format: \"{filePath}::{astPath}\"\n * where both filePath and astPath are non-empty.\n *\n * @param canonicalId - The canonical ID to validate\n * @returns Validation result with isValid boolean and optional error reason\n */\nexport const validateCanonicalId = (canonicalId: string): CanonicalIdValidationResult => {\n  const idx = canonicalId.indexOf(canonicalIdSeparator);\n\n  if (idx === -1) {\n    return { isValid: false, reason: \"missing '::' separator\" };\n  }\n\n  const filePath = canonicalId.slice(0, idx);\n  const astPath = canonicalId.slice(idx + canonicalIdSeparator.length);\n\n  if (filePath === \"\") {\n    return { isValid: false, reason: \"empty file path\" };\n  }\n\n  if (astPath === \"\") {\n    return { isValid: false, reason: \"empty AST path\" };\n  }\n\n  return { isValid: true };\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  /**\n   * Base directory for relative path computation in canonical IDs.\n   * When provided, canonical IDs will use relative paths from baseDir.\n   */\n  baseDir?: string;\n  getExportName?: (localName: string) => string | undefined;\n}): CanonicalPathTracker => {\n  const { filePath, baseDir, 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, { baseDir });\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,5 +1,5 @@
-const require_canonical_id = require('./canonical-id-CgMNOZyn.cjs');
-require('./utils-CsTwS1dw.cjs');
+const require_canonical_id = require('./canonical-id-DHdeYIsT.cjs');
+require('./utils-Rs7YbafF.cjs');
 
 exports.CanonicalIdSchema = require_canonical_id.CanonicalIdSchema;
 exports.buildAstPath = require_canonical_id.buildAstPath;
@@ -7,4 +7,6 @@ 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.parseCanonicalId = require_canonical_id.parseCanonicalId;
+exports.isRelativeCanonicalId = require_canonical_id.isRelativeCanonicalId;
+exports.parseCanonicalId = require_canonical_id.parseCanonicalId;
+exports.validateCanonicalId = require_canonical_id.validateCanonicalId;

package/dist/canonical-id.d.cts

@@ -1,2 +1,2 @@
-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 };
+import { a as createCanonicalTracker, c as CanonicalId, d as CreateCanonicalIdOptions, f as createCanonicalId, h as validateCanonicalId, i as buildAstPath, l as CanonicalIdSchema, m as parseCanonicalId, n as ScopeFrame, o as createOccurrenceTracker, p as isRelativeCanonicalId, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as CanonicalIdValidationResult } from "./index-DZSebwar.cjs";
+export { CanonicalId, CanonicalIdSchema, CanonicalIdValidationResult, CanonicalPathTracker, CreateCanonicalIdOptions, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, isRelativeCanonicalId, parseCanonicalId, validateCanonicalId };

package/dist/canonical-id.d.mts

@@ -1,2 +1,2 @@
-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 };
+import { a as createCanonicalTracker, c as CanonicalId, d as CreateCanonicalIdOptions, f as createCanonicalId, h as validateCanonicalId, i as buildAstPath, l as CanonicalIdSchema, m as parseCanonicalId, n as ScopeFrame, o as createOccurrenceTracker, p as isRelativeCanonicalId, r as ScopeHandle, s as createPathTracker, t as CanonicalPathTracker, u as CanonicalIdValidationResult } from "./index-AqkJhrm3.mjs";
+export { CanonicalId, CanonicalIdSchema, CanonicalIdValidationResult, CanonicalPathTracker, CreateCanonicalIdOptions, ScopeFrame, ScopeHandle, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, isRelativeCanonicalId, parseCanonicalId, validateCanonicalId };

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, s as parseCanonicalId, t as buildAstPath } from "./canonical-id-BJahCcrS.mjs";
+import "./utils-ZCE_eqCf.mjs";
+import { a as CanonicalIdSchema, c as parseCanonicalId, i as createPathTracker, l as validateCanonicalId, n as createCanonicalTracker, o as createCanonicalId, r as createOccurrenceTracker, s as isRelativeCanonicalId, t as buildAstPath } from "./canonical-id-9alor9gv.mjs";
 
-export { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, parseCanonicalId };
+export { CanonicalIdSchema, buildAstPath, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, isRelativeCanonicalId, parseCanonicalId, validateCanonicalId };

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

@@ -5,7 +5,34 @@ type CanonicalId = string & {
   readonly __brand: "CanonicalId";
 };
 declare const CanonicalIdSchema: z$1.ZodType<CanonicalId>;
-declare const createCanonicalId: (filePath: string, astPath: string) => CanonicalId;
+/**
+ * Options for creating a canonical ID.
+ */
+type CreateCanonicalIdOptions = {
+  /**
+   * Base directory for relative path computation.
+   * When provided, the canonical ID will use a relative path from baseDir.
+   * When undefined, an absolute path is required and used as-is.
+   */
+  readonly baseDir?: string;
+};
+/**
+ * Create a canonical ID from a file path and AST path.
+ *
+ * @param filePath - The file path (absolute, or relative if baseDir is provided)
+ * @param astPath - The AST path identifying the definition within the file
+ * @param options - Optional configuration including baseDir for relative path support
+ * @returns A canonical ID in the format "{path}::{astPath}"
+ */
+declare const createCanonicalId: (filePath: string, astPath: string, options?: CreateCanonicalIdOptions) => CanonicalId;
+/**
+ * Check if a canonical ID uses a relative path.
+ * Relative canonical IDs do not start with '/'.
+ *
+ * @param canonicalId - The canonical ID to check
+ * @returns true if the canonical ID uses a relative path
+ */
+declare const isRelativeCanonicalId: (canonicalId: CanonicalId | string) => boolean;
 /**
  * Parse a canonical ID into its components.
  * @param canonicalId - The canonical ID to parse (e.g., "/app/src/user.ts::userFragment")
@@ -15,6 +42,24 @@ declare const parseCanonicalId: (canonicalId: CanonicalId | string) => {
   filePath: string;
   astPath: string;
 };
+/**
+ * Validation result for canonical ID format.
+ */
+type CanonicalIdValidationResult = {
+  readonly isValid: true;
+} | {
+  readonly isValid: false;
+  readonly reason: string;
+};
+/**
+ * Validate a canonical ID format.
+ * A valid canonical ID has format: "{filePath}::{astPath}"
+ * where both filePath and astPath are non-empty.
+ *
+ * @param canonicalId - The canonical ID to validate
+ * @returns Validation result with isValid boolean and optional error reason
+ */
+declare const validateCanonicalId: (canonicalId: string) => CanonicalIdValidationResult;
 //#endregion
 //#region packages/common/src/canonical-id/path-tracker.d.ts
 
@@ -110,6 +155,11 @@ interface CanonicalPathTracker {
  */
 declare const createCanonicalTracker: (options: {
   filePath: string;
+  /**
+   * Base directory for relative path computation in canonical IDs.
+   * When provided, canonical IDs will use relative paths from baseDir.
+   */
+  baseDir?: string;
   getExportName?: (localName: string) => string | undefined;
 }) => CanonicalPathTracker;
 /**
@@ -129,5 +179,5 @@ declare const createPathTracker: () => {
  */
 declare const buildAstPath: (stack: readonly ScopeFrame[]) => string;
 //#endregion
-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
+export { createCanonicalTracker as a, CanonicalId as c, CreateCanonicalIdOptions as d, createCanonicalId as f, validateCanonicalId as h, buildAstPath as i, CanonicalIdSchema as l, parseCanonicalId as m, ScopeFrame as n, createOccurrenceTracker as o, isRelativeCanonicalId as p, ScopeHandle as r, createPathTracker as s, CanonicalPathTracker as t, CanonicalIdValidationResult as u };
+//# sourceMappingURL=index-AqkJhrm3.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-AqkJhrm3.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;AAKzC;AAiBA;AAoCA;AASa,KA9DD,wBAAA,GA+DG;EAkBH;AAUZ;;;;ECnFY,SAAA,OAAU,CAAA,EAAA,MAAA;AAYtB,CAAA;AAQA;;;;;;AA8EA;AA4GA;AAiBa,cDtNA,iBCuOZ,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EDvO8E,wBCuO9E,EAAA,GDvOyG,WCuOzG;AAKD;;;;;;;cDxMa,qCAAsC;;;;;;cAStC,gCACE;;;;;;;KAkBH,2BAAA;;;;;;;;;;;;;;cAUC,8CAA6C;;;;ACvE1D;AAQA;;AAM0F,KA1B9E,UAAA,GA0B8E;EAMtE;EAiBmB,SAAA,WAAA,EAAA,MAAA;EAAW;EAiDrC,SAAA,IAAA,EAAA,UAuGZ,GAAA,OAAA,GA/FG,UAAA,GAAA,UA+FH,GAAA,QAAA,GAAA,YAAA;EAKY;EAiBA,SAAA,UAAA,EAiBZ,MAAA;AAKD,CAAA;;;;KAzOY,WAAA;;;;;;;UAQK,oBAAA;;;;;;;;UAM8B;;MAA2C;;;;;oBAMtE;;;;;;;;;;;;;;;uCAiBmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiD1B;;;;;;;;MAQT;;;;cAoGS;;;;;;cAiBA;;;;;;cAsBA,+BAAgC"}

package/dist/index-BCu9PNbZ.d.mts

@@ -0,0 +1,139 @@
+import { Result } from "neverthrow";
+
+//#region packages/common/src/utils/tsconfig.d.ts
+
+/**
+ * Parsed tsconfig.json paths configuration.
+ * All paths are resolved to absolute paths.
+ */
+type TsconfigPathsConfig = {
+  /** Absolute base URL for path resolution */
+  readonly baseUrl: string;
+  /** Path mappings with absolute paths */
+  readonly paths: Readonly<Record<string, readonly string[]>>;
+};
+/**
+ * Error types for tsconfig reading.
+ */
+type TsconfigReadError = {
+  readonly code: "TSCONFIG_READ_FAILED" | "TSCONFIG_PARSE_FAILED" | "TSCONFIG_INVALID";
+  readonly message: string;
+};
+/**
+ * Read and parse tsconfig.json to extract paths configuration.
+ * Currently does not support `extends` - reads only the specified file.
+ *
+ * @param tsconfigPath - Absolute path to tsconfig.json
+ * @returns Parsed paths configuration or null if no paths defined
+ */
+declare const readTsconfigPaths: (tsconfigPath: string) => Result<TsconfigPathsConfig | null, TsconfigReadError>;
+//#endregion
+//#region packages/common/src/utils/alias-resolver.d.ts
+/**
+ * Alias resolver interface for resolving path aliases to file paths.
+ */
+type AliasResolver = {
+  /**
+   * Resolve an alias specifier to an absolute file path.
+   * Returns null if the specifier doesn't match any alias pattern
+   * or if the resolved file doesn't exist.
+   */
+  readonly resolve: (specifier: string) => string | null;
+};
+/**
+ * Create an alias resolver from tsconfig paths configuration.
+ *
+ * Resolution behavior:
+ * 1. Try each pattern in order (first match wins per TS spec)
+ * 2. For each matched pattern, try all target paths in order
+ * 3. For each target, apply extension resolution
+ * 4. Return first found file, or null if none found
+ */
+declare const createAliasResolver: (config: TsconfigPathsConfig) => AliasResolver;
+//#endregion
+//#region packages/common/src/utils/cached-fn.d.ts
+declare const cachedFn: <T>(fn: () => T) => {
+  (): T;
+  clear(): void;
+};
+//#endregion
+//#region packages/common/src/utils/path.d.ts
+/**
+ * File extensions to try when resolving module specifiers.
+ * Ordered to match TypeScript's module resolution order.
+ * @see https://www.typescriptlang.org/docs/handbook/module-resolution.html
+ */
+declare const MODULE_EXTENSION_CANDIDATES: readonly [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".jsx"];
+/**
+ * Result of parsing a JS extension from a specifier.
+ */
+type JsExtensionInfo = {
+  /** The specifier without the JS extension */
+  readonly base: string;
+  /** The JS extension found (e.g., ".js", ".mjs") */
+  readonly jsExtension: string;
+  /** The corresponding TS extensions to try (e.g., [".ts", ".tsx"] for ".js") */
+  readonly tsExtensions: readonly string[];
+};
+/**
+ * Parse a JS extension from a specifier for ESM-style import resolution.
+ * Returns the base path (without extension), the JS extension, and corresponding TS extensions.
+ *
+ * @param specifier - The import specifier to parse
+ * @returns Object with base, jsExtension, and tsExtensions, or null if no JS extension found
+ *
+ * @example
+ * parseJsExtension("./foo.js") // { base: "./foo", jsExtension: ".js", tsExtensions: [".ts", ".tsx"] }
+ * parseJsExtension("./foo.mjs") // { base: "./foo", jsExtension: ".mjs", tsExtensions: [".mts"] }
+ * parseJsExtension("./foo") // null
+ * parseJsExtension("./foo.ts") // null
+ */
+declare const parseJsExtension: (specifier: string) => JsExtensionInfo | null;
+/**
+ * Normalize path to use forward slashes (cross-platform).
+ * Ensures consistent path handling across platforms.
+ */
+declare const normalizePath: (value: string) => string;
+/**
+ * Resolve a relative import specifier to an absolute file path.
+ * Tries the specifier as-is, with extensions, and as a directory with index files.
+ *
+ * @param from - Absolute path to the importing file
+ * @param specifier - Relative module specifier (must start with '.')
+ * @returns Absolute POSIX path to the resolved file, or null if not found
+ */
+declare const resolveRelativeImportWithExistenceCheck: ({
+  filePath,
+  specifier
+}: {
+  filePath: string;
+  specifier: string;
+}) => string | null;
+/**
+ * Resolve a relative import specifier to an absolute file path.
+ * Tries the specifier as-is, with extensions, and as a directory with index files.
+ *
+ * @param from - Absolute path to the importing file
+ * @param specifier - Relative module specifier (must start with '.')
+ * @returns Absolute POSIX path to the resolved file, or null if not found
+ */
+declare const resolveRelativeImportWithReferences: <_>({
+  filePath,
+  specifier,
+  references
+}: {
+  filePath: string;
+  specifier: string;
+  references: Map<string, _> | Set<string>;
+}) => string | null;
+/**
+ * Check if a module specifier is relative (starts with '.' or '..')
+ */
+declare const isRelativeSpecifier: (specifier: string) => boolean;
+/**
+ * Check if a module specifier is external (package name, not relative)
+ */
+declare const isExternalSpecifier: (specifier: string) => boolean;
+//#endregion
+export { normalizePath as a, resolveRelativeImportWithReferences as c, createAliasResolver as d, TsconfigPathsConfig as f, isRelativeSpecifier as i, cachedFn as l, readTsconfigPaths as m, MODULE_EXTENSION_CANDIDATES as n, parseJsExtension as o, TsconfigReadError as p, isExternalSpecifier as r, resolveRelativeImportWithExistenceCheck as s, JsExtensionInfo as t, AliasResolver as u };
+//# sourceMappingURL=index-BCu9PNbZ.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-BCu9PNbZ.d.mts","names":[],"sources":["../src/utils/tsconfig.ts","../src/utils/alias-resolver.ts","../src/utils/cached-fn.ts","../src/utils/path.ts"],"sourcesContent":[],"mappings":";;;;;;AAQA;AAUA;AA4Ba,KAtCD,mBAAA,GAgGX;EA1D+D;EAA4B,SAAA,OAAA,EAAA,MAAA;EAAnC;EAAM,SAAA,KAAA,EAlC7C,QAkC6C,CAlCpC,MAkCoC,CAAA,MAAA,EAAA,SAAA,MAAA,EAAA,CAAA,CAAA;;;;ACtC/D;AAoJa,KD1ID,iBAAA,GCyKX;;;;AC3LD;;;;ACQA;AAgBA;AAsBA;AAiBa,cHjBA,iBGiB+E,EAAA,CAAA,YAAA,EAAA,MAAA,EAAA,GHjBnC,MGiBmC,CHjB5B,mBGiB4B,GAAA,IAAA,EHjBA,iBGiBA,CAAA;;;;;AHvD5F;AAUY,KCVA,aAAA,GDUiB;EA4BhB;;;;;;;;ACtCb;AAoJA;;;;AC5JA;;;cD4Ja,8BAA+B,wBAAsB;;;cC5JrD,wBAAyB;MAAA;;AFQtC,CAAA;;;;;;AAAA;AAUA;AA4Ba,cGtCA,2BHgGZ,EAAA,SAAA,CAAA,KAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,EAAA,KAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,CAAA;;;;AA1D8D,KGtBnD,eAAA,GHsBmD;;;;ECtCnD,SAAA,WAAa,EAAA,MAAA;EAoJZ;;;;AC5Jb;;;;ACQA;AAgBA;AAsBA;AAiBA;AAUA;AA+EA;;;AAAuD,cA1G1C,gBA0G0C,EAAA,CAAA,SAAA,EAAA,MAAA,EAAA,GA1GF,eA0GE,GAAA,IAAA;;;;;AA4D1C,cArJA,aAqJ+G,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,MAAA;AAK5H;;;;;;;;cAhJa;;;;;;;;;;;;;;;cA+EA;;;;;;;cAOC,YAAY,KAAK;;;;;cAqDlB;;;;cAKA"}