frontend-project-context 1.0.0

package/src/project-context/projection-store.mjs

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { canonicalJson, digestJson, sha256 } from "./canonical-json.mjs";
+import { validateContract, validateProjectionLock } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { atomicWriteFile, atomicWriteJson, readJsonFile } from "./io.mjs";
+import { assertProjectionPath, resolveWritableInside } from "./path-policy.mjs";
+import { renderProjection, parseProjectionMarker } from "./renderer.mjs";
+
+async function readIfPresent(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function publishProjection(root, project, options, dependencies = {}) {
+  const writeFile = dependencies.writeFile ?? atomicWriteFile;
+  const writeJson = dependencies.writeJson ?? atomicWriteJson;
+  const readJson = dependencies.readJson ?? readJsonFile;
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const { target, output, paths, write } = options;
+  const normalized = output.replaceAll("\\", "/").replace(/^\.\//u, "");
+  assertProjectionPath(target, normalized);
+  const resolved = await resolveWritableInside(root, output, { createParent: write });
+  const rendered = renderProjection(project.contract, paths, target);
+  const existing = await readContent(resolved.absolute);
+  const lockEntry = project.projectionsLock.projections.find((entry) => entry.path === resolved.normalized);
+  if (existing !== null) {
+    const marker = parseProjectionMarker(existing);
+    if (
+      !marker ||
+      !lockEntry ||
+      sha256(existing) !== lockEntry.contentDigest ||
+      marker.target !== lockEntry.target ||
+      marker.rendererVersion !== lockEntry.rendererVersion
+    ) {
+      fail("managed-file-ownership-conflict", `refusing to overwrite unmanaged or modified file: ${resolved.normalized}; use a new scoped AGENTS.md or Ruler projection instead`, {
+        exitCode: 3,
+        details: { path: resolved.normalized },
+      });
+    }
+  }
+  const nextEntry = {
+    path: resolved.normalized,
+    target,
+    paths: rendered.paths,
+    contractDigest: rendered.contractDigest,
+    bundleDigest: rendered.bundleDigest,
+    contentDigest: sha256(rendered.content),
+    itemIds: rendered.itemIds,
+    rendererVersion: rendered.rendererVersion,
+  };
+  const nextLock = {
+    schemaVersion: 1,
+    projections: [
+      ...project.projectionsLock.projections.filter((entry) => entry.path !== resolved.normalized),
+      nextEntry,
+    ].sort((left, right) => left.path.localeCompare(right.path)),
+  };
+  const action = existing === null ? "create" : existing === rendered.content ? "unchanged" : "update";
+  if (write && action !== "unchanged") {
+    if (dependencies.beforeCommit) await dependencies.beforeCommit();
+    const currentContract = validateContract(await readJson(project.files.contract, "contract.json"));
+    const currentProjectionLock = validateProjectionLock(await readJson(project.files.projectionsLock, "projections.lock.json"));
+    if (digestJson(currentContract) !== project.contractDigest) {
+      fail("project-state-changed", "contract changed while the projection was being prepared", { exitCode: 1 });
+    }
+    if (digestJson(currentProjectionLock) !== project.projectionsLockDigest) {
+      fail("projection-state-changed", "projection lock changed while the projection was being prepared", { exitCode: 1 });
+    }
+    const currentContent = await readContent(resolved.absolute);
+    if (currentContent !== existing) {
+      fail("projection-state-changed", "projection file changed while the update was being prepared", {
+        exitCode: 1,
+        details: { path: resolved.normalized },
+      });
+    }
+    await writeJson(project.files.projectionsLock, nextLock);
+    try {
+      await writeFile(resolved.absolute, rendered.content);
+    } catch (error) {
+      try {
+        const recoveryCurrent = validateProjectionLock(await readJson(project.files.projectionsLock, "projections.lock.json"));
+        if (canonicalJson(recoveryCurrent) !== canonicalJson(nextLock)) {
+          if (error && typeof error === "object") {
+            error.details = { ...(error.details ?? {}), recovery: "projection-lock-restore-skipped-concurrent-change" };
+          }
+        } else {
+          await writeJson(project.files.projectionsLock, project.projectionsLock);
+        }
+      } catch (recoveryError) {
+        if (error && typeof error === "object") {
+          error.details = {
+            ...(error.details ?? {}),
+            recovery: "projection-lock-restore-failed",
+            recoveryMessage: recoveryError.message,
+          };
+        }
+      }
+      throw error;
+    }
+  }
+  return { action, content: rendered.content, entry: nextEntry, written: Boolean(write) };
+}

package/src/project-context/renderer.mjs

@@ -0,0 +1,135 @@
+import { canonicalJson, digestJson, sha256 } from "./canonical-json.mjs";
+import { describeScope, effectiveItems } from "./scope-compiler.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+const KIND_TITLES = new Map([
+  ["fact", "Facts"],
+  ["policy", "Policies"],
+  ["reference", "References"],
+  ["validation-description", "Validation descriptions"],
+]);
+export const RENDERER_VERSION = 3;
+
+function fenceFor(value) {
+  const runs = [...String(value).matchAll(/`+/gu)].map((match) => match[0].length);
+  return "`".repeat(Math.max(3, (runs.length ? Math.max(...runs) : 0) + 1));
+}
+
+export function collectBundle(contract, paths) {
+  const normalizedPaths = paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "target path" }));
+  const sections = normalizedPaths.map((targetPath) => ({
+    path: targetPath,
+    items: effectiveItems(contract.items, targetPath),
+  }));
+  const itemIds = [...new Set(sections.flatMap((section) => section.items.map((item) => item.id)))].sort();
+  return {
+    project: contract.project,
+    contractDigest: digestJson(contract),
+    paths: normalizedPaths,
+    sections,
+    itemIds,
+  };
+}
+
+function localizedStatement(statement, locale) {
+  const match = /^\[zh-CN\] ([^\n]+)\n\[en\] ([\s\S]+)$/u.exec(statement);
+  if (!match || locale === "all") return statement;
+  return locale === "en" ? match[2] : match[1];
+}
+
+function renderItem(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}\`; `;
+  const overrides = item.overrides.length > 0
+    ? `\n  - Overrides: ${item.overrides.map((id) => `\`${id}\``).join(", ")}`
+    : "";
+  return `- **${item.id}** — ${localizedStatement(item.statement, locale)}\n  - ${subject}Scope: \`${describeScope(item.scope)}\`; sources: ${sources}${overrides}\n  - Value (canonical JSON):\n\n    ${fence}json\n    ${value}\n    ${fence}`;
+}
+
+function groupedSections(sections) {
+  const groups = [];
+  const byItems = new Map();
+  for (const section of sections) {
+    const key = section.items.map((item) => item.id).join("\u0000");
+    let group = byItems.get(key);
+    if (!group) {
+      group = { paths: [], items: section.items };
+      byItems.set(key, group);
+      groups.push(group);
+    }
+    group.paths.push(section.path);
+  }
+  return groups;
+}
+
+function renderCollectedBundle(bundle, sources, task, options = {}) {
+  const locale = options.locale ?? "zh-CN";
+  const lines = [
+    "# Project Context Bundle",
+    "",
+    `Project: **${bundle.project.name}** (\`${bundle.project.id}\`)`,
+    `Contract digest: \`${bundle.contractDigest}\``,
+  ];
+  if (task !== undefined) {
+    const fence = fenceFor(task);
+    lines.push("", "## Task constraint", "", fence, String(task), fence);
+  }
+  for (const section of groupedSections(bundle.sections)) {
+    const targetLabel = section.paths.length === 1
+      ? `## Target: \`${section.paths[0]}\``
+      : `## Targets: ${section.paths.map((targetPath) => `\`${targetPath}\``).join(", ")}`;
+    lines.push("", targetLabel);
+    for (const [kind, title] of KIND_TITLES) {
+      const items = section.items.filter((item) => item.kind === kind);
+      if (items.length === 0) continue;
+      lines.push("", `### ${title}`, "", ...items.map((item) => renderItem(item, locale)));
+    }
+    if (section.items.length === 0) lines.push("", "No approved contract items apply.");
+  }
+  const sourceIds = [...new Set(bundle.sections.flatMap((section) => section.items.flatMap((item) => item.sources)))].sort();
+  lines.push("", "## Source index", "");
+  if (sourceIds.length === 0) {
+    lines.push("No sources selected.");
+  } else {
+    const sourceMap = new Map(sources.map((source) => [source.id, source]));
+    for (const id of sourceIds) {
+      const source = sourceMap.get(id);
+      const location = source?.path ?? source?.reference ?? "unknown";
+      lines.push(`- \`${id}\` — ${source?.kind ?? "unknown"}: \`${location}\``);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderContextBundle(contract, paths, task, options = {}) {
+  return renderCollectedBundle(collectBundle(contract, paths), contract.sources, task, options);
+}
+
+export function renderProjection(contract, paths, target) {
+  const bundle = collectBundle(contract, paths);
+  const body = renderCollectedBundle(bundle, contract.sources);
+  const bundleDigest = sha256(body);
+  const marker = `<!-- managed-by: project-context; renderer-version: ${RENDERER_VERSION}; target: ${target}; contract-digest: ${bundle.contractDigest}; bundle-digest: ${bundleDigest} -->`;
+  return {
+    content: `${marker}\n${body}`,
+    contractDigest: bundle.contractDigest,
+    bundleDigest,
+    itemIds: bundle.itemIds,
+    paths: bundle.paths,
+    rendererVersion: RENDERER_VERSION,
+  };
+}
+
+export function parseProjectionMarker(content) {
+  const first = String(content).split(/\r?\n/u, 1)[0];
+  const match = first.match(/^<!-- managed-by: project-context; renderer-version: (\d+); target: (agents|ruler); contract-digest: (sha256:[a-f0-9]{64}); bundle-digest: (sha256:[a-f0-9]{64}) -->$/u);
+  if (!match) return null;
+  return {
+    rendererVersion: Number(match[1]),
+    target: match[2],
+    contractDigest: match[3],
+    bundleDigest: match[4],
+  };
+}

package/src/project-context/scope-compiler.mjs

@@ -0,0 +1,132 @@
+import { canonicalJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+function scopePath(scope) {
+  return scope.kind === "project" ? "." : scope.path;
+}
+
+function withinPrefix(target, prefix) {
+  return target === prefix || target.startsWith(`${prefix}/`);
+}
+
+export function scopeApplies(scope, targetPath) {
+  const target = normalizeRelativePath(targetPath, { allowRoot: true, label: "target path" });
+  if (scope.kind === "project") return true;
+  if (scope.kind === "file") return target === scope.path;
+  return withinPrefix(target, scope.path);
+}
+
+export function scopeContains(outer, inner) {
+  if (outer.kind === "project") return true;
+  if (outer.kind === "file") return inner.kind === "file" && outer.path === inner.path;
+  if (inner.kind === "project") return false;
+  return withinPrefix(inner.path, outer.path);
+}
+
+export function scopesOverlap(left, right) {
+  return scopeContains(left, right) || scopeContains(right, left);
+}
+
+export function scopeSpecificity(scope) {
+  if (scope.kind === "project") return 0;
+  const segments = scope.path.split("/").length;
+  return segments * 2 + (scope.kind === "file" ? 1 : 0);
+}
+
+function overrideClosure(items) {
+  const byId = new Map(items.map((item) => [item.id, item]));
+  const memo = new Map();
+  const visiting = new Set();
+  function visit(id) {
+    if (memo.has(id)) return memo.get(id);
+    if (visiting.has(id)) fail("scope-override-cycle", `override cycle includes ${id}`);
+    visiting.add(id);
+    const item = byId.get(id);
+    const values = new Set(item?.overrides ?? []);
+    for (const direct of item?.overrides ?? []) {
+      for (const inherited of visit(direct)) values.add(inherited);
+    }
+    visiting.delete(id);
+    memo.set(id, values);
+    return values;
+  }
+  for (const item of items) visit(item.id);
+  return memo;
+}
+
+export function validateOverrides(items) {
+  const approved = items.filter((item) => item.status === "approved");
+  const byId = new Map(approved.map((item) => [item.id, item]));
+  const findings = [];
+  for (const item of approved) {
+    for (const targetId of item.overrides) {
+      const target = byId.get(targetId);
+      if (!target) {
+        findings.push({ code: "scope-override-invalid", item: item.id, target: targetId, reason: "missing-or-inactive" });
+      } else if (item.subject !== target.subject) {
+        findings.push({ code: "scope-override-invalid", item: item.id, target: targetId, reason: "subject-mismatch" });
+      } else if (!scopeContains(target.scope, item.scope)) {
+        findings.push({ code: "scope-override-invalid", item: item.id, target: targetId, reason: "target-is-narrower" });
+      }
+    }
+  }
+  try {
+    overrideClosure(approved);
+  } catch (error) {
+    findings.push({ code: error.code ?? "scope-override-cycle", message: error.message });
+  }
+  return findings;
+}
+
+export function findConflicts(items) {
+  const approved = items.filter((item) => item.status === "approved");
+  let closures;
+  try {
+    closures = overrideClosure(approved);
+  } catch (error) {
+    return [{ code: error.code ?? "scope-override-cycle", message: error.message }];
+  }
+  const findings = [];
+  for (let leftIndex = 0; leftIndex < approved.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < approved.length; rightIndex += 1) {
+      const left = approved[leftIndex];
+      const right = approved[rightIndex];
+      if (left.subject !== right.subject || !scopesOverlap(left.scope, right.scope)) continue;
+      if (canonicalJson(left.value) === canonicalJson(right.value)) continue;
+      if (closures.get(left.id)?.has(right.id) || closures.get(right.id)?.has(left.id)) continue;
+      findings.push({ code: "contract-conflict", subject: left.subject, items: [left.id, right.id] });
+    }
+  }
+  return findings;
+}
+
+export function effectiveItems(items, targetPath) {
+  const approved = items.filter((item) => item.status === "approved");
+  const applicable = approved.filter((item) => scopeApplies(item.scope, targetPath));
+  const closures = overrideClosure(approved);
+  const overridden = new Set();
+  for (const item of applicable) {
+    for (const target of closures.get(item.id) ?? []) overridden.add(target);
+  }
+  const effective = applicable.filter((item) => !overridden.has(item.id));
+  const conflicts = findConflicts(effective);
+  if (conflicts.length > 0) {
+    fail("contract-conflict", `contract has unresolved conflicts for ${targetPath}`, {
+      exitCode: 1,
+      details: { path: targetPath, findings: conflicts },
+    });
+  }
+  return effective.sort((left, right) => {
+    return (
+      left.kind.localeCompare(right.kind) ||
+      scopeSpecificity(left.scope) - scopeSpecificity(right.scope) ||
+      left.subject.localeCompare(right.subject) ||
+      left.id.localeCompare(right.id)
+    );
+  });
+}
+
+export function describeScope(scope) {
+  return scope.kind === "project" ? "project" : `${scope.kind}:${scopePath(scope)}`;
+}

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

@@ -0,0 +1,124 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { canonicalJson, sha256 } from "./canonical-json.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { resolveExistingInside } from "./path-policy.mjs";
+
+const DEFAULT_IGNORES = new Set([".git", ".project-context", "node_modules", "dist", "build", "coverage"]);
+
+export function decodeJsonPointer(pointer) {
+  if (pointer === "") return [];
+  if (typeof pointer !== "string" || !pointer.startsWith("/")) {
+    fail("json-pointer-invalid", "JSON pointer must be empty or start with '/'");
+  }
+  return pointer.slice(1).split("/").map((part) => {
+    if (/~(?:[^01]|$)/u.test(part)) fail("json-pointer-invalid", `JSON pointer contains an invalid escape: ${pointer}`);
+    return part.replaceAll("~1", "/").replaceAll("~0", "~");
+  });
+}
+
+export function readJsonPointer(value, pointer) {
+  let current = value;
+  for (const token of decodeJsonPointer(pointer)) {
+    const ownToken = current !== null &&
+      typeof current === "object" &&
+      (!Array.isArray(current) || /^(?:0|[1-9][0-9]*)$/u.test(token)) &&
+      Object.hasOwn(current, token);
+    if (!ownToken) {
+      fail("json-pointer-missing", `JSON pointer does not resolve: ${pointer}`);
+    }
+    current = current[token];
+  }
+  return current;
+}
+
+async function digestDirectory(absolute) {
+  const entries = [];
+  async function visit(directory, prefix) {
+    const children = (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const child of children) {
+      if (DEFAULT_IGNORES.has(child.name)) continue;
+      const relative = prefix ? `${prefix}/${child.name}` : child.name;
+      const full = path.join(directory, child.name);
+      if (child.isSymbolicLink()) {
+        entries.push([relative, "symlink"]);
+      } else if (child.isDirectory()) {
+        await visit(full, relative);
+      } else if (child.isFile()) {
+        entries.push([relative, sha256(await readFile(full))]);
+      }
+    }
+  }
+  await visit(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 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 readSourceDigest(projectRoot, source) {
+  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)));
+}
+
+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);
+}
+
+export async function verifyItem(projectRoot, item, sourceMap) {
+  const verification = item.verification;
+  if (!verification || verification.kind === "none") return null;
+  const source = sourceMap.get(verification.source);
+  if (!source) return { code: "verification-source-missing", item: item.id, source: verification.source };
+  if (verification.kind === "file-exists") {
+    try {
+      await resolveExistingInside(projectRoot, source.path);
+      return null;
+    } catch {
+      return { code: "verification-failed", item: item.id, source: source.id };
+    }
+  }
+  if (verification.kind === "json-value") {
+    if (source.kind !== "json-pointer") {
+      return { code: "verification-source-incompatible", item: item.id, source: source.id };
+    }
+    const actualValue = await readJsonSourceValue(projectRoot, source);
+    if (canonicalJson(actualValue) !== canonicalJson(verification.expected)) {
+      return { code: "verification-failed", item: item.id, source: source.id, expected: verification.expected, actual: actualValue };
+    }
+    return null;
+  }
+  if (verification.kind !== "path-digest") {
+    return { code: "verification-kind-unsupported", item: item.id, source: source.id };
+  }
+  const actual = await digestPath(projectRoot, source.path);
+  const expected = verification.expected ?? source.digest;
+  if (actual !== expected) return { code: "verification-failed", item: item.id, source: source.id, expected, actual };
+  return null;
+}
+
+export { DEFAULT_IGNORES };