frontend-project-context 1.0.0

package/src/project-context/discovery.mjs

@@ -0,0 +1,251 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { sha256 } from "./canonical-json.mjs";
+import { sourceRegistrationShape, sourceStatus } from "./contract-schema.mjs";
+import { DEFAULT_IGNORES, digestPath, digestPathIdentity, readSourceDigest } from "./source-reader.mjs";
+
+const CONFIG_FILES = [
+  "tsconfig.json",
+  "eslint.config.js",
+  "eslint.config.mjs",
+  ".eslintrc",
+  ".eslintrc.json",
+  ".prettierrc",
+  ".prettierrc.json",
+  "vite.config.js",
+  "vite.config.ts",
+  "vitest.config.js",
+  "vitest.config.ts",
+  "jest.config.js",
+  "jest.config.ts",
+  "playwright.config.js",
+  "playwright.config.ts",
+];
+const TOOL_DEPENDENCIES = ["react", "vue", "next", "nuxt", "vite", "typescript", "eslint", "prettier", "vitest", "jest", "@playwright/test"];
+
+function slug(value) {
+  return value
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/gu, "-")
+    .replaceAll(/^-+|-+$/gu, "") || "root";
+}
+
+function generatedId(prefix, value) {
+  return `${prefix}-${slug(value)}-${sha256(value).slice(7, 15)}`;
+}
+
+async function fileOrNull(filePath) {
+  try {
+    return await readFile(filePath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function discoverRuleFiles(root) {
+  const results = [];
+  async function visit(directory, prefix, depth) {
+    if (depth > 8) return;
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (DEFAULT_IGNORES.has(entry.name)) continue;
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        await visit(path.join(directory, entry.name), relative, depth + 1);
+      } else if (entry.isFile()) {
+        const basename = entry.name.toLowerCase();
+        const inKnownDirectory = relative.startsWith(".kiro/steering/") || relative.startsWith(".ruler/");
+        if (basename === "agents.md" || basename === "claude.md" || (inKnownDirectory && basename.endsWith(".md"))) {
+          results.push(relative);
+        }
+      }
+    }
+  }
+  await visit(root, "", 0);
+  return results;
+}
+
+async function discoverTopLevelDirectories(root) {
+  const entries = (await readdir(root, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink() && !entry.name.startsWith(".") && !DEFAULT_IGNORES.has(entry.name))
+    .map((entry) => entry.name);
+}
+
+function ruleAliasTarget(relative, contents) {
+  const match = contents.trim().match(/^@([^\s]+)$/u);
+  if (!match) return null;
+  const rawTarget = match[1].replaceAll("\\", "/");
+  if (path.posix.isAbsolute(rawTarget)) return null;
+  const target = path.posix.normalize(path.posix.join(path.posix.dirname(relative), rawTarget));
+  if (target === "." || target.startsWith("../")) return null;
+  return target;
+}
+
+function aliasesWithConcreteTargets(aliasTargets, knownPaths) {
+  const result = new Set();
+  for (const start of aliasTargets.keys()) {
+    const seen = new Set();
+    let current = start;
+    while (aliasTargets.has(current) && !seen.has(current)) {
+      seen.add(current);
+      current = aliasTargets.get(current);
+    }
+    if (!seen.has(current) && knownPaths.has(current)) result.add(start);
+  }
+  return result;
+}
+
+function proposalItem({ id, kind = "fact", subject, value, statement, source, scope = { kind: "project" } }) {
+  return {
+    id,
+    kind,
+    subject,
+    value,
+    statement,
+    scope,
+    status: "proposed",
+    sources: [source],
+    overrides: [],
+  };
+}
+
+export async function discoverProject(root, contract) {
+  const sources = [];
+  const items = [];
+  const addFileSource = async (relative) => {
+    const id = generatedId("source", relative);
+    if (!sources.some((source) => source.id === id)) {
+      sources.push({ id, kind: "file", path: relative, digest: await digestPath(root, relative) });
+    }
+    return id;
+  };
+  const addPathSource = async (relative) => {
+    const id = generatedId("source-path", relative);
+    if (!sources.some((source) => source.id === id)) {
+      sources.push({ id, kind: "path", path: relative, digest: await digestPathIdentity(root, relative) });
+    }
+    return id;
+  };
+  const packageBytes = await fileOrNull(path.join(root, "package.json"));
+  if (packageBytes) {
+    const source = await addFileSource("package.json");
+    let packageJson;
+    try {
+      packageJson = JSON.parse(packageBytes.toString("utf8"));
+    } catch {
+      packageJson = null;
+    }
+    if (packageJson) {
+      if (typeof packageJson.packageManager === "string") {
+        items.push(proposalItem({
+          id: "fact-package-manager",
+          subject: "project.package-manager",
+          value: packageJson.packageManager,
+          statement: `The project declares package manager ${packageJson.packageManager}.`,
+          source,
+        }));
+      }
+      for (const name of Object.keys(packageJson.scripts ?? {}).sort()) {
+        const scriptId = generatedId("script", name);
+        items.push(proposalItem({
+          id: `fact-${scriptId}`,
+          subject: `project.${scriptId.replaceAll("-", ".")}`,
+          value: packageJson.scripts[name],
+          statement: `The project declares the ${name} script.`,
+          source,
+        }));
+      }
+      const dependencies = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
+      for (const name of TOOL_DEPENDENCIES) {
+        if (!(name in dependencies)) continue;
+        const dependencyId = generatedId("dependency", name);
+        items.push(proposalItem({
+          id: `fact-${dependencyId}`,
+          subject: `project.${dependencyId.replaceAll("-", ".")}`,
+          value: dependencies[name],
+          statement: `The project declares ${name} as a dependency.`,
+          source,
+        }));
+      }
+    }
+  }
+  for (const relative of CONFIG_FILES) {
+    if (!(await fileOrNull(path.join(root, relative)))) continue;
+    const source = await addFileSource(relative);
+    const configId = generatedId("config", relative);
+    items.push(proposalItem({
+      id: `fact-${configId}`,
+      subject: `project.${configId.replaceAll("-", ".")}`,
+      value: true,
+      statement: `The project contains ${relative}.`,
+      source,
+    }));
+  }
+  for (const relative of await discoverTopLevelDirectories(root)) {
+    const source = await addPathSource(relative);
+    items.push(proposalItem({
+      id: `fact-${generatedId("top-level-directory", relative)}`,
+      subject: "project.structure.top-level-directory",
+      value: relative,
+      statement: `The project contains the top-level directory ${relative}.`,
+      source,
+      scope: { kind: "path-prefix", path: relative },
+    }));
+  }
+  const rulePaths = await discoverRuleFiles(root);
+  const ruleContents = new Map();
+  for (const relative of rulePaths) {
+    const contents = await readFile(path.join(root, relative), "utf8");
+    if (!contents.startsWith("<!-- managed-by: project-context;")) ruleContents.set(relative, contents);
+  }
+  const knownRulePaths = new Set(ruleContents.keys());
+  const aliasTargets = new Map();
+  for (const [relative, contents] of ruleContents) {
+    const target = ruleAliasTarget(relative, contents);
+    if (target) aliasTargets.set(relative, target);
+  }
+  const redundantAliases = aliasesWithConcreteTargets(aliasTargets, knownRulePaths);
+  for (const [relative] of ruleContents) {
+    if (redundantAliases.has(relative)) continue;
+    const source = await addFileSource(relative);
+    items.push(proposalItem({
+      id: generatedId("reference-agent-rules", relative),
+      kind: "reference",
+      subject: `agent-rules.${slug(relative)}`,
+      value: relative,
+      statement: `Review the existing Agent instruction source at ${relative}.`,
+      source,
+      scope: relative.includes("/") && !relative.startsWith(".")
+        ? { kind: "path-prefix", path: path.posix.dirname(relative) }
+        : { kind: "project" },
+    }));
+  }
+  for (const source of contract.sources) {
+    if (sourceStatus(source) === "deprecated") continue;
+    if (contract.items.some((entry) => entry.sources.includes(source.id))) continue;
+    if (source.kind === "human-decision") continue;
+    try {
+      const registration = sourceRegistrationShape(source);
+      const current = source.kind === "external-reference"
+        ? registration
+        : { ...registration, digest: await readSourceDigest(root, source) };
+      if (!sources.some((entry) => entry.id === current.id)) sources.push(current);
+      items.push(proposalItem({
+        id: generatedId("reference-registered", source.id),
+        kind: "reference",
+        subject: `registered-source.${source.id.replaceAll("-", ".")}`,
+        value: source.path ?? source.reference,
+        statement: `Review the explicitly registered project source ${source.id}.`,
+        source: source.id,
+      }));
+    } catch {
+      // Existing contract drift is reported by check; discovery remains deterministic and best-effort.
+    }
+  }
+  sources.sort((left, right) => left.id.localeCompare(right.id));
+  items.sort((left, right) => left.id.localeCompare(right.id));
+  return { schemaVersion: 1, projectId: contract.project.id, sources, items };
+}

package/src/project-context/errors.mjs

@@ -0,0 +1,13 @@
+export class ProjectContextError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = "ProjectContextError";
+    this.code = code;
+    this.exitCode = options.exitCode ?? 2;
+    this.details = options.details ?? {};
+  }
+}
+
+export function fail(code, message, options) {
+  throw new ProjectContextError(code, message, options);
+}

package/src/project-context/io.mjs

@@ -0,0 +1,93 @@
+import { link, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { prettyCanonicalJson } from "./canonical-json.mjs";
+import { ProjectContextError, fail } from "./errors.mjs";
+
+export async function readJsonFile(filePath, label = path.basename(filePath)) {
+  let source;
+  try {
+    source = await readFile(filePath, "utf8");
+  } catch (error) {
+    fail("file-read-failed", `cannot read ${label}`, { cause: error, details: { path: filePath } });
+  }
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    fail("json-invalid", `${label} contains invalid JSON`, { cause: error, details: { path: filePath } });
+  }
+}
+
+export async function atomicWriteFile(filePath, content) {
+  const directory = path.dirname(filePath);
+  const temporary = path.join(
+    directory,
+    `.${path.basename(filePath)}.project-context-${process.pid}-${randomBytes(6).toString("hex")}.tmp`,
+  );
+  try {
+    await writeFile(temporary, content, { flag: "wx" });
+    await rename(temporary, filePath);
+  } catch (error) {
+    try {
+      await unlink(temporary);
+    } catch {
+      // The temporary file may not have been created or may already have been renamed.
+    }
+    if (error instanceof ProjectContextError) throw error;
+    fail("atomic-write-failed", `failed to atomically write ${filePath}`, {
+      cause: error,
+      exitCode: 2,
+      details: { path: filePath },
+    });
+  }
+}
+
+export async function atomicWriteJson(filePath, value) {
+  await atomicWriteFile(filePath, prettyCanonicalJson(value));
+}
+
+export async function atomicCreateFileOrSame(filePath, content) {
+  try {
+    const existing = await readFile(filePath, "utf8");
+    if (existing === content) return "unchanged";
+    fail("proposal-output-conflict", `refusing to overwrite existing proposal output: ${filePath}`, {
+      details: { path: filePath },
+    });
+  } catch (error) {
+    if (error instanceof ProjectContextError) throw error;
+    if (error?.code !== "ENOENT") {
+      fail("file-read-failed", `cannot inspect proposal output: ${filePath}`, { cause: error, details: { path: filePath } });
+    }
+  }
+
+  const directory = path.dirname(filePath);
+  const temporary = path.join(
+    directory,
+    `.${path.basename(filePath)}.project-context-${process.pid}-${randomBytes(6).toString("hex")}.tmp`,
+  );
+  try {
+    await writeFile(temporary, content, { flag: "wx" });
+    await link(temporary, filePath);
+    await unlink(temporary);
+    return "create";
+  } catch (error) {
+    try {
+      await unlink(temporary);
+    } catch {
+      // The temporary file may not have been created or may already have been removed.
+    }
+    if (error?.code === "EEXIST") {
+      const existing = await readFile(filePath, "utf8");
+      if (existing === content) return "unchanged";
+      fail("proposal-output-conflict", `refusing to overwrite existing proposal output: ${filePath}`, {
+        details: { path: filePath },
+      });
+    }
+    if (error instanceof ProjectContextError) throw error;
+    fail("atomic-write-failed", `failed to atomically create ${filePath}`, {
+      cause: error,
+      exitCode: 2,
+      details: { path: filePath },
+    });
+  }
+}