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

package/dist/resource-registry.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Resource registry for managing collections of markdown resources.
+ *
+ * The registry maintains a collection of parsed markdown resources and provides:
+ * - Resource addition and crawling
+ * - Link validation across the registry
+ * - Link resolution (setting resolvedId for local_file links)
+ * - Query capabilities (by path, ID, or glob pattern)
+ */
+import type { ResourceMetadata } from './schemas/resource-metadata.js';
+import type { ValidationResult } from './schemas/validation-result.js';
+/**
+ * Options for crawling directories to add resources.
+ */
+export interface CrawlOptions {
+    /** Base directory to crawl */
+    baseDir: string;
+    /** Include patterns (default: all .md files) */
+    include?: string[];
+    /** Exclude patterns (default: node_modules, .git, dist) */
+    exclude?: string[];
+    /** Follow symbolic links (default: false) */
+    followSymlinks?: boolean;
+}
+/**
+ * Options for ResourceRegistry constructor.
+ */
+export interface ResourceRegistryOptions {
+    /** Validate resources when they are added (default: false) */
+    validateOnAdd?: boolean;
+}
+/**
+ * Statistics about resources in the registry.
+ */
+export interface RegistryStats {
+    totalResources: number;
+    totalLinks: number;
+    linksByType: Record<string, number>;
+}
+/**
+ * Resource registry for managing collections of markdown resources.
+ *
+ * Provides centralized management of markdown resources with:
+ * - Automatic parsing and ID generation
+ * - Link validation across the registry
+ * - Link resolution between resources
+ * - Query capabilities
+ *
+ * @example
+ * ```typescript
+ * const registry = new ResourceRegistry();
+ *
+ * // Add resources
+ * await registry.addResource('/project/README.md');
+ * await registry.crawl({ baseDir: '/project/docs' });
+ *
+ * // Validate all links
+ * const result = await registry.validate();
+ * console.log(`Found ${result.errorCount} errors`);
+ *
+ * // Resolve links between resources
+ * registry.resolveLinks();
+ *
+ * // Query resources
+ * const readme = registry.getResourceById('readme');
+ * const docs = registry.getResourcesByPattern('docs/**');
+ * ```
+ */
+export declare class ResourceRegistry {
+    private readonly resourcesByPath;
+    private readonly resourcesById;
+    private readonly validateOnAdd;
+    constructor(options?: ResourceRegistryOptions);
+    /**
+     * Add a single resource to the registry.
+     *
+     * Parses the markdown file, generates a unique ID, and stores the resource.
+     * If validateOnAdd is true, validates the resource immediately.
+     *
+     * @param filePath - Path to the markdown file (will be normalized to absolute)
+     * @returns The parsed resource metadata
+     * @throws Error if file cannot be read or parsed
+     *
+     * @example
+     * ```typescript
+     * const resource = await registry.addResource('./docs/README.md');
+     * console.log(`Added ${resource.id} with ${resource.links.length} links`);
+     * ```
+     */
+    addResource(filePath: string): Promise<ResourceMetadata>;
+    /**
+     * Add multiple resources to the registry in parallel.
+     *
+     * @param filePaths - Array of file paths to add
+     * @returns Array of parsed resource metadata
+     *
+     * @example
+     * ```typescript
+     * const resources = await registry.addResources([
+     *   './README.md',
+     *   './docs/guide.md',
+     *   './docs/api.md'
+     * ]);
+     * ```
+     */
+    addResources(filePaths: string[]): Promise<ResourceMetadata[]>;
+    /**
+     * Crawl a directory and add all matching markdown files.
+     *
+     * @param options - Crawl options (baseDir, include, exclude patterns)
+     * @returns Array of all added resources
+     *
+     * @example
+     * ```typescript
+     * // Crawl docs directory, excluding node_modules
+     * const resources = await registry.crawl({
+     *   baseDir: './docs',
+     *   include: ['**\/*.md'],
+     *   exclude: ['**\/node_modules/**']
+     * });
+     * ```
+     */
+    crawl(options: CrawlOptions): Promise<ResourceMetadata[]>;
+    /**
+     * Validate all links in all resources in the registry.
+     *
+     * Checks:
+     * - local_file links: file exists, anchor valid if present
+     * - anchor links: heading exists in current file
+     * - external links: returns info (not errors)
+     * - email links: valid by default
+     * - unknown links: returns warning
+     *
+     * @returns Validation result with all issues and statistics
+     *
+     * @example
+     * ```typescript
+     * const result = await registry.validate();
+     * console.log(`Passed: ${result.passed}`);
+     * console.log(`Errors: ${result.errorCount}`);
+     * console.log(`Warnings: ${result.warningCount}`);
+     * console.log(`Total resources: ${result.totalResources}`);
+     * for (const issue of result.issues) {
+     *   console.log(`${issue.severity}: ${issue.message}`);
+     * }
+     * ```
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Resolve links between resources in the registry.
+     *
+     * For each local_file link, sets the resolvedId property to the ID
+     * of the target resource if it exists in the registry.
+     *
+     * Mutates the ResourceLink objects in place.
+     *
+     * @example
+     * ```typescript
+     * registry.resolveLinks();
+     *
+     * // Now local_file links have resolvedId set
+     * const resource = registry.getResource('/project/README.md');
+     * for (const link of resource.links) {
+     *   if (link.type === 'local_file' && link.resolvedId) {
+     *     console.log(`Link resolves to: ${link.resolvedId}`);
+     *   }
+     * }
+     * ```
+     */
+    resolveLinks(): void;
+    /**
+     * Get a resource by its file path.
+     *
+     * @param filePath - Path to the resource (will be normalized to absolute)
+     * @returns Resource metadata or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const resource = registry.getResource('./docs/README.md');
+     * if (resource) {
+     *   console.log(`Found: ${resource.id}`);
+     * }
+     * ```
+     */
+    getResource(filePath: string): ResourceMetadata | undefined;
+    /**
+     * Get a resource by its ID.
+     *
+     * @param id - Resource ID
+     * @returns Resource metadata or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const resource = registry.getResourceById('readme');
+     * ```
+     */
+    getResourceById(id: string): ResourceMetadata | undefined;
+    /**
+     * Get all resources in the registry.
+     *
+     * @returns Array of all resource metadata
+     *
+     * @example
+     * ```typescript
+     * const allResources = registry.getAllResources();
+     * console.log(`Total: ${allResources.length}`);
+     * ```
+     */
+    getAllResources(): ResourceMetadata[];
+    /**
+     * Get resources matching a glob pattern.
+     *
+     * Normalizes paths to Unix-style (forward slashes) before matching
+     * to ensure consistent behavior across platforms. On Windows,
+     * path.resolve() returns backslashes but glob patterns expect forward slashes.
+     *
+     * @param pattern - Glob pattern (e.g., 'docs/**', '**\/README.md')
+     * @returns Array of matching resources
+     *
+     * @example
+     * ```typescript
+     * const docs = registry.getResourcesByPattern('docs/**');
+     * const readmes = registry.getResourcesByPattern('**\/README.md');
+     * ```
+     */
+    getResourcesByPattern(pattern: string): ResourceMetadata[];
+    /**
+     * Clear all resources from the registry.
+     *
+     * @example
+     * ```typescript
+     * registry.clear();
+     * console.log(registry.getAllResources().length); // 0
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get statistics about the resources in the registry.
+     *
+     * @returns Statistics object with counts
+     *
+     * @example
+     * ```typescript
+     * const stats = registry.getStats();
+     * console.log(`Resources: ${stats.totalResources}`);
+     * console.log(`Links: ${stats.totalLinks}`);
+     * console.log(`Local file links: ${stats.linksByType.local_file}`);
+     * ```
+     */
+    getStats(): RegistryStats;
+    /**
+     * Generate a unique ID from a file path.
+     *
+     * Process:
+     * 1. Get basename without extension
+     * 2. Convert to kebab-case
+     * 3. Handle collisions by appending suffix (-2, -3, etc.)
+     *
+     * @param filePath - Absolute file path
+     * @returns Unique ID
+     */
+    private generateUniqueId;
+    /**
+     * Build a map of file paths to their heading trees.
+     *
+     * Used for link validation.
+     */
+    private buildHeadingsByFileMap;
+    /**
+     * Resolve a relative link href to an absolute file path.
+     *
+     * @param linkHref - The href from the link (e.g., './file.md', '../dir/file.md#anchor')
+     * @param sourceFilePath - Absolute path to the source file
+     * @returns Absolute path to the target file
+     */
+    private resolveRelativeLinkPath;
+}
+//# sourceMappingURL=resource-registry.d.ts.map

package/dist/resource-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.d.ts","sourceRoot":"","sources":["../src/resource-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGxF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4C;IAC5E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;IAC1E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAE5B,OAAO,CAAC,EAAE,uBAAuB;IAI7C;;;;;;;;;;;;;;;OAeG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2C9D;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIpE;;;;;;;;;;;;;;;OAeG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAwB/D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAmD3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,IAAI,IAAI;IAkBpB;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAK3D;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIzD;;;;;;;;;;OAUG;IACH,eAAe,IAAI,gBAAgB,EAAE;IAIrC;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE;IA+B1D;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI,aAAa;IAmBzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAQ9B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;CAQhC"}