@filipebraida/adonis-function-points 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+Counting rules carry their own version, separate from the package version, and
+`fp:diff` **refuses** to compare counts produced by different rule sets. When a
+release moves the number for unchanged code, the rule set version moves with it —
+otherwise the difference would measure the tool's change rather than the work, and
+that difference becomes an invoice.
+
+## 0.3.0
+
+**Rule set `afp@1.2.0`.** Three counting fixes move the number for unchanged code,
+so a 0.2.0 baseline has to be recounted.
+
+All four were found by installing 0.2.0 in a production application, which is the
+only way any of them could have been found.
+
+### Fixed
+
+- **An open input object counted zero.** `vine.object({}).allowUnknownProperties()`
+  declares a field whose own fields live in data; the leaf walk descended into the
+  empty literal, found nothing, and never pushed the field either. An opaque JSON
+  column in the identical position counts 1. It now counts 1 too, and is reported —
+  the opaque-column warning names stores, and this side had no warning at all, which
+  is why the route saving the application's main document had never looked wrong.
+- **`detFromSchema` was off by one.** It replaced the opaque placeholder by
+  subtracting 1 on faith. With no placeholder to replace — the case above — the
+  subtraction removed a field the analysis had read correctly. Opaque DETs are now
+  marked `(opaque)` in the rationale, and the override replaces a marked one or
+  none, warning when it finds nothing to stand in for.
+- **A schema declared in a seeder was not found.** `database/` is excluded from the
+  application roots so a test factory's writes never become counted functions, but
+  `make:seeder` puts seeders there. Naming such a schema reported "not declared
+  anywhere in the code" and left the count at the floor — the exact case the
+  override exists for. The schema catalogue now reads `database/` as well; the call
+  graph still does not.
+- **`@adonisjs/queue` names the execution method `execute`**, which the list of
+  names did not have. It surfaced only once event dispatch started being followed:
+  the listener was what enqueued the job, so that path had never been walked. Third
+  name this list has learned by measurement — a list written from imagination would
+  have missed this one too.
+- **A write through a relation did not maintain the related table.**
+  `distribution.related('files').create({…})` is ordinary Lucid and the relation is
+  the subject of the write. Every relation access was treated as a read, so a table
+  written exclusively that way came out as an EIF. `preload` and `load` still only
+  read, because they hand back the parent.
+
+### New
+
+- `analyze`, `diffCounts`, `measureStructure`, `measureConformance`, `calibrate`,
+  `RULESET_VERSION` and the diff types are exported. The two front-ends were the
+  only way to reach any of this, so anything built on top had to shell out to the
+  CLI and parse its output.
+
+## 0.2.0
+
+**Rule set `afp@1.1.0`.** A baseline saved with 0.1.0 cannot be compared against
+this release: recount it, or `fp:diff` will refuse. That refusal is the feature.
+
+### Counting
+
+- **ILF vs EIF is decided across the whole project, not from HTTP routes.** AFP
+  §6.5.4 asks who _maintains_ a store; reading that off a walk from routes
+  answered a narrower question, so a table written only by a job or a seeder came
+  out as somebody else's table. On three production applications this moved 5
+  stores out of EIF. A store that is only ever read is still an EIF.
+- **A job is followed into its execution method**, which is `handle`,
+  `process`, `run` or `perform` depending on the queue package. Looking only for
+  `handle` resolved the file, found no body, reported the dispatch as unknown and
+  left every write inside it uncounted.
+- **An event dispatch is followed into its listeners.** Bindings are read from
+  `emitter.on(event, [listeners])`; both generated-registry shapes and the direct
+  class reference are handled, as is a binding that names the method.
+- **`request.input('x')` and `request.only([…])` count as input DETs.** §7.2 asks
+  whether a user-recognisable field crosses the boundary, not how it was declared.
+  Deduplicated against validator fields, so nothing is paid for twice.
+
+### Billing
+
+- `fp:diff` factors are reachable from `config/function_points.ts` under `diff`.
+  They were a typed extension point only a test could use.
+- **`diff.reasonFactors`** prices a modified function by _what_ changed about it:
+  `type`, `size`, or `implementation` — same type, same DET, same FTR, different
+  body. On a real pair of releases, 151 of 378 FP billed as change were
+  implementation only. The default does not move: AEP grades the modification
+  factor from 0.25 to 1.75 through Effort Complexity variation, which needs
+  cyclomatic complexity this package does not measure, so it stays at 1 and every
+  diff says so with the amount at stake.
+- The billable total is rounded to cents. `485.00000000000006` is arithmetically
+  the same number and not the same document.
+- Warnings print **above** the per-function list. On a real diff that list is over
+  a hundred lines, and a caveat that has to be scrolled to is not a caveat.
+
+### New
+
+- **`fp:metrics`** — density, coupling (Martin's instability) and conformance,
+  from the same inventory as the count. If function points pay, the team optimises
+  function points; this is the counterweight. Cycles between modules are reported,
+  not scored.
+- **`CallResolver.ignores()`** — a third outcome. `resolve` returning `[]` means
+  _not recognised_, so a strategy that recognised a call and knew it reached no
+  data store had no way to say so. The volume still appears in the confidence
+  block: the escape hatch buys coverage, never function points.
+- **`boundary.business`** — restores a store the AFP naming filter (§6.5.2.1.3)
+  excluded by accident.
+- `fp:count` reports transactions that read the request without enumerating
+  fields (`all()`, `body()`, `except()`), which sit at the floor of their band.
+
+### Breaking
+
+- `Conformance.writesWithValidator` is now `inputsWithValidator`, and its
+  denominator is the transactions that _take_ input rather than every write.
+  Measured over every write it read 39% on a healthy application, inviting the
+  conclusion that 61% of its writes were unvalidated — they were not: most were
+  workflow triggers carrying nothing beyond the route parameter.
+- `HandlerBehavior` gained `requestFields` and `opaqueRequest`.
+- `ResolverContext` gained `exportedAs` and `eventBindings`.
+
+### Fixed
+
+- An aliased import resolved to the local name, so `import { x as y }` searched
+  for `y` in a file that exports `x`.
+- A call on the result of a call was reported as unknown even though the inner
+  call — where the unknown is — is reported in the same body.
+- `X.map(callback)` was claimed by `static-service`, which resolved the module and
+  reported a missing `map` in it.
+- The package was unusable through ace: `commands/main.ts` exported classes
+  instead of the `getMetaData`/`getCommand` contract ace calls, which broke every
+  command in the host application.
+- `configure` generated `config/function_points.ts` and no command read it.
+- Generated-schema detection was disabled on Windows by a path-separator mismatch.
+
+Coverage across four production applications went from 79.7 / 85.9 / 83.5 / 91.4%
+to 94.8 / 95.1 / 98.4 / 91.4%.
+
+## 0.1.0
+
+First release. Counts unadjusted function points from AdonisJS 7 + Lucid 22
+source, following OMG Automated Function Points 1.0 (ISO/IEC 19515), with
+`fp:count`, `fp:inventory`, `fp:explain`, `fp:diff` and `fp:calibrate` in both an
+ace and a standalone front-end.
+
+Validated against the case study published in Vazquez, Simões & Albert (2011): 46
+FP, exact, with the fixture and the reference count frozen before the counter was
+run against them.

package/README.md

@@ -13,7 +13,7 @@ node ace fp:count
 
 ```
 Unadjusted count: 46 FP
-Ruleset: afp@1.0.0
+Ruleset: afp@1.2.0
 
 type      n     FP
 ILF       2     14
@@ -134,6 +134,7 @@ owes you is a number that is still defensible wherever it lands.
 | ------------------------------------- | ---------------------------------------------------------- |
 | `node ace fp:count`                   | counts unadjusted function points                          |
 | `node ace fp:inventory`               | the raw facts: stores, routes, tracing coverage            |
+| `node ace fp:metrics`                 | density, coupling and conformance, from the same run       |
 | `node ace fp:explain <name>`          | why one function was counted that way                      |
 | `node ace fp:diff <previous.json>`    | additions / modifications / deletions, and the billable FP |
 | `node ace fp:calibrate <samples.csv>` | correction factors against a manual count                  |
@@ -143,6 +144,74 @@ saved count against the current state of the application. It deliberately does
 **not** take a git ref: booting an older checkout, with possibly different
 dependencies, is a problem not worth solving.
 
+### How change is priced
+
+AEP §6.5 gives explicit anchors for added (1) and deleted (0.4). For a **modified**
+function it 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 with the amount at
+stake.
+
+What the default leaves on the table is a distinction the tool already measures:
+
+```
+changed      87 functions   378 FP  × 1
+  type              4 functions    23 FP
+  size             38 functions   204 FP
+  implementation   45 functions   151 FP
+```
+
+`implementation` means same type, same DET, same FTR, different body — a refactor.
+On a real pair of releases that was 151 of 378 FP billed as change. Pricing it at
+full functional value is not defensible, and pricing it at a number this package
+invented would be worse, so the number comes from the contract:
+
+```ts
+export default defineConfig({
+  diff: {
+    reasonFactors: { implementation: 0.25 },
+  },
+})
+```
+
+### `fp:metrics` — the counterweight
+
+If function points pay, the team optimises function points: more models, more
+endpoints, less reuse. So density and coupling are reported from the **same**
+inventory, and this command exists to put them on the same page as the number.
+
+```
+Density
+  FP per data store:            27.0
+  transactions per data store:  5.4
+
+Conformance
+  inputs with a validator      100.0%   (30/30)
+  entry points with a handler  100.0%   (163/163)
+  data stores reached           96.7%   (29/30)
+  tracing coverage              95.1%   (15 unresolved calls)
+
+module                  FP  trans stores     I  depends on
+pedidos                211     33      8  0.60  inventores, tecnologias, users
+portal                  69     15      0  1.00  contato, documentos, inventores, ...
+inpi                    70     11      6  0.00
+
+Mutual dependencies (cycle candidates)
+  inventores <-> tecnologias
+```
+
+The denominator of the first line is the transactions that **take** input, not
+every write. Measured over every write it read 39% on a healthy application, which
+invites the conclusion that 61% of its writes are unvalidated — and they are not:
+most are workflow triggers (`POST /orders/:id/submit`) that carry nothing beyond
+the route parameter. A metric that makes the reader draw a false conclusion is
+worse than no metric.
+
+`I` is Martin's instability, `Ce / (Ca + Ce)`: 0 means everyone depends on it and
+it depends on nobody, 1 means the reverse. A module at 0 that changes often is
+where change hurts. Cycles are **reported, not scored** — what to do about one is
+the team's decision, and a number would hide it.
+
 ### `fp:explain` — the number has to be defensible
 
 ```
@@ -251,6 +320,7 @@ export default defineConfig({
   boundary: {
     infrastructure: ['access_tokens', 'audits'], // excluded, with the reason in the report
     externallyMaintained: ['erp_customers'], // counted as EIF instead of ILF
+    business: ['chat_sessions'], // the AFP naming filter caught it by accident
     ignoreEntryPoints: ['prometheus.metrics'],
   },
 
@@ -294,7 +364,38 @@ detail: `CreateUserJob.dispatch(p)`, `UserService.create(p)` and `User.find(p)`
 are all `Identifier.method(args)`, and only ordering tells them apart.
 
 Built-in strategies, most specific first: `same-class-method`, `action-object`,
-`job-dispatch`, `static-service`, `property-service`, `module-function`.
+`event-dispatch`, `job-dispatch`, `transformer`, `static-service`,
+`property-service`, `module-function`.
+
+A job dispatch and an event dispatch are followed as part of the **same**
+transaction: the user clicks and the effect happens, whatever thread runs it.
+Event bindings are read from `emitter.on(event, [listeners])`, so a listener's
+reads and writes count towards the transaction that dispatched the event.
+
+### Declaring that a call reaches no data
+
+`resolve` has two outcomes — _followed_ and _not mine_ — and sometimes a third
+is the truth: the call is recognised, and it reaches no data store. A wrapper
+over a rate limiter or an attachment variant is a real example. Without a way
+to say so, such a call stays unresolved and drags the coverage gate down.
+
+```ts
+const limiterIsDataFree: CallResolver = {
+  name: 'login-limiter',
+  order: 1,
+  resolve: () => [],
+  ignores(call) {
+    // true means: this is mine, and it touches no data store
+    return call.getExpression().getText().startsWith('this.loginLimiter.')
+  },
+}
+```
+
+`ignores` is asked before `resolve`, in the same order, so a later and more
+generic strategy cannot follow the call into a body it has no business reading.
+It is deliberately more expensive than a list of method names to silence: the
+volume still appears in the confidence block of `fp:count`, because a silent
+drop is the worst defect this package can have — whoever writes it.
 
 ## Support
 

package/build/calibration-8eV8CEix.js

@@ -0,0 +1,403 @@
+//#region src/define_config.ts
+const DEFAULTS = {
+	boundary: {},
+	retStrategy: "constant",
+	maxDepth: 3,
+	messageDet: 0
+};
+function defineConfig(config) {
+	return {
+		...DEFAULTS,
+		...config,
+		boundary: {
+			...DEFAULTS.boundary,
+			...config.boundary
+		}
+	};
+}
+//#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 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 = [];
+	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.`);
+	/**
+	* 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),
+		/**
+		* 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
+	};
+}
+/**
+* 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;
+}
+/** 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$1(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$1(count.totals.unadjusted / stores),
+		transactionsPerDataStore: round$1(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$1(ok / total)
+});
+const round$1 = (value) => Math.round(value * 1e3) / 1e3;
+//#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
+export { AEP_FACTORS as a, diffCounts as c, measureStructure as i, DEFAULTS as l, parseSamples as n, IncomparableRulesetsError as o, measureConformance as r, IncomparableSourcesError as s, calibrate as t, defineConfig as u };