jev-agent-tools 0.2.0 → 0.3.0

package/src/core/ask-references.ts

@@ -1,107 +1,122 @@
 import { ASK_MAX_FILES } from "../constants.ts";
 import type { Question, State } from "../jev/types.ts";
+import type { Cause } from "../result-types.ts";
 import type { CompiledAsks } from "./asks.ts";
 
 export interface UnresolvedAskReference {
   reference: string;
   reason: string;
+  /** Admission cause when the reference was refused, e.g. `secret_pattern`. */
+  cause?: Cause;
+  required?: boolean;
+  origin?: "question" | "note";
+  scope?: string;
+  side?: "files" | "files_before";
+}
+export interface EvidenceIndex {
+  files: Readonly<Record<string, string>>;
+  files_before?: Readonly<Record<string, string | null>>;
+  beforeInventory?: readonly string[];
+  aliases?: Readonly<Record<string, string | readonly string[]>>;
+}
+export interface ReferenceResolution {
+  additions: readonly {
+    reference: string;
+    path: string;
+    required: boolean;
+    origin: "question" | "note";
+    scope: string;
+    side: "files" | "files_before";
+  }[];
+  unresolved: readonly UnresolvedAskReference[];
+  aliases: Readonly<Record<string, string>>;
+  invalid: readonly UnresolvedAskReference[];
 }
-
 const fileSelector =
   /\b(files|files_before)\s*\[\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*')\s*\]/g;
 const selector =
   /\b[A-Za-z_$][\w$]*(?:(?:\s*\.\s*[A-Za-z_$][\w$]*)|(?:\s*\[\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\d+)\s*\]))*/g;
-
 function unquote(value: string): string {
   if (value.startsWith('"')) {
     try {
       const parsed: unknown = JSON.parse(value);
       if (typeof parsed === "string") return parsed;
     } catch {
-      return value.slice(1, -1);
+      /* retain the literal selector */
     }
   }
   return value.slice(1, -1).replace(/\\(['\\])/g, "$1");
 }
-
-function looksLikePath(value: string): boolean {
-  if (/\s/.test(value) || /^(?:[a-z]+:|www\.)/i.test(value)) return false;
-  if (
-    !/[A-Za-z_]/.test(value) ||
-    /^(?:state|docs?|files|files_before)\./.test(value)
-  )
-    return false;
-  if (/^(?:e\.g|i\.e|Node\.js|Next\.js|Vue\.js)$/i.test(value)) return false;
+function normalized(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "");
+}
+function forbidden(path: string): boolean {
   return (
-    /^(?:\.?\.?\/)?[\w.@+-]+(?:\/[\w.@+-]+)+$/.test(value) ||
-    /^[\w@+-][\w.@+-]*\.(?:[cm]?[jt]sx?|py|json|jsonc|ya?ml|toml|ini|cfg|conf|md|mdx|txt|rst|html?|css|scss|sql|sh|bash|rs|go|java|rb|php|c|h|cpp|hpp|vue|svelte|xml|csv|env|lock)$/i.test(
-      value,
-    ) ||
-    /^\.[A-Za-z][\w.-]*$/.test(value) ||
-    /^(?:README|LICENSE|LICENCE|Makefile|Dockerfile|CHANGELOG|AGENTS|CLAUDE)(?:\.[\w-]+)?$/.test(
-      value,
-    )
+    /^(?:\/|[A-Za-z]:|[a-z][a-z\d+.-]*:\/\/)/i.test(path) ||
+    path.split(/[\\/]/).some((part) => part === ".." || part === ".git")
   );
 }
-
-/** Explicit paths only: numbers, dates and URLs are not evidence references. */
+function explicitPaths(
+  text: string,
+): { reference: string; side: "files" | "files_before" }[] {
+  const references = new Map<
+    string,
+    { reference: string; side: "files" | "files_before" }
+  >();
+  for (const match of text.matchAll(fileSelector)) {
+    const reference = unquote(match[2] ?? "");
+    const side = match[1] as "files" | "files_before";
+    references.set(JSON.stringify([side, reference]), { reference, side });
+  }
+  return [...references.values()];
+}
+/** Lexical discovery hints, never requirements. Ordinary member expressions are excluded. */
 export function citedPaths(text: string): string[] {
-  const found = new Set<string>();
-  const withoutUrls = text.replace(
-    /\b(?:[a-z][a-z\d+.-]*:\/\/|www\.)[^\s<>"'`]+/gi,
-    " ",
-  );
-  const withoutSelectors = withoutUrls.replace(
-    fileSelector,
-    (_whole, _root: string, quoted: string) => {
-      found.add(unquote(quoted));
-      return " ";
-    },
-  );
-  const withoutFields = withoutSelectors.replace(selector, (value) =>
-    value.includes("[") || /^(?:state|docs?|files|files_before)\./.test(value)
-      ? " "
-      : value,
-  );
-  const unquoted = withoutFields.replace(
+  const found = new Set(explicitPaths(text).map(({ reference }) => reference));
+  const cleaned = text
+    .replace(/\b(?:[a-z][a-z\d+.-]*:\/\/|www\.)[^\s<>"'`]+/gi, " ")
+    .replace(fileSelector, " ")
+    .replace(selector, (value) =>
+      value.includes("[") ||
+      /^(?:state|output|docs?|files|files_before)\./.test(value)
+        ? " "
+        : value,
+    );
+  for (const match of cleaned.matchAll(
     /`([^`\n]+)`|"([^"\n]+)"|'([^'\n]+)'/g,
-    (
-      _whole,
-      backtick: string | undefined,
-      double: string | undefined,
-      single: string | undefined,
-    ) => {
-      const value = backtick ?? double ?? single ?? "";
-      if (looksLikePath(value)) {
-        found.add(value);
-        return " ";
-      }
-      return value;
-    },
-  );
-  for (const match of unquoted.matchAll(/[\w.@+-]+(?:\/[\w.@+-]+)*/g)) {
-    const value = match[0].replace(/[.,;:!?]+$/, "");
+  )) {
+    const value = match[1] ?? match[2] ?? match[3] ?? "";
+    if (/^(?:[\w@+-]+\/)+[\w.@+-]+$/.test(value)) found.add(value);
+  }
+  for (const match of cleaned.matchAll(
+    /\b(?:README|LICENSE|LICENCE|Makefile|Dockerfile|CHANGELOG|AGENTS|CLAUDE)(?:\.[\w-]+)?\b/g,
+  ))
+    found.add(match[0]);
+  for (const match of cleaned.matchAll(
+    /(?:\.?\.?\/)?[\w@+-]+(?:\/[\w.@+-]+)*\.(?:[cm]?[jt]sx?|py|jsonc?|ya?ml|toml|ini|cfg|conf|mdx?|txt|rst|html?|css|scss|sql|sh|bash|rs|go|java|rb|php|cpp|hpp|vue|svelte|xml|csv|lock)\b/g,
+  )) {
+    const start = match.index ?? 0;
     if (
-      looksLikePath(value) &&
-      (!value.includes("/") ||
-        looksLikePath(value.slice(value.lastIndexOf("/") + 1)))
+      (start && /[\w.]/.test(cleaned[start - 1] ?? "")) ||
+      /^(?:Node|Next|Vue)\.js$/i.test(match[0])
     )
-      found.add(value);
+      continue;
+    found.add(match[0]);
   }
   return [...found];
 }
-
 function questionText(question: Question): string {
-  const criteria = question.criteria;
   return [
     question.instructions,
-    ...(criteria ? Object.values(criteria) : []),
+    ...Object.values(question.criteria ?? {}),
   ].join("\n");
 }
-
-function readingTexts(plan: CompiledAsks): { id: string; text: string }[] {
+function readingTexts(
+  plan: CompiledAsks,
+): { id: string; text: string; about?: string }[] {
   return plan.readings.map((reading) => ({
     id: reading.id,
+    about: plan.asks[reading.askIndex]?.about,
     text: [reading.id, reading.twin, ...Object.values(reading.controls ?? {})]
       .flatMap((id) =>
         id && plan.questions[id] ? [questionText(plan.questions[id])] : [],
@@ -109,62 +124,141 @@ function readingTexts(plan: CompiledAsks): { id: string; text: string }[] {
       .join("\n"),
   }));
 }
-
-function normalized(path: string): string {
-  return path.replace(/^(?:\.\/)+/, "");
-}
-
 export function resolveAskReferences(
   plan: CompiledAsks,
   note: string | undefined,
-  files: Readonly<Record<string, string>>,
+  evidence: EvidenceIndex | Readonly<Record<string, string>>,
   inventory: readonly string[],
-): {
-  additions: readonly { reference: string; path: string }[];
-  unresolved: readonly UnresolvedAskReference[];
-} {
-  const references = new Set(
-    readingTexts(plan).flatMap(({ text }) => citedPaths(text)),
-  );
-  for (const reference of citedPaths(note ?? "")) references.add(reference);
-  const paths = [...new Set([...inventory, ...Object.keys(files)])];
-  const exact = new Map(paths.map((path) => [normalized(path), path]));
-  const selected = new Set(Object.keys(files).map(normalized));
-  const additions: { reference: string; path: string }[] = [];
+): ReferenceResolution {
+  const index: EvidenceIndex =
+    evidence.files !== null && typeof evidence.files === "object"
+      ? (evidence as EvidenceIndex)
+      : { files: evidence as Readonly<Record<string, string>> };
+  const supplied = [
+    ...new Set([
+      ...Object.keys(index.files),
+      ...Object.keys(index.files_before ?? {}),
+    ]),
+  ].sort();
+  const currentKnown = [...new Set(inventory)].sort();
+  const beforeKnown = [
+    ...new Set([...inventory, ...(index.beforeInventory ?? [])]),
+  ].sort();
+  const selected = new Set(supplied.map(normalized));
+  const versions = new Set([
+    ...Object.keys(index.files).map((path) => `files:${normalized(path)}`),
+    ...Object.keys(index.files_before ?? {}).map(
+      (path) => `files_before:${normalized(path)}`,
+    ),
+  ]);
+  const additions: ReferenceResolution["additions"][number][] = [];
   const unresolved: UnresolvedAskReference[] = [];
-  for (const reference of references) {
-    if (Object.hasOwn(files, reference)) continue;
-    const key = normalized(reference);
-    const direct = exact.get(key);
-    const matches = direct
-      ? [direct]
-      : paths.filter((path) => normalized(path).endsWith(`/${key}`));
-    if (matches.length !== 1) {
-      unresolved.push({
-        reference,
-        reason: `${reference} is cited but missing from state (${matches.length ? "ambiguous path" : "not found"})`,
-      });
-      continue;
-    }
-    const path = matches[0];
-    if (path === undefined) continue;
-    if (!selected.has(normalized(path)) && selected.size >= ASK_MAX_FILES) {
-      unresolved.push({
+  const invalid: UnresolvedAskReference[] = [];
+  const aliases: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  const sources = [
+    ...readingTexts(plan).map(({ id, text, about }) => ({
+      text: `${about ?? ""}\n${text}`,
+      scope: id,
+      origin: "question" as const,
+      output: about === "output",
+    })),
+    {
+      text: note ?? "",
+      scope: "global",
+      origin: "note" as const,
+      output: false,
+    },
+  ];
+  for (const source of sources) {
+    const explicit = explicitPaths(source.text);
+    const explicitNames = new Set(explicit.map(({ reference }) => reference));
+    const references = [
+      ...explicit.map((ref) => ({ ...ref, required: true })),
+      ...(source.output
+        ? []
+        : citedPaths(source.text)
+            .filter((reference) => !explicitNames.has(reference))
+            .map((reference) => ({
+              reference,
+              side: "files" as const,
+              required: false,
+            }))),
+    ];
+    for (const ref of references) {
+      const { reference, required, side } = ref;
+      const known = side === "files_before" ? beforeKnown : currentKnown;
+      const facts = {
         reference,
-        reason: `${reference} is cited but missing from state (ASK_MAX_FILES limit: ${ASK_MAX_FILES})`,
-      });
-      continue;
+        required,
+        side,
+        origin: source.origin,
+        scope: source.scope,
+      };
+      if (forbidden(reference)) {
+        if (required)
+          invalid.push({
+            ...facts,
+            reason: `Path not permitted: ${reference}`,
+          });
+        continue;
+      }
+      const key = normalized(reference);
+      // Directory-bearing explicit paths are exact, never suffix fallbacks.
+      const exact = supplied.find((path) => normalized(path) === key);
+      const abbreviated = !key.includes("/");
+      let matches: string[] = exact ? [exact] : [];
+      if (!matches.length && abbreviated) {
+        const alias =
+          index.aliases && Object.hasOwn(index.aliases, reference)
+            ? index.aliases[reference]
+            : undefined;
+        if (alias !== undefined)
+          matches = (typeof alias === "string" ? [alias] : [...alias]).filter(
+            (path) => supplied.includes(path),
+          );
+        if (!matches.length)
+          matches = supplied.filter((path) =>
+            normalized(path).endsWith(`/${key}`),
+          );
+      }
+      if (!matches.length)
+        matches = known.filter((path) => normalized(path) === key);
+      if (!matches.length && abbreviated)
+        matches = known.filter((path) => normalized(path).endsWith(`/${key}`));
+      if (matches.length !== 1) {
+        if (required)
+          unresolved.push({
+            ...facts,
+            reason: `${reference} is required but missing from state (${matches.length ? "ambiguous path" : "not found"})`,
+          });
+        continue;
+      }
+      const path = matches[0];
+      if (path === undefined) continue;
+      aliases[reference] = path;
+      const identity = normalized(path);
+      const version = `${side}:${identity}`;
+      if (versions.has(version)) continue;
+      if (!selected.has(identity) && selected.size >= ASK_MAX_FILES) {
+        unresolved.push({
+          ...facts,
+          reason: `${reference} omitted (ASK_MAX_FILES limit: ${ASK_MAX_FILES})`,
+        });
+        continue;
+      }
+      selected.add(identity);
+      versions.add(version);
+      additions.push({ ...facts, path });
     }
-    selected.add(normalized(path));
-    additions.push({ reference, path });
   }
-  return { additions, unresolved };
+  return { additions, unresolved, aliases, invalid };
 }
-
 function object(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object";
 }
-
 function unpack(value: unknown): unknown {
   if (typeof value !== "string" || !/^[\s]*[[{]/.test(value)) return value;
   try {
@@ -173,24 +267,17 @@ function unpack(value: unknown): unknown {
     return value;
   }
 }
-
 function empty(value: unknown): boolean {
   return (
+    value === undefined ||
     value === null ||
     (typeof value === "string" && value.trim() === "") ||
     (object(value) && Object.keys(value).length === 0)
   );
 }
-
 function emptyReference(text: string, state: State): string | undefined {
-  // File references can be plain paths, not just selectors.
-  const files = state.files;
-  if (object(files)) {
-    for (const reference of citedPaths(text)) {
-      if (Object.hasOwn(files, reference) && empty(files[reference]))
-        return reference;
-    }
-  }
+  const metadata = object(state.evidence) ? state.evidence : {};
+  const aliases = object(metadata.aliases) ? metadata.aliases : {};
   for (const match of text.matchAll(selector)) {
     const parts = [
       ...match[0].matchAll(
@@ -198,32 +285,51 @@ function emptyReference(text: string, state: State): string | undefined {
       ),
     ].map(([part]) => (/^["']/.test(part) ? unquote(part) : part));
     const root = parts[0];
-    if (root === undefined) continue;
-    let value: unknown;
-    let offset: number;
-    if (root === "state") {
-      value = state;
-      offset = 1;
-    } else if (Object.hasOwn(state, root)) {
-      value = state[root];
-      offset = 1;
-    } else continue;
-    let present = true;
-    for (const part of parts.slice(offset)) {
+    if (!root) continue;
+    if (
+      !["state", "output", "files", "files_before"].includes(root) &&
+      !Object.hasOwn(state, root)
+    )
+      continue;
+    if (!/[.[]/.test(match[0]) && text.trim() !== match[0].trim()) continue;
+    let value: unknown =
+      root === "state"
+        ? Object.hasOwn(state, "state")
+          ? state.state
+          : state
+        : state[root];
+    const tail = parts.slice(1);
+    if (
+      (root === "files" || root === "files_before") &&
+      tail[0] &&
+      object(value) &&
+      !Object.hasOwn(value, tail[0])
+    ) {
+      const alias = Object.hasOwn(aliases, tail[0])
+        ? aliases[tail[0]]
+        : undefined;
+      if (typeof alias === "string") tail[0] = alias;
+    }
+    for (const part of tail) {
       value = unpack(value);
-      if (!object(value) || !Object.hasOwn(value, part)) {
-        present = false;
-        break;
-      }
-      value = value[part];
+      value =
+        object(value) && Object.hasOwn(value, part) ? value[part] : undefined;
     }
-    // A file absent from the base proves creation; it is not empty evidence.
-    if (root === "files_before" && value === null) continue;
-    if (present && empty(unpack(value))) return match[0].trim();
+    // null before is admitted only by the base reader for a tracked-tree absence.
+    if (
+      root === "files_before" &&
+      value === null &&
+      typeof state.base_sha === "string" &&
+      state.base_sha.length > 0
+    )
+      continue;
+    if (
+      empty(root === "files" || root === "files_before" ? value : unpack(value))
+    )
+      return match[0].trim();
   }
   return undefined;
 }
-
 export function blockedAskReadings(
   plan: CompiledAsks,
   state: State,
@@ -231,19 +337,29 @@ export function blockedAskReadings(
   note?: string,
 ): ReadonlyMap<string, string> {
   const blocked = new Map<string, string>();
-  const notePaths = new Set(citedPaths(note ?? ""));
   const noteEmpty = emptyReference(note ?? "", state);
-  for (const { id, text } of readingTexts(plan)) {
-    const paths = new Set(citedPaths(text));
+  for (const { id, text, about } of readingTexts(plan)) {
+    const explicit = new Set(
+      explicitPaths(`${about ?? ""}\n${text}`).map(
+        ({ reference }) => reference,
+      ),
+    );
     const missing = unresolved.find(
-      ({ reference }) => paths.has(reference) || notePaths.has(reference),
+      (ref) =>
+        ref.required !== false &&
+        (ref.scope === "global" ||
+          ref.scope === id ||
+          (ref.scope === undefined && explicit.has(ref.reference))),
     );
     if (missing) {
       blocked.set(id, missing.reason);
       continue;
     }
-    const reference = noteEmpty ?? emptyReference(text, state);
-    if (reference) blocked.set(id, `${reference} is empty`);
+    const reference =
+      noteEmpty ??
+      (about ? emptyReference(about, state) : undefined) ??
+      emptyReference(text, state);
+    if (reference) blocked.set(id, `${reference} is missing or empty`);
   }
   return blocked;
 }

package/src/core/asks.ts

@@ -505,8 +505,7 @@ export function readAsks(
         .join("; ");
       result.push({
         label: r.label,
-        value: { head: "unjudged", p: 0 },
-        band: "unsure",
+        unjudged: true,
         reason: `${reason}; ${r.missing}`,
         uncalibrated: r.uncalibrated,
       });
@@ -520,7 +519,23 @@ export function readAsks(
           : undefined;
       result.push({
         label: level ? `${r.label} ${JSON.stringify(level)}` : r.label,
+        source: answer.source,
+        ...(answer.type === "bool" ? { publicResult: answer.p >= 0.5 } : {}),
         answer,
+        rawValues:
+          answer.type === "bool"
+            ? [
+                {
+                  label: "bool",
+                  value: answer.p >= 0.5,
+                  probability: { status: "known", value: answer.p },
+                },
+              ]
+            : Object.entries(answer.probabilities).map(([label, value]) => ({
+                label,
+                value: label,
+                probability: { status: "known" as const, value },
+              })),
         uncalibrated: r.uncalibrated,
       });
       continue;
@@ -583,13 +598,22 @@ export function readAsks(
     if (
       Object.values(r.controls ?? {}).some((id) => answers[id]?.type !== "bool")
     ) {
-      band = "unsure";
-      reason =
-        "coherence control unjudged; no verdict: rerun with decisive evidence";
+      result.push({
+        label: r.label,
+        unjudged: true,
+        reason: "required coherence control has no valid bool response",
+        missing: r.missing,
+      });
+      continue;
     }
     if (!r.twin && Object.hasOwn(reversed, r.id) && !second) {
-      band = "unsure";
-      reason = `reverse-order control unjudged; no verdict: ${r.missing}`;
+      result.push({
+        label: r.label,
+        unjudged: true,
+        reason: "required reverse-order control unjudged",
+        missing: r.missing,
+      });
+      continue;
     }
     const firstMerged = merged(original, r.kind === "verify");
     const secondMerged = second
@@ -601,6 +625,54 @@ export function readAsks(
         ? `${r.label} ${JSON.stringify(r.options[head])}`
         : r.label,
       answer: { ...answer, probabilities: p, choice: head },
+      source: answer.source,
+      rawValues: Object.entries(original).map(([label, value]) => ({
+        label,
+        value: label,
+        probability: { status: "known" as const, value },
+      })),
+      reportControls: [
+        ...members.slice(1).map(([id, label]) => ({
+          id,
+          label,
+          answer: answers[id],
+          kind: "cross_check" as const,
+        })),
+        ...(!r.twin && reversed[r.id]
+          ? [
+              {
+                id: `${r.id}:reverse`,
+                label: "reverse order",
+                answer: reversed[r.id],
+                kind: "order" as const,
+              },
+            ]
+          : []),
+      ].flatMap(({ id, label, answer: a, kind }) => {
+        if (!a || a.type === "unjudged" || !a.source) return [];
+        return [
+          {
+            id,
+            kind,
+            source: a.source,
+            outcome: label,
+            rawValues:
+              a.type === "bool"
+                ? [
+                    {
+                      label,
+                      value: a.p >= 0.5,
+                      probability: { status: "known" as const, value: a.p },
+                    },
+                  ]
+                : Object.entries(a.probabilities).map(([key, value]) => ({
+                    label: key,
+                    value: key,
+                    probability: { status: "known" as const, value },
+                  })),
+          },
+        ];
+      }),
       value: { head, p: mass },
       band,
       reason,

package/src/core/import-boundaries.ts

@@ -58,9 +58,14 @@ export function checkImportBoundaries(
         detail: `cannot resolve ${edge.specifier} inside src/`,
       });
     } else if (
-      ["core", "presets", "texts", "constants.ts", "result.ts"].includes(
-        layer,
-      ) &&
+      [
+        "core",
+        "presets",
+        "texts",
+        "constants.ts",
+        "result.ts",
+        "result-types.ts",
+      ].includes(layer) &&
       !(layer === "core" && ["node:path", "path"].includes(edge.specifier)) &&
       !(
         layer === "core" &&