al-sem 0.0.1

package/src/cli/format-fingerprint.ts

@@ -0,0 +1,295 @@
+import type { CapabilityFact, CapabilityOp, CapabilityResourceKind } from "../model/capability.ts";
+import type {
+	BlockResource,
+	FingerprintBlock,
+	FingerprintQueryResult,
+	PermissionLine,
+} from "./fingerprint-query.ts";
+import type { WitnessHop } from "./fingerprint-witness.ts";
+
+export interface RenderOptions {
+	/**
+	 * Reserved for a future deterministic-output pass (e.g. pinned timestamps,
+	 * sorted collections). Currently ignored by the renderer; determinism is
+	 * enforced upstream by the query layer when `FingerprintFilters` requests it.
+	 * Wired through the CLI (--deterministic) so the surface is ready.
+	 */
+	deterministic?: boolean;
+	/**
+	 * Reserved for a future ANSI-color rendering pass. Currently ignored;
+	 * the renderer always emits color-free output. Wired through the CLI
+	 * (--color) so the surface is ready when implementation lands.
+	 */
+	color?: boolean;
+	verbosity?: "compact" | "full";
+}
+
+const LABEL_WIDTH = 12;
+
+const EXTERNAL_FAMILIES: readonly CapabilityResourceKind[] = [
+	"http",
+	"isolated-storage",
+	"file",
+	"background",
+	"telemetry",
+	"ui",
+];
+
+function q(s: string): string {
+	return JSON.stringify(s);
+}
+
+function pad(label: string): string {
+	return `${label}:`.padEnd(LABEL_WIDTH, " ");
+}
+
+export function formatFingerprint(
+	result: FingerprintQueryResult,
+	opts: RenderOptions = {},
+): string {
+	const lines: string[] = [];
+	if (result.blocks.length === 0) {
+		lines.push("No root classifications match the filters.");
+		return `${lines.join("\n")}\n`;
+	}
+	const totalTrunc = result.blocks.reduce(
+		(n, b) => n + b.witnesses.filter((w) => w.truncated).length,
+		0,
+	);
+	const truncSuffix =
+		totalTrunc > 0
+			? ` ${totalTrunc} witness set${totalTrunc === 1 ? "" : "s"} truncated; details inline.`
+			: "";
+	const filterClause =
+		result.summary.renderedBlocks === result.summary.totalClassifications
+			? `Rendering ${result.summary.renderedBlocks} root classification${result.summary.renderedBlocks === 1 ? "" : "s"}.`
+			: `Rendering ${result.summary.renderedBlocks} of ${result.summary.totalClassifications} root classifications.`;
+	lines.push(filterClause + truncSuffix);
+	lines.push("");
+	for (let i = 0; i < result.blocks.length; i++) {
+		if (i > 0) lines.push("");
+		renderBlock(result.blocks[i] as FingerprintBlock, opts, lines);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function renderBlock(b: FingerprintBlock, opts: RenderOptions, lines: string[]): void {
+	const verb = opts.verbosity ?? "compact";
+	const marker =
+		b.classificationSource === "config"
+			? " [config-root]"
+			: b.classificationSource === "ast+config"
+				? " [config-asserted]"
+				: "";
+	lines.push(`${b.objectDisplay}::${b.routineDisplay}  [${b.kinds.join(", ")}]${marker}`);
+
+	// coverage (always first — G6 coverage-first discipline)
+	const reasons =
+		b.coverage.reasons.length > 0 ? ` — ${[...b.coverage.reasons].sort().join(", ")}` : "";
+	lines.push(`  ${pad("coverage")}${b.coverage.status}${reasons}`);
+	if (b.coverage.unknownTargets.length > 0) {
+		const shown = b.coverage.unknownTargetDisplays.slice(0, 5);
+		const more = b.coverage.unknownTargets.length - shown.length;
+		const moreSuffix = more > 0 ? ` (+${more} more)` : "";
+		lines.push(
+			`  ${" ".repeat(LABEL_WIDTH)}${b.coverage.unknownTargets.length} opaque/unresolved targets: ${shown.join(", ")}${moreSuffix}`,
+		);
+	}
+	if (b.coverage.inheritedExcluded) {
+		lines.push(`  ${" ".repeat(LABEL_WIDTH)}(direct-only; coverage reflects direct cone)`);
+	}
+
+	// writes / reads / commit / publish / dispatch / external families
+	renderFamilyLine(b, "writes", "table", "insert", lines);
+	renderFamilyLine(b, "reads", "table", "read", lines);
+	renderCommit(b, lines);
+	renderFamilyLine(b, "publish", "event", "publish", lines);
+	renderDispatch(b, lines);
+	renderExternalFamilies(b, verb, lines);
+	renderPermissions(b, lines);
+	renderWitnesses(b, lines);
+}
+
+function renderFamilyLine(
+	b: FingerprintBlock,
+	label: string,
+	kind: CapabilityResourceKind,
+	op: CapabilityOp,
+	lines: string[],
+): void {
+	const fam = b.families.find((f) => f.kind === kind);
+	const items: BlockResource[] = (fam?.resources ?? []).filter((r) => r.ops.includes(op));
+	if (items.length === 0 && b.coverage.status === "complete") return;
+	if (items.length === 0) {
+		lines.push(`  ${pad(label)}none known reachable`);
+		return;
+	}
+	const rendered = items.map((r) => `${kindPrefix(kind)} ${q(r.display)}`).join(", ");
+	lines.push(`  ${pad(label)}${rendered}`);
+}
+
+function kindPrefix(kind: CapabilityResourceKind): string {
+	switch (kind) {
+		case "table":
+			return "TableData";
+		case "event":
+			return "Event";
+		case "codeunit":
+			return "Codeunit";
+		case "page":
+			return "Page";
+		case "report":
+			return "Report";
+		default:
+			return kind;
+	}
+}
+
+function renderCommit(b: FingerprintBlock, lines: string[]): void {
+	if (b.mayCommit.presence === "no") return; // omit "no" commits in compact
+	lines.push(`  ${pad("commit")}${b.mayCommit.presence}`);
+}
+
+function renderDispatch(b: FingerprintBlock, lines: string[]): void {
+	const r = b.dispatch.resolved.length;
+	const u = b.dispatch.unresolved.length;
+	if (r === 0 && u === 0) return;
+	const parts: string[] = [];
+	if (r > 0) {
+		const list = b.dispatch.resolved
+			.slice(0, 4)
+			.map((d) => d.targetDisplay ?? d.targetId ?? "?")
+			.join(", ");
+		const more = r > 4 ? `, +${r - 4} more` : "";
+		parts.push(`${r} static (${list}${more})`);
+	}
+	if (u > 0) {
+		parts.push(`${u} unresolved-dynamic`);
+	}
+	lines.push(`  ${pad("dispatch")}${parts.join("; ")}`);
+}
+
+function renderExternalFamilies(
+	b: FingerprintBlock,
+	verbosity: "compact" | "full",
+	lines: string[],
+): void {
+	const emptyExternal: CapabilityResourceKind[] = [];
+	for (const kind of EXTERNAL_FAMILIES) {
+		const fam = b.families.find((f) => f.kind === kind);
+		const present = fam !== undefined && fam.resources.length > 0;
+		if (!present) {
+			emptyExternal.push(kind);
+			if (verbosity === "full") {
+				const word = b.coverage.status === "complete" ? "none" : "none known reachable";
+				lines.push(`  ${pad(externalLabel(kind))}${word}`);
+			}
+			continue;
+		}
+		const rendered = (fam?.resources ?? []).map((r) => q(r.display)).join(", ");
+		lines.push(`  ${pad(externalLabel(kind))}${rendered}`);
+	}
+	if (verbosity === "compact" && emptyExternal.length > 0 && b.coverage.status !== "complete") {
+		const list = emptyExternal.map(externalLabel).join("/");
+		lines.push(`  no known ${list} capabilities — cone partial`);
+	}
+}
+
+function externalLabel(kind: CapabilityResourceKind): string {
+	switch (kind) {
+		case "http":
+			return "http";
+		case "isolated-storage":
+			return "storage";
+		case "file":
+			return "file";
+		case "background":
+			return "background";
+		case "telemetry":
+			return "telemetry";
+		case "ui":
+			return "ui";
+		default:
+			return kind;
+	}
+}
+
+function renderPermissions(b: FingerprintBlock, lines: string[]): void {
+	if (b.requiredPermissions.length === 0) return;
+	const allComplete =
+		b.requiredPermissions.every((p) => p.coverage === "complete") &&
+		b.coverage.status === "complete";
+	const heading = allComplete ? "permissions:" : "permissions (inferred, may be incomplete):";
+	lines.push(`  ${heading}`);
+	const sorted = [...b.requiredPermissions].sort((x, y) =>
+		x.targetDisplay < y.targetDisplay ? -1 : x.targetDisplay > y.targetDisplay ? 1 : 0,
+	);
+	for (const p of sorted) {
+		const prefix = p.targetKind === "table" ? "TableData" : "Object";
+		lines.push(`    ${prefix} ${q(p.targetDisplay)} ${p.rights}`);
+	}
+}
+
+function renderWitnesses(b: FingerprintBlock, lines: string[]): void {
+	if (b.witnesses.length === 0) return;
+	const present = b.witnesses.filter((w) => w.paths.length > 0 || w.truncated);
+	if (present.length === 0) return;
+	lines.push("");
+	lines.push("  witnesses:");
+	for (const w of present) {
+		const desc = factDescription(w.fact);
+		const total = w.paths.length;
+		lines.push(`    ${desc} — ${total} path${total === 1 ? "" : "s"} shown`);
+		for (let i = 0; i < w.paths.length; i++) {
+			lines.push(`      Path ${i + 1}/${total} shown:`);
+			const path = w.paths[i];
+			if (path === undefined) continue;
+			for (let h = 0; h < path.hops.length; h++) {
+				const hop = path.hops[h];
+				if (hop === undefined) continue;
+				const indent = `        ${"  ".repeat(h)}`;
+				lines.push(`${indent}${hopArrow(h)}${formatHop(hop)}`);
+			}
+			lines.push("");
+		}
+		if (w.truncated) {
+			const cap = w.diagnostics.find((d) => d.kind === "path-limit-reached") as
+				| { cap?: number }
+				| undefined;
+			lines.push(
+				`      warning: witnesses truncated at ${cap?.cap ?? "?"} for ${desc}; narrow with --routine/--roots or raise --witness.`,
+			);
+		}
+	}
+}
+
+function hopArrow(depth: number): string {
+	return depth === 0 ? "" : "→ ";
+}
+
+function formatHop(hop: WitnessHop): string {
+	switch (hop.kind) {
+		case "call":
+			return `${hop.routineDisplay} (via ${hop.calleeDisplay}${hop.sourceFile ? ` at ${hop.sourceFile}:${hop.line ?? 0}:${hop.column ?? 0}` : ""})`;
+		case "object-run":
+			return `${hop.routineDisplay} (via Codeunit.Run ${hop.targetDisplay ?? "<unresolved>"}${hop.sourceFile ? ` at ${hop.sourceFile}:${hop.line ?? 0}:${hop.column ?? 0}` : ""})`;
+		case "event-dispatch":
+			return `event ${hop.eventDisplay}`;
+		case "implicit-trigger":
+			return `trigger ${hop.triggerKind} on ${hop.routineDisplay}`;
+		case "dependency-export":
+			return `${hop.routineDisplay} (into dependency app ${hop.targetAppGuid}, via ${hop.calleeDisplay ?? "?"}${hop.sourceFile ? ` at ${hop.sourceFile}:${hop.line ?? 0}:${hop.column ?? 0}` : ""})`;
+		case "terminal":
+			if (hop.evidenceKind === "operation") {
+				return `direct ${hop.displayText}${hop.sourceFile ? ` at ${hop.sourceFile}:${hop.line ?? 0}:${hop.column ?? 0}` : ""}`;
+			}
+			if (hop.evidenceKind === "callsite") {
+				return `call ${hop.displayText}${hop.sourceFile ? ` at ${hop.sourceFile}:${hop.line ?? 0}:${hop.column ?? 0}` : ""}`;
+			}
+			return hop.displayText;
+	}
+}
+
+function factDescription(fact: CapabilityFact): string {
+	return `${fact.op} ${fact.resourceKind}${fact.resourceId ? ` ${q(String(fact.resourceId))}` : ""}`;
+}