@filipebraida/adonis-function-points 0.1.0

package/build/runners-Bt8tbISi.js

@@ -0,0 +1,630 @@
+import { n as defineConfig, t as DEFAULTS } from "./define_config-DOqWyPwV.js";
+import { n as analyze, r as toPosix } from "./pipeline-BzP-ITGN.js";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+//#region src/cli/print.ts
+function printResult(result, printer) {
+	for (const note of result.notes ?? []) printer.note(note);
+	if (result.errors?.length) {
+		for (const message of result.errors) printer.error(message);
+		return 1;
+	}
+	if (result.output) printer.log(result.output);
+	return 0;
+}
+//#endregion
+//#region src/albrecht/calibration.ts
+/**
+* Minimum sample size per type for a factor to mean anything.
+*
+* Below this, the "factor" is noise from one or two functions, and using it to
+* correct a count is worse than not correcting at all.
+*/
+const MIN_SAMPLES_PER_TYPE = 10;
+function calibrate(result, samples) {
+	const byIdentity = new Map(result.functions.map((fn) => [fn.name, fn]));
+	const grouped = /* @__PURE__ */ new Map();
+	const unmatched = [];
+	let manualTotal = 0;
+	let automaticTotal = 0;
+	let exactTotal = 0;
+	for (const sample of samples) {
+		const counted = byIdentity.get(sample.function);
+		if (!counted) {
+			unmatched.push(sample.function);
+			continue;
+		}
+		const bucket = grouped.get(counted.type) ?? {
+			manual: 0,
+			automatic: 0,
+			deviations: [],
+			exact: 0
+		};
+		bucket.manual += sample.manual;
+		bucket.automatic += counted.points;
+		bucket.deviations.push(Math.abs(counted.points - sample.manual));
+		if (counted.points === sample.manual) bucket.exact++;
+		grouped.set(counted.type, bucket);
+		manualTotal += sample.manual;
+		automaticTotal += counted.points;
+		if (counted.points === sample.manual) exactTotal++;
+	}
+	const byType = [...grouped.entries()].map(([type, bucket]) => ({
+		type,
+		samples: bucket.deviations.length,
+		manualPoints: bucket.manual,
+		automaticPoints: bucket.automatic,
+		factor: bucket.automatic === 0 ? 1 : round(bucket.manual / bucket.automatic),
+		meanAbsoluteDeviation: round(bucket.deviations.reduce((total, value) => total + value, 0) / bucket.deviations.length),
+		exactMatches: bucket.exact
+	})).sort((a, b) => a.type.localeCompare(b.type));
+	const warnings = [];
+	for (const calibration of byType) if (calibration.samples < MIN_SAMPLES_PER_TYPE) warnings.push(`${calibration.type}: ${calibration.samples} samples, below the minimum of ${MIN_SAMPLES_PER_TYPE}. The factor ${calibration.factor} is noise from a handful of functions — do not use it to correct a count.`);
+	if (unmatched.length > 0) warnings.push(`${unmatched.length} samples matched no counted function. Check the identity: it is "VERB /pattern" with parameters written as ":param".`);
+	const matched = samples.length - unmatched.length;
+	if (matched > 0 && exactTotal === matched) warnings.push("every sample matched exactly. Check that the manual count was not derived from the automatic one — calibrating against itself measures nothing.");
+	return {
+		byType,
+		overall: {
+			samples: matched,
+			manualPoints: manualTotal,
+			automaticPoints: automaticTotal,
+			deviation: manualTotal === 0 ? 0 : round((automaticTotal - manualTotal) / manualTotal),
+			exactMatches: exactTotal
+		},
+		unmatched,
+		warnings
+	};
+}
+const round = (value) => Math.round(value * 1e3) / 1e3;
+/**
+* Reads samples from CSV: `function,fp` with a header row.
+*
+* Deliberately plain. A metrics analyst exports from a spreadsheet, and
+* demanding JSON would add friction where none is needed.
+*/
+function parseSamples(csv) {
+	const samples = [];
+	for (const [index, line] of csv.split(/\r?\n/).entries()) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const separator = trimmed.lastIndexOf(",");
+		if (separator === -1) continue;
+		const name = trimmed.slice(0, separator).trim().replace(/^"|"$/g, "");
+		const manual = Number(trimmed.slice(separator + 1).trim());
+		if (!Number.isFinite(manual)) {
+			if (index > 0 && ![
+				"function",
+				"funcao",
+				"função"
+			].includes(name)) throw new Error(`line ${index + 1}: unreadable function points in "${trimmed}"`);
+			continue;
+		}
+		samples.push({
+			function: name,
+			manual
+		});
+	}
+	return samples;
+}
+//#endregion
+//#region src/albrecht/diff.ts
+/**
+* Added, changed and removed functions between two counts — what becomes an
+* invoice.
+*
+* Normative base: **OMG Automated Enhancement Points 1.0**, the sibling of AFP,
+* written to size maintenance between two revisions.
+*
+*   "Each Artifact shall be analyzed in both revisions to determine whether it
+*    is: Added — when it exists in revision ToRevision while it didn't exist in
+*    FromRevision. […] Modified — when it exists in both revisions but whose
+*    source code changed."  — AEP §6.3
+*
+* Two decisions make this workable:
+*
+* 1. **It operates on two saved counts**, never on two checkouts. Booting the
+*    older revision, with possibly different dependencies, is the kind of
+*    problem not worth solving.
+* 2. **It refuses to compare different rule sets.** If the rules changed in
+*    between, the difference measures the rule change, not the work — and the
+*    result would go into an invoice.
+*/
+var IncomparableRulesetsError = class extends Error {
+	constructor(from, to) {
+		super(`counts from different rule sets are not comparable: ${from} vs ${to}. The rules changed between the two measurements, so the difference does not measure work — it measures the rule change.`);
+		this.name = "IncomparableRulesetsError";
+	}
+};
+const AEP_FACTORS = {
+	added: 1,
+	changed: 1,
+	removed: .4,
+	unchanged: 0
+};
+/**
+* Two counts of DIFFERENT applications compare cleanly and mean nothing.
+*
+* The ruleset guard already refuses counts produced by different rules. This
+* refuses counts produced over different subjects, which is the same class of
+* error and the easier one to make in CI, where both files arrive as paths.
+*/
+var IncomparableSourcesError = class extends Error {
+	constructor(from, to) {
+		super(`refusing to compare counts of different applications: "${from}" and "${to}". The difference would not measure work, it would measure that the two files are about different things.`);
+		this.from = from;
+		this.to = to;
+		this.name = "IncomparableSourcesError";
+	}
+};
+function diffCounts(from, to, options = {}) {
+	if (from.rulesetVersion !== to.rulesetVersion || from.ruleset !== to.ruleset) throw new IncomparableRulesetsError(`${from.ruleset}@${from.rulesetVersion}`, `${to.ruleset}@${to.rulesetVersion}`);
+	if (from.source && to.source && from.source.app !== to.source.app) throw new IncomparableSourcesError(from.source.app, to.source.app);
+	const factors = {
+		...AEP_FACTORS,
+		...options.factors
+	};
+	const before = new Map(from.functions.map((fn) => [fn.id, fn]));
+	const after = new Map(to.functions.map((fn) => [fn.id, fn]));
+	const entries = [];
+	for (const [id, fn] of after) {
+		const previous = before.get(id);
+		if (!previous) {
+			entries.push({
+				function: fn,
+				change: "added"
+			});
+			continue;
+		}
+		const reason = reasonBetween(previous, fn);
+		entries.push({
+			function: fn,
+			change: reason ? "changed" : "unchanged",
+			previous,
+			...reason ? { reason } : {}
+		});
+	}
+	for (const [id, fn] of before) if (!after.has(id)) entries.push({
+		function: fn,
+		change: "removed"
+	});
+	const warnings = [];
+	/**
+	* Provenance warnings. None of them stops the comparison — they qualify the
+	* number that comes out of it, which is what goes onto an invoice.
+	*/
+	for (const [side, count] of [["from", from], ["to", to]]) {
+		if (!count.source) {
+			warnings.push(`the "${side}" count records no source: it cannot be tied to a revision, so this difference cannot be reproduced or audited later.`);
+			continue;
+		}
+		if (count.source.dirty) warnings.push(`the "${side}" count was taken over a tree with uncommitted changes (${count.source.app}${count.source.revision ? ` at ${count.source.revision.slice(0, 8)}` : ""}): no revision reproduces it.`);
+	}
+	if (from.source?.revision && from.source.revision === to.source?.revision && !from.source.dirty && !to.source.dirty) warnings.push(`both counts are of the same revision (${from.source.revision.slice(0, 8)}): any difference here comes from the tool or its configuration, not from work done.`);
+	if (entries.some((entry) => entry.change === "changed") && factors.changed === 1) warnings.push("change factor pinned at 1: AEP grades it from 0.25 to 1.75 through Effort Complexity variation, which requires cyclomatic complexity — not measured yet. Changed functions are being billed at full value.");
+	return {
+		from: options.labels?.from ?? "previous",
+		to: options.labels?.to ?? "current",
+		entries: entries.sort(byChangeThenName),
+		totals: totalsOf(entries),
+		changedByReason: changedByReasonOf(entries),
+		billable: entries.reduce((total, entry) => total + entry.function.points * factors[entry.change], 0),
+		factors,
+		warnings
+	};
+}
+/**
+* What counts as a change.
+*
+* A change in the implementation scope (checksum of the normalised AST) **or**
+* in the functional size. Formatting and comments do not count: the hash
+* already ignores them.
+*
+* Renaming a route does not show up here because identity is
+* `(verb, pattern)` — and neither does moving a controller between modules,
+* which is implementation.
+*/
+/**
+* Why the function changed, or null when it did not.
+*
+* Reported by the most consequential cause: a reclassification usually moves
+* the size too, and naming the type is the fact that explains the rest. The
+* rendered line carries the DET and FTR movement, so nothing is hidden behind
+* the label.
+*/
+function reasonBetween(previous, current) {
+	if (previous.type !== current.type) return "type";
+	if (previous.det !== current.det || previous.refs !== current.refs) return "size";
+	if ((previous.scopeHash ?? "") !== (current.scopeHash ?? "")) return "implementation";
+	return null;
+}
+/**
+* Where an invoice actually comes from.
+*
+* `changed` is usually the largest line, and until this split it said nothing
+* about whether it was paying for growth or for refactoring.
+*/
+function changedByReasonOf(entries) {
+	const byReason = {
+		type: {
+			count: 0,
+			points: 0
+		},
+		size: {
+			count: 0,
+			points: 0
+		},
+		implementation: {
+			count: 0,
+			points: 0
+		}
+	};
+	for (const entry of entries) {
+		if (entry.change !== "changed" || !entry.reason) continue;
+		byReason[entry.reason].count++;
+		byReason[entry.reason].points += entry.function.points;
+	}
+	return byReason;
+}
+const ORDER = {
+	added: 0,
+	changed: 1,
+	removed: 2,
+	unchanged: 3
+};
+const byChangeThenName = (a, b) => ORDER[a.change] - ORDER[b.change] || a.function.name.localeCompare(b.function.name);
+function totalsOf(entries) {
+	const totals = {
+		added: {
+			count: 0,
+			points: 0
+		},
+		changed: {
+			count: 0,
+			points: 0
+		},
+		removed: {
+			count: 0,
+			points: 0
+		},
+		unchanged: {
+			count: 0,
+			points: 0
+		}
+	};
+	for (const entry of entries) {
+		totals[entry.change].count++;
+		totals[entry.change].points += entry.function.points;
+	}
+	return totals;
+}
+//#endregion
+//#region src/reporters/table.ts
+/**
+* Text reports.
+*
+* They return a string instead of printing: that is what makes them testable
+* without capturing output, and it keeps each ace command down to
+* `this.logger.log(render(...))`.
+*/
+const pad = (value, width) => String(value).padEnd(width);
+const padStart = (value, width) => String(value).padStart(width);
+function renderCount(result) {
+	const lines = [];
+	lines.push(`Unadjusted count: ${result.totals.unadjusted} FP`);
+	lines.push(`Ruleset: ${result.ruleset}@${result.rulesetVersion}`);
+	lines.push("");
+	lines.push(`${pad("type", 6)}${padStart("n", 5)}${padStart("FP", 7)}`);
+	for (const [type, value] of Object.entries(result.totals.byType)) {
+		if (value.count === 0) continue;
+		lines.push(`${pad(type, 6)}${padStart(value.count, 5)}${padStart(value.points, 7)}`);
+	}
+	lines.push("");
+	lines.push(`${pad("function", 40)}${pad("type", 6)}${padStart("DET", 5)}${padStart("FTR", 5)}${padStart("FP", 5)}`);
+	for (const fn of result.functions) lines.push(`${pad(fn.name.slice(0, 39), 40)}${pad(fn.type, 6)}${padStart(fn.det, 5)}${padStart(fn.refs, 5)}${padStart(fn.points, 5)}`);
+	/**
+	* How much of the total stopped coming from the code.
+	*
+	* An override is legitimate where static analysis is blind, and poison as a
+	* habit: if it grows, the count comes from a spreadsheet and the tool loses
+	* its reason to exist. Printing the share is what keeps that visible.
+	*/
+	const overridden = result.functions.filter((fn) => fn.rationale.overrides?.length);
+	if (overridden.length > 0) {
+		const points = overridden.reduce((total, fn) => total + fn.points, 0);
+		const share = (points / (result.totals.unadjusted || 1) * 100).toFixed(1);
+		lines.push("");
+		lines.push(`Declared by override: ${overridden.length} function(s), ${points} FP (${share}% of the total)`);
+		for (const fn of overridden) for (const override of fn.rationale.overrides ?? []) lines.push(`  ${fn.name} — ${override.reason}`);
+	}
+	/**
+	* Confidence comes right after the number, never hidden. AFP §6.5.3 requires
+	* whatever could not be traced to appear in the report.
+	*/
+	const { unresolvedCalls, entryPointsWithoutHandler, warnings } = result.confidence;
+	if (unresolvedCalls > 0 || entryPointsWithoutHandler > 0 || warnings.length > 0) {
+		lines.push("");
+		lines.push("Confidence:");
+		if (unresolvedCalls > 0) lines.push(`  ${unresolvedCalls} unresolved calls`);
+		if (entryPointsWithoutHandler > 0) lines.push(`  ${entryPointsWithoutHandler} entry points without a handler`);
+		for (const warning of warnings) lines.push(`  ${warning}`);
+	}
+	return lines.join("\n");
+}
+/** `fp:explain`: a function's provenance, which is what supports a dispute */
+function renderExplain(fn) {
+	const lines = [];
+	lines.push(`${fn.name}  —  ${fn.type}, ${fn.complexity} complexity, ${fn.points} FP`);
+	lines.push(`module: ${fn.module}`);
+	lines.push("");
+	lines.push(`Rule applied: ${fn.rationale.rule}`);
+	/**
+	* A declared count is marked on the line itself. Printing `DET = 60` above a
+	* list of five sources reads as an inconsistency, when in fact the number
+	* came from a person and the sources are what the analysis could still see.
+	*/
+	const overridden = (field) => fn.rationale.overrides?.some((o) => o.fields.includes(field)) ? "  (declared by override)" : "";
+	lines.push("");
+	lines.push(`DET = ${fn.det}${overridden("det")}`);
+	for (const source of fn.rationale.detSources) lines.push(`  ${source}`);
+	lines.push("");
+	lines.push(`${fn.type === "ILF" || fn.type === "EIF" ? "RET" : "FTR"} = ${fn.refs}${overridden("refs")}`);
+	for (const source of fn.rationale.refSources) lines.push(`  ${source}`);
+	if (fn.rationale.trace?.length) {
+		lines.push("");
+		lines.push("Path walked:");
+		for (const step of fn.rationale.trace) {
+			const marca = step.writes ? " [writes]" : "";
+			lines.push(`  ${"  ".repeat(step.depth)}${step.file.split("/").slice(-2).join("/")}#${step.member ?? "handle"}  (${step.by})${marca}`);
+		}
+	}
+	if (fn.rationale.overrides?.length) {
+		lines.push("");
+		lines.push("Manual overrides:");
+		for (const override of fn.rationale.overrides) lines.push(`  ${override.by}: ${override.reason}`);
+	}
+	return lines.join("\n");
+}
+/** `fp:diff`: added, changed and removed — what becomes an invoice */
+/**
+* What moved, for a size change. Shown beside the label so the reason is never
+* a claim the reader has to take on trust.
+*/
+function movementOf(entry) {
+	if (entry.reason === "type" && entry.previous) return `   ${entry.previous.type} -> ${entry.function.type}`;
+	if (entry.reason !== "size" || !entry.previous) return "";
+	const parts = [];
+	if (entry.previous.det !== entry.function.det) parts.push(`DET ${entry.previous.det} -> ${entry.function.det}`);
+	if (entry.previous.refs !== entry.function.refs) parts.push(`FTR ${entry.previous.refs} -> ${entry.function.refs}`);
+	return parts.length > 0 ? `   ${parts.join(", ")}` : "";
+}
+function renderDiff(diff) {
+	const lines = [];
+	lines.push(`${diff.from} -> ${diff.to}`);
+	lines.push("");
+	for (const [change, total] of Object.entries(diff.totals)) {
+		if (total.count === 0) continue;
+		const factor = diff.factors[change];
+		lines.push(`${pad(change, 11)}${padStart(total.count, 4)} functions${padStart(total.points, 6)} FP  × ${factor}`);
+		/**
+		* `changed` is usually the largest line on the invoice, and on its own it
+		* does not say whether it is paying for growth or for refactoring.
+		*/
+		if (change === "changed") for (const [reason, split] of Object.entries(diff.changedByReason)) {
+			if (split.count === 0) continue;
+			lines.push(`  ${pad(reason, 16)}${padStart(split.count, 3)} functions${padStart(split.points, 6)} FP`);
+		}
+	}
+	lines.push("");
+	lines.push(`Billable FP: ${diff.billable}`);
+	const mudou = diff.entries.filter((entry) => entry.change !== "unchanged");
+	if (mudou.length > 0) {
+		lines.push("");
+		for (const entry of mudou) {
+			const label = entry.reason ? `${entry.change} (${entry.reason})` : entry.change;
+			lines.push(`  ${pad(label, 26)} ${pad(entry.function.name.slice(0, 40), 41)}${padStart(entry.function.points, 4)} PF${movementOf(entry)}`);
+		}
+	}
+	for (const warning of diff.warnings) {
+		lines.push("");
+		lines.push(`Warning: ${warning}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/cli/load_config.ts
+/**
+* Loads `config/function_points.ts` from the application being analysed.
+*
+* Both front-ends need this and neither could do it alone: the ace commands run
+* with `startApp: false`, so there is no booted container to read config from;
+* and the standalone CLI has no container at all. The file is therefore
+* imported directly, through jiti, which transforms the whole module graph —
+* a config may import a resolver from the application, and that resolver may
+* import files using decorators, which Node's type stripping cannot handle.
+*
+* **A config that exists and fails to load is an error, never a fallback.**
+* Falling back to defaults with a warning would silently change the count, and
+* the count becomes an invoice. Absence of a config file is a different thing,
+* and is legitimate: it means the defaults.
+*/
+const CONFIG_PATHS = ["config/function_points.ts", "config/function_points.js"];
+var ConfigLoadError = class extends Error {
+	constructor(file, cause) {
+		super(`failed to load ${file}: ${cause instanceof Error ? cause.message : String(cause)}\nThe count was NOT produced. Fix the configuration, or remove the file to use the defaults — falling back silently would change the number without telling you.`);
+		this.file = file;
+		this.cause = cause;
+		this.name = "ConfigLoadError";
+	}
+};
+async function loadConfig(root) {
+	const found = CONFIG_PATHS.map((candidate) => path.join(root, candidate)).find((candidate) => existsSync(candidate));
+	if (!found) return {
+		config: { ...DEFAULTS },
+		file: null
+	};
+	let loaded;
+	try {
+		loaded = await createJiti(pathToFileURL(path.join(root, "noop.js")).href, { interopDefault: true }).import(found, { default: true });
+	} catch (error) {
+		throw new ConfigLoadError(found, error);
+	}
+	if (!loaded || typeof loaded !== "object") throw new ConfigLoadError(found, /* @__PURE__ */ new Error("the default export is not a configuration object"));
+	return {
+		config: defineConfig(loaded),
+		file: toPosix(found)
+	};
+}
+//#endregion
+//#region src/cli/runners.ts
+/**
+* An empty inventory is never a number.
+*
+* Both front-ends can be pointed at a directory that is not the application —
+* a monorepo root is the common case — and the symptom is not an error, it is
+* a confident zero: 0 FP at 100% coverage, exit 0, CI green. Counting nothing
+* and reporting nothing are indistinguishable from the outside, so the only
+* safe answer is to refuse.
+*/
+function refuseIfEmpty(root, stores, entryPoints) {
+	if (stores > 0 || entryPoints > 0) return null;
+	return [
+		`found no data stores and no entry points in ${root}.`,
+		`That is not a count of zero — it is a failure to find the application.`,
+		`Check that --root points at the AdonisJS application (apps/<name> in a monorepo).`
+	];
+}
+/** every run says which configuration produced it — provenance starts here */
+async function configFor(root) {
+	const { config, file } = await loadConfig(root);
+	const notes = file ? [`config: ${file}`] : ["config: defaults (no config/function_points.ts found)"];
+	return {
+		config: {
+			...config,
+			configFile: file
+		},
+		notes
+	};
+}
+async function runInventory(options) {
+	const { config, notes } = await configFor(options.root);
+	const { inventory } = await analyze(options.root, config);
+	const empty = refuseIfEmpty(options.root, inventory.dataStores.length, inventory.entryPoints.length);
+	if (empty) return {
+		output: "",
+		notes,
+		errors: empty
+	};
+	if (options.out) {
+		await writeFile(options.out, JSON.stringify(inventory, null, 2));
+		return {
+			output: `inventory written to ${options.out}`,
+			notes
+		};
+	}
+	const { coverage } = inventory;
+	return {
+		notes,
+		output: [
+			`data stores:   ${inventory.dataStores.length}`,
+			`entry points:  ${coverage.entryPointsTotal}`,
+			`coverage:      ${(coverage.ratio * 100).toFixed(1)}% (${coverage.unresolvedCalls} unresolved calls)`
+		].join("\n")
+	};
+}
+async function runCount(options) {
+	const { config, notes } = await configFor(options.root);
+	const { inventory, count } = await analyze(options.root, {
+		...config,
+		minCoverage: options.minCoverage ?? config.minCoverage
+	});
+	const empty = refuseIfEmpty(options.root, inventory.dataStores.length, inventory.entryPoints.length);
+	if (empty) return {
+		output: "",
+		notes,
+		errors: empty
+	};
+	if (options.out) {
+		await writeFile(options.out, JSON.stringify(count, null, 2));
+		notes.push(`count written to ${options.out}`);
+	}
+	return {
+		notes,
+		output: options.json ? JSON.stringify(count, null, 2) : renderCount(count)
+	};
+}
+async function runExplain(options) {
+	const { config, notes } = await configFor(options.root);
+	const { count } = await analyze(options.root, config);
+	const matched = count.functions.filter((fn) => fn.name.toLowerCase().includes(options.name.toLowerCase()));
+	if (matched.length === 0) return {
+		output: "",
+		notes,
+		errors: [`no function matching "${options.name}"`]
+	};
+	return {
+		notes,
+		output: matched.map(renderExplain).join("\n\n" + "-".repeat(70) + "\n\n")
+	};
+}
+const readCount = async (file) => JSON.parse(await readFile(file, "utf8"));
+/**
+* Compares a saved count against the current tree, or against a second saved
+* count.
+*
+* The two-file form is the shape CI has: a pipeline counts the base revision
+* and the head revision, and neither of them is "the current working tree" by
+* the time they are compared. Since the analyser needs nothing installed in the
+* application, counting an older revision is a `git worktree` away.
+*/
+async function runDiff(options) {
+	const { config, notes } = await configFor(options.root);
+	const previous = await readCount(options.previous);
+	let current;
+	if (options.current) current = await readCount(options.current);
+	else current = (await analyze(options.root, config)).count;
+	const to = options.current ?? "current";
+	for (const [label, count] of [[options.previous, previous], [to, current]]) {
+		const source = count.source;
+		if (!source) continue;
+		notes.push(`${label}: ${source.app}` + (source.revision ? ` @ ${source.revision.slice(0, 8)}` : "") + (source.dirty ? " (dirty)" : ""));
+	}
+	try {
+		return {
+			notes,
+			output: renderDiff(diffCounts(previous, current, { labels: {
+				from: options.previous,
+				to
+			} }))
+		};
+	} catch (error) {
+		if (error instanceof IncomparableRulesetsError || error instanceof IncomparableSourcesError) return {
+			output: "",
+			notes,
+			errors: [error.message]
+		};
+		throw error;
+	}
+}
+async function runCalibrate(options) {
+	const { config, notes } = await configFor(options.root);
+	const samples = parseSamples(await readFile(options.samples, "utf8"));
+	const { count } = await analyze(options.root, config);
+	const calibration = calibrate(count, samples);
+	const { overall } = calibration;
+	const lines = [
+		`samples: ${overall.samples} · manual ${overall.manualPoints} FP · automatic ${overall.automaticPoints} FP · deviation ${(overall.deviation * 100).toFixed(1)}%`,
+		`exact matches: ${overall.exactMatches}/${overall.samples}`,
+		""
+	];
+	for (const item of calibration.byType) lines.push(`${item.type.padEnd(4)} n=${String(item.samples).padStart(3)} factor ${item.factor.toFixed(3)} · mean deviation ${item.meanAbsoluteDeviation} FP`);
+	return {
+		notes: [...notes, ...calibration.warnings],
+		output: lines.join("\n")
+	};
+}
+//#endregion
+export { runInventory as a, runExplain as i, runCount as n, ConfigLoadError as o, runDiff as r, printResult as s, runCalibrate as t };

package/build/scripts/smoke_package.d.ts

@@ -0,0 +1 @@
+export {};

package/build/src/albrecht/calibration.d.ts

@@ -0,0 +1,62 @@
+import type { CountResult, FunctionType } from '../types.js';
+/**
+ * Calibration: measuring the counter's bias against manual counts.
+ *
+ * This is what turns a percentage of deviation into a usable number. The
+ * premise was never exactness against a certified counter — it was
+ * **repeatability**, which is what makes calibration possible: systematic error
+ * can be calibrated away, variance between human counters cannot.
+ *
+ * AFP takes the same position on purpose:
+ *
+ *   "This specification prioritizes repeatability and consistency over
+ *    consistency with the IFPUG CPM counting guidelines."  — AFP §6.1
+ *
+ * What this module does NOT do: apply the factor. Calibrating is a decision for
+ * whoever signs the contract, and a factor applied silently would stop the
+ * count from being reproducible from the source.
+ */
+export type CalibrationSample = {
+    /** function identity, as it appears in the count */
+    function: string;
+    /** function points from the manual count */
+    manual: number;
+};
+export type TypeCalibration = {
+    type: FunctionType;
+    samples: number;
+    manualPoints: number;
+    automaticPoints: number;
+    /**
+     * Factor bringing the automatic count towards the manual one:
+     * `manual / automatic`.
+     *
+     * Greater than 1 means the counter **underestimates** this type.
+     */
+    factor: number;
+    /** mean absolute deviation, in function points per function */
+    meanAbsoluteDeviation: number;
+    exactMatches: number;
+};
+export type Calibration = {
+    byType: TypeCalibration[];
+    overall: {
+        samples: number;
+        manualPoints: number;
+        automaticPoints: number;
+        /** relative deviation of the total, signed: positive means automatic is larger */
+        deviation: number;
+        exactMatches: number;
+    };
+    /** samples that matched no counted function */
+    unmatched: string[];
+    warnings: string[];
+};
+export declare function calibrate(result: CountResult, samples: CalibrationSample[]): Calibration;
+/**
+ * Reads samples from CSV: `function,fp` with a header row.
+ *
+ * Deliberately plain. A metrics analyst exports from a spreadsheet, and
+ * demanding JSON would add friction where none is needed.
+ */
+export declare function parseSamples(csv: string): CalibrationSample[];