treedocs 0.3.0

package/src/core.ts

@@ -0,0 +1,2051 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import {
+	access,
+	lstat,
+	mkdir,
+	readdir,
+	readFile,
+	writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import addFormats from "ajv-formats";
+import { parse, stringify } from "yaml";
+
+export const cliVersion = "0.3.0";
+export const currentSchemaVersion = "0.2.0";
+export const schemaUrl =
+	"https://dandylyons.github.io/treedocs/schemas/0.2.0/treedocs.schema.json";
+export const stateFileName = "treedocs.yaml";
+
+export class TreedocsError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "TreedocsError";
+	}
+}
+
+export type CheckSeverity = "error" | "warn";
+
+export interface ProjectMetadata {
+	name?: string;
+	version?: string;
+	last_updated?: string;
+	[key: string]: string | undefined;
+}
+
+export interface TreedocsConfig {
+	exclude?: string[];
+	use_gitignore?: boolean;
+	max_description_length?: number;
+	indent_size?: number;
+	align_columns?: boolean;
+	check_severity?: CheckSeverity;
+	auto_init_empty?: boolean;
+	theme?: string;
+	icons?: boolean;
+	ai_provider?: string;
+	ai_model?: string;
+}
+
+export interface ResolvedTreedocsConfig {
+	exclude: string[];
+	use_gitignore: boolean;
+	max_description_length: number;
+	indent_size: number;
+	align_columns: boolean;
+	check_severity: CheckSeverity;
+	auto_init_empty: boolean;
+	theme?: string;
+	icons: boolean;
+	ai_provider?: string;
+	ai_model?: string;
+}
+
+export interface EntryDocumentation {
+	description?: string;
+	references: string[];
+}
+
+export interface TreeEntry {
+	documentation?: EntryDocumentation;
+	link?: string;
+	children: Tree;
+	isDirectory: boolean;
+}
+
+export type Tree = Record<string, TreeEntry>;
+
+export interface TreedocsFile {
+	schemaVersion: string;
+	project: ProjectMetadata;
+	overrides?: TreedocsConfig;
+	signature?: string;
+	tree: Tree;
+}
+
+export interface TreeScanResult {
+	tree: Tree;
+	normalizedPaths: string[];
+	nestedBoundaries: string[];
+	signature: string;
+}
+
+export interface SyncChanges {
+	addedPaths: string[];
+	removedPaths: string[];
+	changedTypePaths: string[];
+}
+
+export interface SyncResult {
+	file: TreedocsFile;
+	saved: boolean;
+	signatureUnchanged: boolean;
+	changes: SyncChanges;
+	missingDescriptions: string[];
+}
+
+export interface CheckReport {
+	schemaWarnings: string[];
+	schemaErrors: string[];
+	storedSignature?: string;
+	currentSignature: string;
+	missingDescriptions: string[];
+	missingPaths: string[];
+	extraPaths: string[];
+	changedPaths: string[];
+	nestedBoundaries: string[];
+	shadowedPaths: string[];
+	severity: CheckSeverity;
+	hasSignatureDrift: boolean;
+	hasIssues: boolean;
+	shouldFail: boolean;
+	requiresSyncBeforeFill: boolean;
+}
+
+export interface InspectReport {
+	path: string;
+	entry: TreeEntry;
+	linkResolution: LinkResolution;
+	recursiveOutput?: string;
+}
+
+export type LinkResolution =
+	| { type: "none" }
+	| { type: "external"; url: string }
+	| { type: "resolved"; path: string; chain: string[]; entry: TreeEntry }
+	| { type: "broken"; target: string; chain: string[] }
+	| { type: "cycle"; chain: string[] };
+
+interface RepositoryPaths {
+	root: string;
+	stateFile: string;
+	projectConfig: string;
+	projectIgnore: string;
+	gitignore: string;
+}
+
+interface LoadedConfiguration {
+	config: ResolvedTreedocsConfig;
+	ignorePatterns: string[];
+}
+
+type EntryStatus = "clean" | "warning" | "error";
+
+const defaultConfig: ResolvedTreedocsConfig = {
+	exclude: [],
+	use_gitignore: true,
+	max_description_length: 120,
+	indent_size: 2,
+	align_columns: false,
+	check_severity: "error",
+	auto_init_empty: false,
+	icons: false,
+};
+
+const standardExcludedNames = new Set([
+	".git",
+	".build",
+	".swiftpm",
+	".treedocs",
+	".agents",
+	".opencode",
+	"node_modules",
+	stateFileName,
+]);
+
+export const missingDescriptionNextStep =
+	'Add missing descriptions with `treedocs update <path> "..."` or by editing `treedocs.yaml`, then run `treedocs check`.';
+
+export function normalizeRelativePath(raw: string): string {
+	return normalizePathComponents(raw.replaceAll("\\", "/").split("/")).join(
+		"/",
+	);
+}
+
+export function relativePathComponents(raw: string): string[] {
+	return normalizePathComponents(raw.replaceAll("\\", "/").split("/"));
+}
+
+export function resolveLinkTarget(raw: string, currentPath: string): string {
+	if (raw.startsWith("./") || raw.startsWith("../")) {
+		const baseComponents = relativePathComponents(currentPath).slice(0, -1);
+		return normalizePathComponents([
+			...baseComponents,
+			...raw.replaceAll("\\", "/").split("/"),
+		]).join("/");
+	}
+
+	return normalizeRelativePath(raw);
+}
+
+function normalizePathComponents(rawComponents: string[]): string[] {
+	const result: string[] = [];
+	for (const component of rawComponents) {
+		if (component === "" || component === ".") {
+			continue;
+		}
+		if (component === "..") {
+			if (result.length > 0) {
+				result.pop();
+			}
+			continue;
+		}
+		result.push(component);
+	}
+	return result;
+}
+
+function trimmedNilIfEmpty(value: string | undefined): string | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function parseString(value: unknown): string | undefined {
+	switch (typeof value) {
+		case "string":
+			return value;
+		case "number":
+		case "boolean":
+		case "bigint":
+			return String(value);
+		default:
+			return undefined;
+	}
+}
+
+function parseBoolean(value: unknown): boolean | undefined {
+	if (typeof value === "boolean") {
+		return value;
+	}
+	if (typeof value === "number") {
+		return value !== 0;
+	}
+	if (typeof value !== "string") {
+		return undefined;
+	}
+
+	switch (value.toLowerCase()) {
+		case "true":
+		case "yes":
+		case "1":
+			return true;
+		case "false":
+		case "no":
+		case "0":
+			return false;
+		default:
+			return undefined;
+	}
+}
+
+function parseInteger(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isInteger(value)) {
+		return value;
+	}
+	if (typeof value === "string" && /^-?\d+$/.test(value)) {
+		return Number.parseInt(value, 10);
+	}
+	return undefined;
+}
+
+function parseStringArray(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) {
+		return undefined;
+	}
+	return value.flatMap((item) => {
+		const parsed = parseString(item);
+		return parsed === undefined ? [] : [parsed];
+	});
+}
+
+function parseSeverity(value: unknown): CheckSeverity | undefined {
+	const parsed = parseString(value)?.toLowerCase();
+	return parsed === "error" || parsed === "warn" ? parsed : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function documentationIsEmpty(documentation: EntryDocumentation | undefined) {
+	return (
+		documentation === undefined ||
+		(documentation.description === undefined &&
+			documentation.references.length === 0)
+	);
+}
+
+export function makeDocumentation(
+	description?: string,
+	references: string[] = [],
+): EntryDocumentation | undefined {
+	if (description === undefined && references.length === 0) {
+		return undefined;
+	}
+	return {
+		description: description === undefined ? undefined : description.trim(),
+		references: [...references],
+	};
+}
+
+export function makeTreeEntry(options: {
+	description?: string;
+	documentation?: EntryDocumentation;
+	references?: string[];
+	link?: string;
+	children?: Tree;
+	isDirectory?: boolean;
+}): TreeEntry {
+	const documentation =
+		options.documentation ??
+		makeDocumentation(options.description, options.references ?? []);
+	const normalizedLink = trimmedNilIfEmpty(options.link);
+	return {
+		documentation: documentationIsEmpty(documentation)
+			? undefined
+			: documentation,
+		link: normalizedLink,
+		children: options.children ?? {},
+		isDirectory: options.isDirectory ?? false,
+	};
+}
+
+export function entryDescription(entry: TreeEntry): string | undefined {
+	return entry.documentation?.description;
+}
+
+export function entryReferences(entry: TreeEntry): string[] {
+	return entry.documentation?.references ?? [];
+}
+
+export function entryNeedsDescription(entry: TreeEntry): boolean {
+	const description = entryDescription(entry);
+	return (description === undefined || description.length === 0) && !entry.link;
+}
+
+function entryHasReferences(entry: TreeEntry): boolean {
+	return entryReferences(entry).length > 0;
+}
+
+export function insertEntry(
+	entry: TreeEntry,
+	components: string[],
+	tree: Tree,
+) {
+	const [first, ...remaining] = components;
+	if (first === undefined) {
+		return;
+	}
+
+	if (remaining.length === 0) {
+		const existing = tree[first];
+		if (existing) {
+			existing.documentation = entry.documentation ?? existing.documentation;
+			existing.link = entry.link ?? existing.link;
+			existing.isDirectory = existing.isDirectory || entry.isDirectory;
+			for (const [key, value] of Object.entries(entry.children)) {
+				existing.children[key] = value;
+			}
+			return;
+		}
+		tree[first] = entry;
+		return;
+	}
+
+	const parent =
+		tree[first] ?? makeTreeEntry({ children: {}, isDirectory: true });
+	parent.isDirectory = true;
+	insertEntry(entry, remaining, parent.children);
+	tree[first] = parent;
+}
+
+export function entryAt(
+	relativePath: string,
+	tree: Tree,
+): TreeEntry | undefined {
+	const components = relativePathComponents(relativePath);
+	if (components.length === 0) {
+		return makeTreeEntry({ children: tree, isDirectory: true });
+	}
+
+	let currentTree = tree;
+	let currentEntry: TreeEntry | undefined;
+	for (const component of components) {
+		const nextEntry = currentTree[component];
+		if (!nextEntry) {
+			return undefined;
+		}
+		currentEntry = nextEntry;
+		currentTree = nextEntry.children;
+	}
+	return currentEntry;
+}
+
+export function updateEntry(
+	relativePath: string,
+	tree: Tree,
+	mutate: (entry: TreeEntry) => void,
+): boolean {
+	const components = relativePathComponents(relativePath);
+	const [first, ...remaining] = components;
+	if (first === undefined) {
+		return false;
+	}
+
+	const entry = tree[first];
+	if (!entry) {
+		return false;
+	}
+
+	if (remaining.length === 0) {
+		mutate(entry);
+		return true;
+	}
+
+	return updateEntry(remaining.join("/"), entry.children, mutate);
+}
+
+export function flattenTree(
+	tree: Tree,
+	prefix = "",
+): Array<[string, TreeEntry]> {
+	const result: Array<[string, TreeEntry]> = [];
+	for (const key of Object.keys(tree).sort()) {
+		const entry = tree[key];
+		if (!entry) {
+			continue;
+		}
+		const path = prefix ? `${prefix}/${key}` : key;
+		result.push([path, entry]);
+		if (entry.isDirectory) {
+			result.push(...flattenTree(entry.children, path));
+		}
+	}
+	return result;
+}
+
+export function collectNormalizedPaths(
+	tree: Tree,
+	prefix = "",
+	result: string[] = [],
+): string[] {
+	for (const key of Object.keys(tree).sort()) {
+		const entry = tree[key];
+		if (!entry) {
+			continue;
+		}
+		const path = prefix ? `${prefix}/${key}` : key;
+		result.push(entry.isDirectory ? `${path}/` : path);
+		if (entry.isDirectory) {
+			collectNormalizedPaths(entry.children, path, result);
+		}
+	}
+	return result;
+}
+
+export function treeSignature(normalizedPaths: string[]): string {
+	const payload = [...normalizedPaths].sort().join("\n");
+	return `sha256:${createHash("sha256").update(payload).digest("hex")}`;
+}
+
+export function missingDescriptionPaths(tree: Tree): string[] {
+	return flattenTree(tree)
+		.filter(([, entry]) => entryNeedsDescription(entry))
+		.map(([path]) => path);
+}
+
+export function missingPaths(stored: Tree, scanned: Tree): string[] {
+	return sortedDifference(pathSet(scanned), pathSet(stored));
+}
+
+export function extraPaths(stored: Tree, scanned: Tree): string[] {
+	return sortedDifference(pathSet(stored), pathSet(scanned));
+}
+
+export function changedPaths(stored: Tree, scanned: Tree): string[] {
+	const storedEntries = entryMap(stored);
+	const scannedEntries = entryMap(scanned);
+	return [...storedEntries.keys()]
+		.filter((path) => {
+			const storedEntry = storedEntries.get(path);
+			const scannedEntry = scannedEntries.get(path);
+			return (
+				storedEntry !== undefined &&
+				scannedEntry !== undefined &&
+				storedEntry.isDirectory !== scannedEntry.isDirectory
+			);
+		})
+		.sort();
+}
+
+export function shadowedPaths(
+	stored: Tree,
+	nestedBoundaries: string[],
+): string[] {
+	return [...pathSet(stored)]
+		.filter((path) =>
+			nestedBoundaries.some((boundary) => path.startsWith(`${boundary}/`)),
+		)
+		.sort();
+}
+
+export function mergePreservingMetadata(scanned: Tree, existing: Tree): Tree {
+	const merged: Tree = {};
+	for (const key of Object.keys(scanned).sort()) {
+		const scannedEntry = scanned[key];
+		if (!scannedEntry) {
+			continue;
+		}
+		merged[key] = mergeEntry(scannedEntry, existing[key]);
+	}
+	return merged;
+}
+
+export function applyDescriptions(
+	descriptions: Record<string, string>,
+	tree: Tree,
+): string[] {
+	const updatedPaths: string[] = [];
+	for (const path of Object.keys(descriptions).sort()) {
+		const description = trimmedNilIfEmpty(descriptions[path]);
+		if (description === undefined) {
+			continue;
+		}
+		if (
+			updateEntry(path, tree, (entry) => {
+				entry.documentation = makeDocumentation(
+					description,
+					entryReferences(entry),
+				);
+			})
+		) {
+			updatedPaths.push(path);
+		}
+	}
+	return updatedPaths;
+}
+
+export function firstPathMatching(
+	query: string,
+	tree: Tree,
+): string | undefined {
+	const normalizedQuery = query.toLowerCase();
+	const entries = flattenTree(tree).sort(([left], [right]) =>
+		left.localeCompare(right),
+	);
+	const allPaths = entries.map(([path]) => path);
+
+	return (
+		allPaths.find((path) => path.toLowerCase() === normalizedQuery) ??
+		allPaths.find((path) => path.toLowerCase().startsWith(normalizedQuery)) ??
+		allPaths.find((path) => path.toLowerCase().includes(normalizedQuery)) ??
+		entries.find(([, entry]) =>
+			entryDescription(entry)?.toLowerCase().includes(normalizedQuery),
+		)?.[0]
+	);
+}
+
+function mergeEntry(
+	scanned: TreeEntry,
+	existing: TreeEntry | undefined,
+): TreeEntry {
+	const merged = makeTreeEntry({
+		documentation: scanned.documentation,
+		link: scanned.link,
+		children: { ...scanned.children },
+		isDirectory: scanned.isDirectory,
+	});
+
+	if (existing && existing.isDirectory === scanned.isDirectory) {
+		merged.documentation = existing.documentation;
+		merged.link = existing.link;
+		if (scanned.isDirectory) {
+			merged.children = mergePreservingMetadata(
+				scanned.children,
+				existing.children,
+			);
+		}
+	}
+
+	return merged;
+}
+
+function pathSet(tree: Tree): Set<string> {
+	return new Set(flattenTree(tree).map(([path]) => path));
+}
+
+function entryMap(tree: Tree): Map<string, TreeEntry> {
+	return new Map(flattenTree(tree));
+}
+
+function sortedDifference(left: Set<string>, right: Set<string>): string[] {
+	return [...left].filter((path) => !right.has(path)).sort();
+}
+
+export function treeEntryFromYaml(value: unknown): TreeEntry {
+	if (typeof value === "string") {
+		return makeTreeEntry({ description: value });
+	}
+	if (typeof value === "number" || typeof value === "boolean") {
+		return makeTreeEntry({ description: String(value) });
+	}
+	if (!isRecord(value)) {
+		throw new TreedocsError("Invalid tree entry in treedocs.yaml.");
+	}
+
+	const reservedLeafKeys = new Set(["_description", "_references", "_link"]);
+	const hasDirectoryMarker = Object.hasOwn(value, "_doc");
+	const childKeys = Object.keys(value).filter(
+		(key) => !reservedLeafKeys.has(key) && key !== "_doc",
+	);
+	const isDirectory = hasDirectoryMarker || childKeys.length > 0;
+
+	if (isDirectory) {
+		const children: Tree = {};
+		for (const childKey of childKeys) {
+			insertEntry(
+				treeEntryFromYaml(value[childKey]),
+				relativePathComponents(childKey),
+				children,
+			);
+		}
+		return makeTreeEntry({
+			documentation: documentationFromYaml(value._doc),
+			link: parseString(value._link),
+			children,
+			isDirectory: true,
+		});
+	}
+
+	return makeTreeEntry({
+		documentation: documentationFromYaml(value),
+		link: parseString(value._link),
+	});
+}
+
+export function documentationFromYaml(
+	value: unknown,
+): EntryDocumentation | undefined {
+	if (value === undefined || value === null) {
+		return undefined;
+	}
+	if (
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	) {
+		return makeDocumentation(String(value));
+	}
+	if (!isRecord(value)) {
+		throw new TreedocsError("Invalid documentation entry in treedocs.yaml.");
+	}
+	return makeDocumentation(
+		parseString(value._description),
+		parseStringArray(value._references) ?? [],
+	);
+}
+
+export function treeEntryToYamlValue(entry: TreeEntry): unknown {
+	if (entry.isDirectory) {
+		const mapping: Record<string, unknown> = {};
+		if (!documentationIsEmpty(entry.documentation)) {
+			mapping._doc = documentationToYamlValue(entry.documentation);
+		}
+		if (entry.link) {
+			mapping._link = entry.link;
+		}
+		for (const key of Object.keys(entry.children).sort()) {
+			mapping[key] = treeEntryToYamlValue(entry.children[key]);
+		}
+		return mapping;
+	}
+
+	if (!entry.link && entryReferences(entry).length === 0) {
+		const description = entryDescription(entry);
+		if (description !== undefined) {
+			return description;
+		}
+	}
+
+	const mapping: Record<string, unknown> = {};
+	const description = entryDescription(entry);
+	if (description !== undefined) {
+		mapping._description = description;
+	}
+	const references = entryReferences(entry);
+	if (references.length > 0) {
+		mapping._references = references;
+	}
+	if (entry.link) {
+		mapping._link = entry.link;
+	}
+	return mapping;
+}
+
+function documentationToYamlValue(
+	documentation: EntryDocumentation | undefined,
+): unknown {
+	if (!documentation) {
+		return undefined;
+	}
+	if (
+		documentation.references.length === 0 &&
+		documentation.description !== undefined
+	) {
+		return documentation.description;
+	}
+	const mapping: Record<string, unknown> = {};
+	if (documentation.description !== undefined) {
+		mapping._description = documentation.description;
+	}
+	if (documentation.references.length > 0) {
+		mapping._references = documentation.references;
+	}
+	return mapping;
+}
+
+export function treedocsFileFromYaml(yaml: string): TreedocsFile {
+	if (yaml.trim().length === 0) {
+		return {
+			schemaVersion: currentSchemaVersion,
+			project: {},
+			tree: {},
+		};
+	}
+
+	const parsed = parse(yaml) as unknown;
+	if (parsed === null || parsed === undefined) {
+		return {
+			schemaVersion: currentSchemaVersion,
+			project: {},
+			tree: {},
+		};
+	}
+	if (!isRecord(parsed)) {
+		throw new TreedocsError("treedocs.yaml must contain a root mapping.");
+	}
+
+	const tree: Tree = {};
+	if (isRecord(parsed.tree)) {
+		for (const [key, value] of Object.entries(parsed.tree)) {
+			insertEntry(treeEntryFromYaml(value), relativePathComponents(key), tree);
+		}
+	}
+
+	return {
+		schemaVersion: parseString(parsed.schema_version) ?? currentSchemaVersion,
+		project: projectMetadataFromYaml(parsed.project),
+		overrides: configFromYaml(parsed.overrides),
+		signature: parseString(parsed.signature),
+		tree,
+	};
+}
+
+export function treedocsFileToYaml(file: TreedocsFile): string {
+	const root: Record<string, unknown> = {
+		schema_version: file.schemaVersion || currentSchemaVersion,
+	};
+
+	if (!projectMetadataIsEmpty(file.project)) {
+		root.project = projectMetadataToYamlValue(file.project);
+	}
+
+	const overrides = configToYamlValue(file.overrides);
+	if (Object.keys(overrides).length > 0) {
+		root.overrides = overrides;
+	}
+
+	if (file.signature) {
+		root.signature = file.signature;
+	}
+
+	const tree: Record<string, unknown> = {};
+	for (const key of Object.keys(file.tree).sort()) {
+		tree[key] = treeEntryToYamlValue(file.tree[key]);
+	}
+	root.tree = tree;
+
+	return stringify(root, { indent: 2, lineWidth: 0 });
+}
+
+export function serializedTreedocsDocument(file: TreedocsFile): string {
+	return `# yaml-language-server: $schema=${schemaUrl}\n${treedocsFileToYaml(file)}`;
+}
+
+function projectMetadataFromYaml(value: unknown): ProjectMetadata {
+	if (typeof value === "string" && value.trim().length > 0) {
+		return { name: value };
+	}
+	if (!isRecord(value)) {
+		return {};
+	}
+
+	const project: ProjectMetadata = {};
+	for (const [key, rawValue] of Object.entries(value)) {
+		const parsed = parseString(rawValue);
+		if (parsed !== undefined) {
+			project[key] = parsed;
+		}
+	}
+
+	project.name = trimmedNilIfEmpty(project.name);
+	project.version = trimmedNilIfEmpty(project.version);
+	project.last_updated = trimmedNilIfEmpty(project.last_updated);
+	return project;
+}
+
+function projectMetadataIsEmpty(project: ProjectMetadata): boolean {
+	return Object.values(project).every((value) => value === undefined);
+}
+
+function projectMetadataToYamlValue(
+	project: ProjectMetadata,
+): Record<string, string> {
+	const mapping: Record<string, string> = {};
+	for (const key of ["name", "version", "last_updated"]) {
+		const value = project[key];
+		if (value !== undefined) {
+			mapping[key] = value;
+		}
+	}
+	for (const key of Object.keys(project).sort()) {
+		if (key === "name" || key === "version" || key === "last_updated") {
+			continue;
+		}
+		const value = project[key];
+		if (value !== undefined) {
+			mapping[key] = value;
+		}
+	}
+	return mapping;
+}
+
+export function configFromYaml(value: unknown): TreedocsConfig | undefined {
+	if (value === undefined || value === null) {
+		return undefined;
+	}
+	if (!isRecord(value)) {
+		throw new TreedocsError("Invalid treedocs config: expected a mapping.");
+	}
+	return {
+		exclude: parseStringArray(value.exclude),
+		use_gitignore: parseBoolean(value.use_gitignore),
+		max_description_length: parseInteger(value.max_description_length),
+		indent_size: parseInteger(value.indent_size),
+		align_columns: parseBoolean(value.align_columns),
+		check_severity: parseSeverity(value.check_severity),
+		auto_init_empty: parseBoolean(value.auto_init_empty),
+		theme: parseString(value.theme),
+		icons: parseBoolean(value.icons),
+		ai_provider: parseString(value.ai_provider),
+		ai_model: parseString(value.ai_model),
+	};
+}
+
+export function configToYamlValue(
+	config: TreedocsConfig | undefined,
+): Record<string, unknown> {
+	const mapping: Record<string, unknown> = {};
+	if (!config) {
+		return mapping;
+	}
+	for (const key of [
+		"exclude",
+		"use_gitignore",
+		"max_description_length",
+		"indent_size",
+		"align_columns",
+		"check_severity",
+		"auto_init_empty",
+		"theme",
+		"icons",
+		"ai_provider",
+		"ai_model",
+	] as const) {
+		const value = config[key];
+		if (value !== undefined) {
+			mapping[key] = value;
+		}
+	}
+	return mapping;
+}
+
+export function mergeConfig(
+	base: TreedocsConfig,
+	overrides: TreedocsConfig | undefined,
+): TreedocsConfig {
+	return {
+		...base,
+		...Object.fromEntries(
+			Object.entries(overrides ?? {}).filter(
+				([, value]) => value !== undefined,
+			),
+		),
+	};
+}
+
+export function resolveConfig(config: TreedocsConfig): ResolvedTreedocsConfig {
+	return {
+		exclude: config.exclude ?? defaultConfig.exclude,
+		use_gitignore: config.use_gitignore ?? defaultConfig.use_gitignore,
+		max_description_length:
+			config.max_description_length ?? defaultConfig.max_description_length,
+		indent_size: config.indent_size ?? defaultConfig.indent_size,
+		align_columns: config.align_columns ?? defaultConfig.align_columns,
+		check_severity: config.check_severity ?? defaultConfig.check_severity,
+		auto_init_empty: config.auto_init_empty ?? defaultConfig.auto_init_empty,
+		theme: config.theme,
+		icons: config.icons ?? defaultConfig.icons,
+		ai_provider: config.ai_provider,
+		ai_model: config.ai_model,
+	};
+}
+
+export async function loadConfiguration(
+	root: string,
+	stateOverrides?: TreedocsConfig,
+	globalConfigPath = defaultGlobalConfigPath(),
+): Promise<LoadedConfiguration> {
+	const repositoryPaths = pathsForRoot(root);
+	const globalConfig = await loadConfigIfExists(globalConfigPath);
+	const projectConfig = await loadConfigIfExists(repositoryPaths.projectConfig);
+	const config = resolveConfig(
+		mergeConfig(
+			mergeConfig(defaultConfig, globalConfig),
+			mergeConfig(projectConfig ?? {}, stateOverrides),
+		),
+	);
+	const ignorePatterns = [
+		...config.exclude,
+		...(config.use_gitignore
+			? await loadIgnoreFileIfExists(repositoryPaths.gitignore)
+			: []),
+		...(await loadIgnoreFileIfExists(repositoryPaths.projectIgnore)),
+	];
+
+	return { config, ignorePatterns };
+}
+
+async function loadConfigIfExists(
+	path: string | undefined,
+): Promise<TreedocsConfig | undefined> {
+	if (!path || !(await pathExists(path))) {
+		return undefined;
+	}
+	return configFromYaml(parse(await readFile(path, "utf8")));
+}
+
+async function loadIgnoreFileIfExists(path: string): Promise<string[]> {
+	if (!(await pathExists(path))) {
+		return [];
+	}
+	return (await readFile(path, "utf8"))
+		.split(/\r?\n/u)
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+
+function defaultGlobalConfigPath(): string | undefined {
+	const home = process.env.HOME;
+	return home ? join(home, ".config/treedocs/config.yaml") : undefined;
+}
+
+export class IgnoreMatcher {
+	constructor(private readonly patterns: string[]) {}
+
+	shouldIgnore(relativePath: string, isDirectory: boolean): boolean {
+		const normalized = normalizeRelativePath(relativePath);
+		if (!normalized) {
+			return false;
+		}
+
+		const components = normalized.split("/");
+		if (components.some((component) => standardExcludedNames.has(component))) {
+			return true;
+		}
+
+		let ignored = false;
+		for (const pattern of this.patterns) {
+			const rawPattern = trimmedNilIfEmpty(pattern);
+			if (!rawPattern) {
+				continue;
+			}
+			const isNegated = rawPattern.startsWith("!");
+			const effectivePattern = isNegated ? rawPattern.slice(1) : rawPattern;
+			if (
+				matchesIgnorePattern(
+					effectivePattern,
+					normalized,
+					components.at(-1) ?? "",
+					isDirectory,
+				)
+			) {
+				ignored = !isNegated;
+			}
+		}
+		return ignored;
+	}
+}
+
+function matchesIgnorePattern(
+	pattern: string,
+	path: string,
+	basenameValue: string,
+	isDirectory: boolean,
+): boolean {
+	const rawPattern = trimmedNilIfEmpty(pattern);
+	if (!rawPattern) {
+		return false;
+	}
+
+	const directoryPattern = rawPattern.endsWith("/");
+	const unwrapped = directoryPattern ? rawPattern.slice(0, -1) : rawPattern;
+	const anchored = unwrapped.startsWith("/");
+	const normalizedPattern = anchored ? unwrapped.slice(1) : unwrapped;
+
+	if (directoryPattern && !isDirectory && path === normalizedPattern) {
+		return false;
+	}
+
+	if (containsGlob(normalizedPattern)) {
+		if (globMatches(normalizedPattern, path)) {
+			return true;
+		}
+		if (!anchored && globMatches(normalizedPattern, basenameValue)) {
+			return true;
+		}
+	}
+
+	if (anchored) {
+		return (
+			path === normalizedPattern || path.startsWith(`${normalizedPattern}/`)
+		);
+	}
+
+	if (normalizedPattern.includes("/")) {
+		return (
+			path === normalizedPattern ||
+			path.startsWith(`${normalizedPattern}/`) ||
+			path.endsWith(`/${normalizedPattern}`)
+		);
+	}
+
+	return (
+		basenameValue === normalizedPattern ||
+		path.split("/").includes(normalizedPattern)
+	);
+}
+
+function containsGlob(pattern: string): boolean {
+	return pattern.includes("*") || pattern.includes("?");
+}
+
+function globMatches(pattern: string, value: string): boolean {
+	const expression = pattern
+		.split("")
+		.map((character) => {
+			if (character === "*") {
+				return "[^/]*";
+			}
+			if (character === "?") {
+				return "[^/]";
+			}
+			return character.replace(/[|\\{}()[\]^$+?.]/gu, "\\$&");
+		})
+		.join("");
+	return new RegExp(`^${expression}$`, "u").test(value);
+}
+
+export async function scanTree(
+	root: string,
+	ignoreMatcher: IgnoreMatcher,
+): Promise<TreeScanResult> {
+	const nestedBoundaries: string[] = [];
+	const tree = await buildTree(root, "", ignoreMatcher, nestedBoundaries);
+	const normalizedPaths = collectNormalizedPaths(tree);
+	return {
+		tree,
+		normalizedPaths,
+		nestedBoundaries: nestedBoundaries.sort(),
+		signature: treeSignature(normalizedPaths),
+	};
+}
+
+async function buildTree(
+	root: string,
+	relativePath: string,
+	ignoreMatcher: IgnoreMatcher,
+	nestedBoundaries: string[],
+): Promise<Tree> {
+	const absolutePath = relativePath ? join(root, relativePath) : root;
+	const childNames = (await readdir(absolutePath)).sort();
+	const result: Tree = {};
+
+	for (const childName of childNames) {
+		const childRelativePath = relativePath
+			? `${relativePath}/${childName}`
+			: childName;
+		const childAbsolutePath = join(root, childRelativePath);
+		const stats = await lstat(childAbsolutePath);
+		const isDirectory = stats.isDirectory();
+
+		if (ignoreMatcher.shouldIgnore(childRelativePath, isDirectory)) {
+			continue;
+		}
+
+		if (isDirectory) {
+			if (existsSync(join(childAbsolutePath, stateFileName))) {
+				nestedBoundaries.push(childRelativePath);
+				result[childName] = makeTreeEntry({
+					description: "",
+					children: {},
+					isDirectory: true,
+				});
+				continue;
+			}
+			result[childName] = makeTreeEntry({
+				description: "",
+				children: await buildTree(
+					root,
+					childRelativePath,
+					ignoreMatcher,
+					nestedBoundaries,
+				),
+				isDirectory: true,
+			});
+			continue;
+		}
+
+		result[childName] = makeTreeEntry({ description: "" });
+	}
+
+	return result;
+}
+
+export async function resolveRepositoryPaths(
+	rootPath: string,
+): Promise<RepositoryPaths> {
+	const root = resolve(rootPath);
+	let stats: Awaited<ReturnType<typeof lstat>>;
+	try {
+		stats = await lstat(root);
+	} catch {
+		throw new TreedocsError(`Path does not exist: ${root}`);
+	}
+	if (!stats.isDirectory()) {
+		throw new TreedocsError(`Path is not a directory: ${root}`);
+	}
+	return pathsForRoot(root);
+}
+
+function pathsForRoot(root: string): RepositoryPaths {
+	return {
+		root,
+		stateFile: join(root, stateFileName),
+		projectConfig: join(root, ".treedocs/config.yaml"),
+		projectIgnore: join(root, ".treedocs/.treedocs_ignore"),
+		gitignore: join(root, ".gitignore"),
+	};
+}
+
+export async function loadTreedocsFile(path: string): Promise<TreedocsFile> {
+	if (!(await pathExists(path))) {
+		throw new TreedocsError(
+			`Missing treedocs state file at ${path}. Run \`treedocs init\` first.`,
+		);
+	}
+	const yaml = await readFile(path, "utf8");
+	validateTreedocsYaml(yaml);
+	return treedocsFileFromYaml(yaml);
+}
+
+export async function loadTreedocsFileWithoutValidation(
+	path: string,
+): Promise<TreedocsFile> {
+	return treedocsFileFromYaml(await readFile(path, "utf8"));
+}
+
+export async function saveTreedocsFile(
+	file: TreedocsFile,
+	path: string,
+): Promise<void> {
+	const document = serializedTreedocsDocument(file);
+	validateTreedocsYaml(document);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, document, "utf8");
+}
+
+let validateSchema: ReturnType<Ajv2020["compile"]> | undefined;
+
+export function validateTreedocsYaml(yaml: string): void {
+	const parsed = parse(yaml) as unknown;
+	if (!isRecord(parsed)) {
+		throw new TreedocsError(
+			"Schema validation failed: # must be an object with project, signature, and tree.",
+		);
+	}
+
+	const schemaVersion = parseString(parsed.schema_version);
+	if (!schemaVersion) {
+		throw new TreedocsError(
+			"Schema validation failed: missing required root schema_version.",
+		);
+	}
+	if (schemaVersion !== currentSchemaVersion) {
+		throw new TreedocsError(
+			`Unsupported treedocs.yaml schema_version "${schemaVersion}". This CLI supports: ${currentSchemaVersion}.`,
+		);
+	}
+
+	const validator = getSchemaValidator();
+	if (!validator(parsed)) {
+		throw new TreedocsError(
+			`Schema validation failed: ${formatValidationErrors(
+				validator.errors ?? [],
+			)}`,
+		);
+	}
+}
+
+function getSchemaValidator(): ReturnType<Ajv2020["compile"]> {
+	if (validateSchema) {
+		return validateSchema;
+	}
+	const ajv = new Ajv2020({ allErrors: true, strict: false });
+	addFormats(ajv);
+	validateSchema = ajv.compile(JSON.parse(readBundledSchema()));
+	return validateSchema;
+}
+
+function readBundledSchema(): string {
+	const candidates = [
+		join(import.meta.dir, "../site/schemas/0.2.0/treedocs.schema.json"),
+		join(process.cwd(), "site/schemas/0.2.0/treedocs.schema.json"),
+	];
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) {
+			return readFileSync(candidate, "utf8");
+		}
+	}
+	throw new TreedocsError(
+		'Unable to find bundled canonical schema for schema_version "0.2.0".',
+	);
+}
+
+function formatValidationErrors(
+	errors: NonNullable<ReturnType<Ajv2020["compile"]>["errors"]>,
+): string {
+	if (errors.length === 0) {
+		return "document does not match the bundled treedocs schema.";
+	}
+	return errors
+		.map((error) => {
+			const location = error.instancePath ? `#${error.instancePath}` : "#";
+			return `${location}: ${error.message ?? "invalid value"}`;
+		})
+		.join("; ");
+}
+
+export async function schemaValidationErrors(path: string): Promise<string[]> {
+	try {
+		validateTreedocsYaml(await readFile(path, "utf8"));
+		return [];
+	} catch (error) {
+		return [error instanceof Error ? error.message : String(error)];
+	}
+}
+
+export function resolveLink(path: string, tree: Tree): LinkResolution {
+	const startingEntry = entryAt(path, tree);
+	if (!startingEntry?.link) {
+		return { type: "none" };
+	}
+	if (isExternalLink(startingEntry.link)) {
+		return { type: "external", url: startingEntry.link };
+	}
+
+	const visited = new Set([path]);
+	const chain = [path];
+	let currentPath = resolveLinkTarget(startingEntry.link, path);
+
+	while (true) {
+		chain.push(currentPath);
+		const currentEntry = entryAt(currentPath, tree);
+		if (!currentEntry) {
+			return { type: "broken", target: currentPath, chain };
+		}
+
+		if (!currentEntry.link) {
+			return {
+				type: "resolved",
+				path: currentPath,
+				chain,
+				entry: currentEntry,
+			};
+		}
+
+		if (isExternalLink(currentEntry.link)) {
+			return { type: "external", url: currentEntry.link };
+		}
+		if (visited.has(currentPath)) {
+			return { type: "cycle", chain };
+		}
+
+		visited.add(currentPath);
+		currentPath = resolveLinkTarget(currentEntry.link, currentPath);
+	}
+}
+
+function isExternalLink(link: string): boolean {
+	return link.startsWith("http://") || link.startsWith("https://");
+}
+
+export class TreeRenderer {
+	render(
+		tree: Tree,
+		options: {
+			subtreePath?: string;
+			config: ResolvedTreedocsConfig;
+			statusOverrides?: Record<string, EntryStatus>;
+		},
+	): string {
+		const subtreePath = trimmedNilIfEmpty(
+			options.subtreePath
+				? normalizeRelativePath(options.subtreePath)
+				: undefined,
+		);
+		const statusOverrides = options.statusOverrides ?? {};
+		const rootLabel: string =
+			subtreePath && entryAt(subtreePath, tree)?.isDirectory
+				? `${subtreePath}/`
+				: (subtreePath ?? ".");
+		const rootEntry = subtreePath ? entryAt(subtreePath, tree) : undefined;
+		if (subtreePath && !rootEntry) {
+			throw new TreedocsError(
+				`Path not found in treedocs tree: ${subtreePath}`,
+			);
+		}
+
+		const renderedTree = rootEntry?.isDirectory
+			? rootEntry.children
+			: subtreePath
+				? {}
+				: tree;
+		const rootPath = subtreePath ?? "";
+		const rows = [
+			this.rootRow(
+				rootLabel,
+				rootEntry,
+				rootPath,
+				options.config,
+				statusOverrides,
+			),
+			...this.flattenForRender(
+				renderedTree,
+				"",
+				rootPath,
+				options.config,
+				statusOverrides,
+			),
+		];
+		return this.renderRows(rows, options.config);
+	}
+
+	renderExploration(
+		tree: Tree,
+		options: {
+			expandedPaths: string[];
+			config: ResolvedTreedocsConfig;
+			statusOverrides?: Record<string, EntryStatus>;
+		},
+	): string {
+		const normalizedPaths =
+			options.expandedPaths.length === 0
+				? [""]
+				: options.expandedPaths.map(normalizeRelativePath);
+		const expandedPathSet = new Set(normalizedPaths);
+		for (const path of expandedPathSet) {
+			if (!entryAt(path, tree)) {
+				throw new TreedocsError(`Path not found in treedocs tree: ${path}`);
+			}
+		}
+
+		const hint =
+			"Expand collapsed folders with `treedocs explore <subpath> [subpath ...]`.";
+		const rows: RenderRow[] = [
+			{ label: hint, visibleLabelLength: hint.length },
+			this.rootRow(
+				".",
+				undefined,
+				"",
+				options.config,
+				options.statusOverrides ?? {},
+			),
+			...this.flattenForExploration(
+				tree,
+				"",
+				"",
+				expandedPathSet,
+				options.config,
+				options.statusOverrides ?? {},
+			),
+		];
+		return this.renderRows(rows, options.config);
+	}
+
+	private renderRows(
+		rows: RenderRow[],
+		config: ResolvedTreedocsConfig,
+	): string {
+		const labelWidth = config.align_columns
+			? Math.max(...rows.map((row) => row.visibleLabelLength), 0)
+			: 0;
+		return rows
+			.map((row) => {
+				const padding = config.align_columns
+					? " ".repeat(Math.max(labelWidth - row.visibleLabelLength, 0))
+					: "";
+				return row.description
+					? `${row.label}${padding}  ${row.description}`
+					: row.label;
+			})
+			.join("\n");
+	}
+
+	private rootRow(
+		label: string,
+		entry: TreeEntry | undefined,
+		path: string,
+		config: ResolvedTreedocsConfig,
+		statusOverrides: Record<string, EntryStatus>,
+	): RenderRow {
+		const status =
+			statusOverrides[path] ?? (entry ? entryStatus(entry, config) : "clean");
+		const decorated = decorateLabel(statusLabel(label, status), entry);
+		const plain = decorateLabel(statusLabel(label, status), entry);
+		return {
+			label: decorated,
+			visibleLabelLength: plain.length,
+			description: entry ? descriptionText(entry, config) : undefined,
+		};
+	}
+
+	private flattenForRender(
+		tree: Tree,
+		prefix: string,
+		pathPrefix: string,
+		config: ResolvedTreedocsConfig,
+		statusOverrides: Record<string, EntryStatus>,
+	): RenderRow[] {
+		const lines: RenderRow[] = [];
+		const keys = Object.keys(tree).sort();
+		for (const [index, key] of keys.entries()) {
+			const entry = tree[key];
+			const isLast = index === keys.length - 1;
+			const connector = isLast ? "└── " : "├── ";
+			const childPrefix = prefix + (isLast ? "    " : "│   ");
+			const path = pathPrefix ? `${pathPrefix}/${key}` : key;
+			const marker = entry.isDirectory ? `${key}/` : key;
+			const status = statusOverrides[path] ?? entryStatus(entry, config);
+			const label = statusLabel(marker, status);
+			const decorated = decorateLabel(label, entry);
+			lines.push({
+				label: prefix + connector + decorated,
+				visibleLabelLength: (prefix + connector + decorateLabel(label, entry))
+					.length,
+				description: descriptionText(entry, config),
+			});
+			if (entry.isDirectory) {
+				lines.push(
+					...this.flattenForRender(
+						entry.children,
+						childPrefix,
+						path,
+						config,
+						statusOverrides,
+					),
+				);
+			}
+		}
+		return lines;
+	}
+
+	private flattenForExploration(
+		tree: Tree,
+		prefix: string,
+		pathPrefix: string,
+		expandedPaths: Set<string>,
+		config: ResolvedTreedocsConfig,
+		statusOverrides: Record<string, EntryStatus>,
+	): RenderRow[] {
+		const lines: RenderRow[] = [];
+		const keys = visibleExplorationKeys(tree, pathPrefix, expandedPaths);
+		for (const [index, key] of keys.entries()) {
+			const entry = tree[key];
+			const isLast = index === keys.length - 1;
+			const connector = isLast ? "└── " : "├── ";
+			const childPrefix = prefix + (isLast ? "    " : "│   ");
+			const path = pathPrefix ? `${pathPrefix}/${key}` : key;
+			const marker = entry.isDirectory ? `${key}/` : key;
+			const status = statusOverrides[path] ?? entryStatus(entry, config);
+			const shouldDescend =
+				entry.isDirectory &&
+				shouldDescendDuringExploration(path, expandedPaths);
+			const countSuffix =
+				entry.isDirectory && !shouldDescend
+					? ` ${collapsedItemCount(entry)}`
+					: "";
+			const label = `${decorateLabel(statusLabel(marker, status), entry)}${countSuffix}`;
+			lines.push({
+				label: prefix + connector + label,
+				visibleLabelLength: (prefix + connector + label).length,
+				description: descriptionText(entry, config),
+			});
+			if (shouldDescend) {
+				lines.push(
+					...this.flattenForExploration(
+						entry.children,
+						childPrefix,
+						path,
+						expandedPaths,
+						config,
+						statusOverrides,
+					),
+				);
+			}
+		}
+		return lines;
+	}
+}
+
+interface RenderRow {
+	label: string;
+	visibleLabelLength: number;
+	description?: string;
+}
+
+function entryStatus(
+	entry: TreeEntry,
+	config: ResolvedTreedocsConfig,
+): EntryStatus {
+	if (!entryNeedsDescription(entry)) {
+		return "clean";
+	}
+	return config.check_severity === "warn" ? "warning" : "error";
+}
+
+function statusLabel(label: string, status: EntryStatus): string {
+	switch (status) {
+		case "warning":
+			return `? ${label}`;
+		case "error":
+			return `! ${label}`;
+		default:
+			return label;
+	}
+}
+
+function decorateLabel(label: string, entry: TreeEntry | undefined): string {
+	const suffixes: string[] = [];
+	if (entryHasReferences(entry ?? makeTreeEntry({}))) {
+		suffixes.push("[ref]");
+	}
+	if (entry?.link) {
+		suffixes.push(`[link->${entry.link}]`);
+	}
+	return suffixes.length === 0 ? label : `${label} ${suffixes.join(" ")}`;
+}
+
+function descriptionText(
+	entry: TreeEntry,
+	config: ResolvedTreedocsConfig,
+): string | undefined {
+	const description = entryDescription(entry);
+	if (description === undefined) {
+		return undefined;
+	}
+	const maxLength = Math.max(config.max_description_length, 0);
+	if (maxLength === 0 || description.length <= maxLength) {
+		return description;
+	}
+	if (maxLength <= 3) {
+		return description.slice(0, maxLength);
+	}
+	return `${description.slice(0, maxLength - 3)}...`;
+}
+
+function visibleExplorationKeys(
+	tree: Tree,
+	pathPrefix: string,
+	expandedPaths: Set<string>,
+): string[] {
+	const keys = Object.keys(tree).sort();
+	if (!pathPrefix || expandedPaths.has(pathPrefix)) {
+		return keys;
+	}
+	return keys.filter((key) => {
+		const childPath = `${pathPrefix}/${key}`;
+		return (
+			expandedPaths.has(childPath) ||
+			[...expandedPaths].some((path) => path.startsWith(`${childPath}/`))
+		);
+	});
+}
+
+function shouldDescendDuringExploration(
+	path: string,
+	expandedPaths: Set<string>,
+): boolean {
+	return (
+		expandedPaths.has(path) ||
+		[...expandedPaths].some((expandedPath) =>
+			expandedPath.startsWith(`${path}/`),
+		)
+	);
+}
+
+function collapsedItemCount(entry: TreeEntry): string {
+	const count = Object.keys(entry.children).length;
+	return `(${count} ${count === 1 ? "item" : "items"})`;
+}
+
+export class TreedocsService {
+	constructor(private readonly globalConfigPath?: string) {}
+
+	async initialize(rootPath: string, force: boolean): Promise<TreedocsFile> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		if ((await pathExists(repositoryPaths.stateFile)) && !force) {
+			throw new TreedocsError(
+				"treedocs.yaml already exists. Re-run with `--force` to overwrite it.",
+			);
+		}
+
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			undefined,
+			this.globalConfigPath,
+		);
+		const scan = await scanTree(
+			repositoryPaths.root,
+			new IgnoreMatcher(loaded.ignorePatterns),
+		);
+		const file: TreedocsFile = {
+			schemaVersion: currentSchemaVersion,
+			project: {
+				name: basename(repositoryPaths.root),
+				version: "0.0.0",
+				last_updated: currentDateString(),
+			},
+			signature: scan.signature,
+			tree: scan.tree,
+		};
+		await saveTreedocsFile(file, repositoryPaths.stateFile);
+		return file;
+	}
+
+	async sync(rootPath: string): Promise<TreedocsFile> {
+		return (await this.syncResult(rootPath)).file;
+	}
+
+	async syncResult(rootPath: string): Promise<SyncResult> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const current = await loadTreedocsFile(repositoryPaths.stateFile);
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			current.overrides,
+			this.globalConfigPath,
+		);
+		const scan = await scanTree(
+			repositoryPaths.root,
+			new IgnoreMatcher(loaded.ignorePatterns),
+		);
+		const changes: SyncChanges = {
+			addedPaths: missingPaths(current.tree, scan.tree),
+			removedPaths: extraPaths(current.tree, scan.tree),
+			changedTypePaths: changedPaths(current.tree, scan.tree),
+		};
+		const merged: TreedocsFile = {
+			schemaVersion: current.schemaVersion,
+			project: current.project,
+			overrides: current.overrides,
+			signature: scan.signature,
+			tree: mergePreservingMetadata(scan.tree, current.tree),
+		};
+		await saveTreedocsFile(merged, repositoryPaths.stateFile);
+		return {
+			file: merged,
+			saved: true,
+			signatureUnchanged: current.signature === scan.signature,
+			changes,
+			missingDescriptions: missingDescriptionPaths(merged.tree),
+		};
+	}
+
+	async check(rootPath: string): Promise<CheckReport> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const schemaErrors = await schemaValidationErrors(
+			repositoryPaths.stateFile,
+		);
+		const current = await loadTreedocsFileWithoutValidation(
+			repositoryPaths.stateFile,
+		);
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			current.overrides,
+			this.globalConfigPath,
+		);
+		const scan = await scanTree(
+			repositoryPaths.root,
+			new IgnoreMatcher(loaded.ignorePatterns),
+		);
+		return makeCheckReport({
+			schemaWarnings: [],
+			schemaErrors,
+			storedSignature: current.signature,
+			currentSignature: scan.signature,
+			missingDescriptions: missingDescriptionPaths(current.tree),
+			missingPaths: missingPaths(current.tree, scan.tree),
+			extraPaths: extraPaths(current.tree, scan.tree),
+			changedPaths: changedPaths(current.tree, scan.tree),
+			nestedBoundaries: scan.nestedBoundaries,
+			shadowedPaths: shadowedPaths(current.tree, scan.nestedBoundaries),
+			severity: loaded.config.check_severity,
+		});
+	}
+
+	async inspect(
+		rootPath: string,
+		path: string,
+		recursive: boolean,
+	): Promise<InspectReport> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const file = await loadTreedocsFile(repositoryPaths.stateFile);
+		const normalizedPath = normalizeRelativePath(path);
+		const entry = entryAt(normalizedPath, file.tree);
+		if (!entry) {
+			throw new TreedocsError(
+				`Path not found in treedocs tree: ${normalizedPath}`,
+			);
+		}
+
+		let recursiveOutput: string | undefined;
+		if (recursive && entry.isDirectory) {
+			const loaded = await loadConfiguration(
+				repositoryPaths.root,
+				file.overrides,
+				this.globalConfigPath,
+			);
+			recursiveOutput = new TreeRenderer().render(file.tree, {
+				subtreePath: normalizedPath,
+				config: loaded.config,
+			});
+		}
+
+		return {
+			path: normalizedPath,
+			entry,
+			linkResolution: resolveLink(normalizedPath, file.tree),
+			recursiveOutput,
+		};
+	}
+
+	async update(
+		rootPath: string,
+		options: {
+			path: string;
+			description?: string;
+			addReferences: string[];
+			removeReferences: string[];
+			link?: string;
+			clearLink: boolean;
+		},
+	): Promise<TreedocsFile> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const file = await loadTreedocsFile(repositoryPaths.stateFile);
+		const normalizedPath = normalizeRelativePath(options.path);
+		const updated = updateEntry(normalizedPath, file.tree, (entry) => {
+			const description =
+				options.description === undefined
+					? entryDescription(entry)
+					: trimmedNilIfEmpty(options.description);
+			const references = [...entryReferences(entry)];
+			for (const reference of options.addReferences) {
+				if (!references.includes(reference)) {
+					references.push(reference);
+				}
+			}
+			const remainingReferences = references.filter(
+				(reference) => !options.removeReferences.includes(reference),
+			);
+			entry.documentation = makeDocumentation(description, remainingReferences);
+
+			if (options.clearLink) {
+				entry.link = undefined;
+			} else if (options.link !== undefined) {
+				entry.link = trimmedNilIfEmpty(options.link);
+			}
+		});
+
+		if (!updated) {
+			throw new TreedocsError(
+				`Path not found in treedocs tree: ${normalizedPath}`,
+			);
+		}
+
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			file.overrides,
+			this.globalConfigPath,
+		);
+		const scan = await scanTree(
+			repositoryPaths.root,
+			new IgnoreMatcher(loaded.ignorePatterns),
+		);
+		file.signature = scan.signature;
+		await saveTreedocsFile(file, repositoryPaths.stateFile);
+		return file;
+	}
+
+	async renderTree(
+		rootPath: string,
+		subtreePath?: string,
+		fullDescriptions = false,
+	): Promise<string> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const file = await loadTreedocsFile(repositoryPaths.stateFile);
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			file.overrides,
+			this.globalConfigPath,
+		);
+		return new TreeRenderer().render(file.tree, {
+			subtreePath,
+			config: renderConfig(loaded.config, fullDescriptions),
+		});
+	}
+
+	async explore(
+		rootPath: string,
+		expandedPaths: string[],
+		fullDescriptions = false,
+	): Promise<string> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const file = await loadTreedocsFile(repositoryPaths.stateFile);
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			file.overrides,
+			this.globalConfigPath,
+		);
+		return new TreeRenderer().renderExploration(file.tree, {
+			expandedPaths,
+			config: renderConfig(loaded.config, fullDescriptions),
+		});
+	}
+
+	async show(
+		rootPath: string,
+		path: string,
+		checkFirst: boolean,
+		fullDescriptions = false,
+	): Promise<string> {
+		const lines: string[] = [];
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const file = await loadTreedocsFile(repositoryPaths.stateFile);
+		const loaded = await loadConfiguration(
+			repositoryPaths.root,
+			file.overrides,
+			this.globalConfigPath,
+		);
+		const normalizedPath = normalizeRelativePath(path);
+		let displayTree = file.tree;
+		const statusOverrides: Record<string, EntryStatus> = {};
+
+		if (checkFirst) {
+			const report = await this.check(rootPath);
+			if (report.hasIssues) {
+				const subtreeHasIssues = hasScopedIssues(report, normalizedPath);
+				lines.push(
+					scopedDiscrepancyText(normalizedPath, subtreeHasIssues, file.tree),
+				);
+				if (report.hasSignatureDrift) {
+					const scan = await scanTree(
+						repositoryPaths.root,
+						new IgnoreMatcher(loaded.ignorePatterns),
+					);
+					displayTree = mergePreservingMetadata(scan.tree, file.tree);
+					const status: EntryStatus =
+						report.severity === "warn" ? "warning" : "error";
+					for (const path of report.missingPaths) {
+						if (isPathInside(path, normalizedPath)) {
+							statusOverrides[path] = status;
+						}
+					}
+				}
+			} else {
+				lines.push("The treedocs below is up to date with the filesystem.");
+			}
+		}
+
+		const config = renderConfig(loaded.config, fullDescriptions);
+		const resolution = resolveLink(normalizedPath, file.tree);
+		if (resolution.type === "external") {
+			lines.push(
+				`External alias: ${displayPath(normalizedPath)} -> ${resolution.url}`,
+			);
+		} else if (resolution.type === "resolved") {
+			lines.push(
+				new TreeRenderer().render(displayTree, {
+					subtreePath: resolution.path,
+					config,
+					statusOverrides,
+				}),
+			);
+		} else if (resolution.type === "broken") {
+			throw new TreedocsError(
+				`Broken link: ${resolution.chain.join(" -> ")} (missing target: ${resolution.target})`,
+			);
+		} else if (resolution.type === "cycle") {
+			throw new TreedocsError(
+				`Link cycle detected: ${resolution.chain.join(" -> ")}`,
+			);
+		} else {
+			lines.push(
+				new TreeRenderer().render(displayTree, {
+					subtreePath: path,
+					config,
+					statusOverrides,
+				}),
+			);
+		}
+
+		return lines.join("\n");
+	}
+
+	async findPath(rootPath: string, query: string): Promise<string | undefined> {
+		const repositoryPaths = await resolveRepositoryPaths(rootPath);
+		const file = await loadTreedocsFile(repositoryPaths.stateFile);
+		return firstPathMatching(query, file.tree);
+	}
+}
+
+function renderConfig(
+	config: ResolvedTreedocsConfig,
+	fullDescriptions: boolean,
+): ResolvedTreedocsConfig {
+	return fullDescriptions ? { ...config, max_description_length: 0 } : config;
+}
+
+function makeCheckReport(
+	report: Omit<
+		CheckReport,
+		"hasSignatureDrift" | "hasIssues" | "shouldFail" | "requiresSyncBeforeFill"
+	>,
+): CheckReport {
+	const hasSignatureDrift = report.storedSignature !== report.currentSignature;
+	const hasIssues =
+		report.schemaErrors.length > 0 ||
+		hasSignatureDrift ||
+		report.missingDescriptions.length > 0 ||
+		report.missingPaths.length > 0 ||
+		report.extraPaths.length > 0 ||
+		report.changedPaths.length > 0 ||
+		report.shadowedPaths.length > 0;
+	const shouldFail = hasIssues && report.severity === "error";
+	const requiresSyncBeforeFill =
+		report.schemaErrors.length > 0 ||
+		hasSignatureDrift ||
+		report.missingPaths.length > 0 ||
+		report.extraPaths.length > 0 ||
+		report.changedPaths.length > 0 ||
+		report.shadowedPaths.length > 0;
+	return {
+		...report,
+		hasSignatureDrift,
+		hasIssues,
+		shouldFail,
+		requiresSyncBeforeFill,
+	};
+}
+
+function hasScopedIssues(report: CheckReport, subtreePath: string): boolean {
+	if (!subtreePath) {
+		return report.hasIssues;
+	}
+	return [
+		...report.missingDescriptions,
+		...report.missingPaths,
+		...report.extraPaths,
+		...report.changedPaths,
+		...report.shadowedPaths,
+	].some((path) => isPathInside(path, subtreePath));
+}
+
+function scopedDiscrepancyText(
+	subtreePath: string,
+	subtreeHasIssues: boolean,
+	tree: Tree,
+): string {
+	if (!subtreePath) {
+		return "Warning: treedocs discrepancies found. Run `treedocs check` for the full diagnostic report.";
+	}
+	if (subtreeHasIssues) {
+		return "Warning: this subtree has treedocs discrepancies. Run `treedocs check` for the full diagnostic report.";
+	}
+	return `Note: treedocs has drift elsewhere in this repo; \`${displayFocusedPath(
+		subtreePath,
+		tree,
+	)}\` is current. Run \`treedocs check\` or \`treedocs sync\`.`;
+}
+
+function isPathInside(path: string, subtreePath: string): boolean {
+	return (
+		!subtreePath || path === subtreePath || path.startsWith(`${subtreePath}/`)
+	);
+}
+
+function displayPath(path: string): string {
+	return path || ".";
+}
+
+function displayFocusedPath(path: string, tree: Tree): string {
+	const entry = entryAt(path, tree);
+	return entry?.isDirectory ? `${displayPath(path)}/` : displayPath(path);
+}
+
+function currentDateString(): string {
+	return new Date().toISOString().slice(0, 10);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}