@nifrajs/web 2.14.1 → 3.2.0

package/dist/internal/head-merge.js

@@ -1,8 +1,24 @@
+// Server head serialization may memoize only objects that came exclusively from a static meta export.
+// A dynamic function is allowed to reuse and mutate one object, including an object another route also
+// exports statically, so identity alone does not prove cacheability. Once observed dynamically, an
+// object stays uncacheable: losing a small static optimization is safer than cross-request stale data.
+const STATIC_META = new WeakSet();
+const DYNAMIC_META = new WeakSet();
+/** @internal Whether `resolveMeta` observed this object as a static export. */
+export function isStaticMeta(meta) {
+    return STATIC_META.has(meta) && !DYNAMIC_META.has(meta);
+}
 /** Resolve a route's `meta` export - a static object, or a function of the route's data/params. */
 export function resolveMeta(meta, args) {
     if (meta === undefined)
         return {};
-    return typeof meta === "function" ? meta(args) : meta;
+    if (typeof meta === "function") {
+        const resolved = meta(args);
+        DYNAMIC_META.add(resolved);
+        return resolved;
+    }
+    STATIC_META.add(meta);
+    return meta;
 }
 /**
  * Merge a layout chain's heads, outermost first: `title`/`lang`/`dir` are nearest-wins, and

package/dist/internal/head-merge.js.map

@@ -1 +1 @@
-{"version":3,"file":"head-merge.js","sourceRoot":"","sources":["../../src/internal/head-merge.ts"],"names":[],"mappings":"AAuBA,mGAAmG;AACnG,MAAM,UAAU,WAAW,CAAC,IAA2B,EAAE,IAAc;IACrE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACjC,OAAO,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACvD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,6FAA6F;IAC7F,sGAAsG;IACtG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAS,CAAA;IAC/C,IAAI,KAAyB,CAAA;IAC7B,IAAI,IAAwB,CAAA;IAC5B,IAAI,GAAgB,CAAA;IACpB,MAAM,IAAI,GAAqB,EAAE,CAAA;IACjC,MAAM,IAAI,GAAqB,EAAE,CAAA;IACjC,MAAM,MAAM,GAAuB,EAAE,CAAA;IACrC,MAAM,YAAY,GAA6B,EAAE,CAAA;IACjD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;YAAE,KAAK,GAAG,CAAC,CAAC,KAAK,CAAA,CAAC,gDAAgD;QAC3F,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAA,CAAC,2BAA2B;QACnE,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS;YAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAA;QACpC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA,CAAC,gDAAgD;QACrG,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS;YAAE,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAA;IACxE,CAAC;IACD,iGAAiG;IACjG,sGAAsG;IACtG,mGAAmG;IACnG,gBAAgB;IAChB,MAAM,MAAM,GAQR,EAAE,CAAA;IACN,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAA;IAC7C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;IACvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;IACvC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAA;IAC7C,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,YAAY,GAAG,YAAY,CAAA;IAC/D,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;IAC1C,IAAI,GAAG,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,GAAG,GAAG,CAAA;IACvC,OAAO,MAAc,CAAA;AACvB,CAAC"}
+{"version":3,"file":"head-merge.js","sourceRoot":"","sources":["../../src/internal/head-merge.ts"],"names":[],"mappings":"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"}

package/dist/internal/identity-policy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One source for which packages are identity-sensitive, and how each frontend framework is pinned to a
+ * single physical copy in a bundle.
+ *
+ * The identity-sensitive PACKAGE set lives in `@nifrajs/core` (`IDENTITY_SENSITIVE_PACKAGES`) - it is
+ * what single-copy enforcement and `nifra check` read, and it must be the same answer everywhere. This
+ * module does not restate it; it re-exports the one predicate every web caller should ask
+ * (`isIdentitySensitivePackage`) so a second list can never drift from core's.
+ *
+ * What this module DOES own is the per-bundler dedupe STRATEGY, which is a web concern (it names Bun and
+ * Vite mechanics core knows nothing about). The two client pipelines - `Bun.build` (build.ts) and Vite
+ * (build-vite.ts) - used to spell their framework coverage out independently, and they had already
+ * drifted: the Bun build pinned react + preact + svelte while the Vite build deduped react alone, so a
+ * Vite-built app silently shipped a second Preact or Svelte runtime. Both now read {@link
+ * FRONTEND_DEDUPE_POLICIES}, so their coverage cannot diverge again.
+ *
+ * Not every identity-sensitive framework is name-pinned here. Solid and Vue select their single runtime
+ * through export CONDITIONS rather than a resolver override, so they carry no entry - the conformance
+ * test allows core's set to be a superset of this table for exactly that reason, and only forbids the
+ * reverse (a strategy for a package core does not consider identity-sensitive).
+ */
+/**
+ * Whether nifra treats a package as identity-sensitive: a second physical copy breaks behaviour (a hook
+ * dispatcher, a renderer's options global, a `Server` class identity) rather than merely costing bytes.
+ * The single predicate the whole web package asks, delegating to core's canonical declaration.
+ */
+export declare const isIdentitySensitivePackage: (name: string) => boolean;
+/**
+ * How one frontend framework's runtime is pinned to a single copy in each client bundler.
+ *
+ * The two arms differ because the bundlers resolve differently. `Bun.build` needs an `onResolve` hook,
+ * fed either a fixed specifier list (each resolved once) or a pattern (resolved per matched import, for
+ * a framework with an open-ended subpath surface like `svelte/internal/*`). Vite takes bare package
+ * names in `resolve.dedupe` and handles the subpaths itself. A framework declares whichever Bun arm
+ * fits plus its Vite names, so both pipelines pin the same framework from this one entry.
+ */
+export interface FrontendDedupePolicy {
+    readonly framework: string;
+    /** Exact specifiers the Bun build pins to the app's copy. Mutually exclusive with `bunPattern`. */
+    readonly bunSpecs?: readonly string[];
+    /** Specifier pattern the Bun build resolves per match, for an open-ended subpath surface. */
+    readonly bunPattern?: RegExp;
+    /** Bare package names the Vite build lists in `resolve.dedupe`. */
+    readonly viteDedupe: readonly string[];
+}
+export declare const FRONTEND_DEDUPE_POLICIES: readonly FrontendDedupePolicy[];
+/** Look up one framework's dedupe policy, throwing if a plugin references a framework the table dropped. */
+export declare const dedupePolicyFor: (framework: string) => FrontendDedupePolicy;
+/** The flat, de-duplicated `resolve.dedupe` list for the Vite client build. */
+export declare const viteDedupePackages: () => readonly string[];
+//# sourceMappingURL=identity-policy.d.ts.map

package/dist/internal/identity-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-policy.d.ts","sourceRoot":"","sources":["../../src/internal/identity-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,MAAM,KAAG,OACO,CAAA;AAEjE;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,6FAA6F;IAC7F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,eAAO,MAAM,wBAAwB,EAAE,SAAS,oBAAoB,EAyBnE,CAAA;AAED,4GAA4G;AAC5G,eAAO,MAAM,eAAe,GAAI,WAAW,MAAM,KAAG,oBAMnD,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,QAAO,SAAS,MAAM,EAEpD,CAAA"}

package/dist/internal/identity-policy.js

@@ -0,0 +1,67 @@
+/**
+ * One source for which packages are identity-sensitive, and how each frontend framework is pinned to a
+ * single physical copy in a bundle.
+ *
+ * The identity-sensitive PACKAGE set lives in `@nifrajs/core` (`IDENTITY_SENSITIVE_PACKAGES`) - it is
+ * what single-copy enforcement and `nifra check` read, and it must be the same answer everywhere. This
+ * module does not restate it; it re-exports the one predicate every web caller should ask
+ * (`isIdentitySensitivePackage`) so a second list can never drift from core's.
+ *
+ * What this module DOES own is the per-bundler dedupe STRATEGY, which is a web concern (it names Bun and
+ * Vite mechanics core knows nothing about). The two client pipelines - `Bun.build` (build.ts) and Vite
+ * (build-vite.ts) - used to spell their framework coverage out independently, and they had already
+ * drifted: the Bun build pinned react + preact + svelte while the Vite build deduped react alone, so a
+ * Vite-built app silently shipped a second Preact or Svelte runtime. Both now read {@link
+ * FRONTEND_DEDUPE_POLICIES}, so their coverage cannot diverge again.
+ *
+ * Not every identity-sensitive framework is name-pinned here. Solid and Vue select their single runtime
+ * through export CONDITIONS rather than a resolver override, so they carry no entry - the conformance
+ * test allows core's set to be a superset of this table for exactly that reason, and only forbids the
+ * reverse (a strategy for a package core does not consider identity-sensitive).
+ */
+import { IDENTITY_SENSITIVE_PACKAGES, matchesSingleCopyDeclaration, } from "@nifrajs/core/single-copy";
+/**
+ * Whether nifra treats a package as identity-sensitive: a second physical copy breaks behaviour (a hook
+ * dispatcher, a renderer's options global, a `Server` class identity) rather than merely costing bytes.
+ * The single predicate the whole web package asks, delegating to core's canonical declaration.
+ */
+export const isIdentitySensitivePackage = (name) => matchesSingleCopyDeclaration(IDENTITY_SENSITIVE_PACKAGES, name);
+export const FRONTEND_DEDUPE_POLICIES = [
+    {
+        framework: "react",
+        // react-dom is absent on purpose: it imports react, so pinning react's core (and its JSX runtimes)
+        // gives it the one dispatcher. Vite dedupes react-dom by name because it collapses by package.
+        bunSpecs: ["react", "react/jsx-runtime", "react/jsx-dev-runtime"],
+        viteDedupe: ["react", "react-dom"],
+    },
+    {
+        framework: "preact",
+        bunSpecs: [
+            "preact",
+            "preact/hooks",
+            "preact/compat",
+            "preact/jsx-runtime",
+            "preact/jsx-dev-runtime",
+        ],
+        viteDedupe: ["preact"],
+    },
+    {
+        framework: "svelte",
+        // Svelte's client runtime has many internal subpaths, so match the family and resolve each per hit.
+        bunPattern: /^svelte($|\/internal\/)/,
+        viteDedupe: ["svelte"],
+    },
+];
+/** Look up one framework's dedupe policy, throwing if a plugin references a framework the table dropped. */
+export const dedupePolicyFor = (framework) => {
+    const policy = FRONTEND_DEDUPE_POLICIES.find((entry) => entry.framework === framework);
+    if (policy === undefined) {
+        throw new Error(`[nifra/web] no frontend dedupe policy for ${framework}`);
+    }
+    return policy;
+};
+/** The flat, de-duplicated `resolve.dedupe` list for the Vite client build. */
+export const viteDedupePackages = () => [
+    ...new Set(FRONTEND_DEDUPE_POLICIES.flatMap((policy) => policy.viteDedupe)),
+];
+//# sourceMappingURL=identity-policy.js.map

package/dist/internal/identity-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-policy.js","sourceRoot":"","sources":["../../src/internal/identity-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,2BAA2B,CAAA;AAElC;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,IAAY,EAAW,EAAE,CAClE,4BAA4B,CAAC,2BAA2B,EAAE,IAAI,CAAC,CAAA;AAqBjE,MAAM,CAAC,MAAM,wBAAwB,GAAoC;IACvE;QACE,SAAS,EAAE,OAAO;QAClB,mGAAmG;QACnG,+FAA+F;QAC/F,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,CAAC;QACjE,UAAU,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;KACnC;IACD;QACE,SAAS,EAAE,QAAQ;QACnB,QAAQ,EAAE;YACR,QAAQ;YACR,cAAc;YACd,eAAe;YACf,oBAAoB;YACpB,wBAAwB;SACzB;QACD,UAAU,EAAE,CAAC,QAAQ,CAAC;KACvB;IACD;QACE,SAAS,EAAE,QAAQ;QACnB,oGAAoG;QACpG,UAAU,EAAE,yBAAyB;QACrC,UAAU,EAAE,CAAC,QAAQ,CAAC;KACvB;CACF,CAAA;AAED,4GAA4G;AAC5G,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,SAAiB,EAAwB,EAAE;IACzE,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAA;IACtF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,6CAA6C,SAAS,EAAE,CAAC,CAAA;IAC3E,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAsB,EAAE,CAAC;IACzD,GAAG,IAAI,GAAG,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;CAC5E,CAAA"}

package/dist/internal/parity.d.ts

@@ -5,9 +5,16 @@
  * modules and emitted app surfaces resolve to one coherent graph? This internal seam owns path and
  * manifest normalization so those callers cannot quietly grow separate rules.
  */
+import { type SingleCopyRegistration } from "@nifrajs/core/single-copy";
 export interface IdentityParityCopy {
     readonly version: string;
     readonly path: string;
+    /**
+     * The resolved realpath of the copy. `path` is display-relative to the invoked directory, which
+     * reads well in a report but cannot be pasted into a resolver or an editor from anywhere else.
+     * Absent on a finding built by hand (a test fixture, an older cached result).
+     */
+    readonly absolutePath?: string;
     readonly importers: readonly string[];
 }
 export type IdentityParityCause = "version-skew" | "duplicate-path";
@@ -20,14 +27,84 @@ export interface IdentityParityFinding {
     readonly cause: IdentityParityCause;
     readonly explanation: string;
     readonly remediation: string;
+    /**
+     * Why the copies exist, in install-topology terms: how many physical paths sit under how many
+     * install roots, and whether any of those roots is outside the scanned project.
+     *
+     * A path list alone leaves the reader to reverse-engineer the shape. The two shapes need opposite
+     * fixes: a NESTED install under the scanned root shadows the hoisted copy and one reinstall
+     * collapses it, while a SIBLING install root (a linked checkout, a standalone app beside this one)
+     * owns its own `node_modules` and no reinstall here can touch it.
+     *
+     * Absent on a finding built by hand (a test fixture, an older cached result).
+     */
+    readonly topology?: string;
+    /**
+     * Why a copy the invoked directory does not import is still fatal here.
+     *
+     * The gate is workspace-wide on purpose. Scoping it to the invoked app would be more precise and
+     * would also reintroduce the blindness this guard was built for: a copy that arrives through a
+     * workspace-linked dependency is not visible from the app directory, and that case shipped a
+     * broken dev server while the check reported "none". A workspace-wide answer over-reports in
+     * exchange for never under-reporting - and over-reporting is the failure a developer can see and
+     * act on, where under-reporting is the one nobody knows happened.
+     *
+     * Present only when the answer would otherwise look wrong: a subdirectory was scanned as its
+     * workspace, and at least one copy sits outside that subdirectory.
+     */
+    readonly scope?: string;
+    /**
+     * The copies exist but the app declared this package single-copy, so the resolver collapses them
+     * before anything loads. Reported, never fatal - see `SingleCopyCoverage`.
+     */
+    readonly deduplicated: boolean;
+}
+/**
+ * What the app declared about deduplication, and how much of it is actually armed.
+ *
+ * A duplicate physical path is only a defect if something still LOADS both copies. An app consuming a
+ * linked sibling repository cannot collapse the paths without giving up the property it chose `link:`
+ * for - each repository owning its own `node_modules` - so nifra lets it declare the packages instead
+ * (`"nifra": { "singleCopy": [...] }` in package.json) and verifies the declaration here rather than
+ * failing on the raw path count.
+ *
+ * Bundled phases need nothing further: `buildClient`/`buildServer`/dev inject the resolver themselves.
+ * Unbundled phases do, because Bun's runtime never offers a bare specifier to a resolver hook, so the
+ * plugin has to be preloaded to intercept the load. `registration` is that proof, read statically out
+ * of `bunfig.toml`.
+ */
+export interface SingleCopyCoverage {
+    /** Declared package names and patterns, exactly as written. Empty when nothing was declared. */
+    readonly declared: readonly string[];
+    readonly registration: SingleCopyRegistration;
 }
 export interface IdentityParityResult {
+    /**
+     * The governing workspace root: where importer enumeration starts, and how far a copy lookup may
+     * walk up from an importer.
+     *
+     * EVERY caller resolves this the same way. The doctor and the build/dev preflight used to differ
+     * here - one anchored at the workspace, the other at the app directory - so the same project could
+     * be told it had duplicates by one command and a clean bill by the other. Two answers from one
+     * toolchain is worse than either answer, so the basis is now fixed and reported rather than chosen.
+     */
     readonly workspaceRoot: string;
+    /** The directory the caller asked about. Differs from `workspaceRoot` when a package subdirectory
+     * is governed by a workspace above it; carried so a report can state the basis it scanned on. */
+    readonly requestedRoot: string;
+    /**
+     * Enumeration stopped at `MAX_WORKSPACE_IMPORTERS`, so this scan is PARTIAL.
+     *
+     * An empty `findings` then means "nothing found in the part that was scanned", never "clean" - a
+     * caller that prints a clean bill on a truncated scan is the exact silence this flag exists to
+     * prevent.
+     */
+    readonly truncated: boolean;
+    /** Findings that no declaration covers - the ones a build must refuse to start on. */
     readonly findings: readonly IdentityParityFinding[];
-}
-export interface IdentityParityOptions {
-    /** Scan the governing workspace when the caller is a package subdirectory. */
-    readonly useWorkspaceRoot?: boolean;
+    /** Duplicates the declaration covers. Worth printing, never worth failing. */
+    readonly deduplicated: readonly IdentityParityFinding[];
+    readonly singleCopy: SingleCopyCoverage;
 }
 export interface BuildManifestLike {
     readonly entry: string;
@@ -49,6 +126,9 @@ export interface DevelopmentParityInput {
     readonly routes: Readonly<Record<string, number>>;
     readonly publicFiles: readonly string[];
     readonly css: readonly string[];
+    /** The scanned first-party source root, carried only so a css parity failure can name where the
+     * scanner looked. Optional: callers that hand-build an input for a unit test may omit it. */
+    readonly sourceRoot?: string;
 }
 export type ManifestParitySection = "module-graph" | "public-files" | "css";
 export interface ManifestParityDifference {
@@ -56,6 +136,7 @@ export interface ManifestParityDifference {
     readonly development: unknown;
     readonly production: unknown;
 }
+export declare const pathInside: (root: string, path: string) => boolean;
 /** Resolve the workspace root once, even when the caller starts in a workspace package. */
 export declare function resolveParityWorkspaceRoot(start: string): Promise<{
     readonly root: string;
@@ -67,13 +148,28 @@ export declare const resolvedInstalledCopy: (importer: string, boundary: string,
 } | undefined>;
 export declare const displayPath: (cwd: string, path: string) => string;
 /** Find duplicate identity-sensitive package realpaths without reading application payloads. */
-export declare function collectIdentityParity(cwd: string, rootPackage?: Record<string, unknown>, options?: IdentityParityOptions): Promise<IdentityParityResult>;
-/** One `- pkg [cause]: ...` line per finding, shared by the hard failure and the dev warning. */
+export declare function collectIdentityParity(cwd: string, rootPackage?: Record<string, unknown>): Promise<IdentityParityResult>;
+/** One `- pkg [cause]: ...` block per finding, shared by the hard failure and the dev warning. */
 export declare function formatIdentityParityFindings(findings: readonly IdentityParityFinding[]): string;
+/**
+ * The basis a scan ran on, for any surface that reports its result.
+ *
+ * A verdict about installs is only as good as where it looked, and the reader cannot see that from a
+ * list of relative paths. Stating it also makes a truncated scan impossible to read as a clean one.
+ */
+export declare function identityParityBasis(result: IdentityParityResult): string;
 /** `2 primary package findings` / `1 primary package finding`. */
 export declare const identityParityHeadline: (count: number) => string;
-/** Fail before dev/build when the same identity-sensitive package has multiple realpaths. */
-export declare function assertIdentityParity(cwd: string, rootPackage?: Record<string, unknown>, options?: IdentityParityOptions): Promise<IdentityParityResult>;
+/**
+ * Fail before dev/build when the same identity-sensitive package has multiple realpaths AND nothing
+ * is collapsing them.
+ *
+ * A declared package is not a suppression: the build injects the single-copy resolver, so the duplicate
+ * genuinely cannot reach the output. Failing on it anyway would leave the only supported answer being
+ * to change the install topology, which is the thing an app using linked sibling repositories cannot
+ * do. `result.deduplicated` still carries every covered duplicate for the caller to print.
+ */
+export declare function assertIdentityParity(cwd: string, rootPackage?: Record<string, unknown>): Promise<IdentityParityResult>;
 /** Convert hashed production asset names into the stable module-graph contract. */
 export declare function logicalStaticAssets(manifest: BuildManifestLike): readonly string[];
 export declare function normalizeBuildManifest(manifest: BuildManifestLike): ParityManifest;

package/dist/internal/parity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parity.d.ts","sourceRoot":"","sources":["../../src/internal/parity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parity.d.ts","sourceRoot":"","sources":["../../src/internal/parity.ts"],"names":[],"mappings":"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"}