@andares/pi-toolkits 0.9.8 → 0.11.0

package/src/features/init/detect.ts

@@ -0,0 +1,808 @@
+/**
+ * init feature — read-only survey of a project.
+ *
+ * Everything here is a fact read from disk, with no judgement: the plan and the
+ * audit decide what those facts mean. Two rules shape the code:
+ *
+ *  1. **Bounded** — the survey must never stall the command on a huge repo, so
+ *     the walk is capped, ignored dirs are explicit, and oversized files are
+ *     read for headings only.
+ *  2. **Reproducible** — the reference scan used for "N occurrences in M files"
+ *     is the same predicate the rewrite uses. Counts and edits can therefore be
+ *     reconciled instead of trusted.
+ */
+import { execFileSync } from "node:child_process";
+import {
+	existsSync,
+	readFileSync,
+	readdirSync,
+	statSync,
+} from "node:fs";
+import { join, posix, relative, sep } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import {
+	AGENTS_DIR,
+	DEPRECATED_ROOT_DIRS,
+	FRAMEWORK_DIR,
+	FRAMEWORK_VERSION,
+	IMPLEMENTATIONS_DIR,
+	LEGACY_DOC_NAMES,
+	MEMORY_DIR,
+	OVERRIDE_FILE,
+	PROMPTS_DIR,
+	RETIRED_ROOT_DIRS,
+	SCAN,
+	SPECS_DIR,
+	STATE_FILE,
+	isMemoryFileName,
+	type ProjectLanguage,
+} from "./spec.js";
+import type {
+	DocInfo,
+	Facts,
+	FileInfo,
+	FrameworkState,
+	Heading,
+	ProjectFacts,
+	RefArea,
+	RefScan,
+	RootInfo,
+} from "./types.js";
+
+/* -------------------------------------------------------------------------- */
+/* Small filesystem helpers                                                    */
+/* -------------------------------------------------------------------------- */
+
+function toPosix(path: string): string {
+	return sep === "/" ? path : path.split(sep).join("/");
+}
+
+export function statFile(root: string, rel: string): FileInfo | undefined {
+	try {
+		const absolute = join(root, rel);
+		const stat = statSync(absolute);
+		if (!stat.isFile()) return undefined;
+		let lines = 0;
+		if (stat.size <= SCAN.maxFileBytes) {
+			const text = readFileSync(absolute, "utf8");
+			lines = countLines(text);
+		}
+		return { rel, bytes: stat.size, lines, mtimeMs: stat.mtimeMs };
+	} catch {
+		return undefined;
+	}
+}
+
+function countLines(text: string): number {
+	if (text.length === 0) return 0;
+	let lines = 1;
+	for (let i = 0; i < text.length; i += 1) {
+		if (text.charCodeAt(i) === 10) lines += 1;
+	}
+	return lines;
+}
+
+export function readTextFile(root: string, rel: string): string | undefined {
+	try {
+		const absolute = join(root, rel);
+		const stat = statSync(absolute);
+		if (!stat.isFile()) return undefined;
+		const buffer = readFileSync(absolute);
+		// Binary check: a NUL in the first 8 KiB is enough to classify.
+		const probe = buffer.subarray(0, 8192);
+		if (probe.includes(0)) return undefined;
+		const limit = SCAN.maxFileBytes;
+		const text =
+			buffer.length > limit
+				? buffer.subarray(0, limit).toString("utf8")
+				: buffer.toString("utf8");
+		return text;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Headings outside fenced code blocks, with 1-based line numbers. */
+export function parseHeadings(text: string): Heading[] {
+	const headings: Heading[] = [];
+	let fence: string | undefined;
+	const lines = text.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		const fenceMatch = /^\s*(```+|~~~+)/.exec(line);
+		if (fenceMatch) {
+			const marker = fenceMatch[1][0];
+			if (!fence) fence = marker;
+			else if (fence === marker) fence = undefined;
+			continue;
+		}
+		if (fence) continue;
+		const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+		if (match) {
+			headings.push({ level: match[1].length, text: match[2].trim(), line: index + 1 });
+		}
+	}
+	return headings;
+}
+
+export function readDoc(root: string, rel: string): DocInfo | undefined {
+	const text = readTextFile(root, rel);
+	if (text === undefined) return undefined;
+	const info = statFile(root, rel);
+	if (!info) return undefined;
+	return { ...info, text, headings: parseHeadings(text) };
+}
+
+function listDir(root: string, rel: string): string[] {
+	try {
+		return readdirSync(join(root, rel)).sort();
+	} catch {
+		return [];
+	}
+}
+
+function isDir(root: string, rel: string): boolean {
+	try {
+		return statSync(join(root, rel)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function isFile(root: string, rel: string): boolean {
+	try {
+		return statSync(join(root, rel)).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/* -------------------------------------------------------------------------- */
+/* Tree walk                                                                   */
+/* -------------------------------------------------------------------------- */
+
+export interface WalkEntry {
+	readonly rel: string;
+	readonly bytes: number;
+}
+
+/**
+ * Walk `root` with the shared ignore list. Directories listed in `excludePrefix`
+ * are skipped entirely (the framework's own runtime dir must never be scanned:
+ * snapshots are copies, reports quote old paths).
+ */
+export function walk(
+	root: string,
+	options: { excludePrefix?: string[]; maxDepth?: number; maxFiles?: number } = {},
+): WalkEntry[] {
+	const out: WalkEntry[] = [];
+	const maxDepth = options.maxDepth ?? SCAN.maxDepth;
+	const maxFiles = options.maxFiles ?? SCAN.maxFiles;
+	const excluded = options.excludePrefix ?? [];
+
+	const visit = (rel: string, depth: number): boolean => {
+		if (out.length >= maxFiles) return false;
+		let names: string[];
+		try {
+			names = readdirSync(join(root, rel), { withFileTypes: true })
+				.map((entry) => `${entry.isDirectory() ? "d:" : "f:"}${entry.name}`)
+				.sort();
+		} catch {
+			return true;
+		}
+		for (const tagged of names) {
+			const kind = tagged.slice(0, 2);
+			const name = tagged.slice(2);
+			const child = rel === "" ? name : `${rel}/${name}`;
+			if (excluded.some((prefix) => child === prefix || child.startsWith(`${prefix}/`))) {
+				continue;
+			}
+			if (kind === "d:") {
+				if (SCAN.ignoreDirs.has(name)) continue;
+				if (depth >= maxDepth) continue;
+				if (!visit(child, depth + 1)) return false;
+				continue;
+			}
+			let bytes = 0;
+			try {
+				bytes = statSync(join(root, child)).size;
+			} catch {
+				continue;
+			}
+			out.push({ rel: child, bytes });
+			if (out.length >= maxFiles) return false;
+		}
+		return true;
+	};
+
+	visit("", 0);
+	return out;
+}
+
+export function isTextExtension(rel: string): boolean {
+	const dot = rel.lastIndexOf(".");
+	if (dot < 0) return false;
+	return SCAN.refExtensions.has(rel.slice(dot).toLowerCase());
+}
+
+/* -------------------------------------------------------------------------- */
+/* Reference scan                                                              */
+/* -------------------------------------------------------------------------- */
+
+const REF_NAMES = ["memory/", "implementations/"] as const;
+
+/**
+ * True when the occurrence at `index` is a *bare* reference: not already under
+ * `.agents/`, not a longer hyphenated name (`my-memory/`), and not the tail of
+ * somebody else's absolute path (`~/.pi/agent/memory/`).
+ *
+ * Relative prefixes are part of the reference, not a reason to skip it:
+ * `../memory/X.md` and `./memory/X.md` must be rewritten just like `memory/X.md`
+ * (the prefix is preserved, only the directory name changes).
+ */
+export function isBareRef(text: string, index: number, name: string): boolean {
+	if (text.startsWith(name, index) === false) return false;
+	const before = text.slice(Math.max(0, index - 32), index);
+	if (before.endsWith(".agents/")) return false;
+	const prev = index > 0 ? text[index - 1] : "";
+	if (prev === "/") {
+		const prefix = text.slice(0, index);
+		// Only `./` and one or more `../` count as a reference prefix. Anything
+		// else (`agent/memory/`, `/memory/`) is a different path altogether.
+		return /(?:\.\.\/)+$/.test(prefix) || /\.\/$/.test(prefix);
+	}
+	// `-` continues a compound name (`my-memory/`); letters, digits and `.` are
+	// the same story (`foo.memory/`).
+	if (prev && /[A-Za-z0-9_.-]/.test(prev)) return false;
+	return true;
+}
+
+/** Count bare occurrences of `name` in `text`. */
+export function countBareRefs(text: string, name: string): number {
+	let count = 0;
+	let index = text.indexOf(name);
+	while (index >= 0) {
+		if (isBareRef(text, index, name)) count += 1;
+		index = text.indexOf(name, index + name.length);
+	}
+	return count;
+}
+
+function areaOf(rel: string): string {
+	const slash = rel.indexOf("/");
+	return slash < 0 ? "(root)" : rel.slice(0, slash);
+}
+
+export function scanRefs(root: string): RefScan {
+	const entries = walk(root, { excludePrefix: [FRAMEWORK_DIR] });
+	const byArea: Record<string, RefArea> = {};
+	const examples: RefScan["examples"] = [];
+	const paths: string[] = [];
+	let files = 0;
+	let hits = 0;
+
+	for (const entry of entries) {
+		if (entry.bytes === 0 || entry.bytes > SCAN.maxFileBytes) continue;
+		if (!isTextExtension(entry.rel)) continue;
+		const text = readTextFile(root, entry.rel);
+		if (text === undefined) continue;
+		files += 1;
+		let fileHits = 0;
+		for (const name of REF_NAMES) fileHits += countBareRefs(text, name);
+		if (fileHits === 0) continue;
+		hits += fileHits;
+		paths.push(entry.rel);
+		const area = areaOf(entry.rel);
+		const bucket = (byArea[area] ??= { files: 0, hits: 0 });
+		bucket.files += 1;
+		bucket.hits += fileHits;
+		if (examples.length < 8) {
+			const line = lineOfFirstRef(text);
+			examples.push({
+				path: entry.rel,
+				line,
+				text: firstRefLine(text) ?? "",
+			});
+		}
+	}
+
+	return { files, hits, byArea, examples, paths };
+}
+
+function lineOfFirstRef(text: string): number {
+	const lines = text.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		for (const name of REF_NAMES) {
+			let at = lines[index].indexOf(name);
+			while (at >= 0) {
+				if (isBareRef(lines[index], at, name)) return index + 1;
+				at = lines[index].indexOf(name, at + name.length);
+			}
+		}
+	}
+	return 1;
+}
+
+function firstRefLine(text: string): string | undefined {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		for (const name of REF_NAMES) {
+			let at = line.indexOf(name);
+			while (at >= 0) {
+				if (isBareRef(line, at, name)) return line.trim().slice(0, 160);
+				at = line.indexOf(name, at + name.length);
+			}
+		}
+	}
+	return undefined;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Git                                                                         */
+/* -------------------------------------------------------------------------- */
+
+function git(args: string[], root: string): string | undefined {
+	try {
+		return execFileSync("git", ["-C", root, ...args], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			maxBuffer: 8 * 1024 * 1024,
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+function gitInfo(root: string): Pick<Facts, "isGit" | "gitClean" | "gitDirtyCount"> {
+	const inside = git(["rev-parse", "--is-inside-work-tree"], root);
+	if (inside?.trim() !== "true") return { isGit: false };
+	const status = git(["status", "--porcelain"], root);
+	if (status === undefined) return { isGit: true };
+	const lines = status.split("\n").filter((line) => line.length > 0);
+	return { isGit: true, gitClean: lines.length === 0, gitDirtyCount: lines.length };
+}
+
+/* -------------------------------------------------------------------------- */
+/* State                                                                       */
+/* -------------------------------------------------------------------------- */
+
+export function loadState(root: string): { state?: FrameworkState; error?: string } {
+	if (!existsSync(join(root, STATE_FILE))) return {};
+	try {
+		const raw = readFileSync(join(root, STATE_FILE), "utf8");
+		return { state: parseState(raw) };
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+/**
+ * Defensive reader for our own state file: unknown or missing fields fall back
+ * instead of throwing, so a partially hand-edited state file still produces a
+ * plan (and a warning) rather than a dead command.
+ */
+export function parseState(raw: string): FrameworkState {
+	const data = parseToml(raw) as Record<string, unknown>;
+	const version = Number(data.version ?? 0);
+	const tool = String(data.tool ?? "");
+	const created = String(data.created ?? "");
+	const updated = String(data.updated ?? created);
+	const profile = data.profile === "full" ? "full" : "core";
+	const modules = Array.isArray(data.modules) ? data.modules.map(String) : [];
+	const lang = data.lang === "zh" ? "zh" : "en";
+	const budgets = data.budgets as Record<string, unknown> | undefined;
+	const roots = Array.isArray(data.roots)
+		? (data.roots as Array<Record<string, unknown>>).map((entry) => ({
+				label: String(entry.label ?? ""),
+				path: String(entry.path ?? ""),
+				absolute: String(entry.absolute ?? ""),
+				role: entry.role === undefined ? undefined : String(entry.role),
+				agentsMd:
+					entry.agents_md === "scope-card" ||
+					entry.agents_md === "independent" ||
+					entry.agents_md === "none"
+						? (entry.agents_md as RootInfo["agentsMd"])
+						: "unknown",
+				source: "state" as const,
+				exists: true,
+				lastSeen: entry.last_seen === undefined ? undefined : String(entry.last_seen),
+			}))
+		: [];
+	const managed = Array.isArray(data.managed)
+		? (data.managed as Array<Record<string, unknown>>).map((entry) => ({
+				path: String(entry.path ?? ""),
+				sha256: String(entry.sha256 ?? ""),
+				template: String(entry.template ?? ""),
+			}))
+		: [];
+	const migrations = Array.isArray(data.migrations)
+		? (data.migrations as Array<Record<string, unknown>>).map((entry) => ({
+				at: String(entry.at ?? ""),
+				to: String(entry.to ?? ""),
+				notes: entry.notes === undefined ? undefined : String(entry.notes),
+			}))
+		: [];
+	return {
+		version: Number.isFinite(version) ? version : 0,
+		tool,
+		created,
+		updated,
+		profile,
+		modules,
+		lang,
+		budgets: budgets
+			? {
+					agentsMdSoftChars: numberOrUndefined(
+						budgets.agents_md_soft_chars ?? budgets.agentsMdSoftChars,
+					),
+					agentsMdHardChars: numberOrUndefined(
+						budgets.agents_md_hard_chars ?? budgets.agentsMdHardChars,
+					),
+					memoryFileChars: numberOrUndefined(
+						budgets.memory_file_chars ?? budgets.memoryFileChars,
+					),
+				}
+			: undefined,
+		roots,
+		managed,
+		migrations,
+	};
+}
+
+function numberOrUndefined(value: unknown): number | undefined {
+	if (value === undefined || value === null) return undefined;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Language                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export function detectLanguage(
+	root: string,
+	fallback: ProjectLanguage = "en",
+): ProjectLanguage {
+	const candidates = ["AGENTS.md", "README.md", "README.zh-CN.md", "readme.md"];
+	for (const candidate of candidates) {
+		const text = readTextFile(root, candidate);
+		if (!text) continue;
+		const sample = text.slice(0, 20_000);
+		let cjk = 0;
+		let visible = 0;
+		for (const char of sample) {
+			const code = char.codePointAt(0) ?? 0;
+			if (code <= 32) continue;
+			visible += 1;
+			if (code >= 0x4e00 && code <= 0x9fff) cjk += 1;
+		}
+		if (visible === 0) continue;
+		return cjk / visible >= 0.08 ? "zh" : "en";
+	}
+	return fallback;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Project facts                                                               */
+/* -------------------------------------------------------------------------- */
+
+const MANIFESTS = [
+	"package.json",
+	"Cargo.toml",
+	"pyproject.toml",
+	"go.mod",
+	"pom.xml",
+	"build.gradle",
+	"composer.json",
+	"Gemfile",
+	"mix.exs",
+];
+
+const LOCKFILES: Array<[string, string]> = [
+	["pnpm-lock.yaml", "pnpm"],
+	["package-lock.json", "npm"],
+	["yarn.lock", "yarn"],
+	["bun.lockb", "bun"],
+	["Cargo.lock", "cargo"],
+	["uv.lock", "uv"],
+	["poetry.lock", "poetry"],
+	["Pipfile.lock", "pipenv"],
+	["go.sum", "go"],
+];
+
+function detectProject(root: string): ProjectFacts {
+	const manifests = MANIFESTS.filter((name) => isFile(root, name));
+	const lockfiles: string[] = [];
+	let pkgManager: string | undefined;
+	for (const [name, manager] of LOCKFILES) {
+		if (!isFile(root, name)) continue;
+		lockfiles.push(name);
+		pkgManager ??= manager;
+	}
+	const licenseName = listDir(root, "").find((name) =>
+		/^(LICENSE|LICENCE|COPYING)(\..*)?$/i.test(name),
+	);
+	const ci: string[] = [];
+	if (isDir(root, ".github/workflows")) {
+		for (const name of listDir(root, ".github/workflows")) {
+			if (/\.ya?ml$/i.test(name)) ci.push(`.github/workflows/${name}`);
+		}
+	}
+	if (isFile(root, ".gitlab-ci.yml")) ci.push(".gitlab-ci.yml");
+	if (isFile(root, "azure-pipelines.yml")) ci.push("azure-pipelines.yml");
+	if (isFile(root, "Jenkinsfile")) ci.push("Jenkinsfile");
+
+	const scripts: Record<string, string> = {};
+	const pkg = readTextFile(root, "package.json");
+	if (pkg) {
+		try {
+			const parsed = JSON.parse(pkg) as {
+				scripts?: Record<string, string>;
+				packageManager?: string;
+			};
+			for (const [key, value] of Object.entries(parsed.scripts ?? {})) {
+				if (typeof value === "string") scripts[key] = value;
+			}
+			if (parsed.packageManager) {
+				pkgManager = parsed.packageManager.split("@")[0];
+			}
+		} catch {
+			// A malformed manifest is a project problem, not an init failure.
+		}
+	}
+
+	return { manifests, lockfiles, license: licenseName, ci, scripts, pkgManager };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Roots                                                                       */
+/* -------------------------------------------------------------------------- */
+
+function classifyRootAgentsMd(root: string, absolute: string): RootInfo["agentsMd"] {
+	const rel = toPosix(relative(root, absolute));
+	const agentsRel = rel === "" ? "AGENTS.md" : posix.join(rel, "AGENTS.md");
+	if (!isFile(root, agentsRel)) return "none";
+	const text = readTextFile(root, agentsRel) ?? "";
+	const lines = text.split("\n").length;
+	// A secondary root that already carries the framework contract owns its own
+	// memory; we must not treat it as a scope card.
+	if (text.includes(".agents/memory") || text.includes("agent-framework")) {
+		return "independent";
+	}
+	return lines <= 40 ? "scope-card" : "independent";
+}
+
+export function mergeRoots(
+	root: string,
+	stateRoots: RootInfo[],
+	added: Array<{ label: string; absolute: string }>,
+): RootInfo[] {
+	const byAbsolute = new Map<string, RootInfo>();
+	for (const entry of stateRoots) {
+		byAbsolute.set(entry.absolute, {
+			...entry,
+			exists: existsSync(entry.absolute),
+			agentsMd: classifyRootAgentsMd(root, entry.absolute),
+		});
+	}
+	for (const entry of added) {
+		const rel = toPosix(relative(root, entry.absolute));
+		const inside = !rel.startsWith("..");
+		byAbsolute.set(entry.absolute, {
+			label: entry.label,
+			path: inside ? rel : entry.absolute,
+			absolute: entry.absolute,
+			agentsMd: classifyRootAgentsMd(root, entry.absolute),
+			source: "add-dir",
+			exists: existsSync(entry.absolute),
+		});
+	}
+	return [...byAbsolute.values()].sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/* -------------------------------------------------------------------------- */
+/* The survey                                                                  */
+/* -------------------------------------------------------------------------- */
+
+export interface DetectOptions {
+	/** Absolute paths added via pi-add-dir in this session. */
+	readonly addedRoots?: Array<{ label: string; absolute: string }>;
+	/** Language override (`--lang`). */
+	readonly lang?: ProjectLanguage;
+}
+
+function readDocs(root: string, rel: string, keep: (name: string) => boolean): DocInfo[] {
+	const docs: DocInfo[] = [];
+	for (const name of listDir(root, rel)) {
+		if (!name.endsWith(".md") || !keep(name)) continue;
+		const doc = readDoc(root, `${rel}/${name}`);
+		if (doc) docs.push(doc);
+	}
+	return docs;
+}
+
+function readFiles(root: string, rel: string): FileInfo[] {
+	const files: FileInfo[] = [];
+	for (const name of listDir(root, rel)) {
+		if (!name.endsWith(".md")) continue;
+		const info = statFile(root, `${rel}/${name}`);
+		if (info) files.push(info);
+	}
+	return files;
+}
+
+function countFilesUnder(root: string, rel: string, limit = 5000): number {
+	let count = 0;
+	const visit = (current: string): void => {
+		if (count >= limit) return;
+		for (const name of listDir(root, current)) {
+			if (count >= limit) return;
+			const child = `${current}/${name}`;
+			if (isDir(root, child)) {
+				if (SCAN.ignoreDirs.has(name)) continue;
+				visit(child);
+				continue;
+			}
+			count += 1;
+		}
+	};
+	visit(rel);
+	return count;
+}
+
+function readDeprecated(root: string): {
+	deprecated: Facts["deprecated"];
+	deprecatedFiles: Facts["deprecatedFiles"];
+	retiredTodos: boolean;
+} {
+	const deprecated = {
+		memory: isDir(root, DEPRECATED_ROOT_DIRS[0]),
+		implementations: isDir(root, DEPRECATED_ROOT_DIRS[1]),
+		prompts: isDir(root, DEPRECATED_ROOT_DIRS[2]),
+	};
+	return {
+		deprecated,
+		deprecatedFiles: {
+			memory: deprecated.memory ? countFilesUnder(root, "memory") : 0,
+			implementations: deprecated.implementations ? countFilesUnder(root, "implementations") : 0,
+			prompts: deprecated.prompts ? countFilesUnder(root, "prompts") : 0,
+		},
+		retiredTodos: isDir(root, RETIRED_ROOT_DIRS[0]),
+	};
+}
+
+function readLegacyDocs(root: string): DocInfo[] {
+	const docs: DocInfo[] = [];
+	for (const name of [...LEGACY_DOC_NAMES, ".github/copilot-instructions.md", ".cursorrules", ".windsurfrules"]) {
+		if (!isFile(root, name)) continue;
+		const doc = readDoc(root, name);
+		if (doc) docs.push(doc);
+	}
+	if (isDir(root, ".cursor/rules")) {
+		docs.push(...readDocs(root, ".cursor/rules", () => true));
+	}
+	for (const rel of ["adr", "decisions", "docs/adr", "docs/decisions"]) {
+		if (!isDir(root, rel)) continue;
+		docs.push(...readDocs(root, rel, () => true));
+	}
+	return docs;
+}
+
+function readNestedAgents(root: string): FileInfo[] {
+	const files: FileInfo[] = [];
+	for (const entry of walk(root, { maxDepth: 3 })) {
+		if (entry.rel === "AGENTS.md") continue;
+		if (!/(^|\/)(AGENTS|CLAUDE)\.md$/.test(entry.rel)) continue;
+		const info = statFile(root, entry.rel);
+		if (info) files.push(info);
+	}
+	return files;
+}
+
+function readModulesPresent(root: string, memory: readonly DocInfo[]): string[] {
+	return MEMORY_MODULES.filter((module) => {
+		if (module === "function") {
+			return memory.some((doc) => doc.rel.startsWith(".agents/memory/FUNCTION-"));
+		}
+		return isFile(root, `${MEMORY_DIR}/${module.toUpperCase()}.md`);
+	});
+}
+
+function readEmptyRootFiles(root: string): string[] {
+	return listDir(root, "").filter((name) => {
+		const info = statFile(root, name);
+		return info !== undefined && info.bytes === 0;
+	});
+}
+
+function contextWarnings(
+	context: Facts["context"],
+	state: FrameworkState | undefined,
+	stateError: string | undefined,
+): string[] {
+	const warnings: string[] = [];
+	if (stateError) warnings.push(`state file unreadable: ${stateError}`);
+	if (state && state.version > FRAMEWORK_VERSION) {
+		warnings.push(
+			`state version ${state.version} is newer than this tool (${FRAMEWORK_VERSION}); refusing to plan a migration`,
+		);
+	}
+	if (context.override) {
+		warnings.push(
+			`${OVERRIDE_FILE} exists: pi loads it instead of AGENTS.md in this directory, so the framework entry is invisible to the agent`,
+		);
+	}
+	if (!context.agents && context.claude) {
+		warnings.push("only CLAUDE.md exists; AGENTS.md is the pi entry and will be created");
+	}
+	return warnings;
+}
+
+export function detect(root: string, options: DetectOptions = {}): Facts {
+	const { state, error: stateError } = loadState(root);
+	const context = {
+		agents: readDoc(root, "AGENTS.md"),
+		claude: readDoc(root, "CLAUDE.md"),
+		override: readDoc(root, OVERRIDE_FILE),
+		piAgents: readDoc(root, ".pi/AGENTS.md"),
+	};
+	const dirs: Record<string, boolean> = {};
+	for (const rel of [
+		AGENTS_DIR,
+		MEMORY_DIR,
+		IMPLEMENTATIONS_DIR,
+		PROMPTS_DIR,
+		FRAMEWORK_DIR,
+		SPECS_DIR,
+		"design",
+		"docs",
+		"legal",
+	]) {
+		dirs[rel] = isDir(root, rel);
+	}
+
+	const memory = readDocs(
+		root,
+		MEMORY_DIR,
+		// PLAN.md is not a memory file in v1, but an older install may still
+		// have one here; it must stay visible so the plan can move it to specs/.
+		(name) => isMemoryFileName(name) || name === "PLAN.md",
+	);
+	const legacyMemory = readDocs(root, "memory", () => true);
+	const specs = readDocs(root, SPECS_DIR, () => true);
+	const implementations = [
+		...readFiles(root, IMPLEMENTATIONS_DIR),
+		...readFiles(root, "implementations"),
+	];
+	const todos = readDocs(root, "todos", () => true);
+	const { deprecated, deprecatedFiles, retiredTodos } = readDeprecated(root);
+
+	return {
+		root,
+		...gitInfo(root),
+		state,
+		stateError,
+		context,
+		dirs,
+		deprecated,
+		deprecatedFiles,
+		retiredTodos,
+		rootEmptyFiles: readEmptyRootFiles(root),
+		memory,
+		legacyMemory,
+		specs,
+		implementations,
+		todos,
+		legacyDocs: readLegacyDocs(root),
+		nestedAgents: readNestedAgents(root),
+		modulesPresent: readModulesPresent(root, memory),
+		refs: scanRefs(root),
+		project: detectProject(root),
+		language: options.lang ?? state?.lang ?? detectLanguage(root),
+		roots: mergeRoots(root, state?.roots ?? [], options.addedRoots ?? []),
+		warnings: contextWarnings(context, state, stateError),
+	};
+}
+
+/** Module ids recognised inside `.agents/memory/`. */
+const MEMORY_MODULES = ["design", "terms", "review", "debugging", "function"] as const;