frontend-project-context 1.0.0

package/src/project-context/authoring.mjs

@@ -0,0 +1,190 @@
+import { canonicalJson } from "./canonical-json.mjs";
+import {
+  sourceForContract,
+  sourceRegistrationShape,
+  sourceStatus,
+  validateItem,
+  validateProposal,
+  validateSource,
+  validateSourceLock,
+  validateContract,
+} from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+import { writeProjectState } from "./project-store.mjs";
+import { readSourceDigest } from "./source-reader.mjs";
+import { validateOverrides } from "./scope-compiler.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const REFERENCE_SOURCE_KINDS = new Set(["human-decision", "external-reference"]);
+const VERIFICATION_KINDS = new Set(["none", "file-exists", "json-value", "path-digest"]);
+
+function has(value) {
+  return value !== undefined;
+}
+
+function sourceLocator(source) {
+  return canonicalJson({
+    kind: source.kind,
+    ...(source.path !== undefined ? { path: source.path } : {}),
+    ...(source.pointer !== undefined ? { pointer: source.pointer } : {}),
+    ...(source.reference !== undefined ? { reference: source.reference } : {}),
+  });
+}
+
+export async function buildRegisteredSource(root, input) {
+  const { id, kind, path: sourcePath, pointer, reference } = input;
+  let source;
+  if (LOCAL_SOURCE_KINDS.has(kind)) {
+    if (!has(sourcePath) || has(reference) || (kind === "json-pointer" ? !has(pointer) : has(pointer))) {
+      fail("argument-conflict", `${kind} source requires the documented path/pointer arguments`, { details: { source: id } });
+    }
+    source = {
+      id,
+      kind,
+      path: normalizeRelativePath(sourcePath, { label: "source path" }),
+      ...(kind === "json-pointer" ? { pointer } : {}),
+    };
+    source.digest = await readSourceDigest(root, source);
+  } else if (REFERENCE_SOURCE_KINDS.has(kind)) {
+    if (!has(reference) || has(sourcePath) || has(pointer)) {
+      fail("argument-conflict", `${kind} source requires only --reference`, { details: { source: id } });
+    }
+    source = { id, kind, reference };
+  } else {
+    fail("schema-invalid-enum", `source kind is invalid: ${kind}`, { details: { source: id } });
+  }
+  return validateSource(source);
+}
+
+export async function registerSource(root, project, input, options = {}) {
+  const source = await buildRegisteredSource(root, input);
+  const existingById = project.contract.sources.find((entry) => entry.id === source.id);
+  if (existingById) {
+    if (sourceStatus(existingById) === "deprecated" || canonicalJson(sourceRegistrationShape(existingById)) !== canonicalJson(source)) {
+      fail("source-id-conflict", `source ID conflicts with contract: ${source.id}`, { details: { source: source.id } });
+    }
+    return { action: "unchanged", source: structuredClone(existingById), written: false };
+  }
+  const locator = sourceLocator(source);
+  const existingByLocation = project.contract.sources.find((entry) =>
+    sourceStatus(entry) === "active" && sourceLocator(entry) === locator,
+  );
+  if (existingByLocation) {
+    fail("source-location-conflict", `source location is already registered as ${existingByLocation.id}`, {
+      details: { source: source.id, existing: existingByLocation.id },
+    });
+  }
+
+  const nextContract = structuredClone(project.contract);
+  const storedSource = sourceForContract(source, nextContract.schemaVersion);
+  nextContract.sources.push(storedSource);
+  nextContract.sources.sort((left, right) => left.id.localeCompare(right.id));
+  validateContract(nextContract);
+
+  const locks = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  if (typeof source.digest === "string") locks.set(source.id, source.digest);
+  const nextSourcesLock = validateSourceLock({
+    schemaVersion: 1,
+    sources: [...locks].map(([id, digest]) => ({ id, digest })).sort((left, right) => left.id.localeCompare(right.id)),
+  });
+
+  if (options.write) {
+    if (LOCAL_SOURCE_KINDS.has(source.kind)) {
+      const actual = await readSourceDigest(root, source);
+      if (actual !== source.digest) {
+        fail("source-changed-during-register", `source changed while registration was being prepared: ${source.id}`, {
+          exitCode: 1,
+          details: { source: source.id, expected: source.digest, actual },
+        });
+      }
+    }
+    await writeProjectState(project, nextContract, nextSourcesLock);
+  }
+  return { action: "create", source: storedSource, written: Boolean(options.write) };
+}
+
+function buildScope(kind, scopePath) {
+  if (kind === "project") {
+    if (has(scopePath)) fail("argument-conflict", "project scope does not accept --scope-path");
+    return { kind: "project" };
+  }
+  if (kind !== "path-prefix" && kind !== "file") fail("schema-invalid-enum", `scope kind is invalid: ${kind}`);
+  if (!has(scopePath)) fail("argument-missing", `--scope-path is required for ${kind} scope`);
+  return { kind, path: normalizeRelativePath(scopePath, { label: "scope path" }) };
+}
+
+function buildVerification(input) {
+  const kind = input.verification;
+  const source = input.verificationSource;
+  const expectedPresent = input.verificationExpectedPresent;
+  if (!has(kind)) {
+    if (has(source) || expectedPresent) fail("argument-conflict", "verification details require --verification");
+    return undefined;
+  }
+  if (!VERIFICATION_KINDS.has(kind)) fail("schema-invalid-enum", `verification kind is invalid: ${kind}`);
+  if (kind === "none") {
+    if (has(source) || expectedPresent) fail("argument-conflict", "none verification does not accept source or expected value");
+    return { kind };
+  }
+  if (!has(source)) fail("argument-missing", `--verification-source is required for ${kind}`);
+  if (kind === "file-exists" && expectedPresent) fail("argument-conflict", "file-exists verification does not accept expected value");
+  if (kind === "json-value" && !expectedPresent) fail("argument-missing", "--verification-expected-json is required for json-value");
+  return { kind, source, ...(expectedPresent ? { expected: input.verificationExpected } : {}) };
+}
+
+export function buildItemProposal(project, input) {
+  if (project.contract.items.some((entry) => entry.id === input.id)) {
+    fail("item-id-conflict", `item ID already exists in contract: ${input.id}`, { details: { item: input.id } });
+  }
+  const sourceIds = [...new Set(input.sources)];
+  if (sourceIds.length !== input.sources.length) fail("schema-duplicate", "--sources contains duplicate IDs");
+  const sourceMap = new Map(project.contract.sources.map((source) => [source.id, source]));
+  for (const sourceId of sourceIds) {
+    const source = sourceMap.get(sourceId);
+    if (!source) {
+      fail("source-reference-missing", `item references unknown source: ${sourceId}`, { details: { item: input.id, source: sourceId } });
+    }
+    if (sourceStatus(source) === "deprecated") {
+      fail("source-reference-deprecated", `item references deprecated source: ${sourceId}`, {
+        details: { item: input.id, source: sourceId },
+      });
+    }
+  }
+  const verification = buildVerification(input);
+  if (verification?.source && !sourceIds.includes(verification.source)) {
+    fail("source-reference-missing", "verification source must be included in --sources", {
+      details: { item: input.id, source: verification.source },
+    });
+  }
+  const item = {
+    id: input.id,
+    kind: input.kind,
+    subject: input.subject,
+    value: input.value,
+    statement: input.statement,
+    scope: buildScope(input.scope, input.scopePath),
+    status: "proposed",
+    sources: sourceIds,
+    overrides: input.overrides ?? [],
+    ...(verification ? { verification } : {}),
+  };
+  validateItem(item, "proposal item", { proposal: true });
+
+  if (item.overrides.length > 0) {
+    const hypothetical = { ...structuredClone(item), status: "approved", approval: { by: "proposal-preflight", at: "1970-01-01T00:00:00.000Z" } };
+    const findings = validateOverrides([...project.contract.items, hypothetical]);
+    if (findings.length > 0) {
+      fail("approval-preflight-failed", "proposed overrides are invalid", { exitCode: 1, details: { item: item.id, findings } });
+    }
+  }
+
+  return validateProposal({
+    schemaVersion: 1,
+    projectId: project.contract.project.id,
+    sources: sourceIds
+      .map((id) => sourceRegistrationShape(sourceMap.get(id)))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    items: [item],
+  });
+}

package/src/project-context/canonical-json.mjs

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+
+function assertJsonCompatible(value, ancestors) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("canonical JSON requires finite numbers");
+    return;
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(`canonical JSON does not support ${typeof value}`);
+  }
+  if (ancestors.has(value)) throw new TypeError("canonical JSON does not support cyclic values");
+  ancestors.add(value);
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length) throw new TypeError("canonical JSON does not support sparse arrays");
+    value.forEach((entry) => assertJsonCompatible(entry, ancestors));
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("canonical JSON requires plain objects");
+    }
+    Object.values(value).forEach((entry) => assertJsonCompatible(entry, ancestors));
+  }
+  ancestors.delete(value);
+}
+
+export function validateJsonValue(value) {
+  assertJsonCompatible(value, new WeakSet());
+  return value;
+}
+
+export function canonicalValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalValue(value[key])]));
+  }
+  return value;
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+
+export function prettyCanonicalJson(value) {
+  return `${JSON.stringify(canonicalValue(value), null, 2)}\n`;
+}
+
+export function sha256(value) {
+  const input = Buffer.isBuffer(value) ? value : Buffer.from(String(value));
+  return `sha256:${createHash("sha256").update(input).digest("hex")}`;
+}
+
+export function digestJson(value) {
+  return sha256(canonicalJson(value));
+}

package/src/project-context/checker.mjs

@@ -0,0 +1,132 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { sha256 } from "./canonical-json.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { readSourceDigest, verifyItem } from "./source-reader.mjs";
+import { findConflicts, validateOverrides } from "./scope-compiler.mjs";
+import { parseProjectionMarker, RENDERER_VERSION, renderProjection } from "./renderer.mjs";
+import { resolveWritableInside } from "./path-policy.mjs";
+
+export async function checkProject(root, project) {
+  const findings = [];
+  const contractSourceIds = new Set(project.contract.sources.map((source) => source.id));
+  const sourceLock = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  for (const source of project.contract.sources) {
+    if (sourceStatus(source) === "deprecated") continue;
+    if (source.kind === "human-decision" || source.kind === "external-reference") continue;
+    const locked = sourceLock.get(source.id);
+    if (!locked) {
+      findings.push({ code: "source-lock-missing", source: source.id, path: source.path });
+      continue;
+    }
+    if (locked !== source.digest) {
+      findings.push({ code: "source-lock-mismatch", source: source.id, path: source.path });
+      continue;
+    }
+    try {
+      const actual = await readSourceDigest(root, source);
+      if (actual !== locked) findings.push({ code: "source-changed", source: source.id, path: source.path, expected: locked, actual });
+    } catch (error) {
+      const code = error.code === "source-missing"
+        ? "source-missing"
+        : error.code === "json-pointer-missing"
+          ? "source-changed"
+          : "source-unreadable";
+      findings.push({ code, source: source.id, path: source.path });
+    }
+  }
+  const contractSources = new Map(project.contract.sources.map((source) => [source.id, source]));
+  for (const entry of project.sourcesLock.sources) {
+    if (!contractSourceIds.has(entry.id)) {
+      findings.push({ code: "source-lock-orphan", source: entry.id });
+    } else if (sourceStatus(contractSources.get(entry.id)) === "deprecated") {
+      findings.push({ code: "source-lock-deprecated", source: entry.id });
+    }
+  }
+  for (const item of project.contract.items.filter((candidate) => candidate.status === "proposed")) {
+    findings.push({ code: "item-approval-pending", item: item.id });
+  }
+  findings.push(...validateOverrides(project.contract.items), ...findConflicts(project.contract.items));
+  const sourceMap = new Map(project.contract.sources.map((source) => [source.id, source]));
+  for (const item of project.contract.items.filter((candidate) => candidate.status === "approved")) {
+    try {
+      const verification = await verifyItem(root, item, sourceMap);
+      if (verification) findings.push(verification);
+    } catch (error) {
+      findings.push({
+        code: "verification-failed",
+        item: item.id,
+        source: item.verification?.source,
+        reason: error.code ?? "unreadable",
+      });
+    }
+  }
+  const itemIds = new Set(project.contract.items.map((item) => item.id));
+  for (const entry of project.projectionsLock.projections) {
+    let resolved;
+    try {
+      resolved = await resolveWritableInside(root, entry.path);
+    } catch (error) {
+      findings.push({ code: "projection-path-invalid", path: entry.path, message: error.message });
+      continue;
+    }
+    let content;
+    try {
+      content = await readFile(resolved.absolute, "utf8");
+    } catch (error) {
+      findings.push({ code: error?.code === "ENOENT" ? "projection-missing" : "projection-unreadable", path: entry.path });
+      continue;
+    }
+    const marker = parseProjectionMarker(content);
+    if (!marker) {
+      findings.push({ code: "projection-ownership-conflict", path: entry.path });
+      continue;
+    }
+    if (sha256(content) !== entry.contentDigest) {
+      findings.push({ code: "projection-ownership-conflict", path: entry.path });
+      continue;
+    }
+    if (marker.target !== entry.target || marker.rendererVersion !== entry.rendererVersion) {
+      findings.push({ code: "projection-ownership-conflict", path: entry.path });
+      continue;
+    }
+    if (entry.rendererVersion !== RENDERER_VERSION) {
+      findings.push({ code: "projection-renderer-stale", path: entry.path, expected: RENDERER_VERSION, actual: entry.rendererVersion });
+      continue;
+    }
+    if (entry.contractDigest !== project.contractDigest || marker.contractDigest !== project.contractDigest) {
+      findings.push({ code: "projection-stale", path: entry.path });
+      continue;
+    }
+    if (entry.itemIds.some((id) => !itemIds.has(id))) {
+      findings.push({ code: "projection-item-missing", path: entry.path });
+      continue;
+    }
+    const expected = renderProjection(project.contract, entry.paths, entry.target);
+    if (expected.content !== content || expected.bundleDigest !== entry.bundleDigest) {
+      findings.push({ code: "projection-diverged", path: entry.path });
+    }
+  }
+  return findings.sort((left, right) => {
+    return left.code.localeCompare(right.code) || String(left.path ?? left.source ?? left.item ?? "").localeCompare(String(right.path ?? right.source ?? right.item ?? ""));
+  });
+}
+
+export function checkExitCode(findings) {
+  return findings.some((finding) => finding.code === "projection-ownership-conflict") ? 3 : findings.length > 0 ? 1 : 0;
+}
+
+export function blockingContextFindings(findings) {
+  return findings.filter((finding) =>
+    finding.code.startsWith("source-") ||
+    finding.code === "item-approval-pending" ||
+    finding.code.startsWith("scope-") ||
+    finding.code === "contract-conflict" ||
+    finding.code.startsWith("verification-"),
+  );
+}
+
+export function findingSeverity(finding) {
+  if (finding.code === "projection-ownership-conflict") return "conflict";
+  return blockingContextFindings([finding]).length > 0 ? "blocked" : "attention";
+}