codex-context-map 0.1.0

package/src/report.js

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+import { validateSnapshot } from "./core.js";
+
+export async function renderReport(snapshot, { demo = false } = {}) {
+  snapshot = validateSnapshot(snapshot);
+  const read = (relative) =>
+    readFile(new URL(relative, import.meta.url), "utf8");
+  const [template, css, core, demoSource, app] = await Promise.all([
+    read("../site/template.html"),
+    read("../site/style.css"),
+    read("./core.js"),
+    read("./demo.js"),
+    read("../site/app.js"),
+  ]);
+  const moduleBody = (text) =>
+    text.replace(/^import .*;\r?\n/gm, "").replace(/^export /gm, "");
+  const data = JSON.stringify({ snapshot, demo })
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  const script = `${moduleBody(core)}\n${moduleBody(demoSource)}\nconst initialData = ${data};\n${app}`;
+  return template
+    .replace("/* STYLE */", () => css)
+    .replace("/* SCRIPT */", () => script);
+}

package/src/scan.js

@@ -0,0 +1,170 @@
+import { readdir, lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import {
+  candidateNames,
+  validateSnapshot,
+  MAX_BUDGET,
+  MAX_FILES,
+  MAX_DIRECTORIES,
+  MAX_SNAPSHOT_BYTES,
+  DEFAULT_BUDGET,
+} from "./core.js";
+
+export const SKIP_DIRECTORIES = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".next",
+  ".nuxt",
+  "coverage",
+  "dist",
+  "build",
+  "target",
+  "vendor",
+  ".codex-context-map",
+  ".artifacts",
+]);
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const posix = (value) => value.split(path.sep).join("/") || ".";
+
+async function exists(file) {
+  try {
+    await lstat(file);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function findProjectRoot(directory) {
+  let current = directory;
+  while (true) {
+    if (await exists(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return directory;
+    current = parent;
+  }
+}
+
+export async function scanProject(target = ".", options = {}) {
+  let cwd = await realpath(path.resolve(target));
+  if (!(await lstat(cwd)).isDirectory()) cwd = path.dirname(cwd);
+  const root = options.root
+    ? await realpath(path.resolve(options.root))
+    : await findProjectRoot(cwd);
+  if (!(await lstat(root)).isDirectory())
+    throw new Error("Project root must be a directory.");
+  const relative = path.relative(root, cwd);
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  )
+    throw new Error("Target must be inside --root.");
+  const settings = {
+    maxBytes: options.maxBytes ?? DEFAULT_BUDGET,
+    fallbackNames: options.fallbackNames ?? [],
+  };
+  const names = candidateNames(settings.fallbackNames);
+  const files = [],
+    directories = [],
+    projectRoots = [],
+    warnings = [];
+  let totalBytes = 0;
+  const warn = (message) => {
+    if (warnings.length < 100) warnings.push(message);
+  };
+
+  async function readInstruction(absolute, relativePath, scope = "project") {
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink()) {
+      warn(`Skipped symlink: ${relativePath}. Codex may follow it.`);
+      return;
+    }
+    if (!info.isFile()) return;
+    if (info.size > MAX_BUDGET)
+      throw new Error(`Instruction file exceeds 1 MiB: ${relativePath}`);
+    if (
+      totalBytes + info.size > MAX_SNAPSHOT_BYTES ||
+      files.length >= MAX_FILES
+    )
+      throw new Error("Scan exceeds the snapshot size or file limit.");
+    const raw = await readFile(absolute);
+    totalBytes += raw.length;
+    if (totalBytes > MAX_SNAPSHOT_BYTES || raw.length > MAX_BUDGET)
+      throw new Error("Scan exceeds the instruction size limit.");
+    let content;
+    try {
+      content = utf8.decode(raw);
+    } catch {
+      throw new Error(`Instruction file is not valid UTF-8: ${relativePath}`);
+    }
+    files.push({ path: relativePath, scope, content });
+  }
+
+  async function walk(absolute, dir = ".", depth = 0) {
+    if (depth > 64 || directories.length >= MAX_DIRECTORIES)
+      throw new Error(
+        "Scan exceeds the directory or depth limit. Choose a smaller --root.",
+      );
+    directories.push(dir);
+    const entries = await readdir(absolute, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name, "en"));
+    if (entries.some((e) => e.name === ".git") || (dir === "." && options.root))
+      projectRoots.push(dir);
+    for (const name of names) {
+      if (entries.some((e) => e.name === name)) {
+        await readInstruction(
+          path.join(absolute, name),
+          dir === "." ? name : `${dir}/${name}`,
+        );
+      }
+    }
+    for (const entry of entries) {
+      const child = dir === "." ? entry.name : `${dir}/${entry.name}`;
+      if (entry.isSymbolicLink()) {
+        if (!names.includes(entry.name)) warn(`Skipped symlink: ${child}.`);
+        continue;
+      }
+      if (!entry.isDirectory() || entry.name === ".git") continue;
+      // Still traverse the requested directory and its ancestors if usually excluded.
+      const selected = posix(relative);
+      const onTarget = selected === child || selected.startsWith(`${child}/`);
+      if (
+        !options.includeIgnored &&
+        SKIP_DIRECTORIES.has(entry.name) &&
+        !onTarget
+      )
+        continue;
+      await walk(path.join(absolute, entry.name), child, depth + 1);
+    }
+  }
+  await walk(root);
+  if (options.global) {
+    const codexDir = path.resolve(
+      options.codexHome ??
+        process.env.CODEX_HOME ??
+        path.join(os.homedir(), ".codex"),
+    );
+    for (const name of ["AGENTS.override.md", "AGENTS.md"]) {
+      const file = path.join(codexDir, name);
+      if (await exists(file)) await readInstruction(file, name, "global");
+    }
+  }
+  return validateSnapshot({
+    schemaVersion: 1,
+    projectName: path.basename(root),
+    defaultTarget: posix(relative),
+    settings,
+    files,
+    directories,
+    projectRoots,
+    warnings,
+  });
+}