frontend-project-context 1.3.1 → 1.7.0

package/src/project-context/renderer.mjs

@@ -1,5 +1,5 @@
 import { canonicalJson, digestJson, sha256 } from "./canonical-json.mjs";
-import { describeScope, effectiveItems } from "./scope-compiler.mjs";
+import { describeScope, effectiveItems, scopeApplies } from "./scope-compiler.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
 const KIND_TITLES = new Map([
@@ -107,6 +107,80 @@ export function renderContextBundle(contract, paths, task, options = {}) {
   return renderCollectedBundle(collectBundle(contract, paths), contract.sources, task, options);
 }
 
+export function renderSelectedContextBundle(contract, paths, itemIds, task, options = {}) {
+  const selected = new Set(itemIds);
+  const normalizedPaths = paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "target path" }));
+  const selectedItems = contract.items.filter((item) => item.status === "approved" && selected.has(item.id));
+  const sections = normalizedPaths.map((targetPath) => ({
+    path: targetPath,
+    items: selectedItems.filter((item) => scopeApplies(item.scope, targetPath)).sort((left, right) => left.id.localeCompare(right.id)),
+  }));
+  const bundle = {
+    project: contract.project,
+    contractDigest: digestJson(contract),
+    paths: normalizedPaths,
+    sections,
+    itemIds: [...selected].sort(),
+  };
+  return renderCollectedBundle(bundle, contract.sources, task, options);
+}
+
+// Task delivery deliberately has its own renderer. Managed AGENTS/Ruler projections
+// keep using renderCollectedBundle and RENDERER_VERSION 3 byte-for-byte.
+function renderTaskItem(item, locale) {
+  const sources = item.sources.map((source) => `\`${source}\``).join(", ");
+  const value = canonicalJson(item.value);
+  const fence = fenceFor(value);
+  const subject = item.subject === item.id ? "" : `Subject: \`${item.subject}\`; `;
+  return `- **${item.id}** — ${localizedStatement(item.statement, locale)}\n  - ${subject}Scope: \`${describeScope(item.scope)}\`; source IDs: ${sources}\n  - Value (canonical JSON):\n\n    ${fence}json\n    ${value}\n    ${fence}`;
+}
+
+export function renderTaskContextBundle(contract, paths, itemIds, task, options = {}) {
+  const locale = options.locale ?? "zh-CN";
+  const selected = new Set(itemIds);
+  const normalizedPaths = paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "target path" }));
+  const effectiveByPath = normalizedPaths.map((targetPath) => ({
+    path: targetPath,
+    items: effectiveItems(contract.items, targetPath)
+      .filter((item) => selected.has(item.id))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+  }));
+  const commonIds = effectiveByPath.length === 0 ? new Set() : new Set(effectiveByPath[0].items.map((item) => item.id));
+  for (const section of effectiveByPath.slice(1)) {
+    const ids = new Set(section.items.map((item) => item.id));
+    for (const id of [...commonIds]) if (!ids.has(id)) commonIds.delete(id);
+  }
+  const common = effectiveByPath[0]?.items.filter((item) => commonIds.has(item.id)) ?? [];
+  const lines = [
+    "# Project Context Task Delivery",
+    "",
+    `Project: **${contract.project.name}** (\`${contract.project.id}\`)`,
+    `Contract digest: \`${digestJson(contract)}\``,
+  ];
+  const fence = fenceFor(task);
+  lines.push("", "## Task constraint", "", fence, String(task), fence);
+  const renderKinds = (items) => {
+    for (const [kind, title] of KIND_TITLES) {
+      const entries = items.filter((item) => item.kind === kind);
+      if (entries.length > 0) lines.push("", `### ${title}`, "", ...entries.map((item) => renderTaskItem(item, locale)));
+    }
+  };
+  if (common.length > 0) {
+    lines.push("", "## Applies to all targets");
+    renderKinds(common);
+  }
+  for (const section of effectiveByPath) {
+    const delta = section.items.filter((item) => !commonIds.has(item.id));
+    lines.push("", `## Target delta: \`${section.path}\``);
+    if (delta.length === 0) lines.push("", "No additional approved contract items apply.");
+    else renderKinds(delta);
+  }
+  lines.push("", "## Source IDs", "");
+  const sourceIds = [...new Set(effectiveByPath.flatMap((section) => section.items.flatMap((item) => item.sources)))].sort();
+  lines.push(sourceIds.length === 0 ? "No sources selected." : sourceIds.map((id) => `- \`${id}\``).join("\n"));
+  return `${lines.join("\n")}\n`;
+}
+
 export function renderProjection(contract, paths, target) {
   const bundle = collectBundle(contract, paths);
   const body = renderCollectedBundle(bundle, contract.sources);

package/src/project-context/source-reader.mjs

@@ -33,7 +33,20 @@ export function readJsonPointer(value, pointer) {
   return current;
 }
 
-async function digestDirectory(absolute) {
+export function createSourceReadContext() {
+  return {
+    cache: new Map(),
+    metrics: { sourceDigestReads: 0, sourceBodyReads: 0, sourceIdentityReads: 0 },
+  };
+}
+
+async function cached(context, key, read) {
+  if (!context?.cache) return read();
+  if (!context.cache.has(key)) context.cache.set(key, Promise.resolve().then(read));
+  return context.cache.get(key);
+}
+
+async function digestDirectory(absolute, context) {
   const entries = [];
   async function visit(directory, prefix) {
     const children = (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
@@ -46,7 +59,11 @@ async function digestDirectory(absolute) {
       } else if (child.isDirectory()) {
         await visit(full, relative);
       } else if (child.isFile()) {
-        entries.push([relative, sha256(await readFile(full))]);
+        const body = await cached(context, `body:${full}`, async () => {
+          if (context?.metrics) context.metrics.sourceBodyReads += 1;
+          return readFile(full);
+        });
+        entries.push([relative, sha256(body)]);
       }
     }
   }
@@ -54,42 +71,58 @@ async function digestDirectory(absolute) {
   return sha256(canonicalJson(entries));
 }
 
-export async function digestPath(projectRoot, relativePath) {
-  const { absolute } = await resolveExistingInside(projectRoot, relativePath);
-  const info = await stat(absolute);
-  if (info.isDirectory()) return digestDirectory(absolute);
-  if (!info.isFile()) fail("source-unsupported", `source is not a regular file or directory: ${relativePath}`);
-  return sha256(await readFile(absolute));
+export async function digestPath(projectRoot, relativePath, context) {
+  return cached(context, `digest:${relativePath}`, async () => {
+    if (context?.metrics) context.metrics.sourceDigestReads += 1;
+    const { absolute } = await resolveExistingInside(projectRoot, relativePath);
+    const info = await stat(absolute);
+    if (info.isDirectory()) return digestDirectory(absolute, context);
+    if (!info.isFile()) fail("source-unsupported", `source is not a regular file or directory: ${relativePath}`);
+    const body = await cached(context, `body:${absolute}`, async () => {
+      if (context?.metrics) context.metrics.sourceBodyReads += 1;
+      return readFile(absolute);
+    });
+    return sha256(body);
+  });
 }
 
-export async function digestPathIdentity(projectRoot, relativePath) {
-  const { absolute } = await resolveExistingInside(projectRoot, relativePath);
-  const info = await stat(absolute);
-  const kind = info.isDirectory() ? "directory" : info.isFile() ? "file" : null;
-  if (!kind) fail("source-unsupported", `source is not a regular file or directory: ${relativePath}`);
-  return sha256(canonicalJson({ kind }));
+export async function digestPathIdentity(projectRoot, relativePath, context) {
+  return cached(context, `identity:${relativePath}`, async () => {
+    if (context?.metrics) context.metrics.sourceIdentityReads += 1;
+    const { absolute } = await resolveExistingInside(projectRoot, relativePath);
+    const info = await stat(absolute);
+    const kind = info.isDirectory() ? "directory" : info.isFile() ? "file" : null;
+    if (!kind) fail("source-unsupported", `source is not a regular file or directory: ${relativePath}`);
+    return sha256(canonicalJson({ kind }));
+  });
 }
 
-export async function readSourceDigest(projectRoot, source) {
+export async function readSourceDigest(projectRoot, source, context) {
   if (sourceStatus(source) === "deprecated") return null;
   if (source.kind === "human-decision" || source.kind === "external-reference") return null;
-  if (source.kind === "path") return digestPathIdentity(projectRoot, source.path);
-  if (source.kind === "file") return digestPath(projectRoot, source.path);
-  return sha256(canonicalJson(await readJsonSourceValue(projectRoot, source)));
+  if (source.kind === "path") return digestPathIdentity(projectRoot, source.path, context);
+  if (source.kind === "file") return digestPath(projectRoot, source.path, context);
+  return sha256(canonicalJson(await readJsonSourceValue(projectRoot, source, context)));
 }
 
-async function readJsonSourceValue(projectRoot, source) {
-  const { absolute } = await resolveExistingInside(projectRoot, source.path);
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(absolute, "utf8"));
-  } catch (error) {
-    fail("source-json-invalid", `cannot parse JSON source: ${source.path}`, { cause: error });
-  }
-  return readJsonPointer(parsed, source.pointer);
+async function readJsonSourceValue(projectRoot, source, context) {
+  return cached(context, `json:${source.path}:${source.pointer}`, async () => {
+    const { absolute } = await resolveExistingInside(projectRoot, source.path);
+    let parsed;
+    try {
+      const body = await cached(context, `body:${absolute}`, async () => {
+        if (context?.metrics) context.metrics.sourceBodyReads += 1;
+        return readFile(absolute, "utf8");
+      });
+      parsed = JSON.parse(body);
+    } catch (error) {
+      fail("source-json-invalid", `cannot parse JSON source: ${source.path}`, { cause: error });
+    }
+    return readJsonPointer(parsed, source.pointer);
+  });
 }
 
-export async function verifyItem(projectRoot, item, sourceMap) {
+export async function verifyItem(projectRoot, item, sourceMap, context) {
   const verification = item.verification;
   if (!verification || verification.kind === "none") return null;
   const source = sourceMap.get(verification.source);
@@ -106,7 +139,7 @@ export async function verifyItem(projectRoot, item, sourceMap) {
     if (source.kind !== "json-pointer") {
       return { code: "verification-source-incompatible", item: item.id, source: source.id };
     }
-    const actualValue = await readJsonSourceValue(projectRoot, source);
+    const actualValue = await readJsonSourceValue(projectRoot, source, context);
     if (canonicalJson(actualValue) !== canonicalJson(verification.expected)) {
       return { code: "verification-failed", item: item.id, source: source.id, expected: verification.expected, actual: actualValue };
     }
@@ -115,7 +148,7 @@ export async function verifyItem(projectRoot, item, sourceMap) {
   if (verification.kind !== "path-digest") {
     return { code: "verification-kind-unsupported", item: item.id, source: source.id };
   }
-  const actual = await digestPath(projectRoot, source.path);
+  const actual = await digestPath(projectRoot, source.path, context);
   const expected = verification.expected ?? source.digest;
   if (actual !== expected) return { code: "verification-failed", item: item.id, source: source.id, expected, actual };
   return null;

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

@@ -1,4 +1,5 @@
 import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { selectAdaptiveItems } from "./adaptive-context.mjs";
 import { blockingContextFindings, checkProject } from "./checker.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
 import { readJsonFile } from "./io.mjs";
@@ -91,8 +92,18 @@ function normalizedReceipts(receiptInputs, plan) {
   return byStage;
 }
 
-function selectedItems(contract, targetPaths, findings) {
+function selectedItems(contract, targetPaths, findings, adaptiveText) {
   const byId = new Map();
+  if (adaptiveText !== undefined) {
+    const adaptiveFindings = [];
+    const selection = selectAdaptiveItems(contract, null, {
+      task: { text: adaptiveText, topics: [], paths: targetPaths, changedPaths: [], itemIds: [] },
+      level: "initial",
+    }, { findings: adaptiveFindings });
+    findings.push(...adaptiveFindings);
+    for (const item of selection.selected) byId.set(item.id, item);
+  }
+  if (adaptiveText === undefined) {
   for (const targetPath of targetPaths) {
     try {
       for (const item of effectiveItems(contract.items, targetPath)) byId.set(item.id, item);
@@ -102,6 +113,7 @@ function selectedItems(contract, targetPaths, findings) {
       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,
@@ -205,7 +217,7 @@ async function buildStageContextBundleCore(root, project, plan, options, receipt
     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 contractItems = selectedItems(project.contract, targetPaths, findings, `${plan.task.goal}\n${stage.objective}`);
   const readTargets = mergeReadTargets([
     ...stage.paths.map((entry) => ({ path: entry, reason: "stage-scope" })),
     ...changedPaths.map((entry) => ({ path: entry, reason: "host-changed-path-signal" })),