@intentius/chant 0.84.0 → 0.85.0

package/src/workspace/records.ts

@@ -62,6 +62,12 @@ export const RECORD_WARNING_CODES = [
   "asset-stale",
   /** A supersedes link from a record whose state is weaker than the one it names, so it has no effect yet (#2524 D4). */
   "record-supersedes-pending",
+  /**
+   * The kind's pins field is an empty list: the record cites no evidence and
+   * pins no file. Information for a reviewer, such as a decision made in a
+   * product's own design flow with nothing to cite (#2654).
+   */
+  "record-no-evidence",
 ] as const satisfies readonly ReasonCode[];
 export type RecordWarningCode = (typeof RECORD_WARNING_CODES)[number];
 
@@ -344,22 +350,54 @@ export interface ReadRecordsResult {
 
 type Validator = (data: unknown) => { ok: true } | { ok: false; errors: string[] };
 
+/** One ajv error, compiled with `verbose` so the failing schema and data come with it. */
+interface SchemaError {
+  instancePath: string;
+  schemaPath: string;
+  keyword: string;
+  message?: string;
+  params?: { failingKeyword?: string };
+  parentSchema?: Record<string, unknown>;
+  data?: unknown;
+}
+
+/**
+ * ajv's errors as `<path> <message>` lines. A failed `if` whose `then` or
+ * `else` branch has a `description` is reported by that description alone, in
+ * place of the branch's own errors, with each `{field}` filled from the value
+ * the branch checked. The decision schema words its dissent rule this way, so
+ * the message names the reviewer (#2652). The schema stays plain JSON Schema,
+ * with no keyword a strict validator would refuse.
+ */
+function renderSchemaErrors(errors: readonly SchemaError[]): string[] {
+  const replaced: string[] = [];
+  const described = new Map<SchemaError, string>();
+  for (const e of errors) {
+    const branch = e.keyword === "if" ? e.params?.failingKeyword : undefined;
+    const text = branch ? (e.parentSchema?.[branch] as { description?: unknown } | undefined)?.description : undefined;
+    if (!branch || typeof text !== "string") continue;
+    const at = e.data !== null && typeof e.data === "object" ? (e.data as Record<string, unknown>) : {};
+    described.set(e, text.replace(/\{([A-Za-z0-9_]+)\}/g, (all, key: string) => (typeof at[key] === "string" ? (at[key] as string) : all)));
+    replaced.push(`${e.schemaPath.replace(/\/if$/, "")}/${branch}/`);
+  }
+  return errors
+    .filter((e) => described.has(e) || !replaced.some((prefix) => e.schemaPath.startsWith(prefix)))
+    .map((e) => `${e.instancePath || "/"} ${described.get(e) ?? e.message ?? "is invalid"}`);
+}
+
 async function compileSchema(schema: Record<string, unknown>): Promise<Validator> {
   const mod = (await import("ajv")) as unknown as { default: unknown };
   // ajv is CommonJS; its class is the default export, or that export's own default.
   const Ajv = ((mod.default as { default?: unknown }).default ?? mod.default) as new (opts: object) => {
-    compile(s: object): ((d: unknown) => boolean) & { errors?: Array<{ instancePath: string; message?: string }> | null };
+    compile(s: object): ((d: unknown) => boolean) & { errors?: SchemaError[] | null };
   };
   let validate: ReturnType<InstanceType<typeof Ajv>["compile"]>;
   try {
-    validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
+    validate = new Ajv({ allErrors: true, strict: false, verbose: true }).compile(schema);
   } catch (err) {
     throw new RecordReadError("schema-invalid", `the kind's schema does not compile: ${message(err)}`);
   }
-  return (data) =>
-    validate(data)
-      ? { ok: true }
-      : { ok: false, errors: (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}`) };
+  return (data) => (validate(data) ? { ok: true } : { ok: false, errors: renderSchemaErrors(validate.errors ?? []) });
 }
 
 /** Read every record `loaded` locates, through `options.source`. */
@@ -392,10 +430,16 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     if (!result.ok) {
       entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
     }
-    if (kind.pins && options.assets) {
-      const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
-      entry.assets = checked.assets;
-      entry.warnings = checked.warnings;
+    if (kind.pins) {
+      const cited = fm.value[kind.pins.field];
+      if (Array.isArray(cited) && cited.length === 0) {
+        entry.warnings.push({ code: "record-no-evidence", message: `${kind.pins.field} is empty: the record cites nothing and pins no file` });
+      }
+      if (options.assets) {
+        const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
+        entry.assets = checked.assets;
+        entry.warnings.push(...checked.warnings);
+      }
     }
   }