treedocs 0.3.0

package/src/cli.ts

@@ -0,0 +1,650 @@
+#!/usr/bin/env bun
+import {
+	type CheckReport,
+	cliVersion,
+	entryDescription,
+	entryReferences,
+	missingDescriptionNextStep,
+	type SyncChanges,
+	stateFileName,
+	TreedocsError,
+	TreedocsService,
+} from "./core.ts";
+
+interface GlobalOptions {
+	path: string;
+	nonInteractive: boolean;
+}
+
+interface ParsedArguments {
+	command: string;
+	values: string[];
+	options: Map<string, string[]>;
+	globals: GlobalOptions;
+}
+
+const commands = new Set([
+	"init",
+	"sync",
+	"check",
+	"show",
+	"inspect",
+	"update",
+	"ls",
+	"explore",
+	"path",
+	"help",
+]);
+
+export async function main(
+	rawArguments = process.argv.slice(2),
+): Promise<number> {
+	try {
+		const rewrittenArguments = rewriteArguments(rawArguments);
+		if (rewrittenArguments.includes("--version")) {
+			console.log(cliVersion);
+			return 0;
+		}
+		if (
+			rewrittenArguments.length === 0 ||
+			rewrittenArguments[0] === "--help" ||
+			rewrittenArguments[0] === "-h" ||
+			rewrittenArguments[0] === "help"
+		) {
+			printRootHelp();
+			return 0;
+		}
+
+		const parsed = parseArguments(rewrittenArguments);
+		if (parsed.options.has("help") || parsed.options.has("h")) {
+			printCommandHelp(parsed.command);
+			return 0;
+		}
+
+		const service = new TreedocsService();
+		await runCommand(parsed, service);
+		return typeof process.exitCode === "number" ? process.exitCode : 0;
+	} catch (error) {
+		if (error instanceof TreedocsError) {
+			console.error(error.message);
+			return 1;
+		}
+		if (error instanceof Error) {
+			console.error(error.message);
+			return 1;
+		}
+		console.error(String(error));
+		return 1;
+	}
+}
+
+async function runCommand(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	switch (parsed.command) {
+		case "init":
+			await runInit(parsed, service);
+			return;
+		case "sync":
+			await runSync(parsed, service);
+			return;
+		case "check":
+			await runCheck(parsed, service);
+			return;
+		case "show":
+			await runShow(parsed, service);
+			return;
+		case "ls":
+			await runLs(parsed, service);
+			return;
+		case "explore":
+			await runExplore(parsed, service);
+			return;
+		case "inspect":
+			await runInspect(parsed, service);
+			return;
+		case "update":
+			await runUpdate(parsed, service);
+			return;
+		case "path":
+			await runPath(parsed, service);
+			return;
+		default:
+			throw new TreedocsError(`Unknown command: ${parsed.command}`);
+	}
+}
+
+async function runInit(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const file = await service.initialize(
+		parsed.globals.path,
+		hasFlag(parsed, "force"),
+	);
+	console.log(
+		`Initialized ${stateFileName} (${file.signature ?? "no signature"})`,
+	);
+}
+
+async function runSync(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	void parsed.globals.nonInteractive;
+	const result = await service.syncResult(parsed.globals.path);
+	if (result.signatureUnchanged) {
+		console.log("No change found.");
+	} else {
+		for (const message of changeSummaryMessages(result.changes)) {
+			console.log(message);
+		}
+	}
+	console.log(
+		`Synced ${stateFileName} (${result.file.signature ?? "no signature"})`,
+	);
+	for (const message of remainingIssueMessages(result.missingDescriptions)) {
+		console.log(message);
+	}
+}
+
+async function runCheck(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const report = await service.check(parsed.globals.path);
+	printSection("Schema warnings", report.schemaWarnings);
+	printSection("Schema validation failures", report.schemaErrors);
+
+	if (report.hasSignatureDrift) {
+		console.log(
+			`Stale tree: stored signature ${report.storedSignature ?? "<missing>"} does not match current signature ${report.currentSignature}`,
+		);
+	}
+
+	printSection("Missing paths", report.missingPaths);
+	printSection("Extra documented paths", report.extraPaths);
+	printSection("Changed paths", report.changedPaths);
+	printSection("Nested documentation boundaries", report.nestedBoundaries);
+	printSection("Shadowed child-owned paths", report.shadowedPaths);
+	printSection("Missing descriptions", report.missingDescriptions);
+
+	if (!report.hasIssues && report.schemaWarnings.length === 0) {
+		console.log("Tree is up to date.");
+		return;
+	}
+
+	printSection("Next steps", nextSteps(report));
+	if (report.shouldFail) {
+		process.exitCode = 1;
+	}
+}
+
+async function runShow(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const targetPath = parsed.values[0] ?? ".";
+	const output = await service.show(
+		parsed.globals.path,
+		targetPath,
+		!hasFlag(parsed, "no-check"),
+		hasFlag(parsed, "full-descriptions") || hasFlag(parsed, "f"),
+	);
+	console.log(output);
+}
+
+async function runLs(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const output = await service.renderTree(
+		parsed.globals.path,
+		parsed.values[0],
+		hasFlag(parsed, "full-descriptions") || hasFlag(parsed, "f"),
+	);
+	console.log(output);
+}
+
+async function runExplore(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const output = await service.explore(
+		parsed.globals.path,
+		parsed.values,
+		hasFlag(parsed, "full-descriptions") || hasFlag(parsed, "f"),
+	);
+	console.log(output);
+}
+
+async function runInspect(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const targetPath = requiredValue(parsed, "inspect requires a path.");
+	const report = await service.inspect(
+		parsed.globals.path,
+		targetPath,
+		hasFlag(parsed, "recursive"),
+	);
+
+	console.log(`Path: ${report.path}`);
+	console.log(`Type: ${report.entry.isDirectory ? "directory" : "file"}`);
+	console.log(`Description: ${entryDescription(report.entry) ?? "<missing>"}`);
+	const references = entryReferences(report.entry);
+	if (references.length > 0) {
+		console.log("References:");
+		for (const reference of references) {
+			console.log(`- ${reference}`);
+		}
+	}
+
+	switch (report.linkResolution.type) {
+		case "external":
+			console.log(`Link: external -> ${report.linkResolution.url}`);
+			break;
+		case "resolved":
+			console.log(`Link: ${report.linkResolution.chain.join(" -> ")}`);
+			console.log(`Resolved: ${report.linkResolution.path}`);
+			break;
+		case "broken":
+			console.log(`Link: ${report.linkResolution.chain.join(" -> ")}`);
+			console.log(`Broken target: ${report.linkResolution.target}`);
+			break;
+		case "cycle":
+			console.log(`Link cycle: ${report.linkResolution.chain.join(" -> ")}`);
+			break;
+		case "none":
+			break;
+	}
+
+	if (report.recursiveOutput) {
+		console.log("Tree:");
+		console.log(report.recursiveOutput);
+	}
+}
+
+async function runUpdate(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const targetPath = requiredValue(parsed, "update requires a path.");
+	const description = parsed.values[1];
+	const addReferences = valuesFor(parsed, "add-reference");
+	const removeReferences = valuesFor(parsed, "remove-reference");
+	const link = valueFor(parsed, "link");
+	const clearLink = hasFlag(parsed, "clear-link");
+
+	if (
+		description === undefined &&
+		addReferences.length === 0 &&
+		removeReferences.length === 0 &&
+		link === undefined &&
+		!clearLink
+	) {
+		throw new TreedocsError(
+			"No update requested. Provide a description or one of the reference/link flags.",
+		);
+	}
+
+	const file = await service.update(parsed.globals.path, {
+		path: targetPath,
+		description,
+		addReferences,
+		removeReferences,
+		link,
+		clearLink,
+	});
+	console.log(`Updated ${targetPath} (${file.signature ?? "no signature"})`);
+}
+
+async function runPath(
+	parsed: ParsedArguments,
+	service: TreedocsService,
+): Promise<void> {
+	const query = requiredValue(parsed, "path requires a query.");
+	const match = await service.findPath(parsed.globals.path, query);
+	if (!match) {
+		process.exitCode = 1;
+		return;
+	}
+	console.log(match);
+}
+
+export function rewriteArguments(argumentsToRewrite: string[]): string[] {
+	if (argumentsToRewrite.length === 0) {
+		return ["show", "."];
+	}
+
+	const pathIndex = firstPathArgumentIndex(argumentsToRewrite);
+	if (pathIndex === undefined) {
+		return argumentsToRewrite;
+	}
+
+	const rewritten = [...argumentsToRewrite];
+	rewritten.splice(pathIndex, 0, "show");
+	return rewritten;
+}
+
+function firstPathArgumentIndex(argumentsToScan: string[]): number | undefined {
+	let index = 0;
+	while (index < argumentsToScan.length) {
+		const argument = argumentsToScan[index];
+		if (commands.has(argument) || argument === "--help" || argument === "-h") {
+			return undefined;
+		}
+		if (argument === "--path" || argument === "-p") {
+			index += 2;
+			continue;
+		}
+		if (argument.startsWith("--path=")) {
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith("-")) {
+			return undefined;
+		}
+		return index;
+	}
+	return undefined;
+}
+
+function parseArguments(argumentsToParse: string[]): ParsedArguments {
+	const globals: GlobalOptions = { path: ".", nonInteractive: false };
+	let commandIndex = 0;
+	while (commandIndex < argumentsToParse.length) {
+		const argument = argumentsToParse[commandIndex];
+		if (argument === "--path" || argument === "-p") {
+			globals.path = argumentsToParse[commandIndex + 1] ?? ".";
+			commandIndex += 2;
+			continue;
+		}
+		if (argument.startsWith("--path=")) {
+			globals.path = argument.slice("--path=".length);
+			commandIndex += 1;
+			continue;
+		}
+		if (argument === "--non-interactive" || argument === "-n") {
+			globals.nonInteractive = true;
+			commandIndex += 1;
+			continue;
+		}
+		break;
+	}
+
+	const command = argumentsToParse[commandIndex];
+	const rest = argumentsToParse.slice(commandIndex + 1);
+	if (!command) {
+		return {
+			command: "show",
+			values: ["."],
+			options: new Map(),
+			globals,
+		};
+	}
+
+	const options = new Map<string, string[]>();
+	const values: string[] = [];
+
+	for (let index = 0; index < rest.length; index += 1) {
+		const argument = rest[index];
+		if (argument === "--path" || argument === "-p") {
+			globals.path = rest[index + 1] ?? ".";
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith("--path=")) {
+			globals.path = argument.slice("--path=".length);
+			continue;
+		}
+		if (argument === "--non-interactive" || argument === "-n") {
+			globals.nonInteractive = true;
+			continue;
+		}
+		if (argument === "-f") {
+			addOptionValue(options, "f", "true");
+			continue;
+		}
+		if (argument.startsWith("--")) {
+			const [optionName, inlineValue] = splitLongOption(argument);
+			if (isValueOption(optionName)) {
+				const consumed = collectOptionValues(rest, index, inlineValue);
+				for (const value of consumed.values) {
+					addOptionValue(options, optionName, value);
+				}
+				index = consumed.nextIndex;
+				continue;
+			}
+			addOptionValue(options, optionName, inlineValue ?? "true");
+			continue;
+		}
+		if (argument.startsWith("-") && argument.length > 1) {
+			for (const flag of argument.slice(1)) {
+				addOptionValue(options, flag, "true");
+			}
+			continue;
+		}
+		values.push(argument);
+	}
+
+	return { command, values, options, globals };
+}
+
+function splitLongOption(argument: string): [string, string | undefined] {
+	const withoutPrefix = argument.slice(2);
+	const equalsIndex = withoutPrefix.indexOf("=");
+	if (equalsIndex === -1) {
+		return [withoutPrefix, undefined];
+	}
+	return [
+		withoutPrefix.slice(0, equalsIndex),
+		withoutPrefix.slice(equalsIndex + 1),
+	];
+}
+
+function isValueOption(optionName: string): boolean {
+	return ["add-reference", "remove-reference", "link"].includes(optionName);
+}
+
+function collectOptionValues(
+	argumentsToParse: string[],
+	optionIndex: number,
+	inlineValue: string | undefined,
+): { values: string[]; nextIndex: number } {
+	if (inlineValue !== undefined) {
+		return { values: [inlineValue], nextIndex: optionIndex };
+	}
+
+	const values: string[] = [];
+	let index = optionIndex + 1;
+	while (
+		index < argumentsToParse.length &&
+		!argumentsToParse[index].startsWith("-")
+	) {
+		values.push(argumentsToParse[index]);
+		index += 1;
+	}
+	return { values, nextIndex: index - 1 };
+}
+
+function addOptionValue(
+	options: Map<string, string[]>,
+	name: string,
+	value: string,
+): void {
+	const values = options.get(name) ?? [];
+	values.push(value);
+	options.set(name, values);
+}
+
+function hasFlag(parsed: ParsedArguments, name: string): boolean {
+	return parsed.options.has(name);
+}
+
+function valuesFor(parsed: ParsedArguments, name: string): string[] {
+	return parsed.options.get(name) ?? [];
+}
+
+function valueFor(parsed: ParsedArguments, name: string): string | undefined {
+	return valuesFor(parsed, name).at(-1);
+}
+
+function requiredValue(parsed: ParsedArguments, message: string): string {
+	const value = parsed.values[0];
+	if (!value) {
+		throw new TreedocsError(message);
+	}
+	return value;
+}
+
+function printSection(title: string, values: string[]): void {
+	if (values.length === 0) {
+		return;
+	}
+	console.log(`${title}:`);
+	for (const value of [...values].sort()) {
+		console.log(`- ${value}`);
+	}
+}
+
+function nextSteps(report: CheckReport): string[] {
+	if (!report.shouldFail) {
+		return [];
+	}
+
+	const steps: string[] = [];
+	if (
+		report.schemaErrors.length > 0 ||
+		report.hasSignatureDrift ||
+		report.missingPaths.length > 0 ||
+		report.extraPaths.length > 0 ||
+		report.changedPaths.length > 0 ||
+		report.shadowedPaths.length > 0
+	) {
+		steps.push(
+			"Run `treedocs sync` to reconcile filesystem changes and refresh the stored signature.",
+		);
+	}
+	if (report.shadowedPaths.length > 0) {
+		steps.push(
+			"Nested `treedocs.yaml` files own their descendants; `treedocs sync` keeps only delegated boundary folders in the parent tree.",
+		);
+	}
+	if (report.missingDescriptions.length > 0) {
+		steps.push(missingDescriptionNextStep);
+	}
+	return steps;
+}
+
+function changeSummaryMessages(changes: SyncChanges, pathLimit = 5): string[] {
+	const messages = ["Changes found:"];
+	messages.push(...summaryLines("+", "Added", changes.addedPaths, pathLimit));
+	messages.push(
+		...summaryLines("-", "Removed", changes.removedPaths, pathLimit),
+	);
+	messages.push(
+		...summaryLines("-", "Changed type", changes.changedTypePaths, pathLimit),
+	);
+	return messages.length === 1 ? [] : messages;
+}
+
+function summaryLines(
+	marker: string,
+	title: string,
+	paths: string[],
+	pathLimit: number,
+): string[] {
+	if (paths.length === 0) {
+		return [];
+	}
+	const shownPaths = paths.slice(0, pathLimit).join(", ");
+	const remainingCount = paths.length - Math.min(paths.length, pathLimit);
+	const suffix = remainingCount > 0 ? `, +${remainingCount} more` : "";
+	return [`${marker} ${title}: ${paths.length} (${shownPaths}${suffix})`];
+}
+
+function remainingIssueMessages(missingDescriptions: string[]): string[] {
+	if (missingDescriptions.length === 0) {
+		return [];
+	}
+	return [
+		"Missing descriptions:",
+		...missingDescriptions.sort().map((path) => `- ${path}`),
+		"Next steps:",
+		`- ${missingDescriptionNextStep}`,
+	];
+}
+
+function printRootHelp(): void {
+	console.log(`treedocs ${cliVersion}`);
+	console.log(
+		"Generate and maintain a YAML documentation tree for a repository.",
+	);
+	console.log("");
+	console.log("Usage:");
+	console.log("  treedocs <command> [options]");
+	console.log("  treedocs <path>");
+	console.log("");
+	console.log("Commands:");
+	console.log("  init       Scan the repository and create treedocs.yaml");
+	console.log("  sync       Reconcile treedocs.yaml with the filesystem");
+	console.log(
+		"  check      Report drift, schema issues, and missing descriptions",
+	);
+	console.log("  show       Render a documented path with inline descriptions");
+	console.log("  ls         Render the full tree or a subtree");
+	console.log(
+		"  explore    Render a shallow tree with selected paths expanded",
+	);
+	console.log("  inspect    Show details for one documented path");
+	console.log("  update     Update a description, references, or link");
+	console.log("  path       Return the first documented path matching a query");
+	console.log("");
+	console.log("Global Options:");
+	console.log("  -p, --path <path>       Repository root");
+	console.log("  -n, --non-interactive   Accepted for script compatibility");
+	console.log("  --version               Show version");
+	console.log("  -h, --help              Show help");
+}
+
+function printCommandHelp(command: string): void {
+	switch (command) {
+		case "init":
+			console.log("Usage: treedocs init [--force] [-p <path>]");
+			break;
+		case "sync":
+			console.log("Usage: treedocs sync [-n] [-p <path>]");
+			break;
+		case "check":
+			console.log("Usage: treedocs check [-p <path>]");
+			break;
+		case "show":
+			console.log("Usage: treedocs show <path> [--no-check] [-f]");
+			break;
+		case "ls":
+			console.log("Usage: treedocs ls [path] [-f]");
+			break;
+		case "explore":
+			console.log("Usage: treedocs explore [path ...] [-f]");
+			break;
+		case "inspect":
+			console.log("Usage: treedocs inspect <path> [--recursive]");
+			break;
+		case "update":
+			console.log(
+				"Usage: treedocs update <path> [description] [--add-reference <ref>...] [--remove-reference <ref>...] [--link <target>] [--clear-link]",
+			);
+			break;
+		case "path":
+			console.log("Usage: treedocs path <query>");
+			break;
+		default:
+			printRootHelp();
+	}
+}
+
+if (import.meta.main) {
+	process.exit(await main());
+}