@vibe-agent-toolkit/resources 0.1.3 → 0.1.4

package/src/schemas/validation-result.ts

@@ -1,40 +1,23 @@
 import { z } from 'zod';
 
-/**
- * Severity level for validation issues.
- *
- * - `error`: Critical issue that should block usage (e.g., broken file link)
- * - `warning`: Non-critical issue that should be addressed (e.g., questionable link format)
- * - `info`: Informational message (e.g., external URL not validated)
- */
-export const ValidationSeveritySchema = z.enum([
-  'error',
-  'warning',
-  'info',
-]).describe('Severity level for validation issues');
-
-export type ValidationSeverity = z.infer<typeof ValidationSeveritySchema>;
-
 /**
  * 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
- * - external_url: External URL (informational, not validated)
- * - unknown_link: Unknown link type
  * - frontmatter_missing: Schema requires frontmatter, file has none
  * - frontmatter_invalid_yaml: YAML syntax error in frontmatter
  * - frontmatter_schema_error: Frontmatter fails JSON Schema validation
+ * - 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({
-  severity: ValidationSeveritySchema.describe('Issue severity level'),
   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", "external_url")'),
+  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'),
@@ -46,16 +29,14 @@ export type ValidationIssue = z.infer<typeof ValidationIssueSchema>;
  * Complete results from validating a collection of resources.
  *
  * Provides summary statistics, detailed issues, and validation metadata.
- * The `passed` field indicates whether validation succeeded (no errors).
+ * The `passed` field indicates whether validation succeeded (no issues found).
  */
 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 error-level issues'),
-  warningCount: z.number().int().nonnegative().describe('Number of warning-level issues'),
-  infoCount: z.number().int().nonnegative().describe('Number of info-level issues'),
+  errorCount: z.number().int().nonnegative().describe('Number of issues found'),
   passed: z.boolean().describe('True if validation succeeded (errorCount === 0)'),
   durationMs: z.number().nonnegative().describe('Validation duration in milliseconds'),
   timestamp: z.date().describe('When validation was performed'),

package/src/types/resource-parser.ts

@@ -0,0 +1,302 @@
+/**
+ * Resource parsing functions
+ *
+ * Parses files into typed Resource objects with proper metadata extraction.
+ * Handles markdown, JSON, JSON Schema, and YAML formats.
+ */
+
+import { promises as fs } from 'node:fs';
+
+import yaml from 'js-yaml';
+
+import { calculateChecksum } from '../checksum.js';
+import { parseMarkdown } from '../link-parser.js';
+import type { HeadingNode, ResourceLink } from '../schemas/resource-metadata.js';
+
+import type {
+  Heading,
+  JsonResource,
+  JsonSchemaResource,
+  MarkdownResource,
+  SchemaReference,
+  YamlResource,
+} from './resources.js';
+import { isJsonSchema, ResourceType } from './resources.js';
+
+/**
+ * Parse markdown file into MarkdownResource
+ *
+ * @param absolutePath - Absolute path to markdown file
+ * @param projectPath - Relative path from project root
+ * @param collectionName - Collection this resource belongs to
+ * @returns Parsed MarkdownResource
+ */
+export async function parseMarkdownResource(
+  absolutePath: string,
+  projectPath: string,
+  collectionName: string,
+): Promise<MarkdownResource> {
+  // Get file stats
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const stats = await fs.stat(absolutePath);
+
+  // Parse markdown content
+  const parsed = await parseMarkdown(absolutePath);
+
+  // Calculate checksum
+  const checksum = await calculateChecksum(absolutePath);
+
+  // Extract link hrefs
+  const links = parsed.links.map((link: ResourceLink) => link.href);
+
+  // Convert HeadingNode[] to Heading[]
+  const headings: Heading[] = convertHeadingsToSimple(parsed.headings);
+
+  // Estimate token count (chars / 4)
+  const estimatedTokenCount = Math.floor(parsed.content.length / 4);
+
+  // Extract self-asserted schema from frontmatter $schema field
+  const schemas: SchemaReference[] = [];
+  if (parsed.frontmatter?.['$schema'] !== undefined) {
+    if (typeof parsed.frontmatter['$schema'] === 'string') {
+      schemas.push({
+        schema: parsed.frontmatter['$schema'],
+        source: 'self',
+        applied: false,
+      });
+    }
+  }
+
+  const resource: MarkdownResource = {
+    id: projectPath,
+    projectPath,
+    absolutePath,
+    type: ResourceType.MARKDOWN,
+    mimeType: 'text/markdown',
+    sizeBytes: stats.size,
+    modifiedAt: stats.mtime,
+    checksum,
+    collections: [collectionName],
+    schemas,
+    content: parsed.content,
+    links,
+    headings,
+    estimatedTokenCount,
+  };
+
+  // Only set frontmatter if it exists (exactOptionalPropertyTypes)
+  if (parsed.frontmatter !== undefined) {
+    resource.frontmatter = parsed.frontmatter;
+  }
+
+  return resource;
+}
+
+/**
+ * Parse JSON Schema file into JsonSchemaResource
+ *
+ * @param absolutePath - Absolute path to JSON Schema file
+ * @param projectPath - Relative path from project root
+ * @param collectionName - Collection this resource belongs to
+ * @returns Parsed JsonSchemaResource
+ */
+export async function parseJsonSchemaResource(
+  absolutePath: string,
+  projectPath: string,
+  collectionName: string,
+): Promise<JsonSchemaResource> {
+  // Get file stats
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const stats = await fs.stat(absolutePath);
+
+  // Read and parse JSON
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const content = await fs.readFile(absolutePath, 'utf-8');
+  const schema = JSON.parse(content) as object & {
+    $id?: string;
+    $schema?: string;
+    title?: string;
+    description?: string;
+  };
+
+  // Calculate checksum
+  const checksum = await calculateChecksum(absolutePath);
+
+  // Build resource with required fields
+  const resource: JsonSchemaResource = {
+    id: projectPath,
+    projectPath,
+    absolutePath,
+    type: ResourceType.JSON_SCHEMA,
+    mimeType: 'application/schema+json',
+    sizeBytes: stats.size,
+    modifiedAt: stats.mtime,
+    checksum,
+    collections: [collectionName],
+    schema,
+    referencedBy: [],
+  };
+
+  // Only set optional fields if they exist (exactOptionalPropertyTypes)
+  if (schema.$id !== undefined) {
+    resource.schemaId = schema.$id;
+  }
+  if (schema.$schema !== undefined) {
+    resource.schemaVersion = schema.$schema;
+  }
+  if (schema.title !== undefined) {
+    resource.title = schema.title;
+  }
+  if (schema.description !== undefined) {
+    resource.description = schema.description;
+  }
+
+  return resource;
+}
+
+/**
+ * Parse JSON file into JsonResource
+ *
+ * @param absolutePath - Absolute path to JSON file
+ * @param projectPath - Relative path from project root
+ * @param collectionName - Collection this resource belongs to
+ * @returns Parsed JsonResource
+ */
+export async function parseJsonResource(
+  absolutePath: string,
+  projectPath: string,
+  collectionName: string,
+): Promise<JsonResource> {
+  // Get file stats
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const stats = await fs.stat(absolutePath);
+
+  // Read and parse JSON
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const content = await fs.readFile(absolutePath, 'utf-8');
+  const data: unknown = JSON.parse(content);
+
+  // Calculate checksum
+  const checksum = await calculateChecksum(absolutePath);
+
+  return {
+    id: projectPath,
+    projectPath,
+    absolutePath,
+    type: ResourceType.JSON,
+    mimeType: 'application/json',
+    sizeBytes: stats.size,
+    modifiedAt: stats.mtime,
+    checksum,
+    collections: [collectionName],
+    data,
+  };
+}
+
+/**
+ * Parse YAML file into YamlResource
+ *
+ * @param absolutePath - Absolute path to YAML file
+ * @param projectPath - Relative path from project root
+ * @param collectionName - Collection this resource belongs to
+ * @returns Parsed YamlResource
+ */
+export async function parseYamlResource(
+  absolutePath: string,
+  projectPath: string,
+  collectionName: string,
+): Promise<YamlResource> {
+  // Get file stats
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const stats = await fs.stat(absolutePath);
+
+  // Read and parse YAML
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const content = await fs.readFile(absolutePath, 'utf-8');
+  const data = yaml.load(content);
+
+  // Calculate checksum
+  const checksum = await calculateChecksum(absolutePath);
+
+  return {
+    id: projectPath,
+    projectPath,
+    absolutePath,
+    type: ResourceType.YAML,
+    mimeType: 'application/yaml',
+    sizeBytes: stats.size,
+    modifiedAt: stats.mtime,
+    checksum,
+    collections: [collectionName],
+    data,
+  };
+}
+
+/**
+ * Detect resource type from file path and content
+ *
+ * @param filePath - Path to file
+ * @param data - Parsed data (for JSON/YAML detection)
+ * @returns Detected ResourceType
+ */
+export function detectResourceType(filePath: string, data?: unknown): ResourceType {
+  const ext = filePath.toLowerCase().split('.').pop();
+
+  // Check extension first
+  if (ext === 'md' || ext === 'markdown') {
+    return ResourceType.MARKDOWN;
+  }
+
+  if (ext === 'yaml' || ext === 'yml') {
+    return ResourceType.YAML;
+  }
+
+  if (ext === 'json') {
+    // Use heuristics to detect JSON Schema
+    if (data && isJsonSchema(data)) {
+      return ResourceType.JSON_SCHEMA;
+    }
+    return ResourceType.JSON;
+  }
+
+  // Default fallback
+  if (data && typeof data === 'object' && isJsonSchema(data)) {
+    return ResourceType.JSON_SCHEMA;
+  }
+
+  return ResourceType.JSON; // Default
+}
+
+// ============================================================================
+// Helper functions
+// ============================================================================
+
+/**
+ * Convert HeadingNode[] to simple Heading[] for Phase 1
+ *
+ * @param nodes - Parsed heading nodes
+ * @returns Simplified heading array
+ */
+function convertHeadingsToSimple(nodes: HeadingNode[]): Heading[] {
+  const result: Heading[] = [];
+
+  function traverse(node: HeadingNode): void {
+    result.push({
+      level: node.level,
+      text: node.text,
+      id: node.slug,
+    });
+
+    if (node.children) {
+      for (const child of node.children) {
+        traverse(child);
+      }
+    }
+  }
+
+  for (const node of nodes) {
+    traverse(node);
+  }
+
+  return result;
+}

package/src/types/resource-path-utils.ts

@@ -0,0 +1,102 @@
+/**
+ * Path utilities for resource management
+ *
+ * Handles path normalization, validation, and absolutePath computation.
+ * All projectPath values must be relative with forward slashes.
+ */
+
+import { join, normalize, sep } from 'node:path';
+
+import { toForwardSlash } from '@vibe-agent-toolkit/utils';
+
+/**
+ * Normalize a path to projectPath format
+ *
+ * Converts to relative path with forward slashes:
+ * - Removes leading /, //, file://, file:///
+ * - Converts backslashes to forward slashes
+ * - Preserves relative path structure (including ../)
+ *
+ * @param path - Path to normalize
+ * @returns Normalized projectPath (relative, forward slashes)
+ */
+export function normalizeProjectPath(path: string): string {
+  let normalized = path;
+
+  // Remove file:// or file:/// protocol
+  normalized = normalized.replace(/^file:\/\/\/?/, '');
+
+  // Convert to forward slashes first (handles Windows backslashes)
+  normalized = toForwardSlash(normalized);
+
+  // Remove leading / or // (after converting backslashes)
+  normalized = normalized.replace(/^\/+/, '');
+
+  return normalized;
+}
+
+/**
+ * Validate that a projectPath is safe and relative
+ *
+ * Requirements:
+ * - Must be relative (no leading /, //, C:/, etc.)
+ * - Must use forward slashes only (no backslashes)
+ * - Must not escape project root with ../
+ * - Must not be a URL (http://, https://, file://)
+ * - Must not be empty
+ *
+ * @param projectPath - Path to validate
+ * @returns true if valid projectPath
+ */
+export function isValidProjectPath(projectPath: string): boolean {
+  if (!projectPath) {
+    return false;
+  }
+
+  // Reject absolute paths (leading slash or drive letter)
+  if (projectPath.startsWith('/') || /^[A-Za-z]:/.test(projectPath)) {
+    return false;
+  }
+
+  // Reject URLs
+  if (projectPath.startsWith('http://') || projectPath.startsWith('https://') || projectPath.startsWith('file://')) {
+    return false;
+  }
+
+  // Reject backslashes (must use forward slashes)
+  if (projectPath.includes('\\')) {
+    return false;
+  }
+
+  // Reject paths that escape project root
+  // Normalize the path and check if it starts with ../
+  const normalized = normalize(projectPath);
+  const parts = normalized.split(sep);
+  let depth = 0;
+
+  for (const part of parts) {
+    if (part === '..') {
+      depth--;
+      if (depth < 0) {
+        return false; // Escaped project root
+      }
+    } else if (part !== '.' && part !== '') {
+      depth++;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Compute absolute path from project root and projectPath
+ *
+ * This is a runtime utility - absolutePath should never be serialized.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param projectPath - Relative path from project root
+ * @returns Absolute path to resource
+ */
+export function getResourceAbsolutePath(projectRoot: string, projectPath: string): string {
+  return join(projectRoot, projectPath);
+}

package/src/types/resources.ts

@@ -0,0 +1,211 @@
+/**
+ * Core resource type system for vibe-agent-toolkit
+ *
+ * Defines discriminated unions for different resource types with unified interface.
+ * All resources use projectPath (relative, forward slashes) for serialization,
+ * with optional absolutePath for runtime operations.
+ */
+
+import type { SHA256 } from '../schemas/checksum.js';
+import type { ValidationIssue } from '../schemas/validation-result.js';
+
+/**
+ * Resource type discriminator for type-safe handling
+ */
+export enum ResourceType {
+  MARKDOWN = 'markdown',
+  JSON_SCHEMA = 'json-schema',
+  JSON = 'json',
+  YAML = 'yaml',
+}
+
+/**
+ * Reference to a JSON Schema with validation tracking
+ */
+export interface SchemaReference {
+  /** Path or URL to schema */
+  schema: string;
+
+  /** Source of schema assignment: 'self' (from $schema field), 'cli' (from CLI flag), or collection name */
+  source: string;
+
+  /** Whether validation was attempted for this schema */
+  applied: boolean;
+
+  /** Validation result (undefined if not validated) */
+  valid?: boolean;
+
+  /** Validation errors specific to this schema */
+  errors?: ValidationIssue[];
+}
+
+/**
+ * Simple heading structure for Phase 1
+ * Expanded in future phases
+ */
+export interface Heading {
+  level: number;
+  text: string;
+  id?: string;
+}
+
+/**
+ * Base resource properties shared by all resource types
+ */
+export interface BaseResource {
+  /** Unique identifier for this resource */
+  id: string;
+
+  /** Relative path from project root (forward slashes, no leading /) */
+  projectPath: string;
+
+  /** Absolute path computed at runtime (never serialized) */
+  absolutePath?: string;
+
+  /** Resource type discriminator */
+  type: ResourceType;
+
+  /** MIME type for the resource */
+  mimeType: string;
+
+  /** File size in bytes */
+  sizeBytes: number;
+
+  /** Last modification timestamp */
+  modifiedAt: Date;
+
+  /** SHA-256 checksum of file content */
+  checksum: SHA256;
+
+  /** Collections this resource belongs to (empty for Phase 1) */
+  collections: string[];
+}
+
+/**
+ * Markdown resource with parsed content and metadata
+ */
+export interface MarkdownResource extends BaseResource {
+  type: ResourceType.MARKDOWN;
+  mimeType: 'text/markdown';
+
+  /** Parsed YAML frontmatter (if present) */
+  frontmatter?: Record<string, unknown>;
+
+  /** JSON Schema references with validation tracking */
+  schemas: SchemaReference[];
+
+  /** Raw markdown content */
+  content: string;
+
+  /** Link hrefs found in content */
+  links: string[];
+
+  /** Document heading structure */
+  headings: Heading[];
+
+  /** Estimated token count (chars / 4) */
+  estimatedTokenCount: number;
+}
+
+/**
+ * JSON Schema resource
+ */
+export interface JsonSchemaResource extends BaseResource {
+  type: ResourceType.JSON_SCHEMA;
+  mimeType: 'application/schema+json';
+
+  /** Parsed schema object */
+  schema: object;
+
+  /** Schema $id field (if present) */
+  schemaId?: string;
+
+  /** Schema version (from $schema field) */
+  schemaVersion?: string;
+
+  /** Schema title (if present) */
+  title?: string;
+
+  /** Schema description (if present) */
+  description?: string;
+
+  /** Resource IDs that reference this schema */
+  referencedBy: string[];
+}
+
+/**
+ * JSON resource (not a schema)
+ */
+export interface JsonResource extends BaseResource {
+  type: ResourceType.JSON;
+  mimeType: 'application/json';
+
+  /** Parsed JSON data */
+  data: unknown;
+
+  /** JSON Schema references with validation tracking */
+  schemas?: SchemaReference[];
+}
+
+/**
+ * YAML resource
+ */
+export interface YamlResource extends BaseResource {
+  type: ResourceType.YAML;
+  mimeType: 'application/yaml';
+
+  /** Parsed YAML data */
+  data: unknown;
+
+  /** JSON Schema references with validation tracking */
+  schemas?: SchemaReference[];
+}
+
+/**
+ * Union type for all resource types
+ */
+export type Resource = MarkdownResource | JsonSchemaResource | JsonResource | YamlResource;
+
+// ============================================================================
+// JSON Schema Detection
+// ============================================================================
+
+/**
+ * JSON Schema keywords for heuristic detection
+ * See: https://json-schema.org/understanding-json-schema/reference/
+ */
+const SCHEMA_KEYWORDS = [
+  '$schema',
+  '$id',
+  'title',
+  'description',
+  'type',
+  'properties',
+  'required',
+  'items',
+  'enum',
+  'definitions',
+  '$defs',
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'not',
+] as const;
+
+/**
+ * Detect if data is likely a JSON Schema using heuristics
+ *
+ * Returns true if data is an object with 2+ recognized schema keywords.
+ * This heuristic catches schemas without explicit $schema field.
+ *
+ * @param data - Data to check
+ * @returns true if data appears to be a JSON Schema
+ */
+export function isJsonSchema(data: unknown): boolean {
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    return false;
+  }
+
+  const matchCount = SCHEMA_KEYWORDS.filter((keyword) => keyword in data).length;
+  return matchCount >= 2;
+}