feat: validate context feedback schema

Author: whut09

src/context-registry/feedback-store.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { hashContextText } from "./hash.js";
 import { createContextFeedback, type CreateContextFeedbackInput } from "./feedback.js";
 import type { ContextFeedback, ContextFeedbackStore } from "./types.js";
+import { validateContextFeedbackStore } from "./validators.js";
 
 const FEEDBACK_DIRECTORY = path.join(".agent-context", "context-registry", "feedback");
 
@@ -55,16 +56,9 @@ function emptyStore(repository: string): ContextFeedbackStore {
 }
 
 function validateFeedbackStore(store: ContextFeedbackStore, repository: string): void {
-  if (store.schemaVersion !== 1) throw new Error(`Unsupported Context feedback schemaVersion ${String(store.schemaVersion)}.`);
-  if (!Number.isInteger(store.revision) || store.revision < 0) throw new Error("Context feedback store revision must be non-negative.");
+  const result = validateContextFeedbackStore(store);
+  if (!result.valid) throw new Error(`Invalid Context feedback store: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
   if (path.resolve(store.repository) !== repository) throw new Error("Context feedback store repository does not match the current repository.");
-  if (!Array.isArray(store.feedback)) throw new Error("Context feedback store feedback must be an array.");
-  const ids = new Set<string>();
-  for (const item of store.feedback) {
-    if (!item || item.schemaVersion !== 1 || typeof item.feedbackId !== "string") throw new Error("Context feedback store contains an invalid feedback record.");
-    if (ids.has(item.feedbackId)) throw new Error(`Context feedback store contains duplicate feedbackId ${item.feedbackId}.`);
-    ids.add(item.feedbackId);
-  }
 }
 
 function compareFeedback(left: ContextFeedback, right: ContextFeedback): number {

src/context-registry/validators.ts

@@ -18,6 +18,10 @@ import type {
   ContextEntry,
   ContextEntryKind,
   ContextFetchResult,
+  ContextFeedback,
+  ContextFeedbackLabel,
+  ContextFeedbackStore,
+  ContextFeedbackTarget,
   ContextFile,
   ContextFileRole,
   ContextPack,
@@ -31,6 +35,47 @@ const SOURCE_KINDS = new Set(["local", "remote", "bundled"]);
 const TRUST_LEVELS = new Set<ContextTrustLevel>(["official", "maintainer", "community", "private", "untrusted"]);
 const ENTRY_KINDS = new Set<ContextEntryKind>(["doc", "skill", "reference", "task-pack", "repository"]);
 const ANNOTATION_KINDS = new Set<ContextAnnotationKind>(["environment", "version-difference", "failure-cause", "convention", "workaround"]);
+const FEEDBACK_LABELS = new Set<ContextFeedbackLabel>(["useful", "not-useful", "outdated", "inaccurate", "incomplete", "wrong-version", "wrong-example", "irrelevant"]);
+const FEEDBACK_TARGETS = new Set<ContextFeedbackTarget>(["entry", "file", "retrieval-result", "intervention"]);
+
+export function validateContextFeedback(input: unknown, path = "$"): ContextValidationResult<ContextFeedback> {
+  const issues = validateSchemaEnvelope(input, path);
+  if (!isRecord(input)) return invalidResult(issues);
+  requiredString(input, "feedbackId", path, issues);
+  requiredTimestamp(input, "createdAt", path, issues);
+  const target = requiredString(input, "target", path, issues);
+  const label = requiredString(input, "label", path, issues);
+  requiredString(input, "entryId", path, issues);
+  requiredString(input, "source", path, issues);
+  optionalString(input, "version", path, issues);
+  const file = optionalString(input, "file", path, issues);
+  const retrievalId = optionalString(input, "retrievalId", path, issues);
+  const interventionId = optionalString(input, "interventionId", path, issues);
+  if (target && !FEEDBACK_TARGETS.has(target as ContextFeedbackTarget)) issues.push({ path: `${path}.target`, code: "value", message: `unsupported feedback target ${target}` });
+  if (label && !FEEDBACK_LABELS.has(label as ContextFeedbackLabel)) issues.push({ path: `${path}.label`, code: "value", message: `unsupported feedback label ${label}` });
+  if (file && !normalizeContextFilePath(file)) issues.push({ path: `${path}.file`, code: "path", message: "must be a normalized relative path" });
+  if (target === "file" && !file) issues.push({ path: `${path}.file`, code: "required", message: "file feedback requires file" });
+  if (target === "retrieval-result" && !retrievalId) issues.push({ path: `${path}.retrievalId`, code: "required", message: "retrieval feedback requires retrievalId" });
+  if (target === "intervention" && !interventionId) issues.push({ path: `${path}.interventionId`, code: "required", message: "intervention feedback requires interventionId" });
+  return issues.length ? invalidResult(issues) : validResult(input as unknown as ContextFeedback);
+}
+
+export function validateContextFeedbackStore(input: unknown, path = "$"): ContextValidationResult<ContextFeedbackStore> {
+  const issues = validateSchemaEnvelope(input, path);
+  if (!isRecord(input)) return invalidResult(issues);
+  requiredString(input, "repository", path, issues);
+  if (!Array.isArray(input.feedback)) issues.push({ path: `${path}.feedback`, code: "type", message: "expected an array" });
+  const ids = new Set<string>();
+  for (const [index, item] of (Array.isArray(input.feedback) ? input.feedback : []).entries()) {
+    const result = validateContextFeedback(item, `${path}.feedback[${index}]`);
+    issues.push(...result.issues);
+    if (result.value) {
+      if (ids.has(result.value.feedbackId)) issues.push({ path: `${path}.feedback[${index}].feedbackId`, code: "value", message: "feedback IDs must be unique" });
+      ids.add(result.value.feedbackId);
+    }
+  }
+  return issues.length ? invalidResult(issues) : validResult(input as unknown as ContextFeedbackStore);
+}
 
 export function validateContextFile(input: unknown, path = "$"): ContextValidationResult<ContextFile> {
   const issues = validateSchemaEnvelope(input, path);

test/context-feedback.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { createContextFeedback, CONTEXT_FEEDBACK_LABELS, CONTEXT_FEEDBACK_TARGETS } from "../src/context-registry/feedback.js";
+import { validateContextFeedback, validateContextFeedbackStore } from "../src/context-registry/validators.js";
 
 test("feedback supports every label and target without task or content fields", () => {
   for (const label of CONTEXT_FEEDBACK_LABELS) {
@@ -54,3 +55,13 @@ test("feedback identifiers are deterministic for the same metadata", () => {
   };
   assert.equal(createContextFeedback(input).feedbackId, createContextFeedback(input).feedbackId);
 });
+
+test("feedback schema diagnostics identify unsafe paths and duplicate IDs", () => {
+  const item = createContextFeedback({ repository: "C:/work/project", entryId: "entry", source: "local", revision: 1, target: "file", file: "docs/file.md", label: "useful" });
+  const unsafe = validateContextFeedback({ ...item, file: "../secret.md" });
+  assert.equal(unsafe.valid, false);
+  assert.ok(unsafe.issues.some((issue) => issue.path === "$.file"));
+  const store = validateContextFeedbackStore({ schemaVersion: 1, revision: 1, repository: "C:/work/project", feedback: [item, item] });
+  assert.equal(store.valid, false);
+  assert.ok(store.issues.some((issue) => /unique/.test(issue.message)));
+});