@walkeros/explorer 0.3.1 → 1.0.0

package/dist/utils/monaco-types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Monaco Editor TypeScript Type Management
+ *
+ * This utility manages TypeScript type definitions in Monaco Editor for:
+ * 1. Static walkerOS core types (bundled at build time via Vite ?raw import)
+ * 2. Dynamic destination types (loaded on-the-fly when destinations are added)
+ * 3. Context-specific function signatures (condition, fn, validate)
+ *
+ * Architecture:
+ * - Uses monaco.languages.typescript.typescriptDefaults.addExtraLib()
+ * - Each type definition gets a unique file path (e.g., 'file:///destinations/gtag.d.ts')
+ * - Types can be added/removed dynamically without page reload
+ * - Core types are bundled for offline support and predictable versioning
+ */
+import type { Monaco } from '@monaco-editor/react';
+/**
+ * Configuration for TypeScript compiler options
+ */
+export declare function configureMonacoTypeScript(monaco: Monaco): void;
+/**
+ * Add a type library from a string
+ *
+ * @param monaco - Monaco instance
+ * @param uri - Unique identifier (e.g., 'file:///destinations/gtag.d.ts')
+ * @param content - TypeScript definition content
+ * @returns True if added, false if already exists
+ */
+export declare function addTypeLibrary(monaco: Monaco, uri: string, content: string): boolean;
+/**
+ * Remove a type library
+ *
+ * @param uri - URI to remove
+ * @returns True if removed, false if not found
+ */
+export declare function removeTypeLibrary(uri: string): boolean;
+/**
+ * Update a type library (remove + add)
+ *
+ * @param monaco - Monaco instance
+ * @param uri - URI to update
+ * @param content - New content
+ */
+export declare function updateTypeLibrary(monaco: Monaco, uri: string, content: string): void;
+/**
+ * Load type definitions from a URL
+ *
+ * @param monaco - Monaco instance
+ * @param url - URL to .d.ts file
+ * @param uri - Optional custom URI (defaults to URL)
+ */
+export declare function loadTypeLibraryFromURL(monaco: Monaco, url: string, uri?: string): Promise<boolean>;
+/**
+ * Options for loading package types dynamically
+ */
+export interface LoadPackageTypesOptions {
+    /** Package name (e.g., '@walkeros/destination-gtag') */
+    package: string;
+    /** Version to load (e.g., '0.1.0', 'latest') */
+    version?: string;
+    /** CDN to use ('unpkg' or 'jsdelivr') */
+    cdn?: 'unpkg' | 'jsdelivr';
+    /** Path to .d.ts file within package (defaults to '/dist/index.d.ts') */
+    typesPath?: string;
+}
+export interface LoadPackageTypesOptions {
+    package: string;
+    version?: string;
+}
+export declare function loadPackageTypes(monaco: Monaco, options: LoadPackageTypesOptions): Promise<boolean>;
+/**
+ * Load walkerOS core types (bundled at build time)
+ *
+ * Uses bundled types imported via Vite's ?raw import.
+ * This ensures types are always available offline and match the installed version.
+ */
+export declare function loadWalkerOSCoreTypes(monaco: Monaco): boolean;
+/**
+ * Type of function context (fn, condition, validate)
+ */
+export type FunctionType = 'condition' | 'fn' | 'validate';
+/**
+ * Add context-specific globals for function editors
+ *
+ * Provides type definitions for inline function parameters without imports.
+ * Supports three function types:
+ * - fn: Transform functions (value, mapping, options) => Property
+ * - condition: Condition functions (value, mapping, collector) => boolean
+ * - validate: Validation functions (value) => boolean
+ */
+export interface FunctionContext {
+    type: FunctionType;
+    valueType?: string;
+}
+export declare function addFunctionContextTypes(monaco: Monaco, context: FunctionContext): void;
+/**
+ * Add destination-specific types dynamically
+ *
+ * @param monaco - Monaco instance
+ * @param destinationId - Unique destination identifier (e.g., 'gtag', 'fbq')
+ * @param typeDefinition - TypeScript definition for destination's custom config/event
+ *
+ * @example
+ * ```typescript
+ * addDestinationType(monaco, 'gtag', `
+ *   declare namespace Gtag {
+ *     interface Settings {
+ *       measurementId: string;
+ *       sendPageView?: boolean;
+ *     }
+ *
+ *     interface EventParams {
+ *       event_category?: string;
+ *       event_label?: string;
+ *       value?: number;
+ *     }
+ *   }
+ *
+ *   // Extend WalkerOS namespace
+ *   declare namespace WalkerOS {
+ *     namespace Destination {
+ *       interface ConfigMap {
+ *         gtag: Gtag.Settings;
+ *       }
+ *     }
+ *   }
+ * `);
+ * ```
+ */
+export declare function addDestinationType(monaco: Monaco, destinationId: string, typeDefinition: string): void;
+/**
+ * Remove destination types when destination is removed
+ */
+export declare function removeDestinationType(destinationId: string): void;
+/**
+ * Simple helper to register only walkerOS core types
+ *
+ * Use this for basic scenarios where you just need @walkeros/core types.
+ * For advanced usage (destinations, function contexts), use initializeMonacoTypes.
+ *
+ * @param monaco - Monaco editor instance
+ *
+ * @example
+ * ```typescript
+ * const handleBeforeMount = (monaco: Monaco) => {
+ *   registerWalkerOSTypes(monaco);
+ * };
+ * ```
+ */
+export declare function registerWalkerOSTypes(monaco: Monaco): void;
+/**
+ * Initialize Monaco with walkerOS types (full setup)
+ *
+ * Call this once in CodeBox's beforeMount handler.
+ * Includes core types, TypeScript config, and default function context.
+ *
+ * @param monaco - Monaco editor instance
+ *
+ * @example
+ * ```typescript
+ * const handleBeforeMount = (monaco: Monaco) => {
+ *   initializeMonacoTypes(monaco);
+ * };
+ * ```
+ */
+export declare function initializeMonacoTypes(monaco: Monaco): void;
+/**
+ * Get all loaded type libraries (for debugging)
+ */
+export declare function getLoadedTypeLibraries(): string[];
+/**
+ * Clear all type libraries (for testing)
+ */
+export declare function clearAllTypeLibraries(): void;
+//# sourceMappingURL=monaco-types.d.ts.map

package/dist/utils/monaco-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monaco-types.d.ts","sourceRoot":"","sources":["../../src/utils/monaco-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAoBnD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,QAkCvD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,OAAO,CA2BT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAatD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,QAIhB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiDD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAiB7D;AAyDD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,IAAI,GAAG,UAAU,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,QASzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,QAIvB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,QAG1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAS1D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,SAKpC"}

package/dist/utils/monaco-types.js

@@ -0,0 +1,378 @@
+/**
+ * Monaco Editor TypeScript Type Management
+ *
+ * This utility manages TypeScript type definitions in Monaco Editor for:
+ * 1. Static walkerOS core types (bundled at build time via Vite ?raw import)
+ * 2. Dynamic destination types (loaded on-the-fly when destinations are added)
+ * 3. Context-specific function signatures (condition, fn, validate)
+ *
+ * Architecture:
+ * - Uses monaco.languages.typescript.typescriptDefaults.addExtraLib()
+ * - Each type definition gets a unique file path (e.g., 'file:///destinations/gtag.d.ts')
+ * - Types can be added/removed dynamically without page reload
+ * - Core types are bundled for offline support and predictable versioning
+ */
+import { getContextTypes } from './monaco-context-types';
+// This import will be replaced by tsup plugin with actual TypeScript content
+import walkerosCoreTypesBundled from 'virtual:walkeros-core-types';
+/**
+ * Registry of loaded type libraries
+ */
+const typeLibraries = new Map();
+/**
+ * Configuration for TypeScript compiler options
+ */
+export function configureMonacoTypeScript(monaco) {
+    monaco.languages.typescript.javascriptDefaults.setCompilerOptions({
+        target: monaco.languages.typescript.ScriptTarget.ES2020,
+        lib: ['es2020'],
+        allowNonTsExtensions: true,
+        moduleResolution: monaco.languages.typescript.ModuleResolutionKind.NodeJs,
+        module: monaco.languages.typescript.ModuleKind.CommonJS,
+        noEmit: true,
+        esModuleInterop: true,
+        jsx: monaco.languages.typescript.JsxEmit.React,
+        allowJs: true,
+        checkJs: false,
+        strict: false,
+        noImplicitAny: false,
+        strictNullChecks: false,
+    });
+    monaco.languages.typescript.javascriptDefaults.setDiagnosticsOptions({
+        noSemanticValidation: false,
+        noSyntaxValidation: false,
+        diagnosticCodesToIgnore: [1108, 1005],
+    });
+    monaco.languages.typescript.typescriptDefaults.setCompilerOptions({
+        target: monaco.languages.typescript.ScriptTarget.ES2020,
+        lib: ['es2020'],
+        allowNonTsExtensions: true,
+        moduleResolution: monaco.languages.typescript.ModuleResolutionKind.NodeJs,
+        module: monaco.languages.typescript.ModuleKind.CommonJS,
+        noEmit: true,
+        esModuleInterop: true,
+        jsx: monaco.languages.typescript.JsxEmit.React,
+        strict: false,
+    });
+}
+/**
+ * Add a type library from a string
+ *
+ * @param monaco - Monaco instance
+ * @param uri - Unique identifier (e.g., 'file:///destinations/gtag.d.ts')
+ * @param content - TypeScript definition content
+ * @returns True if added, false if already exists
+ */
+export function addTypeLibrary(monaco, uri, content) {
+    // Check if already loaded
+    if (typeLibraries.has(uri)) {
+        return false;
+    }
+    // Add to both JavaScript and TypeScript language services
+    // This ensures types work whether the editor is in JS or TS mode
+    const jsDisposable = monaco.languages.typescript.javascriptDefaults.addExtraLib(content, uri);
+    const tsDisposable = monaco.languages.typescript.typescriptDefaults.addExtraLib(content, uri);
+    // Track in registry (store both disposables)
+    typeLibraries.set(uri, {
+        uri,
+        content,
+        disposable: {
+            dispose: () => {
+                jsDisposable.dispose();
+                tsDisposable.dispose();
+            },
+        },
+    });
+    return true;
+}
+/**
+ * Remove a type library
+ *
+ * @param uri - URI to remove
+ * @returns True if removed, false if not found
+ */
+export function removeTypeLibrary(uri) {
+    const lib = typeLibraries.get(uri);
+    if (!lib) {
+        return false;
+    }
+    // Dispose Monaco resource
+    lib.disposable?.dispose();
+    // Remove from registry
+    typeLibraries.delete(uri);
+    return true;
+}
+/**
+ * Update a type library (remove + add)
+ *
+ * @param monaco - Monaco instance
+ * @param uri - URI to update
+ * @param content - New content
+ */
+export function updateTypeLibrary(monaco, uri, content) {
+    removeTypeLibrary(uri);
+    addTypeLibrary(monaco, uri, content);
+}
+/**
+ * Load type definitions from a URL
+ *
+ * @param monaco - Monaco instance
+ * @param url - URL to .d.ts file
+ * @param uri - Optional custom URI (defaults to URL)
+ */
+export async function loadTypeLibraryFromURL(monaco, url, uri) {
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            return false;
+        }
+        const content = await response.text();
+        const typeUri = uri || `file:///${url}`;
+        return addTypeLibrary(monaco, typeUri, content);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Strip problematic imports from type definition content
+ *
+ * Removes import statements that Monaco can't resolve, while preserving:
+ * - Type declarations
+ * - Export statements
+ * - Re-export statements (export * from / export { } from)
+ *
+ * Uses multiple strategies for robustness:
+ * 1. Simple single-line imports (fast path)
+ * 2. Multi-line imports (comprehensive)
+ * 3. Import type assertions
+ *
+ * Does NOT remove:
+ * - export { } from 'module' (re-exports)
+ * - export * from 'module' (re-exports)
+ * - Triple-slash directives (/// <reference types="..." />)
+ *
+ * @param content - Raw .d.ts file content
+ * @returns Cleaned content safe for Monaco
+ */
+function stripExternalImports(content) {
+    // Strategy 1: Remove simple single-line imports
+    // Matches: import ... from '...';
+    // Handles: import type, import *, import { }, default imports
+    let cleaned = content.replace(/^import\s+(?:type\s+)?(?:\*\s+as\s+\w+|\{[^}]*\}|[\w$]+)(?:\s*,\s*(?:\{[^}]*\}|\*\s+as\s+\w+))?\s+from\s+['"][^'"]+['"];?\s*$/gm, '');
+    // Strategy 2: Remove multi-line imports (more aggressive)
+    // Matches imports that span multiple lines
+    cleaned = cleaned.replace(/^import\s+(?:type\s+)?(?:\{[^}]*\}|\*\s+as\s+\w+|[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gms, '');
+    // Strategy 3: Remove import type assertions
+    // Matches: import('module')
+    cleaned = cleaned.replace(/import\s*\(\s*['"][^'"]+['"]\s*\)/g, 'any');
+    // Clean up excessive blank lines (more than 2 consecutive)
+    cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+    return cleaned;
+}
+export async function loadPackageTypes(monaco, options) {
+    const { package: packageName, version = 'latest' } = options;
+    const uri = `file:///node_modules/${packageName}/index.d.ts`;
+    if (typeLibraries.has(uri)) {
+        return true;
+    }
+    const url = `https://cdn.jsdelivr.net/npm/${packageName}@${version}/dist/index.d.ts`;
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            return false;
+        }
+        let content = await response.text();
+        content = stripExternalImports(content);
+        const moduleContent = `declare module '${packageName}' {\n${content}\n}`;
+        const success = addTypeLibrary(monaco, uri, moduleContent);
+        return success;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load walkerOS core types (bundled at build time)
+ *
+ * Uses bundled types imported via Vite's ?raw import.
+ * This ensures types are always available offline and match the installed version.
+ */
+export function loadWalkerOSCoreTypes(monaco) {
+    const uri = 'file:///node_modules/@walkeros/core/index.d.ts';
+    // Check if already loaded
+    if (typeLibraries.has(uri)) {
+        return true;
+    }
+    // Clean the types using the same robust stripping function
+    const cleanedTypes = stripExternalImports(walkerosCoreTypesBundled);
+    // Wrap in module declaration
+    const moduleContent = `declare module '@walkeros/core' {
+${cleanedTypes}
+}`;
+    return addTypeLibrary(monaco, uri, moduleContent);
+}
+/**
+ * Minimal fallback types if we can't load from node_modules
+ */
+function getMinimalWalkerOSTypes() {
+    return `
+declare namespace WalkerOS {
+  export interface Event {
+    entity: string;
+    action: string;
+    data?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    user?: {
+      id?: string;
+      device?: string;
+      session?: string;
+      [key: string]: unknown;
+    };
+    nested?: unknown[];
+    consent?: Record<string, boolean>;
+    id?: string;
+    trigger?: string;
+    timestamp?: number;
+    timing?: number;
+    count?: number;
+    version?: {
+      client?: string;
+      tagging?: number;
+    };
+  }
+
+  export interface Properties {
+    [key: string]: unknown;
+  }
+
+  export interface Mapping {
+    [key: string]: unknown;
+  }
+
+  export interface Collector {
+    push: (event: Partial<Event>) => Promise<unknown>;
+    [key: string]: unknown;
+  }
+
+  export namespace Destination {
+    export interface Config<T = unknown> {
+      id?: string;
+      mapping?: Mapping;
+      custom?: T;
+      [key: string]: unknown;
+    }
+  }
+}
+`;
+}
+export function addFunctionContextTypes(monaco, context) {
+    const uri = `file:///context/${context.type}.d.ts`;
+    // Use hand-crafted type templates from monaco-context-types
+    const contextTypes = getContextTypes(context.type);
+    // Update or add
+    updateTypeLibrary(monaco, uri, contextTypes);
+}
+/**
+ * Add destination-specific types dynamically
+ *
+ * @param monaco - Monaco instance
+ * @param destinationId - Unique destination identifier (e.g., 'gtag', 'fbq')
+ * @param typeDefinition - TypeScript definition for destination's custom config/event
+ *
+ * @example
+ * ```typescript
+ * addDestinationType(monaco, 'gtag', `
+ *   declare namespace Gtag {
+ *     interface Settings {
+ *       measurementId: string;
+ *       sendPageView?: boolean;
+ *     }
+ *
+ *     interface EventParams {
+ *       event_category?: string;
+ *       event_label?: string;
+ *       value?: number;
+ *     }
+ *   }
+ *
+ *   // Extend WalkerOS namespace
+ *   declare namespace WalkerOS {
+ *     namespace Destination {
+ *       interface ConfigMap {
+ *         gtag: Gtag.Settings;
+ *       }
+ *     }
+ *   }
+ * `);
+ * ```
+ */
+export function addDestinationType(monaco, destinationId, typeDefinition) {
+    const uri = `file:///destinations/${destinationId}.d.ts`;
+    updateTypeLibrary(monaco, uri, typeDefinition);
+}
+/**
+ * Remove destination types when destination is removed
+ */
+export function removeDestinationType(destinationId) {
+    const uri = `file:///destinations/${destinationId}.d.ts`;
+    removeTypeLibrary(uri);
+}
+/**
+ * Simple helper to register only walkerOS core types
+ *
+ * Use this for basic scenarios where you just need @walkeros/core types.
+ * For advanced usage (destinations, function contexts), use initializeMonacoTypes.
+ *
+ * @param monaco - Monaco editor instance
+ *
+ * @example
+ * ```typescript
+ * const handleBeforeMount = (monaco: Monaco) => {
+ *   registerWalkerOSTypes(monaco);
+ * };
+ * ```
+ */
+export function registerWalkerOSTypes(monaco) {
+    configureMonacoTypeScript(monaco);
+    loadWalkerOSCoreTypes(monaco);
+}
+/**
+ * Initialize Monaco with walkerOS types (full setup)
+ *
+ * Call this once in CodeBox's beforeMount handler.
+ * Includes core types, TypeScript config, and default function context.
+ *
+ * @param monaco - Monaco editor instance
+ *
+ * @example
+ * ```typescript
+ * const handleBeforeMount = (monaco: Monaco) => {
+ *   initializeMonacoTypes(monaco);
+ * };
+ * ```
+ */
+export function initializeMonacoTypes(monaco) {
+    // Configure compiler
+    configureMonacoTypeScript(monaco);
+    // Load core types (now synchronous with bundled types)
+    loadWalkerOSCoreTypes(monaco);
+    // Add default function context (condition)
+    addFunctionContextTypes(monaco, { type: 'condition' });
+}
+/**
+ * Get all loaded type libraries (for debugging)
+ */
+export function getLoadedTypeLibraries() {
+    return Array.from(typeLibraries.keys());
+}
+/**
+ * Clear all type libraries (for testing)
+ */
+export function clearAllTypeLibraries() {
+    for (const [uri, lib] of typeLibraries.entries()) {
+        lib.disposable?.dispose();
+    }
+    typeLibraries.clear();
+}
+//# sourceMappingURL=monaco-types.js.map

package/dist/utils/monaco-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monaco-types.js","sourceRoot":"","sources":["../../src/utils/monaco-types.ts"],"names":[],"mappings":"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"}

package/dist/utils/path-analyzer.d.ts

@@ -0,0 +1,88 @@
+import type { Mapping } from '@walkeros/core';
+/**
+ * Path Context Analyzer
+ *
+ * Provides structural understanding of mapping paths by walking the actual
+ * config and inspecting values at each level.
+ *
+ * This is the single source of truth for understanding what a path points to
+ * in the recursive mapping structure.
+ */
+/**
+ * Structural type of a path segment
+ */
+export type SegmentStructuralType = 'entity' | 'action' | 'ruleProperty' | 'valueConfigProperty' | 'mapKey' | 'arrayIndex';
+/**
+ * Semantic context of what's being edited
+ */
+export type SemanticContext = 'overview' | 'entity' | 'rule' | 'ruleProperty' | 'valueConfig' | 'valueConfigProperty' | 'mapValue' | 'primitive';
+/**
+ * Information about a single segment in the path
+ */
+export interface PathSegmentInfo {
+    segment: string;
+    index: number;
+    structuralType: SegmentStructuralType;
+    value: unknown;
+    parentValue: unknown;
+}
+/**
+ * Complete analysis of a path through the mapping structure
+ */
+export interface PathAnalysis {
+    segments: PathSegmentInfo[];
+    finalValue: unknown;
+    finalContext: SemanticContext;
+    isRuleLevel: boolean;
+    isValueConfigLevel: boolean;
+    propertyName?: string;
+}
+/**
+ * Type guard: Check if value is a Rule object
+ */
+export declare function isRule(value: unknown): boolean;
+/**
+ * Type guard: Check if value is a ValueConfig object
+ */
+export declare function isValueConfig(value: unknown): boolean;
+/**
+ * Type guard: Check if value is a Map object (plain object inside ValueConfig.map)
+ */
+export declare function isMapObject(value: unknown): boolean;
+/**
+ * Analyze a path through the mapping configuration
+ *
+ * Walks through the config structure, inspecting values at each step to
+ * determine the semantic type and context.
+ *
+ * @param path - Array of path segments (e.g., ['page', 'view', 'data', 'map', 'page_location', 'consent'])
+ * @param config - The mapping configuration object
+ * @returns Complete analysis of the path
+ *
+ * @example
+ * const analysis = analyzePath(['page', 'view', 'consent'], config);
+ * // analysis.isRuleLevel === true (consent at rule level)
+ *
+ * @example
+ * const analysis = analyzePath(['page', 'view', 'data', 'map', 'items', 'consent'], config);
+ * // analysis.isValueConfigLevel === true (consent at ValueConfig level)
+ */
+export declare function analyzePath(path: string[], config: Mapping.Config): PathAnalysis;
+/**
+ * Get semantic description for a path
+ *
+ * Returns human-readable description of what's being edited at this path.
+ *
+ * @example
+ * getPathDescription(['page', 'view', 'consent'], config)
+ * // Returns: "Rule-level consent for page view event"
+ *
+ * @example
+ * getPathDescription(['page', 'view', 'data', 'map', 'title', 'consent'], config)
+ * // Returns: "Property-level consent for title field"
+ */
+export declare function getPathDescription(path: string[], config: Mapping.Config): {
+    title: string;
+    description: string;
+};
+//# sourceMappingURL=path-analyzer.d.ts.map

package/dist/utils/path-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-analyzer.d.ts","sourceRoot":"","sources":["../../src/utils/path-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,qBAAqB,GACrB,QAAQ,GACR,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,MAAM,GACN,cAAc,GACd,aAAa,GACb,qBAAqB,GACrB,UAAU,GACV,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,qBAAqB,CAAC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,eAAe,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoB9C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAiBrD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,OAAO,CAAC,MAAM,GACrB,YAAY,CAqHd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,OAAO,CAAC,MAAM,GACrB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAuBxC"}