@vibe-agent-toolkit/resources 0.1.34 → 0.1.36

package/src/schema-uri-walker.ts

@@ -0,0 +1,222 @@
+/**
+ * Pure schema/data traversal that captures every string value sitting at a
+ * JSON Schema position whose `format` is in the URI family.
+ *
+ * Handles:
+ *  - `properties` (recursion)
+ *  - `items` (single-schema and tuple)
+ *  - `oneOf` / `anyOf` / `allOf` (every branch walked) AND sibling keywords
+ *    in the same node (JSON Schema AND semantics)
+ *  - `$ref` (resolved against schema root via JSON Pointer; cycle-protected)
+ *  - `definitions` and `$defs` as ref targets
+ *
+ * Does NOT handle (intentional, see spec §"Non-Goals"):
+ *  - `if`/`then`/`else`, `dependentSchemas`
+ *  - `patternProperties`, schema-form `additionalProperties`
+ *  - `prefixItems` (JSON Schema 2020-12)
+ *
+ * Captures are deduplicated by `(pointer, value)` before return so that
+ * multiple matching composite branches don't produce duplicate issues.
+ *
+ * No I/O. No side effects.
+ */
+
+import { decodeJsonPointerSegment, encodeJsonPointerSegment, formatJsonPointerAsDotted } from './utils.js';
+
+const URI_FAMILY_FORMATS = new Set<UriFamilyFormat>([
+  'uri-reference',
+  'uri',
+  'iri-reference',
+  'iri',
+]);
+
+export type UriFamilyFormat = 'uri' | 'uri-reference' | 'iri' | 'iri-reference';
+
+export interface FrontmatterUriCapture {
+  /** Raw string value from frontmatter */
+  value: string;
+  /** RFC 6901 JSON Pointer to the value within the frontmatter document */
+  pointer: string;
+  /** Developer-friendly dotted form (e.g., adr-citations[0].adr) */
+  dottedPath: string;
+  /** The URI-family format keyword present on the schema node */
+  format: UriFamilyFormat;
+}
+
+interface SchemaNode {
+  type?: string | string[];
+  format?: string;
+  properties?: Record<string, SchemaNode>;
+  items?: SchemaNode | SchemaNode[];
+  oneOf?: SchemaNode[];
+  anyOf?: SchemaNode[];
+  allOf?: SchemaNode[];
+  $ref?: string;
+  // $defs / definitions / etc. are arbitrary root-level keys reached via $ref.
+  [key: string]: unknown;
+}
+
+/**
+ * Walk a frontmatter document against a JSON Schema and return every value
+ * whose schema position has a URI-family `format` keyword.
+ */
+export function walkFrontmatterUriReferences(
+  data: unknown,
+  schema: object,
+): FrontmatterUriCapture[] {
+  if (data === undefined || data === null) return [];
+  const captures: FrontmatterUriCapture[] = [];
+  walk(data, schema as SchemaNode, schema as SchemaNode, [], new Set<string>(), captures);
+  return dedupe(captures);
+}
+
+function walkComposites(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  for (const branchList of [node.oneOf, node.anyOf, node.allOf]) {
+    if (Array.isArray(branchList)) {
+      for (const branch of branchList) {
+        walk(data, branch, root, pointerSegments, visitedRefs, captures);
+      }
+    }
+  }
+}
+
+function walkProperties(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  if (!node.properties || data === null || typeof data !== 'object' || Array.isArray(data)) return;
+  const dataObj = data as Record<string, unknown>;
+  for (const [key, propSchema] of Object.entries(node.properties)) {
+    if (key in dataObj) {
+      walk(
+        dataObj[key],
+        propSchema,
+        root,
+        [...pointerSegments, encodeJsonPointerSegment(key)],
+        visitedRefs,
+        captures,
+      );
+    }
+  }
+}
+
+function walkItems(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  if (!node.items || !Array.isArray(data)) return;
+  if (Array.isArray(node.items)) {
+    const tupleSchemas = node.items;
+    for (const [i, itemValue] of data.entries()) {
+      if (i >= tupleSchemas.length) break;
+      walk(itemValue, tupleSchemas[i] as SchemaNode, root, [...pointerSegments, String(i)], visitedRefs, captures);
+    }
+  } else {
+    for (const [i, itemValue] of data.entries()) {
+      walk(itemValue, node.items, root, [...pointerSegments, String(i)], visitedRefs, captures);
+    }
+  }
+}
+
+function walk(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  if (!node || typeof node !== 'object') return;
+
+  // Resolve $ref against schema root. Cycle protection: skip if already on the
+  // recursion stack. Pop after recursion.
+  if (typeof node.$ref === 'string') {
+    if (visitedRefs.has(node.$ref)) return;
+    const resolved = resolveRef(node.$ref, root);
+    if (!resolved) return;
+    visitedRefs.add(node.$ref);
+    walk(data, resolved, root, pointerSegments, visitedRefs, captures);
+    visitedRefs.delete(node.$ref);
+    return;
+  }
+
+  // Composite schemas: walk every branch. CRITICAL: do NOT short-circuit;
+  // sibling `properties`/`items` are AND-combined with the composite.
+  walkComposites(data, node, root, pointerSegments, visitedRefs, captures);
+
+  // URI-family format leaf
+  if (
+    typeof node.format === 'string' &&
+    URI_FAMILY_FORMATS.has(node.format as UriFamilyFormat) &&
+    typeof data === 'string'
+  ) {
+    const pointer = pointerSegments.length === 0 ? '' : '/' + pointerSegments.join('/');
+    captures.push({
+      value: data,
+      pointer,
+      dottedPath: formatJsonPointerAsDotted(pointer),
+      format: node.format as UriFamilyFormat,
+    });
+    // Fall through — schemas with both `format` and sibling object/array
+    // structure are unusual but possible; let recursion proceed.
+  }
+
+  // Object recursion
+  walkProperties(data, node, root, pointerSegments, visitedRefs, captures);
+
+  // Array recursion
+  walkItems(data, node, root, pointerSegments, visitedRefs, captures);
+
+  // Intentionally NOT handled: if/then/else, dependentSchemas, patternProperties,
+  // schema-form additionalProperties, prefixItems (2020-12). See spec §"Non-Goals".
+}
+
+/**
+ * Resolve a local $ref (e.g., "#/$defs/Foo") against the schema root using a
+ * generic JSON Pointer walk. Returns null for unresolvable refs or non-local
+ * refs (no cross-file support in v1).
+ */
+function resolveRef(ref: string, root: SchemaNode): SchemaNode | null {
+  if (!ref.startsWith('#/')) return null;
+  // eslint-disable-next-line local/no-hardcoded-path-split -- RFC 6901 JSON Pointer segment splitting, not a file path
+  const segments = ref.slice(2).split('/').map(decodeJsonPointerSegment);
+  let cursor: unknown = root;
+  for (const seg of segments) {
+    if (cursor === null || typeof cursor !== 'object') return null;
+    cursor = (cursor as Record<string, unknown>)[seg];
+    if (cursor === undefined) return null;
+  }
+  return (cursor as SchemaNode) ?? null;
+}
+
+/**
+ * Remove duplicate captures by (pointer, value). Multiple matching branches
+ * of `oneOf`/`anyOf`/`allOf` can produce duplicates; users should see one
+ * issue per field, not one per branch.
+ */
+function dedupe(captures: FrontmatterUriCapture[]): FrontmatterUriCapture[] {
+  const seen = new Set<string>();
+  const out: FrontmatterUriCapture[] = [];
+  for (const c of captures) {
+    const key = c.pointer + ' ' + c.value;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(c);
+  }
+  return out;
+}

package/src/schemas/project-config.ts

@@ -1,6 +1,18 @@
 import { ValidationConfigSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
+/**
+ * Official semver regex from https://semver.org/ (anchored).
+ *
+ * Used as the JSON-Schema-friendly source of truth for plugin version
+ * validation. A `.refine()` over `semver.valid()` would not survive
+ * `zod-to-json-schema` export — external consumers validating against the
+ * exported JSON Schema would silently accept invalid versions. A `.regex()`
+ * round-trips into JSON Schema as `pattern`, preserving the constraint.
+ */
+// eslint-disable-next-line security/detect-unsafe-regex, sonarjs/regex-complexity -- Official semver regex from https://semver.org/; not user-controlled input.
+const SEMVER_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
 // Re-export for downstream consumers (unicorn/prefer-export-from satisfied by the import above)
 export { ValidationConfigSchema } from '@vibe-agent-toolkit/agent-schema';
 
@@ -49,6 +61,8 @@ export const CollectionValidationSchema = z.object({
     .describe('Whether to validate external URL links (default: false)'),
   checkGitIgnored: z.boolean().optional()
     .describe('Whether to check if non-ignored files link to git-ignored files (default: true)'),
+  checkFrontmatterLinks: z.boolean().optional()
+    .describe('Whether to validate frontmatter values at JSON Schema positions with a URI-family format (default: true). Set to false to disable for this collection.'),
   externalUrls: ExternalUrlValidationSchema.optional()
     .describe('External URL validation configuration'),
 }).describe('Validation configuration for a collection');
@@ -182,6 +196,12 @@ export const ClaudeMarketplacePluginEntrySchema = z.object({
     .describe('Path to plugin directory (default: plugins/<name>)'),
   files: z.array(SkillFileEntrySchema).optional()
     .describe('Explicit source→dest file mappings for compiled artifacts outside the plugin directory'),
+  version: z.string().regex(SEMVER_REGEX, {
+    message: 'version must be a valid semver string (e.g., "1.2.3" or "1.0.0-rc.1")',
+  }).optional()
+    .describe('Per-plugin semver version (overrides root package.json:version for this plugin)'),
+  changelog: z.string().optional()
+    .describe('Path to per-plugin CHANGELOG (relative to plugin source dir; default: <source>/CHANGELOG.md if it exists)'),
 }).strict().describe('Plugin entry within a marketplace configuration');
 
 export type ClaudeMarketplacePluginEntry = z.infer<typeof ClaudeMarketplacePluginEntrySchema>;

package/src/types.ts

@@ -110,6 +110,7 @@ export {
 // Link validation
 export type { ValidateLinkOptions } from './link-validator.js';
 export { validateLink } from './link-validator.js';
+export { classifyLink } from './link-parser.js';
 
 // Schema assignment
 export {
@@ -124,3 +125,10 @@ export {
   hasSchemaErrors,
   validateFrontmatterMultiSchema,
 } from './multi-schema-validator.js';
+
+// Frontmatter link validation
+export type {
+  FrontmatterExternalUrl,
+  FrontmatterLinkValidationResult,
+} from './frontmatter-link-validator.js';
+export { validateFrontmatterLinks } from './frontmatter-link-validator.js';

package/src/utils.ts

@@ -156,3 +156,57 @@ export function isWithinProject(filePath: string, projectRoot: string): boolean
   // /project-other starting with /project
   return normalizedFile.startsWith(normalizedRoot + '/') || normalizedFile === normalizedRoot;
 }
+
+/**
+ * Escape a property name as a JSON Pointer segment per RFC 6901:
+ * `~` -> `~0`, `/` -> `~1`. Order matters (escape `~` first).
+ */
+export function encodeJsonPointerSegment(name: string): string {
+  return name.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+/**
+ * Reverse RFC 6901 escapes: `~1` -> `/`, `~0` -> `~`. Order matters
+ * (unescape `~1` first).
+ */
+export function decodeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+/**
+ * Format a JSON Pointer (RFC 6901) as developer-friendly dotted notation.
+ *
+ * Numeric segments become bracketed array indices (`0` → `[0]`); non-numeric
+ * segments are dot-joined. Reverses RFC 6901 escapes inside segments.
+ *
+ * @example
+ *   formatJsonPointerAsDotted('/adr-citations/0/adr')  // 'adr-citations[0].adr'
+ *   formatJsonPointerAsDotted('')                       // ''
+ */
+export function formatJsonPointerAsDotted(pointer: string): string {
+  if (pointer === '') return '';
+  // eslint-disable-next-line local/no-hardcoded-path-split -- JSON Pointer RFC 6901 delimiter, not a file path
+  const segments = pointer.slice(1).split('/').map(decodeJsonPointerSegment);
+
+  let out = '';
+  for (const seg of segments) {
+    if (isCanonicalArrayIndex(seg)) {
+      out += `[${seg}]`;
+    } else {
+      out += out === '' ? seg : `.${seg}`;
+    }
+  }
+  return out;
+}
+
+function isCanonicalArrayIndex(s: string): boolean {
+  // Canonical integer per RFC 6901 §4 + JSON canonical form: no leading zeros
+  // except for "0" itself.
+  if (s === '') return false;
+  if (s === '0') return true;
+  if (s.startsWith('0')) return false;
+  for (const ch of s) {
+    if (ch < '0' || ch > '9') return false;
+  }
+  return true;
+}