al-sem 0.0.1

package/src/cli/format-sarif.ts

@@ -0,0 +1,186 @@
+import type { AnalyzeWorkspaceResult } from "../index.ts";
+import type { EvidenceStep } from "../model/finding.ts";
+import { type FindingSummary, projectFinding } from "../projection/finding-summary.ts";
+
+const SARIF_LEVEL: Record<FindingSummary["severity"], "error" | "warning" | "note"> = {
+	critical: "error",
+	high: "error",
+	medium: "warning",
+	low: "note",
+	info: "note",
+};
+
+interface SarifRule {
+	id: string;
+	name?: string;
+	shortDescription: { text: string };
+	helpUri?: string;
+}
+
+const RULES: SarifRule[] = [
+	{
+		id: "d1-db-op-in-loop",
+		name: "DbOpInLoop",
+		shortDescription: { text: "Database operation inside a loop" },
+	},
+	{
+		id: "d2-event-fanout-in-loop",
+		name: "EventFanoutInLoop",
+		shortDescription: { text: "Event raised inside a loop with DB-touching subscribers" },
+	},
+	{
+		id: "d3-missing-setloadfields",
+		name: "MissingSetLoadFields",
+		shortDescription: { text: "Missing SetLoadFields before record retrieval" },
+	},
+	{
+		id: "d4-repeated-lookup-in-loop",
+		name: "RepeatedLookupInLoop",
+		shortDescription: { text: "Repeated identical lookup inside a loop" },
+	},
+	{
+		id: "d5-set-based-opportunity",
+		name: "SetBasedOpportunity",
+		shortDescription: { text: "Loop-and-Modify candidate for ModifyAll" },
+	},
+	{
+		id: "d7-recursive-event-expansion",
+		name: "RecursiveEventExpansion",
+		shortDescription: { text: "Event subscriber chain forms a cycle" },
+	},
+	{
+		id: "d8-commit-in-transaction",
+		name: "CommitInTransaction",
+		shortDescription: { text: "Commit inside a posting transaction span" },
+	},
+	{
+		id: "d9-transaction-span-summary",
+		name: "TransactionSpanSummary",
+		shortDescription: { text: "Transaction span summary (info)" },
+	},
+	{
+		id: "d10-self-modifying-loop",
+		name: "SelfModifyingLoop",
+		shortDescription: { text: "Self-modifying loop" },
+	},
+	{
+		id: "d11-modify-without-get",
+		name: "ModifyWithoutGet",
+		shortDescription: { text: "Modify without prior Get" },
+	},
+	{
+		id: "d12-dead-integration-event",
+		name: "DeadIntegrationEvent",
+		shortDescription: { text: "Integration event has no subscribers" },
+	},
+	{
+		id: "d13-cross-app-internal-call",
+		name: "CrossAppInternalCall",
+		shortDescription: { text: "Cross-extension call into an internal procedure" },
+	},
+	{
+		id: "d14-dead-routine",
+		name: "DeadRoutine",
+		shortDescription: { text: "Routine unreachable from any entry point" },
+	},
+	{
+		id: "d16-obsolete-routine-call",
+		name: "ObsoleteRoutineCall",
+		shortDescription: { text: "Call to an obsolete routine" },
+	},
+	{
+		id: "d17-min-version-drift",
+		name: "MinVersionDrift",
+		shortDescription: { text: "Call into API newer than declared MinVersion" },
+	},
+];
+
+/**
+ * Convert one Finding evidence path to a SARIF threadFlow. Each EvidenceStep
+ * becomes one threadFlowLocation; the step's note carries to the location's
+ * message. SARIF consumers (GitHub code-scanning, Sonar, etc.) render
+ * threadFlows as a navigable trace.
+ */
+function pathToThreadFlow(path: EvidenceStep[]): {
+	locations: { location: { physicalLocation: object; message: { text: string } } }[];
+} {
+	return {
+		locations: path.map((step) => ({
+			location: {
+				physicalLocation: {
+					artifactLocation: { uri: step.sourceAnchor.sourceUnitId },
+					region: {
+						startLine: step.sourceAnchor.range.startLine + 1,
+						startColumn: step.sourceAnchor.range.startColumn + 1,
+					},
+				},
+				message: { text: step.note },
+			},
+		})),
+	};
+}
+
+/**
+ * Format an analysis result as SARIF 2.1.0 JSON. Suitable for `gh code-scanning upload-sarif`.
+ * Per finding emits ruleId, severity-mapped level, message, fingerprint, and one physical
+ * location. Optional logical location encodes object :: routine. When a Finding has
+ * `additionalPaths` (D1/D2 multi-caller cases), each path becomes a SARIF `codeFlow`
+ * (a `threadFlows[]` wrapper) so consumers can render every reaching trace.
+ */
+export function formatSarif(result: AnalyzeWorkspaceResult): string {
+	const findings = result.findings.map((f) => projectFinding(f, result.model));
+	const sarif = {
+		$schema:
+			"https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+		version: "2.1.0",
+		runs: [
+			{
+				tool: {
+					driver: {
+						name: "al-sem",
+						version: "0.0.1",
+						informationUri: "https://github.com/SShadowS/al-sem",
+						rules: RULES,
+					},
+				},
+				results: findings.map((f, idx) => {
+					const raw = result.findings[idx];
+					const allPaths = raw ? [raw.evidencePath, ...(raw.additionalPaths ?? [])] : [];
+					const result_: Record<string, unknown> = {
+						ruleId: f.detector,
+						level: SARIF_LEVEL[f.severity] ?? "warning",
+						message: { text: `${f.title} — ${f.rootCause}` },
+						fingerprints: { "al-sem/v1": f.fingerprint },
+						locations: [
+							{
+								physicalLocation: {
+									artifactLocation: { uri: f.primaryLocation.file },
+									region: {
+										startLine: f.primaryLocation.line,
+										startColumn: f.primaryLocation.column,
+									},
+								},
+								logicalLocations:
+									f.primaryLocation.objectName !== undefined ||
+									f.primaryLocation.routineName !== undefined
+										? [
+												{
+													name: `${f.primaryLocation.objectName ?? ""} :: ${f.primaryLocation.routineName ?? ""}`,
+												},
+											]
+										: undefined,
+							},
+						],
+					};
+					if (allPaths.length > 0 && allPaths.some((p) => p.length > 0)) {
+						result_.codeFlows = allPaths
+							.filter((p) => p.length > 0)
+							.map((p) => ({ threadFlows: [pathToThreadFlow(p)] }));
+					}
+					return result_;
+				}),
+			},
+		],
+	};
+	return JSON.stringify(sarif, null, 2);
+}

package/src/cli/format-terminal.ts

@@ -0,0 +1,153 @@
+import type { AnalyzeWorkspaceResult } from "../index.ts";
+import {
+	type FindingLocation,
+	type FindingSummary,
+	projectFinding,
+} from "../projection/finding-summary.ts";
+import { type RolledOrSingle, rollupFindings } from "../projection/rollup-findings.ts";
+import type { RootClassificationSlot } from "../snapshot/types.ts";
+
+const SEV_ORDER = ["critical", "high", "medium", "low", "info"] as const;
+const SAFETY_RANK = { high: 3, medium: 2, low: 1 } as const;
+
+function locStr(loc: FindingLocation): string {
+	const where =
+		loc.objectName && loc.routineName ? ` in ${loc.objectName} :: ${loc.routineName}` : "";
+	return `${loc.file}:${loc.line}:${loc.column}${where}`;
+}
+
+function renderSingle(f: FindingSummary, lines: string[]): void {
+	lines.push(`  [${f.detector}] ${f.title} — ${f.rootCause}`);
+	lines.push(`    ${locStr(f.primaryLocation)}`);
+	if (f.terminalLocation) lines.push(`    terminal: ${locStr(f.terminalLocation)}`);
+	lines.push(
+		`    confidence: ${f.confidence.level}${f.confidence.cappedBy ? ` (capped by ${f.confidence.cappedBy.join(", ")})` : ""}`,
+	);
+	const pc = f.pathCount ?? 1;
+	if (pc > 1) {
+		const noun = pc - 1 === 1 ? "other path" : "other paths";
+		lines.push(
+			`    also reached from ${pc - 1} ${noun} (full traces in SARIF output / explain_path MCP tool)`,
+		);
+	}
+	if (f.fixHint) lines.push(`    fix (${f.fixHint.safety}): ${f.fixHint.description}`);
+}
+
+function renderRolled(r: Extract<RolledOrSingle, { kind: "rolled" }>, lines: string[]): void {
+	const n = r.contributors.length;
+	lines.push(`  ${locStr(r.primaryLocation)} — ${n} detectors agree:`);
+	for (const c of r.contributors) {
+		lines.push(`    [${c.detector}] ${c.title} (${c.severity})`);
+	}
+	// Union of confidence levels — show the worst-case (lowest) so the user
+	// knows the rolled-up bundle's overall confidence.
+	const confs = r.contributors.map((c) => c.confidence.level);
+	const order = ["confirmed", "likely", "possible"] as const;
+	const worstConf =
+		order.find((lvl) => confs.includes(lvl as (typeof confs)[number])) ?? "possible";
+	const cappedBys = new Set<string>();
+	for (const c of r.contributors) for (const cb of c.confidence.cappedBy ?? []) cappedBys.add(cb);
+	const capStr = cappedBys.size > 0 ? ` (capped by ${[...cappedBys].sort().join(", ")})` : "";
+	lines.push(`    confidence: ${worstConf}${capStr}`);
+	// Aggregate fix recommendations sorted by safety (high → low) — let the
+	// user see the safest replacement first.
+	const fixes = r.contributors
+		.filter((c) => c.fixHint !== undefined)
+		.map((c) => ({ from: c.detector, hint: c.fixHint }))
+		.filter((x) => x.hint !== undefined)
+		.sort((a, b) => {
+			const sa = a.hint ? SAFETY_RANK[a.hint.safety] : 0;
+			const sb = b.hint ? SAFETY_RANK[b.hint.safety] : 0;
+			return sb - sa;
+		});
+	if (fixes.length > 0) {
+		lines.push("    fix options (safest first):");
+		for (const f of fixes) {
+			if (f.hint === undefined) continue;
+			lines.push(`      • (${f.hint.safety}) ${f.hint.description}  [${f.from}]`);
+		}
+	}
+}
+
+/**
+ * Human-readable terminal output: coverage summary, then findings grouped by
+ * severity. Findings that coincide at the same `(file, line, column, tables)`
+ * are rolled up (typically D1/D5/D10 on a single iterating-Modify pattern) —
+ * see `rollupFindings`. The roll-up is purely presentational; underlying
+ * Findings remain per-detector in JSON / SARIF output.
+ */
+/**
+ * Render one RootClassificationSlot as a single line for terminal output
+ * (Phase 1 §4.3, consumed by §4.4 fingerprint CLI).
+ *
+ * Format: `<objectName>::<routineName> [<kind>, <kind>, ...]<marker>`
+ *
+ * `marker` reflects the classification's `source`:
+ *   - `""` (empty)           for `source: "ast"`     — pure AST classification
+ *   - ` [config-asserted]`   for `source: "ast+config"` — AST + roots.config.json agreement (or partial agreement)
+ *   - ` [config-root]`       for `source: "config"`     — declared only in roots.config.json
+ *
+ * `objectName` and `routineName` are passed by the caller because the
+ * snapshot stores StableRoutineId opaquely — the caller has the display
+ * names available via the snapshot's identityTable.
+ */
+export function formatRootClassification(
+	slot: RootClassificationSlot,
+	objectName: string,
+	routineName: string,
+): string {
+	const kindList = slot.kinds.join(", ");
+	const marker =
+		slot.source === "config"
+			? " [config-root]"
+			: slot.source === "ast+config"
+				? " [config-asserted]"
+				: "";
+	return `${objectName}::${routineName} [${kindList}]${marker}`;
+}
+
+export function formatTerminal(result: AnalyzeWorkspaceResult): string {
+	const findings = result.findings.map((f) => projectFinding(f, result.model));
+	const rolled = rollupFindings(findings);
+	const cov = result.model.coverage;
+	const lines: string[] = [];
+
+	const rollupCount = rolled.filter((r) => r.kind === "rolled").length;
+	const rollupNote =
+		rollupCount > 0
+			? `; ${rollupCount} location(s) flagged by multiple detectors (rolled up below).`
+			: ".";
+	lines.push(
+		`Analysed ${cov.routinesTotal} routines (${cov.routinesBodyAvailable} with bodies, ${cov.routinesParseIncomplete.length} parse-incomplete); ${cov.sourceUnitsParsed}/${cov.sourceUnitsTotal} source units parsed; ${cov.opaqueApps.length} opaque app(s)${rollupNote}`,
+	);
+
+	if (findings.length === 0) {
+		lines.push("");
+		lines.push(
+			"No findings. (Absence of a finding is not absence of a problem — see coverage above.)",
+		);
+	}
+
+	for (const sev of SEV_ORDER) {
+		const group = rolled.filter((r) =>
+			r.kind === "rolled" ? r.severity === sev : r.finding.severity === sev,
+		);
+		if (group.length === 0) continue;
+		lines.push("");
+		lines.push(`${sev.toUpperCase()} (${group.length}):`);
+		for (const item of group) {
+			if (item.kind === "single") renderSingle(item.finding, lines);
+			else renderRolled(item, lines);
+		}
+	}
+
+	if (result.diagnostics.length > 0) {
+		lines.push("");
+		lines.push(`Diagnostics (${result.diagnostics.length}):`);
+		for (const d of result.diagnostics) {
+			lines.push(`  [${d.severity}/${d.stage}] ${d.message}`);
+		}
+	}
+
+	return lines.join("\n");
+}