@grafema/core 0.2.4-beta → 0.2.6-beta

package/dist/utils/moduleResolution.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Module Resolution Utilities (REG-320)
+ *
+ * Unified module path resolution logic extracted from:
+ * - MountPointResolver.resolveImportSource()
+ * - JSModuleIndexer.resolveModulePath()
+ * - FunctionCallResolver._resolveImportPath()
+ * - IncrementalModuleIndexer.tryResolve()
+ *
+ * Provides consistent module resolution across all plugins.
+ */
+/**
+ * Default file extensions to try when resolving modules.
+ * Order: exact match first, then JS variants, then TS variants.
+ */
+export declare const DEFAULT_EXTENSIONS: string[];
+/**
+ * Default index files to try when resolving directory imports.
+ * Order: JS variants first (most common), then TS variants.
+ */
+export declare const DEFAULT_INDEX_FILES: string[];
+/**
+ * Options for module path resolution.
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' if exists
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ */
+export interface ModuleResolutionOptions {
+    /**
+     * Use filesystem for path verification.
+     * Default: true
+     *
+     * When true: uses existsSync() to check if files exist
+     * When false: uses fileIndex.has() for lookup
+     *
+     * Performance note: For high-frequency calls during enrichment,
+     * use in-memory mode (useFilesystem: false) with a pre-built fileIndex.
+     * For indexing phase, filesystem mode is acceptable.
+     */
+    useFilesystem?: boolean;
+    /**
+     * Pre-built set of known file paths.
+     * Required when useFilesystem=false.
+     *
+     * Throws Error if useFilesystem=false and fileIndex is not provided.
+     */
+    fileIndex?: Set<string> | null;
+    /**
+     * Extensions to try (in order).
+     * Default: ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx']
+     *
+     * Empty string '' means try exact path first.
+     */
+    extensions?: string[];
+    /**
+     * Index files to try (in order).
+     * Default: ['index.js', 'index.ts', 'index.mjs', 'index.cjs', 'index.jsx', 'index.tsx']
+     */
+    indexFiles?: string[];
+}
+/**
+ * Resolve a base path to an actual file by trying extensions and index files.
+ *
+ * @param basePath - Absolute path (without extension) to resolve
+ * @param options - Resolution options (filesystem vs in-memory, extensions, index files)
+ * @returns Resolved file path or null if not found
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' (if exists)
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ *
+ * Note: Symbolic links are followed by existsSync(). Assumes all paths
+ * are within the project workspace as determined by discovery phase.
+ */
+export declare function resolveModulePath(basePath: string, options?: ModuleResolutionOptions): string | null;
+/**
+ * Check if import specifier is a relative import.
+ *
+ * @param specifier - The import specifier (e.g., './utils', 'lodash')
+ * @returns true if relative import (./ or ../), false otherwise
+ *
+ * @example
+ * ```ts
+ * isRelativeImport('./utils')      // true
+ * isRelativeImport('../shared')    // true
+ * isRelativeImport('lodash')       // false
+ * isRelativeImport('@scope/pkg')   // false
+ * isRelativeImport('node:fs')      // false
+ * ```
+ */
+export declare function isRelativeImport(specifier: string): boolean;
+/**
+ * Resolve relative import specifier to actual file path.
+ *
+ * Combines relative path resolution with module path resolution.
+ * Returns null for non-relative specifiers (bare modules, scoped packages).
+ *
+ * @param specifier - The import specifier (e.g., './utils', '../shared')
+ * @param containingFile - The file containing the import
+ * @param options - Resolution options
+ * @returns Resolved file path or null if not found or not relative
+ *
+ * @example
+ * ```ts
+ * // From /project/src/main.js, import './utils'
+ * resolveRelativeSpecifier('./utils', '/project/src/main.js')
+ * // → '/project/src/utils.js' (if exists)
+ * ```
+ */
+export declare function resolveRelativeSpecifier(specifier: string, containingFile: string, options?: ModuleResolutionOptions): string | null;
+//# sourceMappingURL=moduleResolution.d.ts.map

package/dist/utils/moduleResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleResolution.d.ts","sourceRoot":"","sources":["../../src/utils/moduleResolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,UAAqD,CAAC;AAerF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,UAO/B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAE/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,GAAG,IAAI,CAuDf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,GAAG,IAAI,CAYf"}

package/dist/utils/moduleResolution.js

@@ -0,0 +1,189 @@
+/**
+ * Module Resolution Utilities (REG-320)
+ *
+ * Unified module path resolution logic extracted from:
+ * - MountPointResolver.resolveImportSource()
+ * - JSModuleIndexer.resolveModulePath()
+ * - FunctionCallResolver._resolveImportPath()
+ * - IncrementalModuleIndexer.tryResolve()
+ *
+ * Provides consistent module resolution across all plugins.
+ */
+import { existsSync, statSync } from 'fs';
+import { dirname, extname, resolve, join } from 'path';
+/**
+ * Default file extensions to try when resolving modules.
+ * Order: exact match first, then JS variants, then TS variants.
+ */
+export const DEFAULT_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'];
+/**
+ * TypeScript extension redirects (REG-426).
+ * Maps JS-family extensions to their TS equivalents.
+ * Used when an import specifies a .js extension but only a .ts file exists.
+ * This matches TypeScript's own module resolution behavior for ESM.
+ */
+const TS_EXTENSION_REDIRECTS = {
+    '.js': ['.ts', '.tsx'],
+    '.jsx': ['.tsx'],
+    '.mjs': ['.mts'],
+    '.cjs': ['.cts'],
+};
+/**
+ * Default index files to try when resolving directory imports.
+ * Order: JS variants first (most common), then TS variants.
+ */
+export const DEFAULT_INDEX_FILES = [
+    'index.js',
+    'index.ts',
+    'index.mjs',
+    'index.cjs',
+    'index.jsx',
+    'index.tsx'
+];
+/**
+ * Check if path exists using the configured method.
+ */
+function pathExists(testPath, useFilesystem, fileIndex) {
+    if (useFilesystem) {
+        return existsSync(testPath);
+    }
+    return fileIndex?.has(testPath) ?? false;
+}
+/**
+ * Check if path is a directory (filesystem mode only).
+ */
+function isDirectory(path, useFilesystem) {
+    if (!useFilesystem) {
+        // In in-memory mode, we can't check if it's a directory
+        // The fileIndex should only contain file paths, not directories
+        return false;
+    }
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a base path to an actual file by trying extensions and index files.
+ *
+ * @param basePath - Absolute path (without extension) to resolve
+ * @param options - Resolution options (filesystem vs in-memory, extensions, index files)
+ * @returns Resolved file path or null if not found
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' (if exists)
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ *
+ * Note: Symbolic links are followed by existsSync(). Assumes all paths
+ * are within the project workspace as determined by discovery phase.
+ */
+export function resolveModulePath(basePath, options) {
+    const useFilesystem = options?.useFilesystem ?? true;
+    const fileIndex = options?.fileIndex;
+    const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
+    const indexFiles = options?.indexFiles ?? DEFAULT_INDEX_FILES;
+    // Validation: fail fast if misconfigured
+    if (!useFilesystem && !fileIndex) {
+        throw new Error('fileIndex is required when useFilesystem=false');
+    }
+    // Handle empty path gracefully
+    if (!basePath) {
+        return null;
+    }
+    // Normalize path (remove trailing slash)
+    const normalizedPath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    // Try extensions (including '' for exact match)
+    for (const ext of extensions) {
+        const testPath = normalizedPath + ext;
+        if (pathExists(testPath, useFilesystem, fileIndex)) {
+            // In filesystem mode, don't return directories
+            if (useFilesystem && ext === '' && isDirectory(testPath, useFilesystem)) {
+                // It's a directory, skip to index files
+                continue;
+            }
+            return testPath;
+        }
+    }
+    // TypeScript extension redirect (REG-426):
+    // import './foo.js' → try ./foo.ts when ./foo.js doesn't exist
+    const ext = extname(normalizedPath);
+    const tsAlternatives = TS_EXTENSION_REDIRECTS[ext];
+    if (tsAlternatives) {
+        const withoutExt = normalizedPath.slice(0, -ext.length);
+        for (const tsExt of tsAlternatives) {
+            const testPath = withoutExt + tsExt;
+            if (pathExists(testPath, useFilesystem, fileIndex)) {
+                return testPath;
+            }
+        }
+    }
+    // Try index files in directory
+    for (const indexFile of indexFiles) {
+        const testPath = join(normalizedPath, indexFile);
+        if (pathExists(testPath, useFilesystem, fileIndex)) {
+            return testPath;
+        }
+    }
+    return null;
+}
+/**
+ * Check if import specifier is a relative import.
+ *
+ * @param specifier - The import specifier (e.g., './utils', 'lodash')
+ * @returns true if relative import (./ or ../), false otherwise
+ *
+ * @example
+ * ```ts
+ * isRelativeImport('./utils')      // true
+ * isRelativeImport('../shared')    // true
+ * isRelativeImport('lodash')       // false
+ * isRelativeImport('@scope/pkg')   // false
+ * isRelativeImport('node:fs')      // false
+ * ```
+ */
+export function isRelativeImport(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../');
+}
+/**
+ * Resolve relative import specifier to actual file path.
+ *
+ * Combines relative path resolution with module path resolution.
+ * Returns null for non-relative specifiers (bare modules, scoped packages).
+ *
+ * @param specifier - The import specifier (e.g., './utils', '../shared')
+ * @param containingFile - The file containing the import
+ * @param options - Resolution options
+ * @returns Resolved file path or null if not found or not relative
+ *
+ * @example
+ * ```ts
+ * // From /project/src/main.js, import './utils'
+ * resolveRelativeSpecifier('./utils', '/project/src/main.js')
+ * // → '/project/src/utils.js' (if exists)
+ * ```
+ */
+export function resolveRelativeSpecifier(specifier, containingFile, options) {
+    // Only handle relative imports
+    if (!isRelativeImport(specifier)) {
+        return null;
+    }
+    // Resolve relative path to absolute base path
+    const dir = dirname(containingFile);
+    const basePath = resolve(dir, specifier);
+    // Use main resolution function
+    return resolveModulePath(basePath, options);
+}
+//# sourceMappingURL=moduleResolution.js.map

package/dist/utils/moduleResolution.js.map

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

package/dist/utils/resolveNodeFile.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve a node's file path to an absolute path.
+ *
+ * After REG-408, node.file stores paths relative to projectPath.
+ * This utility resolves them back to absolute for file system access.
+ * Also handles legacy absolute paths for backward compatibility.
+ *
+ * @param nodeFile - The file field from a graph node (relative or absolute)
+ * @param projectPath - The absolute project root path
+ * @returns Absolute file path
+ */
+export declare function resolveNodeFile(nodeFile: string, projectPath: string): string;
+//# sourceMappingURL=resolveNodeFile.d.ts.map

package/dist/utils/resolveNodeFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNodeFile.d.ts","sourceRoot":"","sources":["../../src/utils/resolveNodeFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG7E"}

package/dist/utils/resolveNodeFile.js

@@ -0,0 +1,18 @@
+/**
+ * Resolve a node's file path to an absolute path.
+ *
+ * After REG-408, node.file stores paths relative to projectPath.
+ * This utility resolves them back to absolute for file system access.
+ * Also handles legacy absolute paths for backward compatibility.
+ *
+ * @param nodeFile - The file field from a graph node (relative or absolute)
+ * @param projectPath - The absolute project root path
+ * @returns Absolute file path
+ */
+import { isAbsolute, join } from 'path';
+export function resolveNodeFile(nodeFile, projectPath) {
+    if (isAbsolute(nodeFile))
+        return nodeFile;
+    return join(projectPath, nodeFile);
+}
+//# sourceMappingURL=resolveNodeFile.js.map

package/dist/utils/resolveNodeFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNodeFile.js","sourceRoot":"","sources":["../../src/utils/resolveNodeFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAExC,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,WAAmB;IACnE,IAAI,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AACrC,CAAC"}

package/dist/validation/PathValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathValidator.d.ts","sourceRoot":"","sources":["../../src/validation/PathValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAmBnD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAe;gBAElB,OAAO,EAAE,YAAY;IAIjC;;;;;;OAMG;IACG,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsF7F;;;;;OAKG;YACW,sBAAsB;IAwDpC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAoBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,eAAe;CAexB"}
+{"version":3,"file":"PathValidator.d.ts","sourceRoot":"","sources":["../../src/validation/PathValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAWnD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAe;gBAElB,OAAO,EAAE,YAAY;IAIjC;;;;;;OAMG;IACG,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsF7F;;;;;OAKG;YACW,sBAAsB;IAwDpC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAoBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,eAAe;CAexB"}

package/dist/validation/PathValidator.js

@@ -249,3 +249,4 @@ export class PathValidator {
         return `New endpoint reachable: ${endpoint.name}`;
     }
 }
+//# sourceMappingURL=PathValidator.js.map

package/dist/validation/PathValidator.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+/** Full Grafema version string (e.g., "0.2.5-beta") */
+export declare const GRAFEMA_VERSION: string;
+/**
+ * Extract major.minor.patch from a version string, stripping pre-release tags.
+ *
+ * "0.2.5-beta" → "0.2.5"
+ * "0.2.5" → "0.2.5"
+ * "1.0.0-alpha.1" → "1.0.0"
+ */
+export declare function getSchemaVersion(version: string): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAaA,uDAAuD;AACvD,eAAO,MAAM,eAAe,EAAE,MAAoB,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD"}

package/dist/version.js

@@ -0,0 +1,26 @@
+/**
+ * Grafema version constants.
+ *
+ * Reads version from @grafema/core package.json at module load time.
+ * This is the single source of truth for runtime version checks.
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+/** Full Grafema version string (e.g., "0.2.5-beta") */
+export const GRAFEMA_VERSION = pkg.version;
+/**
+ * Extract major.minor.patch from a version string, stripping pre-release tags.
+ *
+ * "0.2.5-beta" → "0.2.5"
+ * "0.2.5" → "0.2.5"
+ * "1.0.0-alpha.1" → "1.0.0"
+ */
+export function getSchemaVersion(version) {
+    // Strip pre-release tag (everything after first hyphen)
+    const base = version.split('-')[0];
+    return base;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AAErF,uDAAuD;AACvD,MAAM,CAAC,MAAM,eAAe,GAAW,GAAG,CAAC,OAAO,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,wDAAwD;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/core",
-  "version": "0.2.4-beta",
+  "version": "0.2.6-beta",
   "description": "Core analysis engine for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,8 +42,8 @@
     "node-source-walk": "^7.0.1",
     "oxc-parser": "^0.96.0",
     "yaml": "^2.8.2",
-    "@grafema/rfdb-client": "0.2.1-beta",
-    "@grafema/types": "0.2.4-beta"
+    "@grafema/rfdb-client": "0.2.6-beta",
+    "@grafema/types": "0.2.6-beta"
   },
   "optionalDependencies": {
     "@grafema/rfdb": "^0.1.0-alpha.2"
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "postbuild": "cp -r src/instructions/*.md dist/instructions/",
     "clean": "rm -rf dist"
   }
 }