@vibe-agent-toolkit/resources 0.1.0-rc.7

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * @vibe-agent-toolkit/resources
+ *
+ * Markdown resource parsing, validation, and link integrity checking.
+ *
+ * This package provides comprehensive tools for managing collections of markdown resources,
+ * extracting links and headings, validating link integrity, and tracking resource relationships.
+ *
+ * @packageDocumentation
+ *
+ * @example Basic usage with ResourceRegistry
+ * ```typescript
+ * import { ResourceRegistry } from '@vibe-agent-toolkit/resources';
+ *
+ * const registry = new ResourceRegistry();
+ *
+ * // Add resources
+ * await registry.addResource('./README.md');
+ * await registry.crawl({ baseDir: './docs' });
+ *
+ * // Validate all links
+ * const result = await registry.validate();
+ * if (!result.passed) {
+ *   console.error(`Found ${result.errorCount} broken links`);
+ * }
+ * ```
+ */
+// Export main ResourceRegistry class
+export { ResourceRegistry, } from './resource-registry.js';
+// Export schemas for external use (e.g., JSON Schema generation, runtime validation)
+export { LinkTypeSchema, HeadingNodeSchema, ResourceLinkSchema, ResourceMetadataSchema, } from './schemas/resource-metadata.js';
+export { ValidationSeveritySchema, ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';
+// Export parser interface for advanced use cases
+export { parseMarkdown } from './link-parser.js';
+// Note: link-parser and link-validator internals are NOT exported
+// They are implementation details. Users should use ResourceRegistry API.
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EACL,gBAAgB,GAIjB,MAAM,wBAAwB,CAAC;AAahC,qFAAqF;AACrF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,iDAAiD;AACjD,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,kEAAkE;AAClE,0EAA0E"}

package/dist/link-parser.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Markdown link parser and analyzer.
+ *
+ * Parses markdown files to extract:
+ * - Links (regular, reference-style, autolinks)
+ * - Headings (with GitHub-style slugs and nested tree structure)
+ * - File size and token estimates
+ *
+ * Uses unified/remark for robust markdown parsing with GFM support.
+ */
+import type { HeadingNode, ResourceLink } from './types.js';
+/**
+ * Result of parsing a markdown file.
+ */
+export interface ParseResult {
+    links: ResourceLink[];
+    headings: HeadingNode[];
+    content: string;
+    sizeBytes: number;
+    estimatedTokenCount: number;
+}
+/**
+ * Parse a markdown file and extract all links, headings, and metadata.
+ *
+ * @param filePath - Absolute path to the markdown file
+ * @returns Parsed markdown data including links, headings, size, and token estimate
+ * @throws Error if file cannot be read or parsed
+ *
+ * @example
+ * ```typescript
+ * const result = await parseMarkdown('/path/to/document.md');
+ * console.log(`Found ${result.links.length} links`);
+ * console.log(`Document has ${result.headings.length} top-level headings`);
+ * ```
+ */
+export declare function parseMarkdown(filePath: string): Promise<ParseResult>;
+//# sourceMappingURL=link-parser.d.ts.map

package/dist/link-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-parser.d.ts","sourceRoot":"","sources":["../src/link-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,KAAK,EAAE,WAAW,EAAY,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiC1E"}

package/dist/link-parser.js

@@ -0,0 +1,327 @@
+/**
+ * Markdown link parser and analyzer.
+ *
+ * Parses markdown files to extract:
+ * - Links (regular, reference-style, autolinks)
+ * - Headings (with GitHub-style slugs and nested tree structure)
+ * - File size and token estimates
+ *
+ * Uses unified/remark for robust markdown parsing with GFM support.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+/**
+ * Parse a markdown file and extract all links, headings, and metadata.
+ *
+ * @param filePath - Absolute path to the markdown file
+ * @returns Parsed markdown data including links, headings, size, and token estimate
+ * @throws Error if file cannot be read or parsed
+ *
+ * @example
+ * ```typescript
+ * const result = await parseMarkdown('/path/to/document.md');
+ * console.log(`Found ${result.links.length} links`);
+ * console.log(`Document has ${result.headings.length} top-level headings`);
+ * ```
+ */
+export async function parseMarkdown(filePath) {
+    // Read file content and stats
+    const [content, stats] = await Promise.all([
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is user-provided path parameter
+        readFile(filePath, 'utf-8'),
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is user-provided path parameter
+        stat(filePath),
+    ]);
+    const sizeBytes = stats.size;
+    const estimatedTokenCount = Math.ceil(content.length / 4);
+    // Parse markdown with unified/remark
+    const processor = unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .use(remarkFrontmatter);
+    const tree = processor.parse(content);
+    // Extract links
+    const links = extractLinks(tree);
+    // Extract headings with tree structure
+    const headings = extractHeadings(tree);
+    return {
+        links,
+        headings,
+        content,
+        sizeBytes,
+        estimatedTokenCount,
+    };
+}
+/**
+ * Extract all links from the markdown AST.
+ *
+ * Handles:
+ * - Regular links: [text](href)
+ * - Reference-style links: [text][ref]
+ * - Autolinks: <url>
+ *
+ * @param tree - Markdown AST from unified/remark
+ * @returns Array of classified links with line numbers
+ */
+function extractLinks(tree) {
+    const links = [];
+    // Visit link nodes (regular links and autolinks)
+    visit(tree, 'link', (node) => {
+        const link = {
+            text: extractLinkText(node),
+            href: node.url,
+            type: classifyLink(node.url),
+            line: node.position?.start.line,
+        };
+        links.push(link);
+    });
+    // Visit linkReference nodes (reference-style links)
+    visit(tree, 'linkReference', (node) => {
+        // For reference-style links, we use the identifier as href
+        // In a full implementation, we'd resolve the definition, but for now
+        // we'll classify based on the identifier pattern
+        const href = node.identifier;
+        const link = {
+            text: extractLinkText(node),
+            href,
+            type: 'unknown', // Reference links need definition resolution
+            line: node.position?.start.line,
+        };
+        links.push(link);
+    });
+    return links;
+}
+/**
+ * Extract text content from a link node.
+ *
+ * @param node - Link or LinkReference node
+ * @returns Text content of the link
+ */
+function extractLinkText(node) {
+    return extractTextFromChildren(node.children);
+}
+/**
+ * Classify a link based on its href.
+ *
+ * @param href - The href attribute from the link
+ * @returns Classified link type
+ *
+ * @example
+ * ```typescript
+ * classifyLink('https://example.com') // 'external'
+ * classifyLink('mailto:user@example.com') // 'email'
+ * classifyLink('#heading') // 'anchor'
+ * classifyLink('./file.md') // 'local_file'
+ * classifyLink('./file.md#anchor') // 'local_file'
+ * ```
+ */
+function classifyLink(href) {
+    if (href.startsWith('http://') || href.startsWith('https://')) {
+        return 'external';
+    }
+    if (href.startsWith('mailto:')) {
+        return 'email';
+    }
+    if (href.startsWith('#')) {
+        return 'anchor';
+    }
+    // Links with anchors are still local file links
+    if (href.includes('#')) {
+        return 'local_file';
+    }
+    // .md files are always local files
+    if (href.endsWith('.md')) {
+        return 'local_file';
+    }
+    // Paths that look like file paths (start with ./ or ../ or /) or have no extension
+    if (href.startsWith('./') || href.startsWith('../') || href.startsWith('/')) {
+        return 'local_file';
+    }
+    // Paths without extensions (no dot or last dot is before a slash)
+    const lastSlash = href.lastIndexOf('/');
+    const lastDot = href.lastIndexOf('.');
+    if (lastDot === -1 || lastDot < lastSlash) {
+        return 'local_file';
+    }
+    return 'unknown';
+}
+/**
+ * Extract headings from the markdown AST and build a nested tree structure.
+ *
+ * Builds a hierarchical structure where:
+ * - h2 nodes are children of the preceding h1
+ * - h3 nodes are children of the preceding h2
+ * - etc.
+ *
+ * @param tree - Markdown AST from unified/remark
+ * @returns Array of top-level heading nodes with nested children
+ *
+ * @example
+ * For markdown:
+ * ```
+ * # Main
+ * ## Sub
+ * ### Deep
+ * ## Sub2
+ * ```
+ *
+ * Returns:
+ * ```
+ * [
+ *   {
+ *     level: 1,
+ *     text: 'Main',
+ *     slug: 'main',
+ *     children: [
+ *       { level: 2, text: 'Sub', slug: 'sub', children: [
+ *         { level: 3, text: 'Deep', slug: 'deep', children: [] }
+ *       ]},
+ *       { level: 2, text: 'Sub2', slug: 'sub2', children: [] }
+ *     ]
+ *   }
+ * ]
+ * ```
+ */
+function extractHeadings(tree) {
+    const flatHeadings = [];
+    // First pass: collect all headings in document order
+    visit(tree, 'heading', (node) => {
+        const text = extractHeadingText(node);
+        const heading = {
+            level: node.depth,
+            text,
+            slug: generateSlug(text),
+            line: node.position?.start.line,
+        };
+        flatHeadings.push(heading);
+    });
+    // Second pass: build tree structure using a stack
+    return buildHeadingTree(flatHeadings);
+}
+/**
+ * Extract text content from a heading node.
+ *
+ * @param node - Heading node
+ * @returns Text content of the heading
+ */
+function extractHeadingText(node) {
+    return extractTextFromChildren(node.children);
+}
+/**
+ * Extract text content from inline children nodes.
+ *
+ * Handles text nodes, inline code, emphasis, and other inline elements.
+ *
+ * @param children - Array of child nodes or undefined
+ * @returns Concatenated text content
+ */
+function extractTextFromChildren(children) {
+    if (!children || children.length === 0) {
+        return '';
+    }
+    return children
+        .map((child) => {
+        if (child.type === 'text') {
+            return child.value;
+        }
+        // Handle other inline elements (code, emphasis, etc.)
+        if ('value' in child) {
+            return String(child.value);
+        }
+        return '';
+    })
+        .join('');
+}
+/**
+ * Generate a GitHub-style slug from heading text.
+ *
+ * Rules:
+ * - Convert to lowercase
+ * - Replace spaces with hyphens
+ * - Remove special characters
+ * - Collapse multiple hyphens
+ *
+ * @param text - Heading text
+ * @returns GitHub-style slug for anchor links
+ *
+ * @example
+ * ```typescript
+ * generateSlug('Hello World') // 'hello-world'
+ * generateSlug('Section 1.1') // 'section-11'
+ * generateSlug('API Reference (v2)') // 'api-reference-v2'
+ * ```
+ */
+function generateSlug(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replaceAll(/[^\w\s-]/g, '') // Remove special chars
+        .replaceAll(/\s+/g, '-') // Replace spaces with hyphens
+        .replaceAll(/-+/g, '-'); // Collapse multiple hyphens
+}
+/**
+ * Build a nested heading tree from a flat list of headings.
+ *
+ * Uses a stack-based algorithm to correctly nest headings:
+ * - When encountering a higher-level heading, pop stack until we find the parent
+ * - Add the heading as a child of the top of stack
+ * - Push the heading onto the stack
+ *
+ * @param flatHeadings - Array of headings in document order
+ * @returns Array of top-level headings with nested children
+ */
+function buildHeadingTree(flatHeadings) {
+    if (flatHeadings.length === 0) {
+        return [];
+    }
+    const roots = [];
+    const stack = [];
+    for (const heading of flatHeadings) {
+        // Initialize children array
+        const headingWithChildren = {
+            ...heading,
+            children: [],
+        };
+        // Pop stack until we find a heading with lower level (the parent)
+        while (stack.length > 0 && (stack.at(-1)?.level ?? 0) >= heading.level) {
+            stack.pop();
+        }
+        if (stack.length === 0) {
+            // This is a root-level heading
+            roots.push(headingWithChildren);
+        }
+        else {
+            // Add as child of the top of stack
+            const parent = stack.at(-1);
+            if (parent) {
+                parent.children ??= [];
+                parent.children.push(headingWithChildren);
+            }
+        }
+        // Push current heading onto stack
+        stack.push(headingWithChildren);
+    }
+    // Clean up empty children arrays (convert to undefined)
+    cleanupEmptyChildren(roots);
+    return roots;
+}
+/**
+ * Remove empty children arrays from heading tree (convert to undefined).
+ *
+ * @param headings - Array of headings to clean up
+ */
+function cleanupEmptyChildren(headings) {
+    for (const heading of headings) {
+        if (heading.children?.length === 0) {
+            heading.children = undefined;
+        }
+        else if (heading.children && heading.children.length > 0) {
+            cleanupEmptyChildren(heading.children);
+        }
+    }
+}
+//# sourceMappingURL=link-parser.js.map

package/dist/link-parser.js.map

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

package/dist/link-validator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Link validation for markdown resources.
+ *
+ * Validates different types of links:
+ * - local_file: Checks if file exists, validates anchors if present
+ * - anchor: Validates heading exists in current or target file
+ * - external: Returns info (not validated)
+ * - email: Returns null (valid by default)
+ * - unknown: Returns warning
+ */
+import type { ValidationIssue } from './schemas/validation-result.js';
+import type { HeadingNode, ResourceLink } from './types.js';
+/**
+ * Validate a single link in a markdown resource.
+ *
+ * @param link - The link to validate
+ * @param sourceFilePath - Absolute path to the file containing the link
+ * @param headingsByFile - Map of file paths to their heading trees
+ * @returns ValidationIssue if link is broken, null if valid
+ *
+ * @example
+ * ```typescript
+ * const issue = await validateLink(link, '/project/docs/guide.md', headingsMap);
+ * if (issue) {
+ *   console.log(`${issue.severity}: ${issue.message}`);
+ * }
+ * ```
+ */
+export declare function validateLink(link: ResourceLink, sourceFilePath: string, headingsByFile: Map<string, HeadingNode[]>): Promise<ValidationIssue | null>;
+//# sourceMappingURL=link-validator.d.ts.map

package/dist/link-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-validator.d.ts","sourceRoot":"","sources":["../src/link-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,GACzC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuCjC"}

package/dist/link-validator.js

@@ -0,0 +1,217 @@
+/**
+ * Link validation for markdown resources.
+ *
+ * Validates different types of links:
+ * - local_file: Checks if file exists, validates anchors if present
+ * - anchor: Validates heading exists in current or target file
+ * - external: Returns info (not validated)
+ * - email: Returns null (valid by default)
+ * - unknown: Returns warning
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isGitignored } from '@vibe-agent-toolkit/utils';
+import { splitHrefAnchor } from './utils.js';
+/**
+ * Validate a single link in a markdown resource.
+ *
+ * @param link - The link to validate
+ * @param sourceFilePath - Absolute path to the file containing the link
+ * @param headingsByFile - Map of file paths to their heading trees
+ * @returns ValidationIssue if link is broken, null if valid
+ *
+ * @example
+ * ```typescript
+ * const issue = await validateLink(link, '/project/docs/guide.md', headingsMap);
+ * if (issue) {
+ *   console.log(`${issue.severity}: ${issue.message}`);
+ * }
+ * ```
+ */
+export async function validateLink(link, sourceFilePath, headingsByFile) {
+    switch (link.type) {
+        case 'local_file':
+            return await validateLocalFileLink(link, sourceFilePath, headingsByFile);
+        case 'anchor':
+            return await validateAnchorLink(link, sourceFilePath, headingsByFile);
+        case 'external':
+            // External URLs are not validated - return info
+            return {
+                severity: 'info',
+                resourcePath: sourceFilePath,
+                line: link.line,
+                type: 'external_url',
+                link: link.href,
+                message: 'External URL not validated',
+            };
+        case 'email':
+            // Email links are valid by default
+            return null;
+        case 'unknown':
+            return {
+                severity: 'warning',
+                resourcePath: sourceFilePath,
+                line: link.line,
+                type: 'unknown_link',
+                link: link.href,
+                message: 'Unknown link type',
+            };
+        default: {
+            // TypeScript exhaustiveness check
+            const _exhaustive = link.type;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Validate a local file link (with optional anchor).
+ */
+async function validateLocalFileLink(link, sourceFilePath, headingsByFile) {
+    // Extract file path and anchor from href
+    const [filePath, anchor] = splitHrefAnchor(link.href);
+    // Validate the file exists
+    const fileResult = await validateLocalFile(filePath, sourceFilePath);
+    if (!fileResult.exists) {
+        return {
+            severity: 'error',
+            resourcePath: sourceFilePath,
+            line: link.line,
+            type: 'broken_file',
+            link: link.href,
+            message: `File not found: ${fileResult.resolvedPath}`,
+            suggestion: 'Check that the file path is correct and the file exists',
+        };
+    }
+    // Check if the file is gitignored
+    if (fileResult.isGitignored) {
+        return {
+            severity: 'error',
+            resourcePath: sourceFilePath,
+            line: link.line,
+            type: 'broken_file',
+            link: link.href,
+            message: `File is gitignored: ${fileResult.resolvedPath}`,
+            suggestion: 'Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.',
+        };
+    }
+    // If there's an anchor, validate it too
+    if (anchor) {
+        const anchorValid = await validateAnchor(anchor, fileResult.resolvedPath, headingsByFile);
+        if (!anchorValid) {
+            return {
+                severity: 'error',
+                resourcePath: sourceFilePath,
+                line: link.line,
+                type: 'broken_anchor',
+                link: link.href,
+                message: `Anchor not found: #${anchor} in ${fileResult.resolvedPath}`,
+                suggestion: 'Check that the heading exists in the target file',
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Validate an anchor link (within current file).
+ */
+async function validateAnchorLink(link, sourceFilePath, headingsByFile) {
+    // Extract anchor (strip leading #)
+    const anchor = link.href.startsWith('#') ? link.href.slice(1) : link.href;
+    // Validate anchor exists in current file
+    const isValid = await validateAnchor(anchor, sourceFilePath, headingsByFile);
+    if (!isValid) {
+        return {
+            severity: 'error',
+            resourcePath: sourceFilePath,
+            line: link.line,
+            type: 'broken_anchor',
+            link: link.href,
+            message: `Anchor not found: ${link.href}`,
+            suggestion: 'Check that the heading exists in this file',
+        };
+    }
+    return null;
+}
+/**
+ * Validate that a local file exists and is not gitignored.
+ *
+ * @param href - The href to the file (relative or absolute)
+ * @param sourceFilePath - Absolute path to the source file
+ * @returns Object with exists flag, resolved absolute path, and gitignored flag
+ *
+ * @example
+ * ```typescript
+ * const result = await validateLocalFile('./docs/guide.md', '/project/README.md');
+ * if (result.exists && !result.isGitignored) {
+ *   console.log('File exists at:', result.resolvedPath);
+ * }
+ * ```
+ */
+async function validateLocalFile(href, sourceFilePath) {
+    // Resolve the path relative to the source file's directory
+    const sourceDir = path.dirname(sourceFilePath);
+    const resolvedPath = path.resolve(sourceDir, href);
+    // Check if file exists
+    let exists = false;
+    try {
+        await fs.access(resolvedPath, fs.constants.F_OK);
+        exists = true;
+    }
+    catch {
+        exists = false;
+    }
+    // Check if file is gitignored (only if it exists)
+    const gitignored = exists && isGitignored(resolvedPath);
+    return { exists, resolvedPath, isGitignored: gitignored };
+}
+/**
+ * Validate that an anchor (heading slug) exists in a file.
+ *
+ * @param anchor - The heading slug to find (without leading #)
+ * @param targetFilePath - Absolute path to the file containing the heading
+ * @param headingsByFile - Map of file paths to their heading trees
+ * @returns True if anchor exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const valid = await validateAnchor('my-heading', '/project/docs/guide.md', headingsMap);
+ * ```
+ */
+async function validateAnchor(anchor, targetFilePath, headingsByFile) {
+    // Get headings for target file
+    const headings = headingsByFile.get(targetFilePath);
+    if (!headings) {
+        return false;
+    }
+    // Search for matching slug (case-insensitive)
+    return findHeadingBySlug(headings, anchor);
+}
+/**
+ * Recursively search heading tree for a matching slug.
+ *
+ * Performs case-insensitive comparison of slugs.
+ *
+ * @param headings - Array of heading nodes to search
+ * @param targetSlug - The slug to find
+ * @returns True if slug found, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const found = findHeadingBySlug(headings, 'my-heading');
+ * ```
+ */
+function findHeadingBySlug(headings, targetSlug) {
+    const normalizedTarget = targetSlug.toLowerCase();
+    for (const heading of headings) {
+        // Check current heading
+        if (heading.slug.toLowerCase() === normalizedTarget) {
+            return true;
+        }
+        // Recursively check children
+        if (heading.children && findHeadingBySlug(heading.children, targetSlug)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=link-validator.js.map

package/dist/link-validator.js.map

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