@vibe-agent-toolkit/resource-compiler 0.1.11

package/dist/language-service/markdown-cache.js

@@ -0,0 +1,77 @@
+/**
+ * Cache for parsed markdown resources with mtime-based invalidation
+ * Prevents re-parsing markdown files on every IDE operation
+ */
+import { statSync } from 'node:fs';
+/**
+ * Global cache of parsed markdown resources
+ * Key: absolute file path
+ * Value: cache entry with resource and mtime
+ */
+const cache = new Map();
+/**
+ * Get a cached markdown resource or load it using the provided loader
+ * Invalidates cache if file has been modified since last load
+ *
+ * @param filePath - Absolute path to markdown file
+ * @param loader - Function to load and parse the markdown file
+ * @returns Parsed markdown resource
+ *
+ * @example
+ * ```typescript
+ * const resource = getMarkdownResource('/path/to/file.md', () => {
+ *   const content = readFileSync('/path/to/file.md', 'utf-8');
+ *   return parseMarkdown(content);
+ * });
+ * ```
+ */
+export function getMarkdownResource(filePath, loader) {
+    // Get current file modification time
+    let currentMtime;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Using validated path from TypeScript Language Service
+        const stats = statSync(filePath);
+        currentMtime = stats.mtimeMs;
+    }
+    catch {
+        // File doesn't exist or can't be accessed - always reload
+        currentMtime = 0;
+    }
+    // Check if cached version is still valid
+    const cached = cache.get(filePath);
+    if (cached?.mtime === currentMtime) {
+        return cached.resource;
+    }
+    // Load and cache the resource
+    const resource = loader();
+    cache.set(filePath, { resource, mtime: currentMtime });
+    return resource;
+}
+/**
+ * Clear the entire cache
+ * Useful for testing or manual cache invalidation
+ */
+export function clearCache() {
+    cache.clear();
+}
+/**
+ * Remove a specific file from the cache
+ * Useful when a file is deleted or moved
+ *
+ * @param filePath - Absolute path to markdown file
+ */
+export function invalidateFile(filePath) {
+    cache.delete(filePath);
+}
+/**
+ * Get cache statistics for debugging
+ *
+ * @returns Object with cache size and list of cached files
+ */
+export function getCacheStats() {
+    return {
+        size: cache.size,
+        files: [...cache.keys()],
+    };
+}
+//# sourceMappingURL=markdown-cache.js.map

package/dist/language-service/markdown-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-cache.js","sourceRoot":"","sources":["../../src/language-service/markdown-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAWnC;;;;GAIG;AACH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,MAA8B;IAE9B,qCAAqC;IACrC,IAAI,YAAoB,CAAC;IACzB,IAAI,CAAC;QACH,4HAA4H;QAC5H,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjC,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;QAC1D,YAAY,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,yCAAyC;IACzC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,MAAM,EAAE,KAAK,KAAK,YAAY,EAAE,CAAC;QACnC,OAAO,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IAEvD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;KACzB,CAAC;AACJ,CAAC"}

package/dist/language-service/plugin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * TypeScript Language Service Plugin for markdown imports
+ * Provides autocomplete, go-to-definition, diagnostics, and hover support
+ */
+/**
+ * Plugin initialization function
+ * Called by TypeScript when loading the plugin
+ */
+declare function init(modules: {
+    typescript: any;
+}): {
+    create: (info: any) => any;
+};
+export default init;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/language-service/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/language-service/plugin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH;;;GAGG;AACH,iBAAS,IAAI,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,GAAG,CAAA;CAAE;mBAMlB,GAAG,KAAG,GAAG;EA8ChC;AAED,eAAe,IAAI,CAAC"}

package/dist/language-service/plugin.js

@@ -0,0 +1,51 @@
+/**
+ * TypeScript Language Service Plugin for markdown imports
+ * Provides autocomplete, go-to-definition, diagnostics, and hover support
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types -- TypeScript Language Service plugin API requires any */
+import { enhanceCompletions } from './completions.js';
+import { enhanceDefinitions } from './definitions.js';
+import { enhanceDiagnostics } from './diagnostics.js';
+import { enhanceHover } from './hover.js';
+/**
+ * Plugin initialization function
+ * Called by TypeScript when loading the plugin
+ */
+function init(modules) {
+    const ts = modules.typescript;
+    /**
+     * Create the Language Service plugin
+     */
+    function create(info) {
+        const logger = info.project.projectService.logger;
+        logger.info('markdown-import-plugin: Plugin initialized');
+        // Get the original Language Service
+        const languageService = info.languageService;
+        // Create proxy to intercept Language Service methods
+        const proxy = {
+            ...languageService,
+            // Enhance autocomplete with markdown fragment suggestions
+            getCompletionsAtPosition(fileName, position, options) {
+                const prior = languageService.getCompletionsAtPosition(fileName, position, options);
+                return enhanceCompletions(ts, info, prior, fileName, position);
+            },
+            // Enhance go-to-definition for markdown imports and fragments
+            getDefinitionAtPosition(fileName, position) {
+                return enhanceDefinitions(ts, info, fileName, position);
+            },
+            // Enhance diagnostics to check markdown file/fragment existence
+            getSemanticDiagnostics(fileName) {
+                return enhanceDiagnostics(ts, info, fileName);
+            },
+            // Enhance hover tooltips with markdown content
+            getQuickInfoAtPosition(fileName, position) {
+                const prior = languageService.getQuickInfoAtPosition(fileName, position);
+                return enhanceHover(ts, info, prior, fileName, position);
+            },
+        };
+        return proxy;
+    }
+    return { create };
+}
+export default init;
+//# sourceMappingURL=plugin.js.map

package/dist/language-service/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/language-service/plugin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iKAAiK;AAEjK,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,SAAS,IAAI,CAAC,OAA4B;IACxC,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAE9B;;OAEG;IACH,SAAS,MAAM,CAAC,IAAS;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC;QAElD,MAAM,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;QAE1D,oCAAoC;QACpC,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QAE7C,qDAAqD;QACrD,MAAM,KAAK,GAAQ;YACjB,GAAG,eAAe;YAElB,0DAA0D;YAC1D,wBAAwB,CACtB,QAAgB,EAChB,QAAgB,EAChB,OAAY;gBAEZ,MAAM,KAAK,GAAG,eAAe,CAAC,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;gBACpF,OAAO,kBAAkB,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACjE,CAAC;YAED,8DAA8D;YAC9D,uBAAuB,CACrB,QAAgB,EAChB,QAAgB;gBAEhB,OAAO,kBAAkB,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC1D,CAAC;YAED,gEAAgE;YAChE,sBAAsB,CAAC,QAAgB;gBACrC,OAAO,kBAAkB,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChD,CAAC;YAED,+CAA+C;YAC/C,sBAAsB,CAAC,QAAgB,EAAE,QAAgB;gBACvD,MAAM,KAAK,GAAG,eAAe,CAAC,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBACzE,OAAO,YAAY,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC3D,CAAC;SACF,CAAC;QAEF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC;AAED,eAAe,IAAI,CAAC"}

package/dist/language-service/utils.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Utility functions for TypeScript AST traversal and markdown path resolution
+ */
+import type { MarkdownResource } from '../compiler/types.js';
+/**
+ * Find the AST node at a specific position in the source file
+ *
+ * @param ts - TypeScript module
+ * @param sourceFile - Source file to search
+ * @param position - Character position in the file
+ * @returns The deepest node containing the position, or undefined
+ */
+export declare function findNodeAtPosition(ts: any, sourceFile: any, position: number): any;
+/**
+ * Extract markdown file path from an import declaration or expression
+ *
+ * @param ts - TypeScript module
+ * @param node - AST node to check
+ * @returns Markdown file path if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // For: import Core from './core.md';
+ * getMarkdownPathFromImport(node) // → './core.md'
+ *
+ * // For: const x = 5;
+ * getMarkdownPathFromImport(node) // → null
+ * ```
+ */
+export declare function getMarkdownPathFromImport(ts: any, node: any): string | null;
+/**
+ * Extract markdown file path and fragment property from a property access expression
+ *
+ * @param ts - TypeScript module
+ * @param node - AST node to check
+ * @param sourceFile - Source file containing the node
+ * @returns Object with markdown path and fragment name, or null
+ *
+ * @example
+ * ```typescript
+ * // For: Core.fragments.purposeDriven
+ * getMarkdownPathFromExpression(node, sourceFile)
+ * // → { markdownPath: './core.md', fragmentName: 'purposeDriven' }
+ * ```
+ */
+export declare function getMarkdownPathFromExpression(ts: any, node: any, sourceFile: any): {
+    markdownPath: string;
+    fragmentName: string;
+} | null;
+/**
+ * Resolve a markdown import path to an absolute file path
+ *
+ * @param modulePath - Import path from TypeScript
+ * @param containingFile - Absolute path of the file doing the import
+ * @param compilerOptions - TypeScript compiler options
+ * @returns Absolute path to markdown file, or null if not found
+ */
+export declare function resolveMarkdownPath(modulePath: string, containingFile: string, compilerOptions: any): string | null;
+/**
+ * Load and parse a markdown file with caching
+ *
+ * @param filePath - Absolute path to markdown file
+ * @returns Parsed markdown resource
+ */
+export declare function loadMarkdownResource(filePath: string): MarkdownResource;
+/**
+ * Find the position (line/character) of a heading in markdown content
+ *
+ * @param content - Markdown file content
+ * @param heading - Heading text to find (without ## prefix)
+ * @returns Object with line and character position, or null if not found
+ */
+export declare function findHeadingPosition(content: string, heading: string): {
+    line: number;
+    character: number;
+} | null;
+/**
+ * Common pattern: Get source file and node at position
+ * Returns null if source file or node not found
+ *
+ * @param ts - TypeScript module
+ * @param info - Plugin create info
+ * @param fileName - File being edited
+ * @param position - Cursor position
+ * @returns Object with sourceFile and node, or null
+ */
+export declare function getSourceFileAndNode(ts: any, info: any, fileName: string, position: number): {
+    sourceFile: any;
+    node: any;
+} | null;
+/**
+ * Common pattern: Resolve markdown path and load resource
+ * Returns null if path cannot be resolved or file doesn't exist
+ *
+ * @param info - Plugin create info
+ * @param markdownPath - Import path to markdown file
+ * @param containingFile - File containing the import/access
+ * @returns Object with absolutePath and resource, or null
+ */
+export declare function resolveAndLoadMarkdown(info: any, markdownPath: string, containingFile: string): {
+    absolutePath: string;
+    resource: MarkdownResource;
+} | null;
+/**
+ * Common pattern: Resolve markdown path, load resource, and find fragment
+ * Returns null if resolution fails or fragment doesn't exist
+ * This is the shared logic for fragment-based operations (hover, diagnostics, etc.)
+ *
+ * @param info - Plugin create info
+ * @param markdownPath - Import path to markdown file
+ * @param fragmentName - camelCase fragment property name
+ * @param containingFile - File containing the fragment access
+ * @returns Object with absolutePath, resource, and fragment, or null
+ */
+export declare function resolveAndLoadFragment(info: any, markdownPath: string, fragmentName: string, containingFile: string): {
+    absolutePath: string;
+    resource: MarkdownResource;
+    fragment: any;
+} | null;
+/**
+ * Higher-order function for Language Service enhancement operations
+ * Encapsulates common pattern: get source file/node, try operation, catch errors
+ *
+ * @param ts - TypeScript module
+ * @param info - Plugin create info
+ * @param prior - Original result from TypeScript
+ * @param fileName - File being edited
+ * @param position - Cursor position
+ * @param operationName - Name for logging (e.g., "hover", "definitions")
+ * @param enhancer - Function to enhance the result
+ * @returns Enhanced result, or original if no enhancements needed
+ */
+export declare function enhanceLanguageServiceOperation(ts: any, info: any, prior: any, fileName: string, position: number, operationName: string, enhancer: (context: {
+    sourceFile: any;
+    node: any;
+}) => any): any;
+/**
+ * Get the property name node from a node
+ * If the node is a PropertyAccessExpression, returns its name property
+ * Otherwise returns the node itself
+ *
+ * @param ts - TypeScript module
+ * @param node - AST node (property access or identifier)
+ * @returns The property name node for precise text spans
+ */
+export declare function getPropertyNameNode(ts: any, node: any): any;
+/**
+ * Options for withFragmentResolution
+ */
+interface FragmentResolutionOptions {
+    info: any;
+    markdownPath: string;
+    fragmentName: string;
+    containingFile: string;
+    node: any;
+    operationName: string;
+    onSuccess: (result: {
+        absolutePath: string;
+        resource: MarkdownResource;
+        fragment: any;
+    }) => any;
+    onNotFound?: () => any;
+}
+/**
+ * Higher-order function for fragment-based operations (hover, diagnostics, etc.)
+ * Encapsulates common pattern: resolve markdown path, load resource, find fragment, handle errors
+ *
+ * @param options - Configuration options
+ * @returns Result from onSuccess or onNotFound callback
+ */
+export declare function withFragmentResolution(options: FragmentResolutionOptions): any;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/language-service/utils.d.ts.map

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

package/dist/language-service/utils.js

@@ -0,0 +1,341 @@
+/**
+ * Utility functions for TypeScript AST traversal and markdown path resolution
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types, sonarjs/cognitive-complexity, security/detect-non-literal-regexp, import/order -- TypeScript Language Service plugin API requires any and complex AST traversal */
+import { readFileSync } from 'node:fs';
+import { parseMarkdown } from '../compiler/markdown-parser.js';
+import { resolveMarkdownPath as resolveMarkdownPathFromTransformer } from '../transformer/path-resolver.js';
+import { getMarkdownResource } from './markdown-cache.js';
+/**
+ * Find the AST node at a specific position in the source file
+ *
+ * @param ts - TypeScript module
+ * @param sourceFile - Source file to search
+ * @param position - Character position in the file
+ * @returns The deepest node containing the position, or undefined
+ */
+export function findNodeAtPosition(ts, sourceFile, position) {
+    let foundNode;
+    function visit(node) {
+        if (position >= node.pos && position < node.end) {
+            foundNode = node;
+            ts.forEachChild(node, visit);
+        }
+    }
+    visit(sourceFile);
+    return foundNode;
+}
+/**
+ * Extract markdown file path from an import declaration or expression
+ *
+ * @param ts - TypeScript module
+ * @param node - AST node to check
+ * @returns Markdown file path if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // For: import Core from './core.md';
+ * getMarkdownPathFromImport(node) // → './core.md'
+ *
+ * // For: const x = 5;
+ * getMarkdownPathFromImport(node) // → null
+ * ```
+ */
+export function getMarkdownPathFromImport(ts, node) {
+    // Check if it's an import declaration
+    if (ts.isImportDeclaration(node)) {
+        const moduleSpecifier = node.moduleSpecifier;
+        if (ts.isStringLiteral(moduleSpecifier) && moduleSpecifier.text.endsWith('.md')) {
+            return moduleSpecifier.text;
+        }
+    }
+    // Check if it's a dynamic import
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+        const argument = node.arguments[0];
+        if (argument && ts.isStringLiteral(argument) && argument.text.endsWith('.md')) {
+            return argument.text;
+        }
+    }
+    return null;
+}
+/**
+ * Extract markdown file path and fragment property from a property access expression
+ *
+ * @param ts - TypeScript module
+ * @param node - AST node to check
+ * @param sourceFile - Source file containing the node
+ * @returns Object with markdown path and fragment name, or null
+ *
+ * @example
+ * ```typescript
+ * // For: Core.fragments.purposeDriven
+ * getMarkdownPathFromExpression(node, sourceFile)
+ * // → { markdownPath: './core.md', fragmentName: 'purposeDriven' }
+ * ```
+ */
+export function getMarkdownPathFromExpression(ts, node, sourceFile) {
+    // Look for patterns like: Core.fragments.purposeDriven
+    if (!ts.isPropertyAccessExpression(node)) {
+        return null;
+    }
+    // Check if accessing a fragment property
+    const fragmentName = node.name.text;
+    // Check if parent is `.fragments`
+    const parent = node.expression;
+    if (!ts.isPropertyAccessExpression(parent)) {
+        return null;
+    }
+    if (parent.name.text !== 'fragments') {
+        return null;
+    }
+    // Get the imported identifier (e.g., 'Core')
+    const identifier = parent.expression;
+    if (!ts.isIdentifier(identifier)) {
+        return null;
+    }
+    // Find the import declaration for this identifier
+    const importPath = findImportPathForIdentifier(ts, identifier.text, sourceFile);
+    if (!importPath?.endsWith('.md')) {
+        return null;
+    }
+    return { markdownPath: importPath, fragmentName };
+}
+/**
+ * Find the import path for a given identifier in the source file
+ *
+ * @param ts - TypeScript module
+ * @param identifierName - Name of the imported identifier
+ * @param sourceFile - Source file to search
+ * @returns Import path string, or null if not found
+ */
+function findImportPathForIdentifier(ts, identifierName, sourceFile) {
+    let importPath = null;
+    function visit(node) {
+        if (importPath) {
+            return;
+        }
+        // Check import declarations
+        if (ts.isImportDeclaration(node)) {
+            const clause = node.importClause;
+            if (!clause) {
+                return;
+            }
+            const moduleSpecifier = node.moduleSpecifier;
+            if (!ts.isStringLiteral(moduleSpecifier)) {
+                return;
+            }
+            // Check default import
+            const defaultName = clause.name;
+            if (defaultName?.text === identifierName) {
+                importPath = moduleSpecifier.text;
+                return;
+            }
+            // Check named imports
+            const namedBindings = clause.namedBindings;
+            if (namedBindings?.kind === ts.SyntaxKind.NamedImports) {
+                for (const element of namedBindings.elements) {
+                    if (element.name.text === identifierName) {
+                        importPath = moduleSpecifier.text;
+                        return;
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return importPath;
+}
+/**
+ * Resolve a markdown import path to an absolute file path
+ *
+ * @param modulePath - Import path from TypeScript
+ * @param containingFile - Absolute path of the file doing the import
+ * @param compilerOptions - TypeScript compiler options
+ * @returns Absolute path to markdown file, or null if not found
+ */
+export function resolveMarkdownPath(modulePath, containingFile, compilerOptions) {
+    return resolveMarkdownPathFromTransformer(modulePath, containingFile, compilerOptions);
+}
+/**
+ * Load and parse a markdown file with caching
+ *
+ * @param filePath - Absolute path to markdown file
+ * @returns Parsed markdown resource
+ */
+export function loadMarkdownResource(filePath) {
+    return getMarkdownResource(filePath, () => {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Using validated path from TypeScript Language Service
+        const content = readFileSync(filePath, 'utf-8');
+        return parseMarkdown(content);
+    });
+}
+/**
+ * Find the position (line/character) of a heading in markdown content
+ *
+ * @param content - Markdown file content
+ * @param heading - Heading text to find (without ## prefix)
+ * @returns Object with line and character position, or null if not found
+ */
+export function findHeadingPosition(content, heading) {
+    const lines = content.split('\n');
+    const headingPattern = new RegExp(String.raw `^##\s+${escapeRegex(heading)}\s*$`);
+    for (const [i, line] of lines.entries()) {
+        if (line && headingPattern.test(line)) {
+            return { line: i, character: 0 };
+        }
+    }
+    return null;
+}
+/**
+ * Escape special regex characters in a string
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for use in RegExp
+ */
+function escapeRegex(str) {
+    return str.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw `\$&`);
+}
+/**
+ * Common pattern: Get source file and node at position
+ * Returns null if source file or node not found
+ *
+ * @param ts - TypeScript module
+ * @param info - Plugin create info
+ * @param fileName - File being edited
+ * @param position - Cursor position
+ * @returns Object with sourceFile and node, or null
+ */
+export function getSourceFileAndNode(ts, info, fileName, position) {
+    const program = info.languageService.getProgram();
+    if (!program) {
+        return null;
+    }
+    const sourceFile = program.getSourceFile(fileName);
+    if (!sourceFile) {
+        return null;
+    }
+    const node = findNodeAtPosition(ts, sourceFile, position);
+    if (!node) {
+        return null;
+    }
+    return { sourceFile, node };
+}
+/**
+ * Common pattern: Resolve markdown path and load resource
+ * Returns null if path cannot be resolved or file doesn't exist
+ *
+ * @param info - Plugin create info
+ * @param markdownPath - Import path to markdown file
+ * @param containingFile - File containing the import/access
+ * @returns Object with absolutePath and resource, or null
+ */
+export function resolveAndLoadMarkdown(info, markdownPath, containingFile) {
+    const compilerOptions = info.project.getCompilerOptions();
+    const absolutePath = resolveMarkdownPath(markdownPath, containingFile, compilerOptions);
+    if (!absolutePath) {
+        return null;
+    }
+    const resource = loadMarkdownResource(absolutePath);
+    return { absolutePath, resource };
+}
+/**
+ * Common pattern: Resolve markdown path, load resource, and find fragment
+ * Returns null if resolution fails or fragment doesn't exist
+ * This is the shared logic for fragment-based operations (hover, diagnostics, etc.)
+ *
+ * @param info - Plugin create info
+ * @param markdownPath - Import path to markdown file
+ * @param fragmentName - camelCase fragment property name
+ * @param containingFile - File containing the fragment access
+ * @returns Object with absolutePath, resource, and fragment, or null
+ */
+export function resolveAndLoadFragment(info, markdownPath, fragmentName, containingFile) {
+    // Resolve markdown path and load resource
+    const result = resolveAndLoadMarkdown(info, markdownPath, containingFile);
+    if (!result) {
+        return null;
+    }
+    const { absolutePath, resource } = result;
+    // Convert camelCase property name to heading text
+    const headingText = fragmentName
+        .replaceAll(/([A-Z])/g, ' $1')
+        .trim()
+        .split(' ')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+    // Find the fragment in the markdown resource
+    const fragment = resource.fragments.find((frag) => frag.heading === headingText);
+    if (!fragment) {
+        return null;
+    }
+    return { absolutePath, resource, fragment };
+}
+/**
+ * Higher-order function for Language Service enhancement operations
+ * Encapsulates common pattern: get source file/node, try operation, catch errors
+ *
+ * @param ts - TypeScript module
+ * @param info - Plugin create info
+ * @param prior - Original result from TypeScript
+ * @param fileName - File being edited
+ * @param position - Cursor position
+ * @param operationName - Name for logging (e.g., "hover", "definitions")
+ * @param enhancer - Function to enhance the result
+ * @returns Enhanced result, or original if no enhancements needed
+ */
+export function enhanceLanguageServiceOperation(ts, info, prior, fileName, position, operationName, enhancer) {
+    try {
+        // Get the source file and find the node at cursor
+        const context = getSourceFileAndNode(ts, info, fileName, position);
+        if (!context) {
+            return prior;
+        }
+        // Call the specific enhancement logic
+        const enhanced = enhancer(context);
+        return enhanced ?? prior;
+    }
+    catch (error) {
+        // Log error and return original result
+        info.project.projectService.logger.info(`markdown-import-plugin: Error enhancing ${operationName}: ${String(error)}`);
+        return prior;
+    }
+}
+/**
+ * Get the property name node from a node
+ * If the node is a PropertyAccessExpression, returns its name property
+ * Otherwise returns the node itself
+ *
+ * @param ts - TypeScript module
+ * @param node - AST node (property access or identifier)
+ * @returns The property name node for precise text spans
+ */
+export function getPropertyNameNode(ts, node) {
+    if (ts.isPropertyAccessExpression(node)) {
+        return node.name;
+    }
+    return node;
+}
+/**
+ * Higher-order function for fragment-based operations (hover, diagnostics, etc.)
+ * Encapsulates common pattern: resolve markdown path, load resource, find fragment, handle errors
+ *
+ * @param options - Configuration options
+ * @returns Result from onSuccess or onNotFound callback
+ */
+export function withFragmentResolution(options) {
+    const { info, markdownPath, fragmentName, containingFile, operationName, onSuccess, onNotFound } = options;
+    try {
+        // Resolve markdown path, load resource, and find fragment
+        const result = resolveAndLoadFragment(info, markdownPath, fragmentName, containingFile);
+        if (!result) {
+            return onNotFound ? onNotFound() : undefined;
+        }
+        return onSuccess(result);
+    }
+    catch (error) {
+        info.project.projectService.logger.info(`markdown-import-plugin: Error during ${operationName}: ${String(error)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=utils.js.map