@filipebraida/adonis-function-points 0.1.0 → 0.2.0

package/build/{runners-Bt8tbISi.js → runners-DpMd-yZM.js}

@@ -1,10 +1,55 @@
 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 { c as toPosix } from "./resolvers-MFjRl2ef.js";
+import { n as analyze } from "./pipeline-DySlMWcN.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/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/print.ts
 function printResult(result, printer) {
 	for (const note of result.notes ?? []) printer.note(note);
@@ -57,8 +102,8 @@ function calibrate(result, samples) {
 		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),
+		factor: bucket.automatic === 0 ? 1 : round$1(bucket.manual / bucket.automatic),
+		meanAbsoluteDeviation: round$1(bucket.deviations.reduce((total, value) => total + value, 0) / bucket.deviations.length),
 		exactMatches: bucket.exact
 	})).sort((a, b) => a.type.localeCompare(b.type));
 	const warnings = [];
@@ -72,14 +117,14 @@ function calibrate(result, samples) {
 			samples: matched,
 			manualPoints: manualTotal,
 			automaticPoints: automaticTotal,
-			deviation: manualTotal === 0 ? 0 : round((automaticTotal - manualTotal) / manualTotal),
+			deviation: manualTotal === 0 ? 0 : round$1((automaticTotal - manualTotal) / manualTotal),
 			exactMatches: exactTotal
 		},
 		unmatched,
 		warnings
 	};
 }
-const round = (value) => Math.round(value * 1e3) / 1e3;
+const round$1 = (value) => Math.round(value * 1e3) / 1e3;
 /**
 * Reads samples from CSV: `function,fp` with a header row.
 *
@@ -167,6 +212,9 @@ function diffCounts(from, to, options = {}) {
 		...AEP_FACTORS,
 		...options.factors
 	};
+	const reasonFactors = options.reasonFactors ?? {};
+	/** the factor a single entry is billed at, which is the per-reason one when set */
+	const factorFor = (entry) => entry.change === "changed" && entry.reason ? reasonFactors[entry.reason] ?? factors.changed : factors[entry.change];
 	const before = new Map(from.functions.map((fn) => [fn.id, fn]));
 	const after = new Map(to.functions.map((fn) => [fn.id, fn]));
 	const entries = [];
@@ -204,15 +252,36 @@ function diffCounts(from, to, options = {}) {
 		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.");
+	/**
+	* Quantified, because the generic sentence was not actionable.
+	*
+	* On a real pair of releases this warning sat under 118 lines of per-function
+	* output, saying only that the factor was pinned. What a client disputes is
+	* the amount, so the amount is what it has to say.
+	*/
+	const changedPoints = entries.filter((entry) => entry.change === "changed").reduce((total, entry) => total + entry.function.points, 0);
+	if (changedPoints > 0 && factors.changed === 1 && reasonFactors.implementation === void 0) {
+		const byReason = changedByReasonOf(entries);
+		const billable = round2(entries.reduce((total, entry) => total + entry.function.points * factorFor(entry), 0));
+		const share = billable === 0 ? 0 : Math.round(changedPoints / billable * 100);
+		warnings.push(`${changedPoints} of ${billable} billable FP (${share}%) are modified functions at a factor pinned to 1. AEP grades it from 0.25 to 1.75 through Effort Complexity variation, which needs cyclomatic complexity — not measured yet. Of those, ${byReason.implementation.points} FP changed implementation only (same type, DET and FTR): set \`reasonFactors\` to price that differently.`);
+	}
 	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),
+		/**
+		* Rounded to cents at the source, not at the print.
+		*
+		* `485.00000000000006` appeared on the first real diff. It is arithmetically
+		* the same number and it is not the same document: this value is quoted in
+		* an invoice, and a reader who sees that tail stops trusting the rest.
+		*/
+		billable: round2(entries.reduce((total, entry) => total + entry.function.points * factorFor(entry), 0)),
 		factors,
+		reasonFactors,
 		warnings
 	};
 }
@@ -301,6 +370,80 @@ function totalsOf(entries) {
 	}
 	return totals;
 }
+/** two decimals: this number is quoted in an invoice */
+const round2 = (value) => Math.round(value * 100) / 100;
+//#endregion
+//#region src/metrics/structure.ts
+function measureStructure(inventory, count) {
+	/** store -> module that declares it */
+	const storeModule = new Map(inventory.dataStores.map((store) => [store.name, store.module]));
+	/** entry point -> module */
+	const entryModule = new Map(inventory.entryPoints.map((entry) => [entry.id, entry.module]));
+	const modules = new Set([...storeModule.values(), ...entryModule.values()]);
+	const dependsOn = /* @__PURE__ */ new Map();
+	for (const module of modules) dependsOn.set(module, /* @__PURE__ */ new Set());
+	/**
+	* The dependency that matters is USE, not import: module A depends on B when
+	* a transaction of A reaches a store declared in B. A type-only import
+	* creates no functional coupling.
+	*/
+	for (const behavior of inventory.behaviors) {
+		const from = entryModule.get(behavior.entryPointId);
+		if (!from) continue;
+		for (const store of behavior.touches) {
+			const to = storeModule.get(store);
+			if (!to || to === from) continue;
+			dependsOn.get(from)?.add(to);
+		}
+	}
+	const dependedOnBy = /* @__PURE__ */ new Map();
+	for (const module of modules) dependedOnBy.set(module, /* @__PURE__ */ new Set());
+	for (const [from, targets] of dependsOn) for (const to of targets) dependedOnBy.get(to)?.add(from);
+	const transactionsPerModule = /* @__PURE__ */ new Map();
+	for (const module of entryModule.values()) transactionsPerModule.set(module, (transactionsPerModule.get(module) ?? 0) + 1);
+	const storesPerModule = /* @__PURE__ */ new Map();
+	for (const module of storeModule.values()) storesPerModule.set(module, (storesPerModule.get(module) ?? 0) + 1);
+	const moduleMetrics = [...modules].map((module) => {
+		const ce = dependsOn.get(module).size;
+		const ca = dependedOnBy.get(module).size;
+		return {
+			module,
+			functionPoints: count.totals.byModule[module] ?? 0,
+			transactions: transactionsPerModule.get(module) ?? 0,
+			dataStores: storesPerModule.get(module) ?? 0,
+			dependsOn: [...dependsOn.get(module)].sort(),
+			dependedOnBy: [...dependedOnBy.get(module)].sort(),
+			instability: ca + ce === 0 ? 0 : round(ce / (ca + ce))
+		};
+	}).sort((a, b) => b.functionPoints - a.functionPoints);
+	const mutual = [];
+	for (const [from, targets] of dependsOn) for (const to of targets) if (from < to && dependsOn.get(to)?.has(from)) mutual.push([from, to]);
+	const stores = inventory.dataStores.length || 1;
+	return {
+		modules: moduleMetrics,
+		mutualDependencies: mutual.sort(),
+		pointsPerDataStore: round(count.totals.unadjusted / stores),
+		transactionsPerDataStore: round(inventory.entryPoints.length / stores)
+	};
+}
+function measureConformance(inventory) {
+	const behaviors = inventory.behaviors;
+	const takesInput = behaviors.filter((behavior) => behavior.inputFields.length > 0 || behavior.requestFields.length > 0 || behavior.opaqueRequest);
+	const withValidator = takesInput.filter((behavior) => behavior.inputFields.length > 0);
+	const withHandler = inventory.entryPoints.filter((entry) => entry.handler !== null);
+	const reached = new Set(behaviors.flatMap((behavior) => behavior.touches));
+	return {
+		inputsWithValidator: ratio(withValidator.length, takesInput.length),
+		entryPointsWithHandler: ratio(withHandler.length, inventory.entryPoints.length),
+		dataStoresReached: ratio(reached.size, inventory.dataStores.length)
+	};
+}
+const ratio = (ok, total) => ({
+	ok,
+	total,
+	ratio: total === 0 ? 1 : round(ok / total)
+});
+const round = (value) => Math.round(value * 1e3) / 1e3;
 //#endregion
 //#region src/reporters/table.ts
 /**
@@ -355,6 +498,41 @@ function renderCount(result) {
 	return lines.join("\n");
 }
 /** `fp:explain`: a function's provenance, which is what supports a dispute */
+/**
+* Structure and conformance, beside the count and never instead of it.
+*
+* If function points pay, the team optimises function points — more models, more
+* endpoints, less reuse. Density and coupling on the same report are the
+* counterweight, which is why this shares the inventory rather than collecting
+* anything of its own.
+*/
+function renderMetrics(structure, conformance, coverage) {
+	const lines = [];
+	lines.push("Density");
+	lines.push(`  FP per data store:            ${structure.pointsPerDataStore.toFixed(1)}`);
+	lines.push(`  transactions per data store:  ${structure.transactionsPerDataStore.toFixed(1)}`);
+	lines.push("");
+	lines.push("Conformance");
+	for (const [label, value] of [
+		["inputs with a validator", conformance.inputsWithValidator],
+		["entry points with a handler", conformance.entryPointsWithHandler],
+		["data stores reached", conformance.dataStoresReached]
+	]) lines.push(`  ${pad(label, 28)}${padStart(`${(value.ratio * 100).toFixed(1)}%`, 7)}   (${value.ok}/${value.total})`);
+	lines.push(`  ${pad("tracing coverage", 28)}${padStart(`${(coverage.ratio * 100).toFixed(1)}%`, 7)}   (${coverage.unresolvedCalls} unresolved calls)`);
+	lines.push("");
+	lines.push(`${pad("module", 20)}${padStart("FP", 6)}${padStart("trans", 7)}${padStart("stores", 7)}${padStart("I", 6)}  depends on`);
+	for (const module of structure.modules) lines.push(`${pad(module.module.slice(0, 19), 20)}${padStart(module.functionPoints, 6)}${padStart(module.transactions, 7)}${padStart(module.dataStores, 7)}${padStart(module.instability.toFixed(2), 6)}  ${module.dependsOn.join(", ")}`);
+	/**
+	* Reported, not scored. A cycle between two modules is a fact about the code
+	* that a number would hide, and the decision about it is the team's.
+	*/
+	if (structure.mutualDependencies.length > 0) {
+		lines.push("");
+		lines.push("Mutual dependencies (cycle candidates)");
+		for (const [a, b] of structure.mutualDependencies) lines.push(`  ${a} <-> ${b}`);
+	}
+	return lines.join("\n");
+}
 function renderExplain(fn) {
 	const lines = [];
 	lines.push(`${fn.name}  —  ${fn.type}, ${fn.complexity} complexity, ${fn.points} FP`);
@@ -415,70 +593,40 @@ function renderDiff(diff) {
 		*/
 		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`);
+			/**
+			* The effective factor, per reason. Printing only the `changed` factor
+			* hid that `implementation` — no change in type, DET or FTR — was being
+			* billed at the same rate as a functional one.
+			*/
+			const effective = diff.reasonFactors[reason];
+			lines.push(`  ${pad(reason, 16)}${padStart(split.count, 3)} functions${padStart(split.points, 6)} FP` + (effective === void 0 ? "" : `  × ${effective}`));
 		}
 	}
 	lines.push("");
 	lines.push(`Billable FP: ${diff.billable}`);
-	const mudou = diff.entries.filter((entry) => entry.change !== "unchanged");
-	if (mudou.length > 0) {
+	/**
+	* Before the per-function list, not after it.
+	*
+	* On a real pair of releases the list is over a hundred lines, and a caveat
+	* about how most of the total was priced sat below all of them. A warning that
+	* has to be scrolled to is not a warning — and this particular number becomes
+	* an invoice.
+	*/
+	for (const warning of diff.warnings) {
+		lines.push("");
+		lines.push(`Warning: ${warning}`);
+	}
+	const moved = diff.entries.filter((entry) => entry.change !== "unchanged");
+	if (moved.length > 0) {
 		lines.push("");
-		for (const entry of mudou) {
+		for (const entry of moved) {
 			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.
@@ -556,6 +704,42 @@ async function runCount(options) {
 		output: options.json ? JSON.stringify(count, null, 2) : renderCount(count)
 	};
 }
+/**
+* Structure and conformance, from the same inventory as the count.
+*
+* These were implemented and tested and reachable from no front-end at all,
+* which is the recurring defect of this package: a capability that exists,
+* typed and covered, and that nobody can run. A metric nobody can run is not a
+* metric.
+*/
+async function runMetrics(options) {
+	const { config, notes } = await configFor(options.root);
+	const { inventory, count } = await analyze(options.root, config);
+	const empty = refuseIfEmpty(options.root, inventory.dataStores.length, inventory.entryPoints.length);
+	if (empty) return {
+		output: "",
+		notes,
+		errors: empty
+	};
+	const structure = measureStructure(inventory, count);
+	const conformance = measureConformance(inventory);
+	if (options.out) {
+		await writeFile(options.out, JSON.stringify({
+			source: count.source,
+			structure,
+			conformance
+		}, null, 2));
+		notes.push(`metrics written to ${options.out}`);
+	}
+	return {
+		notes,
+		output: options.json ? JSON.stringify({
+			source: count.source,
+			structure,
+			conformance
+		}, null, 2) : renderMetrics(structure, conformance, inventory.coverage)
+	};
+}
 async function runExplain(options) {
 	const { config, notes } = await configFor(options.root);
 	const { count } = await analyze(options.root, config);
@@ -595,10 +779,14 @@ async function runDiff(options) {
 	try {
 		return {
 			notes,
-			output: renderDiff(diffCounts(previous, current, { labels: {
-				from: options.previous,
-				to
-			} }))
+			output: renderDiff(diffCounts(previous, current, {
+				labels: {
+					from: options.previous,
+					to
+				},
+				factors: config.diff?.factors,
+				reasonFactors: config.diff?.reasonFactors
+			}))
 		};
 	} catch (error) {
 		if (error instanceof IncomparableRulesetsError || error instanceof IncomparableSourcesError) return {
@@ -627,4 +815,4 @@ async function runCalibrate(options) {
 	};
 }
 //#endregion
-export { runInventory as a, runExplain as i, runCount as n, ConfigLoadError as o, runDiff as r, printResult as s, runCalibrate as t };
+export { runInventory as a, ConfigLoadError as c, runExplain as i, runCount as n, runMetrics as o, runDiff as r, printResult as s, runCalibrate as t };

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

@@ -21,8 +21,16 @@ export declare const RULESET = "afp";
  * It appears in every report, and `fp:diff` refuses to compare counts produced
  * by different versions — otherwise the difference would measure the rule
  * change rather than the work.
+ *
+ * It must be bumped by ANY change that moves the number for unchanged code, and
+ * that is easy to forget: four such changes landed in 1.1.0 — maintenance read
+ * across the whole project rather than from routes alone, a job followed into
+ * `process`, an event followed into its listeners, and `request.input(…)` counted
+ * as a DET. Without the bump, a baseline saved by the previous version would have
+ * compared cleanly against this one and billed the tool's own improvement as work
+ * done. The guard exists for exactly that, and only this constant arms it.
  */
-export declare const RULESET_VERSION = "1.0.0";
+export declare const RULESET_VERSION = "1.1.0";
 export type CountInput = {
     app: AppContext;
     stores: CollectedDataStore[];
@@ -31,6 +39,12 @@ export type CountInput = {
     behaviors: Map<string, Behavior>;
     /** JSON Schema literals found in the code, for `detFromSchema` — §8 */
     jsonSchemas?: Map<string, DiscoveredSchema>;
+    /**
+     * Stores written anywhere in the application's code, reachable from an entry
+     * point or not — AFP §6.5.4 asks who MAINTAINS the store, and a job or a
+     * seeder is this application just as much as a route is.
+     */
+    writtenAnywhere?: Set<string>;
 };
 export type CountOptions = {
     retStrategy?: 'constant' | 'composition';
@@ -39,6 +53,8 @@ export type CountOptions = {
     boundary?: {
         infrastructure?: string[];
         externallyMaintained?: string[];
+        /** restores what the AFP naming filter caught by accident */
+        business?: string[];
         ignoreEntryPoints?: string[];
     };
     messageDet?: number;

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

@@ -26,6 +26,12 @@ export type DataFunctionOptions = {
     retStrategy: 'constant' | 'composition';
     /** stores maintained by another system, by boundary decision */
     externallyMaintained: Set<string>;
+    /**
+     * Stores the application writes anywhere in its code — a job, a seeder, a
+     * command — whether or not a route reaches that write. §6.5.4 asks who
+     * maintains the store, not which route does.
+     */
+    writtenAnywhere: Set<string>;
     tables: Record<FunctionType, ComplexityTable>;
     weights: Record<FunctionType, Record<Complexity, number>>;
 };

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

@@ -1,4 +1,4 @@
-import type { ChangeType, CountResult, DiffResult } from '../types.js';
+import type { ChangeReason, ChangeType, CountResult, DiffResult } from '../types.js';
 /**
  * Added, changed and removed functions between two counts — what becomes an
  * invoice.
@@ -37,8 +37,24 @@ export declare class IncomparableRulesetsError extends Error {
  */
 export type ChangeFactors = Record<ChangeType, number>;
 export declare const AEP_FACTORS: ChangeFactors;
+/**
+ * Factors for a modified function, by WHAT changed about it.
+ *
+ * The distinction is already measured — `type`, `size` and `implementation` come
+ * out of the same comparison — and pricing all three at 1 throws that away. It
+ * showed up on a real pair of releases: of 378 FP billed as changed, 151 came
+ * from functions whose type, DET and FTR were all identical and only the body
+ * differed. Charging a refactor at full functional value is not defensible, and
+ * charging it at a number this package invented would be worse.
+ *
+ * So no default changes: each reason falls back to `factors.changed`, and the
+ * contract sets what it agreed to price. What the tool owes is the split.
+ */
+export type ChangeReasonFactors = Partial<Record<ChangeReason, number>>;
 export type DiffOptions = {
     factors?: Partial<ChangeFactors>;
+    /** per-reason factors for modified functions; each falls back to `factors.changed` */
+    reasonFactors?: ChangeReasonFactors;
     /** labels for the two measurements, for the report only */
     labels?: {
         from: string;
@@ -49,6 +65,8 @@ export type FunctionPointDiff = DiffResult & {
     /** function points weighted by the factors — this is what gets billed */
     billable: number;
     factors: ChangeFactors;
+    /** what the modified functions were actually billed at, by reason */
+    reasonFactors: ChangeReasonFactors;
     warnings: string[];
 };
 /**

package/build/src/cli/runners.d.ts

@@ -30,6 +30,18 @@ export declare function runCount(options: Common & {
     json?: boolean;
     minCoverage?: number;
 }): Promise<RunResult>;
+/**
+ * Structure and conformance, from the same inventory as the count.
+ *
+ * These were implemented and tested and reachable from no front-end at all,
+ * which is the recurring defect of this package: a capability that exists,
+ * typed and covered, and that nobody can run. A metric nobody can run is not a
+ * metric.
+ */
+export declare function runMetrics(options: Common & {
+    out?: string;
+    json?: boolean;
+}): Promise<RunResult>;
 export declare function runExplain(options: Common & {
     name: string;
 }): Promise<RunResult>;

package/build/src/cli.js

@@ -1,5 +1,5 @@
-import { t as CoverageTooLowError } from "../pipeline-BzP-ITGN.js";
-import { a as runInventory, i as runExplain, n as runCount, o as ConfigLoadError, r as runDiff, s as printResult, t as runCalibrate } from "../runners-Bt8tbISi.js";
+import { t as CoverageTooLowError } from "../pipeline-DySlMWcN.js";
+import { a as runInventory, c as ConfigLoadError, i as runExplain, n as runCount, o as runMetrics, r as runDiff, s as printResult, t as runCalibrate } from "../runners-DpMd-yZM.js";
 import path from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -23,6 +23,7 @@ Usage
 Commands
   count                    count the unadjusted function points
   inventory                the raw facts: stores, routes, tracing coverage
+  metrics                  density, coupling and conformance, from the same run
   explain <name>           why one function was counted that way
   diff <a.json> [b.json]   additions / modifications / deletions, and billable FP
                            one file compares against the current tree; two
@@ -105,6 +106,7 @@ async function run(argv, printer = CONSOLE) {
 	if (![
 		"count",
 		"inventory",
+		"metrics",
 		"explain",
 		"diff",
 		"calibrate"
@@ -153,6 +155,13 @@ async function run(argv, printer = CONSOLE) {
 				out: text(flags.get("out"))
 			});
 			break;
+		case "metrics":
+			result = await runMetrics({
+				root,
+				out: text(flags.get("out")),
+				json: flags.get("json") === true
+			});
+			break;
 		case "explain":
 			result = await runExplain({
 				root,

package/build/src/define_config.d.ts

@@ -1,4 +1,5 @@
 import type { ComplexityTable } from './albrecht/tables.js';
+import type { ChangeFactors, ChangeReasonFactors } from './albrecht/diff.js';
 import type { CallResolver } from './inventory/resolvers/types.js';
 import type { Complexity, FunctionType } from './types.js';
 /**
@@ -35,6 +36,20 @@ export type FunctionPointsConfig = {
          * For example, tables mirrored from an external ERP.
          */
         externallyMaintained?: string[];
+        /**
+         * Stores the AFP naming filter excluded, which are business data here.
+         *
+         * The filter (§6.5.2.1.1, patterns in §6.5.2.1.3) catches names containing
+         * `session`, `template`, `error`, `types` and so on, because in most
+         * applications those hold infrastructure. When they hold the business —
+         * a chat session the user manages, a document template they maintain — the
+         * exclusion is wrong and no heuristic can know it. This wins over the
+         * filter, and the report says which stores were brought back.
+         *
+         * It is the counterpart of `infrastructure`: that one excludes what the
+         * filter missed, this one restores what it caught by accident.
+         */
+        business?: string[];
         /**
          * Entry points with no functional value to the user, by route name or by
          * identity (`GET /health`).
@@ -72,6 +87,25 @@ export type FunctionPointsConfig = {
     complexityTables?: Partial<Record<FunctionType, ComplexityTable>>;
     /** Weights per type and complexity. */
     weights?: Partial<Record<FunctionType, Record<Complexity, number>>>;
+    /**
+     * How change is priced, for `fp:diff`. A clause of the contract, not a flag.
+     *
+     * The AEP anchors are explicit for added (1) and deleted (0.4). For a modified
+     * function AEP grades the factor from 0.25 to 1.75 through Effort Complexity
+     * variation, which needs cyclomatic complexity this package does not measure —
+     * so it defaults to 1, which overestimates, and every diff says so.
+     *
+     * `reasonFactors` is the lever the default leaves on the table. The tool
+     * already distinguishes a change of type, a change of size, and a change of
+     * implementation only — same type, same DET, same FTR, different body — and on
+     * a real pair of releases the last was 151 of 378 FP billed as change. Pricing
+     * a refactor at full functional value is not defensible; pricing it at a number
+     * this package invented would be worse. So the number comes from the contract.
+     */
+    diff?: {
+        factors?: Partial<ChangeFactors>;
+        reasonFactors?: ChangeReasonFactors;
+    };
     /**
      * Custom tracing strategies, added to the built-in ones and running
      * **before** them.
@@ -93,7 +127,7 @@ export type FunctionPointsConfig = {
     minCoverage?: number;
     /**
      * Declared DET or RET/FTR for a function the analysis cannot read, keyed by
-     * the name it has in the count (`Petition`, `POST /books`).
+     * the name it has in the count (`Invoice`, `POST /books`).
      *
      * The case this exists for is a schema-driven application: when the fields a
      * user fills live in a JSON column whose schema is stored in the database,