One fact one source

One Fact, One Source

Core Rule

Keep exactly one canonical function, constant, type, schema, contract, or authoritative output for each business fact.

Allow consumers to present or transport the result differently. Do not let them reimplement the underlying status, amount, permission, classification, or business decision.

This rule covers business facts only. Pure layout helpers and helpers without business meaning are out of scope.

Do not merge code merely because it looks similar. Merge only when the business meaning, inputs, boundaries, and ownership are the same. Preserve and document intentional differences.

Scope of Effort

Match the process weight to the task:

• Audit only: run Discover and produce the Before Editing record. Report definitions, consumers, conflicts, and the recommended canonical source when the evidence is sufficient. Do not modify files or continue into consolidation.
• Small change (touches one existing business fact, no consolidation intended): run a targeted semantic search across business terms, names and aliases, status literals, magic values, equivalent conditions, schemas, contracts, and call sites. Reuse the canonical source without adding a parallel implementation. Skip repo-wide counting, clone scans, and the full consolidation report unless the search reveals conflicting or duplicated definitions.
• Consolidation or refactor (merging duplicates, extracting a canonical source, cross-repo work): run Discover and Before Editing here, then read CONSOLIDATION.md for the While Editing and Validate steps.
• If a small change reveals duplicated definitions of the fact, report the duplication instead of silently expanding scope. Consolidate only when the task authorizes it.

Example

Illustrative example: three consumers independently decide whether an order qualifies for free shipping.

// cart.js, checkout.js, and api/order.js
const freeShipping = subtotal >= 1000

Consolidate the rule into one canonical function:

// domain/shipping.js
const FREE_SHIPPING_MINIMUM = 1000
export const qualifiesForFreeShipping = (subtotal) =>
  subtotal >= FREE_SHIPPING_MINIMUM

All consumers call qualifiesForFreeShipping(). UI labels, fee presentation, and API response shapes may differ, but consumers must not re-derive the eligibility rule.

Do not merge two date + N days functions merely because their code is similar. A payment due date and a contract end date are different business facts when their meanings, ownership, or boundaries differ.

Discover

Use layered discovery:

1. Use rg to find names, synonyms, constants, status values, magic values, inline conditions, types, schemas, and cross-repo copies.
2. Search consumer boundaries, including imports, exports, re-exports, direct calls, string dispatch, configuration, rules, endpoint names, generated code, and cross-language contracts. Record the methods used, scope covered, and known blind spots.
3. When available and supported for the project language, use jscpd to find identical or near-identical code and ast-grep to find structurally equivalent code. Fall back to rg and manual inspection when they are unavailable or unsupported.
4. Inspect every candidate semantically. Tool matches are evidence of duplication, not proof that two implementations represent the same business fact.

Before Editing

For code involving business facts:

1. Record the business fact, canonical name and file, duplicate definitions, consumers found through the recorded search coverage, known blind spots, implementation differences, expected behavior, test baseline, planned removals, public or persisted identifiers, required compatibility names, and authorized behavior or identifier changes.
2. Count the definitions, consumers, old names, and detected clone clusters before editing so the result can be compared after consolidation.
3. If existing implementations disagree, stop and report the differences. Do not guess which behavior is correct.
4. If no canonical source exists, place it in the lowest stable shared layer that owns the business meaning.
5. Separate business meaning from presentation, transport, caching, and platform adapters.
6. Identify every known mirror repository or generated artifact and verify that it is readable. Record inaccessible mirrors before editing.

Consolidating

Read CONSOLIDATION.md before making consolidation edits. It carries the While Editing and Validate steps: git baseline and commit-authorization rules, compatibility aliases, breaking identifier changes, drift checks, and the final report contents.

Completion Gate

Do not claim completion merely because a shared helper exists.

Require all of the following:

• one canonical implementation;
• consumers found through the recorded search coverage migrated, with known blind spots disclosed;
• obsolete definitions removed and retained compatibility aliases delegating to the canonical source;
• intentional differences preserved and documented;
• available tests and builds passing, with missing test infrastructure reported;
• old-name and drift checks executed for accessible scope, with inaccessible mirrors reported; guards extended where infrastructure exists, or recommended in the report.