frontend-project-context 1.2.0 → 1.3.1

package/src/project-context/task-context.mjs

@@ -0,0 +1,502 @@
+import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { blockingContextFindings, checkProject } from "./checker.mjs";
+import { ProjectContextError, fail } from "./errors.mjs";
+import { readJsonFile } from "./io.mjs";
+import { normalizeRelativePath, resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
+import { loadProject } from "./project-store.mjs";
+import { effectiveItems, scopeApplies } from "./scope-compiler.mjs";
+import {
+  CONTEXT_BUDGET_UNIT,
+  INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+  STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+  taskContextPlanDigest,
+  validateStageContextBundle,
+  validateStageReceipt,
+  validateTaskContextPlan,
+} from "./task-context-schema.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const EXCLUDED_BODIES = Object.freeze(["chat-history", "code-bodies", "git-diffs", "source-bodies", "verification-logs"]);
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(project) {
+  return {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+  };
+}
+
+function pathWithin(target, scope) {
+  return target === scope || target.startsWith(`${scope}/`);
+}
+
+function pathsOverlap(left, right) {
+  return pathWithin(left, right) || pathWithin(right, left);
+}
+
+function finding(code, severity, details = {}) {
+  return { code, severity, ...details };
+}
+
+function stableFindings(findings) {
+  const byJson = new Map();
+  for (const entry of findings) byJson.set(canonicalJson(entry), entry);
+  return [...byJson.values()].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
+}
+
+async function validateProjectPaths(root, values, label) {
+  for (const value of values) {
+    try {
+      try {
+        await resolveExistingInside(root, value);
+      } catch (error) {
+        if (error?.code !== "source-missing") throw error;
+        await resolveWritableInside(root, value);
+      }
+    } catch (error) {
+      fail("task-context-path-invalid", `${label} leaves the project or resolves through an unsafe path: ${value}`, {
+        details: { path: value, reason: error.code ?? "invalid-path" },
+      });
+    }
+  }
+}
+
+function normalizeSignalPaths(values, label) {
+  const normalized = values.map((value) => normalizeRelativePath(value, { label }));
+  if (new Set(normalized).size !== normalized.length) fail("task-context-path-invalid", `${label} contains duplicate normalized paths`);
+  return normalized.sort((left, right) => left.localeCompare(right));
+}
+
+async function validatePlanPaths(root, plan) {
+  await validateProjectPaths(root, plan.stages.flatMap((stage) => stage.paths), "task stage path");
+}
+
+function normalizedReceipts(receiptInputs, plan) {
+  const digest = taskContextPlanDigest(plan);
+  const byStage = new Map();
+  for (const input of receiptInputs) {
+    const structural = validateStageReceipt(input);
+    if (byStage.has(structural.stageId)) fail("stage-receipt-duplicate", `multiple receipts were provided for stage: ${structural.stageId}`);
+    if (structural.planDigest === digest) validateStageReceipt(structural, plan);
+    else {
+      // Validate all plan-bound semantics independently while preserving the stale digest as a finding.
+      validateStageReceipt({ ...structural, planDigest: digest }, plan);
+    }
+    byStage.set(structural.stageId, structural);
+  }
+  return byStage;
+}
+
+function selectedItems(contract, targetPaths, findings) {
+  const byId = new Map();
+  for (const targetPath of targetPaths) {
+    try {
+      for (const item of effectiveItems(contract.items, targetPath)) byId.set(item.id, item);
+    } catch (error) {
+      if (!(error instanceof ProjectContextError) || error.code !== "contract-conflict") throw error;
+      findings.push(finding("contract-conflict", "blocked", { path: targetPath }));
+      for (const item of contract.items.filter((entry) => entry.status === "approved" && scopeApplies(entry.scope, targetPath))) byId.set(item.id, item);
+    }
+  }
+  return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id)).map((item) => ({
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    value: structuredClone(item.value),
+    statement: item.statement,
+    scope: structuredClone(item.scope),
+    sourceIds: [...item.sources].sort((left, right) => left.localeCompare(right)),
+  }));
+}
+
+function sourceReadTargets(contract, items) {
+  const sourceIds = new Set(items.flatMap((item) => item.sourceIds));
+  return contract.sources
+    .filter((source) => sourceIds.has(source.id) && LOCAL_SOURCE_KINDS.has(source.kind))
+    .map((source) => ({ path: source.path, reason: "contract-source", sourceId: source.id }));
+}
+
+function mergeReadTargets(targets) {
+  const byPath = new Map();
+  for (const target of targets) {
+    const current = byPath.get(target.path);
+    if (!current) byPath.set(target.path, target);
+    else if (canonicalJson(target).localeCompare(canonicalJson(current)) < 0) byPath.set(target.path, target);
+  }
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function receiptSummary(receipt) {
+  return {
+    stageId: receipt.stageId,
+    status: receipt.status,
+    inputBundleDigest: receipt.inputBundleDigest,
+    changedPaths: [...receipt.changedPaths],
+    acceptanceResults: structuredClone(receipt.acceptanceResults),
+    verificationResults: structuredClone(receipt.verificationResults),
+    decisions: [...receipt.decisions],
+    openIssues: [...receipt.openIssues],
+  };
+}
+
+function withDigestAndBytes(input, digestField) {
+  const value = structuredClone(input);
+  let used = 0;
+  for (let iteration = 0; iteration < 8; iteration += 1) {
+    if (value.budget) value.budget.usedUtf8Bytes = used;
+    delete value[digestField];
+    value[digestField] = digestJson(value);
+    const next = Buffer.byteLength(canonicalJson(value), "utf8");
+    if (next === used) break;
+    used = next;
+  }
+  if (value.budget) value.budget.usedUtf8Bytes = used;
+  delete value[digestField];
+  value[digestField] = digestJson(value);
+  return value;
+}
+
+function baselineFindings(plan, project) {
+  const current = snapshots(project);
+  const findings = [];
+  for (const key of Object.keys(current)) {
+    if (plan.snapshots[key] !== current[key]) findings.push(finding(`${key === "contract" ? "contract-baseline" : key === "sourcesLock" ? "sources-lock-baseline" : "projections-lock-baseline"}-stale`, "blocked", {
+      expected: plan.snapshots[key],
+      actual: current[key],
+    }));
+  }
+  return findings;
+}
+
+function checkerFindings(entries) {
+  const blocking = new Set(blockingContextFindings(entries).map((entry) => canonicalJson(entry)));
+  return entries.map((entry) => finding(
+    entry.code.startsWith("source-") ? "source-drift" : entry.code,
+    blocking.has(canonicalJson(entry)) ? "blocked" : "attention",
+    { projectFinding: entry },
+  ));
+}
+
+function acceptanceFor(plan, stage) {
+  const ids = new Set(stage.acceptanceIds);
+  return plan.task.acceptance.filter((entry) => ids.has(entry.id)).map((entry) => structuredClone(entry));
+}
+
+async function buildStageContextBundleCore(root, project, plan, options, receipts, bindingFindings = []) {
+  const stage = plan.stages.find((entry) => entry.id === options.stageId);
+  if (!stage) fail("task-context-stage-missing", `task context plan has no stage: ${options.stageId}`);
+  const changedPaths = normalizeSignalPaths(options.changedPaths ?? [], "changed path");
+  await validateProjectPaths(root, changedPaths, "changed path");
+  const planDigest = taskContextPlanDigest(plan);
+  const findings = [...bindingFindings, ...baselineFindings(plan, project), ...checkerFindings(await checkProject(root, project))];
+  const dependencyReceipts = [];
+  for (const dependencyId of stage.dependsOn) {
+    const receipt = receipts.get(dependencyId);
+    if (!receipt) {
+      findings.push(finding("stage-dependency-missing", "blocked", { stageId: stage.id, dependencyStageId: dependencyId }));
+      continue;
+    }
+    dependencyReceipts.push(receiptSummary(receipt));
+    if (receipt.planDigest !== planDigest) findings.push(finding("stage-receipt-stale", "blocked", { stageId: dependencyId, reason: "plan-digest" }));
+    if (receipt.status !== "completed") findings.push(finding("stage-dependency-blocked", "blocked", { stageId: stage.id, dependencyStageId: dependencyId }));
+  }
+  const targetPaths = uniqueSorted([...stage.paths, ...changedPaths]);
+  const contractItems = selectedItems(project.contract, targetPaths, findings);
+  const readTargets = mergeReadTargets([
+    ...stage.paths.map((entry) => ({ path: entry, reason: "stage-scope" })),
+    ...changedPaths.map((entry) => ({ path: entry, reason: "host-changed-path-signal" })),
+    ...sourceReadTargets(project.contract, contractItems),
+  ]);
+  if (readTargets.length > plan.budget.maxReadTargets) findings.push(finding("read-target-budget-insufficient", "blocked", {
+    limit: plan.budget.maxReadTargets,
+    required: readTargets.length,
+  }));
+  let bundle = withDigestAndBytes({
+    schemaVersion: STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+    kind: "stage-context-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    task: { id: plan.task.id, title: plan.task.title, goal: plan.task.goal },
+    stage: {
+      id: stage.id,
+      title: stage.title,
+      objective: stage.objective,
+      acceptance: acceptanceFor(plan, stage),
+      paths: [...stage.paths],
+    },
+    workspace: structuredClone(plan.workspace),
+    planDigest,
+    snapshots: snapshots(project),
+    dependencyReceipts: dependencyReceipts.sort((left, right) => left.stageId.localeCompare(right.stageId)),
+    changedPaths,
+    contractItems,
+    readTargets,
+    findings: stableFindings(findings),
+    excluded: [...EXCLUDED_BODIES],
+    budget: {
+      unit: CONTEXT_BUDGET_UNIT,
+      maxUtf8Bytes: plan.budget.maxUtf8Bytes,
+      maxReadTargets: plan.budget.maxReadTargets,
+      usedUtf8Bytes: 0,
+      readTargetCount: readTargets.length,
+    },
+    status: findings.some((entry) => entry.severity === "blocked") ? "blocked" : "ready",
+  }, "bundleDigest");
+  if (bundle.budget.usedUtf8Bytes > plan.budget.maxUtf8Bytes && !bundle.findings.some((entry) => entry.code === "context-budget-insufficient")) {
+    bundle.findings = stableFindings([...bundle.findings, finding("context-budget-insufficient", "blocked", {
+      limit: plan.budget.maxUtf8Bytes,
+      required: bundle.budget.usedUtf8Bytes,
+    })]);
+    bundle.status = "blocked";
+    bundle = withDigestAndBytes(bundle, "bundleDigest");
+  }
+  return bundle;
+}
+
+function sameJson(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+function artifactStageId(input) {
+  return input && typeof input === "object" && !Array.isArray(input) && input.stage
+    && typeof input.stage === "object" && !Array.isArray(input.stage) && typeof input.stage.id === "string"
+    ? input.stage.id
+    : undefined;
+}
+
+async function verifyReceiptBundleBindings(root, project, plan, receipts, receiptBundleInputs) {
+  const findings = [];
+  const candidatesByStage = new Map();
+  for (const input of receiptBundleInputs) {
+    const stageId = artifactStageId(input);
+    let bundle;
+    try {
+      bundle = validateStageContextBundle(input);
+    } catch (error) {
+      if (!(error instanceof ProjectContextError) || error.code !== "stage-context-bundle-schema-invalid") throw error;
+      findings.push(finding("stage-receipt-input-bundle-invalid", "blocked", {
+        ...(stageId ? { stageId } : {}),
+        reason: error.message,
+      }));
+    }
+    if (!stageId) continue;
+    const candidates = candidatesByStage.get(stageId) ?? [];
+    candidates.push(bundle);
+    candidatesByStage.set(stageId, candidates);
+  }
+
+  for (const [stageId, candidates] of candidatesByStage) {
+    if (!receipts.has(stageId)) findings.push(finding("stage-receipt-input-bundle-mismatch", "blocked", {
+      stageId,
+      reason: "receipt-missing",
+    }));
+    if (candidates.length > 1) findings.push(finding("stage-receipt-input-bundle-duplicate", "blocked", {
+      stageId,
+      count: candidates.length,
+    }));
+  }
+
+  const planDigest = taskContextPlanDigest(plan);
+  const currentSnapshots = snapshots(project);
+  const verifiedReceipts = new Map();
+  const verification = new Map();
+
+  async function verify(stageId) {
+    if (verification.has(stageId)) return verification.get(stageId);
+    const pending = (async () => {
+      const receipt = receipts.get(stageId);
+      if (!receipt) return false;
+      const candidates = candidatesByStage.get(stageId) ?? [];
+      if (candidates.length === 0) {
+        findings.push(finding("stage-receipt-input-bundle-missing", "blocked", { stageId }));
+        return false;
+      }
+      if (candidates.length !== 1 || !candidates[0]) return false;
+      const bundle = candidates[0];
+      let valid = true;
+      const mismatch = (reason, details = {}) => {
+        valid = false;
+        findings.push(finding("stage-receipt-input-bundle-mismatch", "blocked", { stageId, reason, ...details }));
+      };
+      const stale = (reason, details = {}) => {
+        valid = false;
+        findings.push(finding("stage-receipt-input-bundle-stale", "blocked", { stageId, reason, ...details }));
+      };
+      if (bundle.project.id !== receipt.projectId) mismatch("project-id", { expected: receipt.projectId, actual: bundle.project.id });
+      if (bundle.task.id !== receipt.taskId) mismatch("task-id", { expected: receipt.taskId, actual: bundle.task.id });
+      if (bundle.stage.id !== receipt.stageId) mismatch("stage-id", { expected: receipt.stageId, actual: bundle.stage.id });
+      if (bundle.project.id !== plan.projectId || bundle.task.id !== plan.task.id || !plan.stages.some((entry) => entry.id === bundle.stage.id)) {
+        mismatch("plan-identity");
+      }
+      if (receipt.planDigest !== planDigest) {
+        stale("receipt-plan-digest", { expected: planDigest, actual: receipt.planDigest });
+        findings.push(finding("stage-receipt-stale", "blocked", { stageId, reason: "plan-digest" }));
+      }
+      if (bundle.planDigest !== planDigest) stale("bundle-plan-digest", { expected: planDigest, actual: bundle.planDigest });
+      for (const key of Object.keys(currentSnapshots)) {
+        if (bundle.snapshots[key] !== plan.snapshots[key] || bundle.snapshots[key] !== currentSnapshots[key]) {
+          stale(`${key}-snapshot`, {
+            plan: plan.snapshots[key],
+            current: currentSnapshots[key],
+            actual: bundle.snapshots[key],
+          });
+        }
+      }
+
+      const stage = plan.stages.find((entry) => entry.id === stageId);
+      const dependencyReceipts = new Map();
+      for (const dependencyId of stage.dependsOn) {
+        if (receipts.has(dependencyId) && await verify(dependencyId)) dependencyReceipts.set(dependencyId, receipts.get(dependencyId));
+      }
+      const rebuilt = await buildStageContextBundleCore(root, project, plan, {
+        stageId,
+        changedPaths: bundle.changedPaths,
+      }, dependencyReceipts);
+      if (!sameJson(bundle, rebuilt)) stale("canonical-content", {
+        expectedBundleDigest: rebuilt.bundleDigest,
+        actualBundleDigest: bundle.bundleDigest,
+      });
+      if (receipt.inputBundleDigest !== bundle.bundleDigest) mismatch("receipt-input-bundle-digest", {
+        expected: bundle.bundleDigest,
+        actual: receipt.inputBundleDigest,
+      });
+      if (receipt.status === "completed" && bundle.status === "blocked") {
+        valid = false;
+        findings.push(finding("stage-receipt-input-bundle-invalid", "blocked", {
+          stageId,
+          reason: "completed-receipt-bound-to-blocked-bundle",
+        }));
+      }
+      if (valid) verifiedReceipts.set(stageId, receipt);
+      return valid;
+    })();
+    verification.set(stageId, pending);
+    return pending;
+  }
+
+  for (const stage of plan.stages) {
+    if (receipts.has(stage.id)) await verify(stage.id);
+  }
+  return { receipts: verifiedReceipts, findings: stableFindings(findings) };
+}
+
+export async function buildStageContextBundle(root, project, planInput, options) {
+  const plan = validateTaskContextPlan(planInput);
+  if (plan.projectId !== project.contract.project.id) fail("task-context-project-mismatch", "task context plan belongs to a different project");
+  await validatePlanPaths(root, plan);
+  const receipts = normalizedReceipts(options.receipts ?? [], plan);
+  const binding = await verifyReceiptBundleBindings(root, project, plan, receipts, options.receiptBundles ?? []);
+  return buildStageContextBundleCore(root, project, plan, options, binding.receipts, binding.findings);
+}
+
+function receiptScopeEscapes(plan, receipt) {
+  const stage = plan.stages.find((entry) => entry.id === receipt.stageId);
+  if (!stage) return receipt.changedPaths;
+  return receipt.changedPaths.filter((changedPath) => !stage.paths.some((stagePath) => pathWithin(changedPath, stagePath)));
+}
+
+function pathOverlapFindings(mainPaths, branchPaths) {
+  const findings = [];
+  for (const mainPath of mainPaths) {
+    for (const branchPath of branchPaths) {
+      if (pathsOverlap(mainPath, branchPath)) findings.push(finding("path-overlap", "attention", { mainPath, branchPath }));
+    }
+  }
+  return findings;
+}
+
+function itemIdsForPaths(contract, paths, findings) {
+  return new Set(selectedItems(contract, paths, findings).map((item) => item.id));
+}
+
+export async function buildIntegrationReviewBundle(root, project, planInput, options = {}) {
+  const plan = validateTaskContextPlan(planInput);
+  if (plan.projectId !== project.contract.project.id) fail("task-context-project-mismatch", "task context plan belongs to a different project");
+  await validatePlanPaths(root, plan);
+  const mainChangedPaths = normalizeSignalPaths(options.mainChangedPaths ?? [], "main changed path");
+  const branchChangedPaths = normalizeSignalPaths(options.branchChangedPaths ?? [], "branch changed path");
+  await validateProjectPaths(root, [...mainChangedPaths, ...branchChangedPaths], "integration changed path");
+  const suppliedReceipts = normalizedReceipts(options.receipts ?? [], plan);
+  const binding = await verifyReceiptBundleBindings(root, project, plan, suppliedReceipts, options.receiptBundles ?? []);
+  const receipts = binding.receipts;
+  const planDigest = taskContextPlanDigest(plan);
+  const findings = [
+    ...binding.findings,
+    ...baselineFindings(plan, project),
+    ...checkerFindings(await checkProject(root, project)),
+    ...pathOverlapFindings(mainChangedPaths, branchChangedPaths),
+  ];
+  for (const stage of plan.stages) {
+    const receipt = receipts.get(stage.id);
+    if (!receipt || receipt.status !== "completed") {
+      findings.push(finding("stage-incomplete", "blocked", { stageId: stage.id, reason: receipt ? receipt.status : "missing-receipt" }));
+      continue;
+    }
+    if (receipt.planDigest !== planDigest) findings.push(finding("stage-receipt-stale", "blocked", { stageId: stage.id, reason: "plan-digest" }));
+    for (const escapedPath of receiptScopeEscapes(plan, receipt)) findings.push(finding("stage-scope-escaped", "blocked", { stageId: stage.id, path: escapedPath }));
+  }
+  const mainItems = itemIdsForPaths(project.contract, mainChangedPaths, findings);
+  const branchItems = itemIdsForPaths(project.contract, branchChangedPaths, findings);
+  for (const itemId of [...mainItems].filter((id) => branchItems.has(id)).sort()) findings.push(finding("contract-overlap", "attention", { itemId }));
+  const decisionCandidates = [...receipts.values()].flatMap((receipt) => receipt.decisions.map((decision) => ({ stageId: receipt.stageId, decision })))
+    .sort((left, right) => left.stageId.localeCompare(right.stageId) || left.decision.localeCompare(right.decision));
+  for (const candidate of decisionCandidates) findings.push(finding("decision-candidate", "attention", candidate));
+  const conflictPaths = uniqueSorted(findings.flatMap((entry) => [entry.mainPath, entry.branchPath, entry.path].filter(Boolean)));
+  const relevantItems = selectedItems(project.contract, uniqueSorted([...mainChangedPaths, ...branchChangedPaths]), findings);
+  const readTargets = mergeReadTargets([
+    ...conflictPaths.map((entry) => ({ path: entry, reason: "integration-conflict" })),
+    ...sourceReadTargets(project.contract, relevantItems),
+  ]);
+  const normalizedFindings = stableFindings(findings);
+  const bundle = {
+    schemaVersion: INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    kind: "integration-review-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    task: { id: plan.task.id, title: plan.task.title, goal: plan.task.goal },
+    workspace: structuredClone(plan.workspace),
+    planDigest,
+    planSnapshots: structuredClone(plan.snapshots),
+    currentSnapshots: snapshots(project),
+    mainChangedPaths,
+    branchChangedPaths,
+    receipts: [...receipts.values()].map(receiptSummary).sort((left, right) => left.stageId.localeCompare(right.stageId)),
+    contractOverlapItemIds: [...mainItems].filter((id) => branchItems.has(id)).sort(),
+    decisionCandidates,
+    readTargets,
+    findings: normalizedFindings,
+    excluded: [...EXCLUDED_BODIES, "git-operations", "test-execution"].sort(),
+    status: normalizedFindings.some((entry) => entry.severity === "blocked") ? "blocked" : "reviewable",
+  };
+  return { ...bundle, bundleDigest: digestJson(bundle) };
+}
+
+async function readInputs(root, planPath, receiptPaths, receiptBundlePaths) {
+  const resolvedPlan = await resolveExistingInside(root, planPath);
+  const plan = await readJsonFile(resolvedPlan.absolute, "task context plan");
+  const receipts = [];
+  for (const receiptPath of receiptPaths) {
+    const resolved = await resolveExistingInside(root, receiptPath);
+    receipts.push(await readJsonFile(resolved.absolute, "stage receipt"));
+  }
+  const receiptBundles = [];
+  for (const bundlePath of receiptBundlePaths) {
+    const resolved = await resolveExistingInside(root, bundlePath);
+    receiptBundles.push(await readJsonFile(resolved.absolute, "stage context bundle"));
+  }
+  return { plan, receipts, receiptBundles };
+}
+
+export async function buildStageContextBundleFiles(root, planPath, options) {
+  const { plan, receipts, receiptBundles } = await readInputs(root, planPath, options.receiptPaths ?? [], options.receiptBundlePaths ?? []);
+  const project = await loadProject(root);
+  return buildStageContextBundle(root, project, plan, { ...options, receipts, receiptBundles });
+}
+
+export async function buildIntegrationReviewBundleFiles(root, planPath, options) {
+  const { plan, receipts, receiptBundles } = await readInputs(root, planPath, options.receiptPaths ?? [], options.receiptBundlePaths ?? []);
+  const project = await loadProject(root);
+  return buildIntegrationReviewBundle(root, project, plan, { ...options, receipts, receiptBundles });
+}