frontend-project-context 1.0.1 → 1.3.0

package/src/project-context/assist.mjs

@@ -0,0 +1,422 @@
+import { digestJson } from "./canonical-json.mjs";
+import { checkProject } from "./checker.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { reviewSource } from "./maintenance.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+import { effectiveItems, scopeApplies } from "./scope-compiler.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const LARGE_IMPACT_THRESHOLD = 100;
+export const ASSIST_BUNDLE_SCHEMA_VERSION = 1;
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(project) {
+  return {
+    contract: project.contractDigest ?? digestJson(project.contract),
+    sourcesLock: project.sourcesLockDigest ?? digestJson(project.sourcesLock),
+    projectionsLock: project.projectionsLockDigest ?? digestJson(project.projectionsLock),
+  };
+}
+
+function sourceLocator(source) {
+  if (source.kind === "json-pointer") return { path: source.path, pointer: source.pointer };
+  if (LOCAL_SOURCE_KINDS.has(source.kind)) return { path: source.path };
+  return { reference: source.reference };
+}
+
+function sourceTarget(source, reason, priority) {
+  return {
+    sourceId: source.id,
+    kind: source.kind,
+    locator: sourceLocator(source),
+    reason,
+    priority,
+  };
+}
+
+function stableFindings(findings) {
+  const seen = new Set();
+  return findings.filter((finding) => {
+    const key = JSON.stringify(finding);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function setupWorkUnits(proposal) {
+  const factAndReferenceItems = proposal.items
+    .filter((item) => item.kind === "fact" || item.kind === "reference")
+    .map((item) => item.id);
+  const guidanceItems = proposal.items.filter((item) => item.kind === "reference");
+  const units = [];
+  if (factAndReferenceItems.length > 0) {
+    units.push({
+      id: "onboarding-facts",
+      kind: "onboarding-facts",
+      sourceIds: uniqueSorted(proposal.items
+        .filter((item) => factAndReferenceItems.includes(item.id))
+        .flatMap((item) => item.sources)),
+      itemIds: uniqueSorted(factAndReferenceItems),
+    });
+  }
+  if (guidanceItems.length > 0) {
+    units.push({
+      id: "authoritative-guidance",
+      kind: "authoritative-guidance",
+      sourceIds: uniqueSorted(guidanceItems.flatMap((item) => item.sources)),
+      itemIds: uniqueSorted(guidanceItems.map((item) => item.id)),
+    });
+  }
+  return units;
+}
+
+function pendingSourceIds(items) {
+  return uniqueSorted(items.flatMap((item) => [
+    ...item.sources,
+    ...(item.verification?.source ? [item.verification.source] : []),
+  ]));
+}
+
+function pendingReviewUnit(items) {
+  return {
+    id: "pending-review",
+    kind: "pending-review",
+    sourceIds: pendingSourceIds(items),
+    itemIds: items.map((item) => item.id),
+  };
+}
+
+function mergeReadTargets(targets) {
+  const bySource = new Map();
+  for (const target of targets) {
+    const existing = bySource.get(target.sourceId);
+    if (!existing || target.priority < existing.priority) bySource.set(target.sourceId, target);
+  }
+  return [...bySource.values()].sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+}
+
+export function buildSetupAssistBundle(project, proposal, options = {}) {
+  const guidanceSourceIds = new Set(
+    proposal.items.filter((item) => item.kind === "reference").flatMap((item) => item.sources),
+  );
+  const pending = project.contract.items
+    .filter((item) => item.status === "proposed")
+    .map(pendingItem)
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const sourceById = new Map([
+    ...project.contract.sources.map((source) => [source.id, source]),
+    ...proposal.sources.map((source) => [source.id, source]),
+  ]);
+  const guidanceTargets = [...guidanceSourceIds]
+    .map((id) => sourceById.get(id))
+    .filter(Boolean)
+    .map((source) => sourceTarget(source, "authoritative-guidance", 1));
+  const pendingTargets = pendingSourceIds(pending)
+    .map((id) => sourceById.get(id))
+    .filter((source) => source && sourceStatus(source) === "active" && LOCAL_SOURCE_KINDS.has(source.kind))
+    .map((source) => sourceTarget(source, "pending-review", 2));
+  const workUnits = setupWorkUnits(proposal);
+  if (pending.length > 0) workUnits.push(pendingReviewUnit(pending));
+  return {
+    schemaVersion: ASSIST_BUNDLE_SCHEMA_VERSION,
+    mode: "setup",
+    project: {
+      id: project.contract.project.id,
+      name: project.contract.project.name,
+      initialized: Boolean(options.initialized),
+    },
+    snapshots: snapshots(project),
+    summary: {
+      candidateSources: proposal.sources.length,
+      candidateItems: proposal.items.length,
+      changedSources: 0,
+      affectedItems: 0,
+      pendingItems: pending.length,
+      affectedProjections: 0,
+    },
+    sourceChanges: [],
+    affectedItems: [],
+    pendingItems: pending,
+    pathSignals: [],
+    projectionPaths: [],
+    findings: [],
+    readTargets: mergeReadTargets([...guidanceTargets, ...pendingTargets]),
+    workUnits: workUnits.sort((left, right) => left.id.localeCompare(right.id)),
+    proposal: structuredClone(proposal),
+    artifacts: [{
+      kind: "proposal",
+      path: options.proposalPath ?? ".project-context/setup.proposal.json",
+      action: options.proposalAction ?? "preview",
+      persisted: Boolean(options.proposalPersisted),
+    }],
+  };
+}
+
+function syncPath(value) {
+  try {
+    return normalizeRelativePath(value, { allowRoot: true, label: "changed path" });
+  } catch (error) {
+    fail("sync-path-invalid", `changed path is invalid: ${value}`, {
+      details: { path: value, reason: error.code ?? "invalid-path" },
+    });
+  }
+}
+
+function registeredSourcesForPath(contract, targetPath) {
+  return contract.sources
+    .filter((source) => sourceStatus(source) === "active" && LOCAL_SOURCE_KINDS.has(source.kind))
+    .filter((source) => {
+      if (source.kind === "json-pointer") return targetPath === source.path;
+      return targetPath === source.path || targetPath.startsWith(`${source.path}/`);
+    })
+    .map((source) => source.id)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function pathSignals(contract, changedPaths) {
+  return uniqueSorted(changedPaths.map(syncPath)).map((targetPath) => {
+    const registeredSourceIds = registeredSourcesForPath(contract, targetPath);
+    let approvedItemIds = [];
+    try {
+      approvedItemIds = effectiveItems(contract.items, targetPath).map((item) => item.id);
+    } catch (error) {
+      if (error?.code !== "contract-conflict" && !error?.code?.startsWith("scope-")) throw error;
+      approvedItemIds = contract.items
+        .filter((item) => item.status === "approved" && scopeApplies(item.scope, targetPath))
+        .map((item) => item.id)
+        .sort((left, right) => left.localeCompare(right));
+    }
+    return {
+      path: targetPath,
+      approvedItemIds,
+      registeredSourceIds,
+      classification: registeredSourceIds.length > 0
+        ? "registered-source"
+        : approvedItemIds.length > 0
+          ? "scope-only"
+          : "unrelated",
+    };
+  });
+}
+
+function impactReasonsByItem(reviews) {
+  const byItem = new Map();
+  for (const review of reviews) {
+    if (!["changed", "missing", "unreadable"].includes(review.status)) continue;
+    for (const item of review.impact.items) {
+      if (!byItem.has(item.id)) byItem.set(item.id, []);
+      byItem.get(item.id).push({ sourceId: review.source.id, reasons: uniqueSorted(item.reasons ?? []) });
+    }
+  }
+  for (const impacts of byItem.values()) impacts.sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+  return byItem;
+}
+
+function affectedItem(item, sourceImpacts, largeImpact) {
+  const base = {
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    status: item.status,
+    itemDigest: digestJson(item),
+    sourceImpacts: structuredClone(sourceImpacts),
+  };
+  if (largeImpact) return { ...base, largeImpact: true };
+  return {
+    ...base,
+    value: structuredClone(item.value),
+    statement: item.statement,
+    sources: [...item.sources],
+    overrides: [...item.overrides],
+    ...(item.verification ? { verification: structuredClone(item.verification) } : {}),
+  };
+}
+
+function pendingItem(item) {
+  return {
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    status: item.status,
+    itemDigest: digestJson(item),
+    value: structuredClone(item.value),
+    statement: item.statement,
+    sources: [...item.sources],
+    overrides: [...item.overrides],
+    ...(item.verification ? { verification: structuredClone(item.verification) } : {}),
+  };
+}
+
+function sourceChange(review) {
+  const hasProblem = ["changed", "missing", "unreadable"].includes(review.status);
+  const itemIds = hasProblem ? review.impact.items.map((item) => item.id) : [];
+  const largeImpact = itemIds.length > LARGE_IMPACT_THRESHOLD;
+  return {
+    sourceId: review.source.id,
+    kind: review.source.kind,
+    locator: sourceLocator(review.source),
+    status: review.status,
+    lockedDigest: review.lockedDigest,
+    currentDigest: review.currentDigest,
+    ...(review.reason ? { reason: review.reason } : {}),
+    affectedItemIds: itemIds,
+    itemRelations: hasProblem && !largeImpact
+      ? review.impact.items.map((item) => ({ id: item.id, reasons: uniqueSorted(item.reasons ?? []) }))
+      : [],
+    fallbackItemIds: hasProblem ? review.impact.fallbackItems.map((item) => item.id) : [],
+    directProjectionPaths: hasProblem ? [...review.impact.directProjectionPaths] : [],
+    staleProjectionPaths: hasProblem ? [...review.impact.staleProjectionPaths] : [],
+    ...(largeImpact ? { largeImpact: true } : {}),
+  };
+}
+
+function nonLocalSourceChange(source) {
+  const deprecated = sourceStatus(source) === "deprecated";
+  return {
+    sourceId: source.id,
+    kind: source.kind,
+    locator: sourceLocator(source),
+    status: deprecated ? "deprecated" : "not-local-checkable",
+    lockedDigest: null,
+    currentDigest: null,
+    affectedItemIds: [],
+    itemRelations: [],
+    fallbackItemIds: [],
+    directProjectionPaths: [],
+    staleProjectionPaths: [],
+  };
+}
+
+function syncWorkUnits(problemReviews, signals, findings, pendingItems) {
+  const units = problemReviews.map((review) => ({
+    id: `source-change:${review.source.id}`,
+    kind: "source-change",
+    sourceIds: [review.source.id],
+    itemIds: review.impact.items.map((item) => item.id),
+    fallbackItemIds: review.impact.fallbackItems.map((item) => item.id),
+    projectionPaths: uniqueSorted([
+      ...review.impact.directProjectionPaths,
+      ...review.impact.staleProjectionPaths,
+    ]),
+    ...(review.impact.items.length > LARGE_IMPACT_THRESHOLD ? { largeImpact: true } : {}),
+  }));
+  for (const signal of signals) {
+    units.push({
+      id: `path-signal:${signal.path}`,
+      kind: "path-signal",
+      paths: [signal.path],
+      sourceIds: [...signal.registeredSourceIds],
+      itemIds: [...signal.approvedItemIds],
+    });
+  }
+  if (pendingItems.length > 0) {
+    units.push(pendingReviewUnit(pendingItems));
+  }
+  const projectionFindings = findings.filter((finding) => finding.code.startsWith("projection-") && finding.path);
+  for (const projectionPath of uniqueSorted(projectionFindings.map((finding) => finding.path))) {
+    units.push({
+      id: `projection-review:${projectionPath}`,
+      kind: "projection-review",
+      projectionPaths: [projectionPath],
+      findingCodes: uniqueSorted(projectionFindings
+        .filter((finding) => finding.path === projectionPath)
+        .map((finding) => finding.code)),
+    });
+  }
+  const conflictFindings = findings.filter((finding) =>
+    finding.code.includes("conflict") || finding.code.startsWith("scope-") || finding.code.startsWith("verification-"),
+  );
+  if (conflictFindings.length > 0) {
+    units.push({
+      id: "conflicts",
+      kind: "conflict",
+      findingCodes: uniqueSorted(conflictFindings.map((finding) => finding.code)),
+      itemIds: uniqueSorted(conflictFindings.flatMap((finding) => finding.items ?? (finding.item ? [finding.item] : []))),
+      sourceIds: uniqueSorted(conflictFindings.flatMap((finding) => finding.source ? [finding.source] : [])),
+      paths: uniqueSorted(conflictFindings.flatMap((finding) => finding.path ? [finding.path] : [])),
+    });
+  }
+  return units.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export async function buildSyncAssistBundle(root, project, changedPaths = []) {
+  const reviewResults = await Promise.all(project.contract.sources.map(async (source) => {
+    if (sourceStatus(source) === "deprecated" || !LOCAL_SOURCE_KINDS.has(source.kind)) {
+      return { source, nonLocal: nonLocalSourceChange(source) };
+    }
+    return { source, review: await reviewSource(root, project, source.id) };
+  }));
+  const reviews = reviewResults.filter((entry) => entry.review).map((entry) => entry.review);
+  const problemReviews = reviews.filter((review) => ["changed", "missing", "unreadable"].includes(review.status));
+  const sourceChanges = reviewResults
+    .filter((entry) => !entry.review || entry.review.status !== "unchanged")
+    .map((entry) => entry.review ? sourceChange(entry.review) : entry.nonLocal)
+    .sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+  const sourceImpacts = impactReasonsByItem(problemReviews);
+  const largeImpactIds = new Set(problemReviews
+    .filter((review) => review.impact.items.length > LARGE_IMPACT_THRESHOLD)
+    .flatMap((review) => review.impact.items.map((item) => item.id)));
+  const itemById = new Map(project.contract.items.map((item) => [item.id, item]));
+  const affectedItems = [...sourceImpacts.keys()]
+    .map((id) => affectedItem(itemById.get(id), sourceImpacts.get(id), largeImpactIds.has(id)))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const signals = pathSignals(project.contract, changedPaths);
+  const findings = stableFindings(await checkProject(root, project));
+  const pending = project.contract.items
+    .filter((item) => item.status === "proposed")
+    .map(pendingItem)
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const projectionPaths = uniqueSorted([
+    ...problemReviews.flatMap((review) => [
+      ...review.impact.directProjectionPaths,
+      ...review.impact.staleProjectionPaths,
+    ]),
+    ...findings
+      .filter((finding) => finding.code.startsWith("projection-") && finding.path)
+      .map((finding) => finding.path),
+  ]);
+  const changedTargets = problemReviews
+    .filter((review) => review.status === "changed")
+    .map((review) => sourceTarget(review.source, "source-change", 1));
+  const sourceById = new Map(project.contract.sources.map((source) => [source.id, source]));
+  const pendingTargets = pendingSourceIds(pending)
+    .map((id) => sourceById.get(id))
+    .filter((source) => source && sourceStatus(source) === "active" && LOCAL_SOURCE_KINDS.has(source.kind))
+    .map((source) => sourceTarget(source, "pending-review", 2));
+  const readTargets = mergeReadTargets([...changedTargets, ...pendingTargets]);
+  return {
+    schemaVersion: ASSIST_BUNDLE_SCHEMA_VERSION,
+    mode: "sync",
+    project: {
+      id: project.contract.project.id,
+      name: project.contract.project.name,
+      initialized: true,
+    },
+    snapshots: snapshots(project),
+    summary: {
+      candidateSources: 0,
+      candidateItems: 0,
+      changedSources: problemReviews.length,
+      affectedItems: affectedItems.length,
+      pendingItems: pending.length,
+      affectedProjections: projectionPaths.length,
+    },
+    sourceChanges,
+    affectedItems,
+    pendingItems: pending,
+    pathSignals: signals,
+    projectionPaths,
+    findings,
+    readTargets,
+    workUnits: syncWorkUnits(problemReviews, signals, findings, pending),
+    proposal: null,
+    artifacts: [],
+  };
+}

package/src/project-context/capabilities.mjs

@@ -0,0 +1,74 @@
+import { ASSIST_BUNDLE_SCHEMA_VERSION } from "./assist.mjs";
+import { DASHBOARD_SCHEMA_VERSION } from "./dashboard-model.mjs";
+import {
+  ACTION_KINDS,
+  ACTION_PLAN_SCHEMA_VERSION,
+  CAPABILITIES_SCHEMA_VERSION,
+  COMMANDS,
+  EXCHANGE_PROTOCOL_VERSION,
+  PACKAGE_VERSION,
+  REVIEW_BUNDLE_SCHEMA_VERSION,
+} from "./exchange-schema.mjs";
+import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { RENDERER_VERSION } from "./renderer.mjs";
+import {
+  CONTEXT_BUDGET_UNIT,
+  INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+  STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+  STAGE_RECEIPT_SCHEMA_VERSION,
+  TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+} from "./task-context-schema.mjs";
+
+function schemas() {
+  return {
+    actionPlan: ACTION_PLAN_SCHEMA_VERSION,
+    assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
+    capabilities: CAPABILITIES_SCHEMA_VERSION,
+    contract: 2,
+    dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
+    integrationReviewBundle: INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    projectionLock: 1,
+    projectionRenderer: RENDERER_VERSION,
+    proposal: 1,
+    reviewBundle: REVIEW_BUNDLE_SCHEMA_VERSION,
+    sourceLock: 1,
+    stageContextBundle: STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+    stageReceipt: STAGE_RECEIPT_SCHEMA_VERSION,
+    taskContextPlan: TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+  };
+}
+
+export async function buildCapabilities(root) {
+  const initialization = await inspectProjectInitialization(root);
+  let project = null;
+  if (initialization.status === "initialized") {
+    const loaded = await loadProject(root);
+    project = { id: loaded.contract.project.id, name: loaded.contract.project.name };
+  }
+  return {
+    schemaVersion: CAPABILITIES_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
+    schemas: schemas(),
+    commands: [...COMMANDS],
+    actionKinds: [...ACTION_KINDS],
+    contextBudget: { unit: CONTEXT_BUDGET_UNIT, modelTokens: false, callerMustProvideLimit: true },
+    initialization: initialization.status,
+    initialized: initialization.status === "initialized",
+    project,
+    boundaries: {
+      provider: false,
+      agentRuntime: false,
+      git: false,
+      network: false,
+      dependencyInstallation: false,
+      automaticApproval: false,
+      businessCodeWrites: false,
+      taskExecution: false,
+      stagePathBodyReads: false,
+      applyPlan: false,
+      scheduler: false,
+      daemon: false,
+    },
+  };
+}