@vibe-agent-toolkit/resources 0.1.38 → 0.1.39-rc.1

package/src/link-validator.ts

@@ -18,15 +18,36 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { createRegistryIssue, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import {
   isGitIgnored,
   type GitTracker,
   verifyCaseSensitiveFilename,
 } from '@vibe-agent-toolkit/utils';
 
-import type { ValidationIssue } from './schemas/validation-result.js';
 import type { HeadingNode, ResourceLink } from './types.js';
-import { isWithinProject, resolveLocalHref } from './utils.js';
+import { isWithinProject, issueLocation, resolveLocalHref } from './utils.js';
+
+type LinkIssueExtras = Partial<Pick<ValidationIssue, 'location' | 'line' | 'link' | 'suggestion'>>;
+
+/**
+ * Build the common `createRegistryIssue` extras for a link issue: relative
+ * location, the problematic href, the line (only when defined — required for
+ * exactOptionalPropertyTypes), and an optional suggestion.
+ */
+function linkExtras(
+  link: ResourceLink,
+  sourceFilePath: string,
+  projectRoot: string | undefined,
+  suggestion?: string,
+): LinkIssueExtras {
+  return {
+    location: issueLocation(sourceFilePath, projectRoot),
+    link: link.href,
+    ...(link.line !== undefined && { line: link.line }),
+    ...(suggestion !== undefined && { suggestion }),
+  };
+}
 
 /**
  * Options for link validation.
@@ -71,7 +92,7 @@ export async function validateLink(
       return await validateLocalFileLink(link, sourceFilePath, headingsByFile, options);
 
     case 'anchor':
-      return await validateAnchorLink(link, sourceFilePath, headingsByFile);
+      return await validateAnchorLink(link, sourceFilePath, headingsByFile, options?.projectRoot);
 
     case 'external':
       // External URLs are not validated - don't report them
@@ -82,13 +103,11 @@ export async function validateLink(
       return null;
 
     case 'unknown':
-      return {
-        resourcePath: sourceFilePath,
-        line: link.line,
-        type: 'unknown_link',
-        link: link.href,
-        message: 'Unknown link type',
-      };
+      return createRegistryIssue(
+        'LINK_UNKNOWN',
+        'Unknown link type',
+        linkExtras(link, sourceFilePath, options?.projectRoot),
+      );
 
     default: {
       // TypeScript exhaustiveness check
@@ -107,31 +126,29 @@ export function resolutionFailureIssue(
   resolved: ReturnType<typeof resolveLocalHref>,
   link: ResourceLink,
   sourceFilePath: string,
+  projectRoot?: string,
 ): ValidationIssue | null {
   if (resolved.kind === 'absolute_no_root') {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message:
-        `Absolute-path link "${link.href}" requires a configured projectRoot; ` +
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `Absolute-path link "${link.href}" requires a configured projectRoot; ` +
         `none was provided. Configure vibe-agent-toolkit.config.yaml or run ` +
         `from within a git repository.`,
-      suggestion:
+      linkExtras(
+        link,
+        sourceFilePath,
+        projectRoot,
         'Rewrite as a source-relative link, or run from a directory with a config or git ancestor.',
-    };
+      ),
+    );
   }
 
   if (resolved.kind === 'absolute_escapes_root') {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `Absolute-path link "${link.href}" escapes the project root via path traversal.`,
-      suggestion: '',
-    };
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `Absolute-path link "${link.href}" escapes the project root via path traversal.`,
+      linkExtras(link, sourceFilePath, projectRoot, ''),
+    );
   }
 
   return null;
@@ -145,29 +162,29 @@ export function fileExistenceIssue(
   fileResult: { exists: boolean; resolvedPath: string; actualName?: string },
   link: ResourceLink,
   sourceFilePath: string,
+  projectRoot?: string,
 ): ValidationIssue | null {
   if (fileResult.exists) return null;
 
   if (fileResult.actualName) {
     const expectedName = path.basename(fileResult.resolvedPath);
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `File found but case mismatch: expected "${expectedName}" but found "${fileResult.actualName}". This will fail on case-sensitive filesystems (Linux). Update the link to match the actual filename.`,
-      suggestion: `Use "${fileResult.actualName}" instead of "${expectedName}"`,
-    };
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `File found but case mismatch: expected "${expectedName}" but found "${fileResult.actualName}". This will fail on case-sensitive filesystems (Linux). Update the link to match the actual filename.`,
+      linkExtras(
+        link,
+        sourceFilePath,
+        projectRoot,
+        `Use "${fileResult.actualName}" instead of "${expectedName}"`,
+      ),
+    );
   }
 
-  return {
-    resourcePath: sourceFilePath,
-    line: link.line,
-    type: 'broken_file',
-    link: link.href,
-    message: `File not found: ${fileResult.resolvedPath}`,
-    suggestion: '',
-  };
+  return createRegistryIssue(
+    'LINK_BROKEN_FILE',
+    `File not found: ${fileResult.resolvedPath}`,
+    linkExtras(link, sourceFilePath, projectRoot, ''),
+  );
 }
 
 /**
@@ -202,14 +219,11 @@ export function gitIgnoreSafetyIssue(
 
   if (sourceIsIgnored || !targetIsIgnored) return null;
 
-  return {
-    resourcePath: sourceFilePath,
-    line: link.line,
-    type: 'link_to_gitignored',
-    link: link.href,
-    message: `Non-ignored file links to gitignored file: ${resolvedTarget}. Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.`,
-    suggestion: '',
-  };
+  return createRegistryIssue(
+    'LINK_TO_GITIGNORED',
+    `Non-ignored file links to gitignored file: ${resolvedTarget}. Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.`,
+    linkExtras(link, sourceFilePath, options.projectRoot, ''),
+  );
 }
 
 /**
@@ -225,23 +239,24 @@ async function validateLocalFileLink(
 
   if (resolved.kind !== 'resolved') {
     // anchor_only → null no-op; absolute_no_root / absolute_escapes_root → broken_file.
-    return resolutionFailureIssue(resolved, link, sourceFilePath);
+    return resolutionFailureIssue(resolved, link, sourceFilePath, options?.projectRoot);
   }
 
   const fileResult = await validateResolvedFile(resolved.resolvedPath);
-  const notFound = fileExistenceIssue(fileResult, link, sourceFilePath);
+  const notFound = fileExistenceIssue(fileResult, link, sourceFilePath, options?.projectRoot);
   if (notFound) return notFound;
 
   if (fileResult.isDirectory) {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `Link target is a directory: ${fileResult.resolvedPath}`,
-      suggestion:
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `Link target is a directory: ${fileResult.resolvedPath}`,
+      linkExtras(
+        link,
+        sourceFilePath,
+        options?.projectRoot,
         'Link to a file inside the directory (e.g., README.md or index.md), or fix the link to point at the intended file.',
-    };
+      ),
+    );
   }
 
   const gitIgnoreIssue = gitIgnoreSafetyIssue(link, sourceFilePath, fileResult.resolvedPath, options);
@@ -250,14 +265,11 @@ async function validateLocalFileLink(
   if (resolved.anchor) {
     const anchorValid = await validateAnchor(resolved.anchor, fileResult.resolvedPath, headingsByFile);
     if (!anchorValid) {
-      return {
-        resourcePath: sourceFilePath,
-        line: link.line,
-        type: 'broken_anchor',
-        link: link.href,
-        message: `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
-        suggestion: '',
-      };
+      return createRegistryIssue(
+        'LINK_BROKEN_ANCHOR',
+        `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
+        linkExtras(link, sourceFilePath, options?.projectRoot, ''),
+      );
     }
   }
 
@@ -270,7 +282,8 @@ async function validateLocalFileLink(
 async function validateAnchorLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>
+  headingsByFile: Map<string, HeadingNode[]>,
+  projectRoot?: string,
 ): Promise<ValidationIssue | null> {
   // Extract anchor (strip leading #)
   const anchor = link.href.startsWith('#') ? link.href.slice(1) : link.href;
@@ -279,14 +292,11 @@ async function validateAnchorLink(
   const isValid = await validateAnchor(anchor, sourceFilePath, headingsByFile);
 
   if (!isValid) {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_anchor',
-      link: link.href,
-      message: `Anchor not found: ${link.href}`,
-      suggestion: '',
-    };
+    return createRegistryIssue(
+      'LINK_BROKEN_ANCHOR',
+      `Anchor not found: ${link.href}`,
+      linkExtras(link, sourceFilePath, projectRoot, ''),
+    );
   }
 
   return null;

package/src/multi-schema-validator.ts

@@ -12,12 +12,14 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
+import { createRegistryIssue } from '@vibe-agent-toolkit/agent-schema';
 import { safePath } from '@vibe-agent-toolkit/utils';
 
 import { validateFrontmatter } from './frontmatter-validator.js';
 import type { ValidationMode } from './schemas/project-config.js';
 import type { ValidationIssue } from './schemas/validation-result.js';
 import type { SchemaReference } from './types/resources.js';
+import { issueLocation } from './utils.js';
 
 /**
  * Load a JSON Schema from a file path
@@ -67,7 +69,7 @@ export async function validateFrontmatterMultiSchema(
       const schema = await loadSchema(schemaRef.schema, projectRoot);
 
       // Validate frontmatter
-      const issues = validateFrontmatter(frontmatter, schema, resourcePath, mode);
+      const issues = validateFrontmatter(frontmatter, schema, resourcePath, mode, undefined, projectRoot);
 
       // Update schema reference with results
       const result: SchemaReference = {
@@ -89,13 +91,13 @@ export async function validateFrontmatterMultiSchema(
         ...schemaRef,
         applied: true,
         valid: false,
-        errors: [{
-          resourcePath,
-          line: 1,
-          type: 'frontmatter_schema_error',
-          link: '',
-          message: `Failed to load or validate schema ${schemaRef.schema}: ${message}`,
-        }],
+        errors: [
+          createRegistryIssue(
+            'FRONTMATTER_SCHEMA_ERROR',
+            `Failed to load or validate schema ${schemaRef.schema}: ${message}`,
+            { location: issueLocation(resourcePath, projectRoot), line: 1 },
+          ),
+        ],
       });
     }
   }

package/src/resource-registry.ts

@@ -11,6 +11,7 @@
 import type fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { createRegistryIssue, type IssueCode, runValidationFramework, type ValidationConfig, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import { crawlDirectory, type CrawlOptions as UtilsCrawlOptions, type GitTracker, normalizedTmpdir, resolveAssetReference, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 
 import { calculateChecksum } from './checksum.js';
@@ -27,8 +28,8 @@ import type { ResourceCollectionInterface } from './resource-collection-interfac
 import type { SHA256 } from './schemas/checksum.js';
 import type { ProjectConfig } from './schemas/project-config.js';
 import type { HeadingNode, ResourceMetadata } from './schemas/resource-metadata.js';
-import type { ValidationIssue, ValidationResult } from './schemas/validation-result.js';
-import { matchesGlobPattern, splitHrefAnchor } from './utils.js';
+import type { ValidationResult } from './schemas/validation-result.js';
+import { issueLocation, matchesGlobPattern, splitHrefAnchor } from './utils.js';
 
 /**
  * Options for crawling directories to add resources.
@@ -72,6 +73,13 @@ export interface ValidateOptions {
   checkExternalUrls?: boolean;
   /** Disable cache for external URL checks (default: false) */
   noCache?: boolean;
+  /**
+   * Validation framework config (severity overrides + per-code allow entries).
+   * Applied INSIDE validate() via runValidationFramework — the library, not the
+   * CLI, resolves severity and drops ignored issues. Defaults to `{}` (no
+   * overrides: every issue keeps its registry default severity).
+   */
+  validationConfig?: ValidationConfig;
 }
 
 /**
@@ -422,13 +430,13 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     const issues: ValidationIssue[] = [];
     for (const resource of this.resourcesByPath.values()) {
       if (resource.frontmatterError) {
-        issues.push({
-          resourcePath: resource.filePath,
-          line: 1,
-          type: 'frontmatter_invalid_yaml',
-          link: '',
-          message: `Invalid YAML syntax in frontmatter: ${resource.frontmatterError}`,
-        });
+        issues.push(
+          createRegistryIssue(
+            'FRONTMATTER_INVALID_YAML',
+            `Invalid YAML syntax in frontmatter: ${resource.frontmatterError}`,
+            { location: issueLocation(resource.filePath, this.baseDir), line: 1 },
+          ),
+        );
       }
     }
     return issues;
@@ -479,7 +487,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         resource.frontmatter,
         schema,
         resource.filePath,
-        mode
+        mode,
+        undefined,
+        this.baseDir,
       );
       issues.push(...frontmatterIssues);
     }
@@ -593,6 +603,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         resource.filePath,
         mode,
         schemaPath,
+        this.baseDir,
       );
 
       // New: walk URI-family frontmatter values. Default-on; explicit `false` disables.
@@ -624,13 +635,13 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     } catch (error) {
       // Handle missing or invalid schema files gracefully
       const errorMessage = error instanceof Error ? error.message : String(error);
-      return [{
-        resourcePath: resource.filePath,
-        line: 1,
-        type: 'frontmatter_schema_error',
-        link: '',
-        message: `Failed to load or parse frontmatter schema '${validation.frontmatterSchema}': ${errorMessage}`,
-      }];
+      return [
+        createRegistryIssue(
+          'FRONTMATTER_SCHEMA_ERROR',
+          `Failed to load or parse frontmatter schema '${validation.frontmatterSchema}': ${errorMessage}`,
+          { location: issueLocation(resource.filePath, this.baseDir), line: 1 },
+        ),
+      ];
     }
   }
 
@@ -706,8 +717,11 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       issues.push(...externalUrlIssues);
     }
 
-    // Count issues (all are errors now)
-    const errorCount = issues.length;
+    // Resolve severity + apply allow-filter INSIDE the library (not the CLI).
+    // `emitted` = post-allow-filter, severity-resolved, with `ignore`d dropped.
+    const framework = runValidationFramework(issues, options?.validationConfig ?? {});
+    const emitted = framework.emitted;
+    const errorCount = emitted.length;
 
     // Count links by type
     const linksByType: Record<string, number> = {};
@@ -726,9 +740,10 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         0
       ),
       linksByType,
-      issues,
+      issues: emitted,
       errorCount,
       passed: errorCount === 0,
+      hasErrors: framework.hasErrors,
       durationMs,
       timestamp: new Date(),
     };
@@ -830,17 +845,17 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         continue;
       }
 
-      const issueType = this.determineExternalUrlIssueType(result.statusCode, result.error);
+      const issueCode = this.determineExternalUrlIssueCode(result.statusCode, result.error);
       const errorMessage = result.error ?? `HTTP ${result.statusCode}`;
 
       for (const location of locations) {
-        issues.push({
-          resourcePath: location.resourcePath,
-          line: location.line,
-          type: issueType,
-          link: result.url,
-          message: `External URL failed: ${errorMessage}`,
-        });
+        issues.push(
+          createRegistryIssue(issueCode, `External URL failed: ${errorMessage}`, {
+            location: issueLocation(location.resourcePath, this.baseDir),
+            link: result.url,
+            ...(location.line !== undefined && { line: location.line }),
+          }),
+        );
       }
     }
 
@@ -848,18 +863,18 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   }
 
   /**
-   * Determine issue type based on validation error.
+   * Determine the registry issue code based on the external-URL validation error.
    * @private
    */
-  private determineExternalUrlIssueType(statusCode: number, error?: string): string {
+  private determineExternalUrlIssueCode(statusCode: number, error?: string): IssueCode {
     if (statusCode === 0) {
       const errorLower = error?.toString().toLowerCase();
       if (errorLower?.includes('timeout')) {
-        return 'external_url_timeout';
+        return 'EXTERNAL_URL_TIMEOUT';
       }
-      return 'external_url_error';
+      return 'EXTERNAL_URL_ERROR';
     }
-    return 'external_url_dead';
+    return 'EXTERNAL_URL_DEAD';
   }
 
   /**

package/src/schemas/project-config.ts

@@ -96,6 +96,8 @@ export const ResourcesConfigSchema = z.object({
     .describe('Global default exclude patterns (not used by collections in Phase 2)'),
   collections: z.record(z.string(), CollectionConfigSchema).optional()
     .describe('Named collections of resources'),
+  validation: ValidationConfigSchema.optional()
+    .describe('Validation framework config: severity overrides and per-code allow entries (applied inside ResourceRegistry.validate)'),
 }).describe('Resources section of project configuration');
 
 export type ResourcesConfig = z.infer<typeof ResourcesConfigSchema>;

package/src/schemas/validation-result.ts

@@ -1,32 +1,7 @@
+import { ValidationIssueSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
-/**
- * A single validation issue found during link validation.
- *
- * Issue types:
- * - broken_file: Local file link points to non-existent file
- * - broken_anchor: Anchor link points to non-existent heading
- * - frontmatter_missing: Schema requires frontmatter, file has none
- * - frontmatter_invalid_yaml: YAML syntax error in frontmatter
- * - frontmatter_schema_error: Frontmatter fails JSON Schema validation
- * - external_url_dead: External URL returned error status (4xx, 5xx)
- * - external_url_timeout: External URL request timed out
- * - external_url_error: External URL validation failed (DNS, network, etc.)
- * - unknown_link: Unknown link type
- *
- * Includes details about what went wrong, where it occurred, and optionally
- * how to fix it.
- */
-export const ValidationIssueSchema = z.object({
-  resourcePath: z.string().describe('Absolute path to the resource containing the issue'),
-  line: z.number().int().positive().optional().describe('Line number where the issue occurs'),
-  type: z.string().describe('Issue type identifier (e.g., "broken_file", "broken_anchor", "frontmatter_schema_error", "unknown_link")'),
-  link: z.string().describe('The problematic link'),
-  message: z.string().describe('Human-readable description of the issue'),
-  suggestion: z.string().optional().describe('Optional suggestion for fixing the issue'),
-}).describe('A single validation issue found during link validation');
-
-export type ValidationIssue = z.infer<typeof ValidationIssueSchema>;
+export { type ValidationIssue, ValidationIssueSchema } from '@vibe-agent-toolkit/agent-schema';
 
 /**
  * Complete results from validating a collection of resources.
@@ -38,9 +13,10 @@ export const ValidationResultSchema = z.object({
   totalResources: z.number().int().nonnegative().describe('Total number of resources validated'),
   totalLinks: z.number().int().nonnegative().describe('Total number of links found across all resources'),
   linksByType: z.record(z.string(), z.number().int().nonnegative()).describe('Count of links by type (e.g., {"local_file": 10, "external": 5})'),
-  issues: z.array(ValidationIssueSchema).describe('All validation issues found'),
-  errorCount: z.number().int().nonnegative().describe('Number of issues found'),
+  issues: z.array(ValidationIssueSchema).describe('Emitted validation issues (allow-filtered + severity-resolved; ignored issues dropped)'),
+  errorCount: z.number().int().nonnegative().describe('Number of emitted issues'),
   passed: z.boolean().describe('True if validation succeeded (errorCount === 0)'),
+  hasErrors: z.boolean().describe('True when any emitted issue has resolved severity "error"'),
   durationMs: z.number().nonnegative().describe('Validation duration in milliseconds'),
   timestamp: z.date().describe('When validation was performed'),
 }).describe('Complete results from validating a collection of resources');

package/src/types/resources.ts

@@ -6,8 +6,9 @@
  * with optional absolutePath for runtime operations.
  */
 
+import type { ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+
 import type { SHA256 } from '../schemas/checksum.js';
-import type { ValidationIssue } from '../schemas/validation-result.js';
 
 /**
  * Resource type discriminator for type-safe handling

package/src/utils.ts

@@ -9,6 +9,21 @@ import path from 'node:path';
 import { toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
 import picomatch from 'picomatch';
 
+/**
+ * Compute a `ValidationIssue.location`: the (absolute) source file path made
+ * relative to the project root. When no project root is known, fall back to the
+ * source path forward-slashed so the location is still useful and stable.
+ *
+ * @param sourceFilePath - Absolute path to the file the issue was found in.
+ * @param projectRoot - Project root, or undefined when none could be determined.
+ * @returns Forward-slashed relative location (or the forward-slashed absolute path).
+ */
+export function issueLocation(sourceFilePath: string, projectRoot: string | undefined): string {
+  return projectRoot === undefined
+    ? toForwardSlash(sourceFilePath)
+    : safePath.relative(projectRoot, sourceFilePath);
+}
+
 /**
  * Check if a file path matches a glob pattern.
  *