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

package/src/schemas/link-auth.ts

@@ -0,0 +1,146 @@
+/**
+ * Zod schema for `resources.linkAuth` config.
+ *
+ * Validates the shape of an adopter's linkAuth configuration: providers
+ * (each either a `use: <macro>` reference or a full inline provider) plus
+ * an optional cache config. Strict — typos in provider field names are
+ * errors, per Postel's law ("writing our output → conservative").
+ *
+ * Provider entries accept EITHER:
+ *   - `{ use: <name>, ...overrides }` — reference a shipped macro by name;
+ *     override fields are deep-merged on top at expansion time. Overrides
+ *     are NOT strictly typed at this layer because they must match the
+ *     macro's shape, which we cannot see until expansion. A typo in an
+ *     override silently no-ops; the full provider shape is validated
+ *     after expansion (slice 2 wires that).
+ *   - A full inline `{ match, rewrite, auth, token, check }` — every field
+ *     required, every nested object strict.
+ *
+ * Mirrors the runtime types in `@vibe-agent-toolkit/utils`'s `link-auth/`
+ * module. Keep these aligned: a config that parses here must satisfy the
+ * `Provider` / `LinkAuthConfig` interfaces over there.
+ *
+ * Per design issue #113 §4 (vocabulary) and §5 (macros).
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Leaf types
+// ---------------------------------------------------------------------------
+
+export const ProviderMatchSchema = z
+  .object({
+    host: z.string().min(1).describe('Glob matched against URL hostname'),
+    excludeHost: z
+      .array(z.string().min(1))
+      .optional()
+      .describe('Globs that, if any match the hostname, exclude this provider'),
+  })
+  .strict()
+  .describe('Provider selection — match.host + optional excludeHost globs');
+
+export const RewriteRuleSchema = z
+  .object({
+    when: z.string().min(1).describe('Regex source (RFC-style, JavaScript-compatible) matched against the URL'),
+    vars: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe('Computed variables, each a template that references captures from `when`'),
+    to: z.string().min(1).describe('URL template — interpolates ${capture} and ${var}'),
+  })
+  .strict()
+  .describe('A single rewrite rule (one entry in a provider\'s ordered rewrite list)');
+
+export const ProviderAuthSchema = z
+  .object({
+    headers: z
+      .record(z.string(), z.string())
+      .describe('Header name → value template. Values interpolate ${token} and any capture/var.'),
+  })
+  .strict()
+  .describe('Auth headers attached to the authenticated fetch');
+
+export const TokenSourceSchema = z
+  .union([
+    z.object({ env: z.string().min(1) }).strict(),
+    z
+      .object({
+        command: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
+      })
+      .strict(),
+  ])
+  .describe('A single token source — env var, or argv command (preferred), or convenience string');
+
+export const ProviderCheckSchema = z
+  .object({
+    method: z.enum(['GET', 'HEAD']),
+    aliveStatus: z
+      .array(z.number().int().min(100).max(599))
+      .min(1)
+      .describe('HTTP status codes meaning the URL is alive (per host semantics)'),
+    notFoundMeaning: z
+      .enum(['ambiguous', 'dead'])
+      .describe(
+        'Per-host: does 404 mean "dead" (honest 404 host like Graph) or "ambiguous" (masking host like GitHub)?',
+      ),
+  })
+  .strict()
+  .describe('Status-to-outcome classifier (consumed by the resources layer, not the pure engine)');
+
+// ---------------------------------------------------------------------------
+// Provider entry (inline OR macro reference)
+// ---------------------------------------------------------------------------
+
+const InlineProviderSchema = z
+  .object({
+    match: ProviderMatchSchema,
+    rewrite: z.array(RewriteRuleSchema).min(1).describe('Ordered rewrite rules — first matching wins'),
+    auth: ProviderAuthSchema,
+    token: z.array(TokenSourceSchema).describe('Ordered token sources — first non-empty wins'),
+    check: ProviderCheckSchema,
+  })
+  .strict();
+
+const MacroProviderSchema = z
+  .object({
+    use: z.string().min(1).describe('Macro name (e.g. "github", "sharepoint")'),
+  })
+  .passthrough()
+  .describe(
+    'Reference a shipped macro by name. Override fields (match/rewrite/auth/token/check) deep-merge on top at expansion time.',
+  );
+
+export const ProviderEntrySchema = z
+  .union([MacroProviderSchema, InlineProviderSchema])
+  .describe('A provider entry — either { use: <macro>, ...overrides } or a full inline provider');
+
+// ---------------------------------------------------------------------------
+// Top-level linkAuth config
+// ---------------------------------------------------------------------------
+
+export const LinkAuthCacheSchema = z
+  .object({
+    ttlMinutes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe('Content cache TTL in minutes (default 30 — used by slice 3 content-fetch)'),
+  })
+  .strict();
+
+export const LinkAuthConfigSchema = z
+  .object({
+    cache: LinkAuthCacheSchema.optional(),
+    providers: z
+      .array(ProviderEntrySchema)
+      .describe('Ordered list of providers — first claiming-by-host wins'),
+  })
+  .strict()
+  .describe('`resources.linkAuth` — authenticated external link resolution config');
+
+export type LinkAuthConfig = z.infer<typeof LinkAuthConfigSchema>;
+export type ProviderEntry = z.infer<typeof ProviderEntrySchema>;
+export type RewriteRule = z.infer<typeof RewriteRuleSchema>;
+export type TokenSource = z.infer<typeof TokenSourceSchema>;

package/src/schemas/project-config.ts

@@ -1,6 +1,8 @@
 import { ValidationConfigSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
+import { LinkAuthConfigSchema } from './link-auth.js';
+
 /**
  * Official semver regex from https://semver.org/ (anchored).
  *
@@ -96,6 +98,10 @@ 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)'),
+  linkAuth: LinkAuthConfigSchema.optional()
+    .describe('Authenticated external link resolution config (issue #113 / link-auth engine)'),
 }).describe('Resources section of project configuration');
 
 export type ResourcesConfig = z.infer<typeof ResourcesConfigSchema>;

package/src/schemas/resource-metadata.ts

@@ -6,6 +6,7 @@ import { SHA256Schema } from './checksum.js';
  * Type of link found in markdown resources.
  *
  * - `local_file`: Link to a local file (relative or absolute path)
+ * - `local_directory`: Link to a local directory, e.g. a ref ending in `/`
  * - `anchor`: Link to a heading anchor (e.g., #heading-slug)
  * - `external`: HTTP/HTTPS URL to external resource
  * - `email`: Mailto link
@@ -13,6 +14,7 @@ import { SHA256Schema } from './checksum.js';
  */
 export const LinkTypeSchema = z.enum([
   'local_file',
+  'local_directory',
   'anchor',
   'external',
   'email',
@@ -36,6 +38,16 @@ export const LinkNodeTypeSchema = z.enum([
 
 export type LinkNodeType = z.infer<typeof LinkNodeTypeSchema>;
 
+/**
+ * Zod schema for an HTML well-formedness diagnostic.
+ */
+export const HtmlParseErrorSchema = z.object({
+  message: z.string().describe('parse5 error code (e.g. "missing-end-tag")'),
+  line: z.number().int().positive().optional().describe('1-based source line, when known'),
+}).describe('HTML well-formedness diagnostic');
+
+export type HtmlParseError = z.infer<typeof HtmlParseErrorSchema>;
+
 /**
  * Represents a heading node in the document's table of contents.
  *
@@ -96,6 +108,10 @@ export const ResourceMetadataSchema = z.object({
   filePath: z.string().describe('Absolute path to the resource file'),
   links: z.array(ResourceLinkSchema).describe('All links found in the resource'),
   headings: z.array(HeadingNodeSchema).describe('Document table of contents (top-level headings only; children are nested)'),
+  anchors: z.array(z.string()).optional()
+    .describe('Fragment targets for anchor validation (HTML id/name attributes)'),
+  parseErrors: z.array(HtmlParseErrorSchema).optional()
+    .describe('HTML well-formedness diagnostics (populated for HTML resources only)'),
   frontmatter: z.record(z.string(), z.unknown()).optional()
     .describe('Parsed YAML frontmatter (if present in markdown file)'),
   frontmatterError: z.string().optional()
@@ -106,6 +122,6 @@ export const ResourceMetadataSchema = z.object({
   checksum: SHA256Schema.describe('SHA-256 checksum of file content'),
   collections: z.array(z.string()).optional()
     .describe('Collection names this resource belongs to (populated when using config-based discovery)'),
-}).describe('Complete metadata for a markdown resource');
+}).strict().describe('Complete metadata for a markdown resource');
 
 export type ResourceMetadata = z.infer<typeof ResourceMetadataSchema>;

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.
  *