@homeflare/site 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Schneider <tim@taslabs.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+    10|furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    20|OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @homeflare/site
+
+One typed site config. The file holds **base values** (an apex, a few labels, networks,
+hosts) and **pinned values**; `derive()` builds every hostname, address, zone suffix,
+Access URL, OIDC redirect and vault mount name from it, the same way in every repo.
+
+```sh
+bun add @homeflare/site effect@4.0.0-rc.115
+```
+
+⛔ **`effect` is a pinned peer.** Effect release candidates are not compatible with each
+other, and the override behaviour this package relies on is measured per version.
+
+★ **Why.** A public stack that types a hostname cannot be run by anyone else, and a stack
+that re-derives a name its own way drifts from its siblings. Swapping the apex here
+changes every derived name by substitution and nothing else — a test proves it.
+
+## Load it
+
+```ts
+import { derive, assertStage } from '@homeflare/site';
+import { loadSite } from '@homeflare/site/load'; // Node / Bun: reads a file, spawns git
+
+const { site, overrides } = await loadSite({ siteDev: flags.siteDev });
+if (overrides.length > 0) console.warn('site overrides:', overrides.join(', '));
+assertStage(site, stage);
+const d = derive(site);
+d.vault.publicAddr; // https://api.v.example.com
+```
+
+- `HF_SITE_FILE` names the file. ⛔ **There is no default path**: without it `loadSite`
+  refuses and points at `node_modules/@homeflare/site/site.example.json`. Copy that, set
+  `kind`, replace every value.
+- **Plain JSON**, not JSONC — Nix, jq and Python read the same file.
+- ⛔ **Reviewed values only.** Unless `siteDev` is set (your `--site-dev` flag), the file
+  must be committed, unmodified, on `main` (`branch` to change it). "Unmodified" is by
+  blob hash, so `--skip-worktree` cannot hide an edit, and a symlink is judged by the
+  file it points at. `readCheckout` and `checkoutProblem` expose the same check.
+- `SITE_FILE_VAR` is `HF_SITE_FILE`; `SITE_EXAMPLE` is the example's path.
+- Workers (no filesystem, no env): `decodeSite(json)` from the main entry. It runs
+  `validateSite` (references, then the derive-version guard) itself.
+
+### Environment overrides
+
+`ENV_OVERRIDES` lists the only `HF_SITE_*` variables accepted — scalars such as
+`HF_SITE_APEX` or `HF_SITE_VAULT_PORT`. Anything else under `HF_SITE_` is refused.
+⛔ **Overrides need `siteDev`**: an override is an unreviewed value, like an uncommitted
+edit, so a stray `HF_SITE_APEX` in a shell refuses a reviewed load instead of renaming
+every derived hostname.
+
+⚠️ **Measured on effect 4.0.0-rc.115**, and each is a test:
+
+- `nested('hf')` must come **before** `constantCase`. The other order looks up
+  `hf_SITE_APEX`, so `HF_SITE_APEX` is ignored silently.
+- An override inside a record or list **replaces** the whole collection (and upper-cases
+  its key), so collections are never overridable.
+- `HF_SITE_X_API` shadows `x`: a field named like another plus `_…` breaks the decode.
+- ⛔ Guard fields — `version`, `deriveVersion`, `kind`, `vault.clusterName`,
+  `vault.namespace` — never: an overridden identity field moves the identity check's
+  expectation along with the client.
+
+## Derived names
+
+| call                                    | example value                                   |
+| --------------------------------------- | ----------------------------------------------- |
+| `d.vault.host` / `d.vault.apiHost`      | `v.example.com` / `api.v.example.com`           |
+| `d.vault.meshAddr` / `d.vault.lanAddr`  | `https://198.18.0.2:8200` / `http://hub.mgmt…`  |
+| `d.vault.oidcRedirects`                 | UI callback on the vault host, then `localhost` |
+| `d.mgmtZone`, `d.zone('lab')`           | `mgmt.example.com`, `lab.example.com`           |
+| `d.host('n2')`, `d.address('n2','lab')` | `n2.mgmt.example.com`, `198.51.100.12`          |
+| `d.access.teamDomain`                   | `https://example-team.cloudflareaccess.com`     |
+| `d.productHost('wiki')`, `d.productUrl` | `kb.example.com` (label), own `domain` if set   |
+| `d.serviceUrl('grafana')`               | `http://hub.mgmt.example.com:3000`              |
+| `d.clusterMembers('c1')`                | member FQDNs                                    |
+| `d.cloudflareMount('main','dns')`       | `cloudflare-main-dns` (all: `cloudflareMounts`) |
+
+⛔ **Unknown keys throw** (`SiteError` code `unknown-key`, listing what is declared). There
+is no fallback host: a plausible default is how a typo becomes a DNS record.
+
+`d.access.teamDomain` is exactly what `verifyAccessJwt` in `@homeflare/cloudflare` calls
+`teamDomain`.
+
+## Pinned, never derived
+
+`pins(site)` reads `pinned.*` by key: `name`, `certificate`, `adopted`, `policy`,
+`principals`.
+
+- ⛔ **Physical names** (Workers, D1, KV, R2, Durable Objects): deriving the alerts D1
+  name would replace it and delete its data.
+- ⛔ **Certificate hostnames** on adopted certificates: a change reissues and revokes the
+  certificate a host is still serving.
+- **Adopted ids** (LB pool, WAF ruleset, Ceph / PBS names, PKI CNs), and the vault's
+  `clusterName`.
+- **Policy and SSH principal lists** stay explicit. `unknownPrincipals`,
+  `pinnedPrincipalIssues` and `inventory` let a consumer test assert they are subsets of
+  the inventory — a break-glass principal must never vanish because a leg was renamed.
+
+## Guards
+
+- `decodeSite` / `loadSite` refuse a file whose `deriveVersion` is not the installed
+  version (`checkDeriveVersion`, code `derive-version`). Read the CHANGELOG, then bump it.
+- `assertStage(site, 'live')` refuses unless `kind` is `live`.
+- `expectedIdentity(site, { account })`, `compareIdentity`, `assertIdentity`: hand in the
+  observed `cluster_name` (from `sys/health`), namespace and Cloudflare account id; any
+  mismatch — or anything expected but not observed — refuses, and so does an expectation
+  naming no field (it would match any system). Pure: fetches nothing.
+
+## Doc placeholders
+
+`SITE_TOKENS` is the fixed set public docs use: `<apex>`, `<vault-host>`,
+`<vault-api-host>`, `<mgmt-zone>`, `<access-team>`, `<github-owner>`, `<estate-root>`,
+`<cluster>`. `tokenValues(site)` gives each single-valued token's value (a leak gate's
+needles); `renderTokens(text, site)` substitutes them. `<cluster>` is a variable.
+
+⛔ Placeholders use only RFC 2606 names and RFC 5737 / 2544 addresses — never `10/8` or
+`100.64/10`, which would blind a leak gate to the ranges it must catch.
+
+## Types and errors
+
+`SiteSchema` (Effect Schema), `Site`, `SiteInput`, `SITE_FORMAT`, `Derived`, `SiteError`
+with a stable `code` and `issues` naming each path, `VERSION`.
+
+## License
+
+MIT © Timothy Schneider

package/dist/checkout.d.ts

@@ -0,0 +1,26 @@
+export interface CheckoutState {
+    /** The checked-out branch, or `undefined` on a detached HEAD. */
+    readonly branch: string | undefined;
+    /** Git knows the file (⚠️ an ignored or untracked file was never reviewed). */
+    readonly tracked: boolean;
+    /**
+     * The file's bytes differ from HEAD, staged or not.
+     * ⚠️ Compared by BLOB HASH, not only by `git status`. Measured 2026-09-21: after
+     *   `git update-index --skip-worktree` (the usual way to keep a local config tweak),
+     *   `status --porcelain` printed nothing for an edited site file, and a status-only
+     *   guard loaded the edited apex as "clean, on main".
+     */
+    readonly dirty: boolean;
+}
+/**
+ * The file's checkout state, or `undefined` when it is not inside a git work tree.
+ *
+ * ⚠️ THE REAL FILE IS CHECKED, NOT THE LINK. Measured 2026-09-21: a committed symlink whose
+ *   target lived outside the repository passed as "clean, on main" while the target was
+ *   edited freely — git tracks the link's target PATH, not the bytes behind it. Resolving
+ *   first makes that target "not inside a git checkout", which refuses.
+ */
+export declare function readCheckout(file: string): Promise<CheckoutState | undefined>;
+/** Why `state` is not a reviewed checkout of `branch`, or `undefined` when it is. */
+export declare function checkoutProblem(state: CheckoutState | undefined, branch: string): string | undefined;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAoBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAgBnF;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,SAAS,CAQpB"}

package/dist/decode.d.ts

@@ -0,0 +1,26 @@
+import * as SchemaIssue from 'effect/SchemaIssue';
+import { type Site } from './schema.ts';
+/**
+ * `pinned.certificates["vault.origin"].0` — a key that itself holds a dot is bracketed,
+ * or the path would read as two levels that do not exist.
+ */
+export declare function joinPath(segments: readonly string[]): string;
+/** Render a schema issue as `path: problem` lines, dropping a leading `skip` segment. */
+export declare function formatIssues(issue: SchemaIssue.Issue, skip?: string): readonly string[];
+/** Schema-only decode. Throws `decode` listing every problem, each with its path. */
+export declare function decodeStrict(input: unknown): Site;
+export interface ValidateOptions {
+    /**
+     * The `@homeflare/site` version to hold `deriveVersion` against. Defaults to the
+     * installed one — which is the point; override only to test the refusal.
+     */
+    readonly installed?: string;
+}
+/** Cross-field references, then the derive-version guard. Returns the same site. */
+export declare function validateSite(site: Site, options?: ValidateOptions): Site;
+/**
+ * Decode and validate a site from plain data (already-parsed JSON).
+ * Throws {@link SiteError}: `decode`, `reference` or `derive-version`.
+ */
+export declare function decodeSite(input: unknown, options?: ValidateOptions): Site;
+//# sourceMappingURL=decode.d.ts.map

package/dist/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../src/decode.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,WAAW,MAAM,oBAAoB,CAAC;AAIlD,OAAO,EAAE,KAAK,IAAI,EAAc,MAAM,aAAa,CAAC;AAgBpD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAO5D;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAavF;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAYjD;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAO5E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAE9E"}

package/dist/derive.d.ts

@@ -0,0 +1,66 @@
+import type { Site } from './schema.ts';
+export interface DerivedHost {
+    /** `<key>.<zone>`; absent when the host declares no zone. */
+    readonly fqdn?: string;
+    /** Network key → address on that network. */
+    readonly addresses: Readonly<Record<string, string>>;
+}
+export interface DerivedVault {
+    /** `<vault-host>`: the browser / UI hostname. */
+    readonly host: string;
+    /** `<vault-api-host>`: the public API hostname. */
+    readonly apiHost: string;
+    /** `https://<vault-api-host>` — the public API. Humans; machines use Mesh or the LAN. */
+    readonly publicAddr: string;
+    /** `https://<mesh address>:<port>` — machines over the private Mesh path. */
+    readonly meshAddr: string;
+    /** The LAN pass-through proxy, as a `BAO_ADDR`. */
+    readonly lanAddr: string;
+    readonly namespace: string;
+    /** Browser callback on `<vault-host>`, then the CLI's localhost listener. */
+    readonly oidcRedirects: readonly string[];
+}
+export interface DerivedAccess {
+    readonly team: string;
+    /**
+     * `https://<team>.cloudflareaccess.com`. ★ Named for `verifyAccessJwt`'s `teamDomain`
+     *   option in `@homeflare/cloudflare`, so it passes straight through.
+     */
+    readonly teamDomain: string;
+    /** The JWKS endpoint Access signs with. */
+    readonly certsUrl: string;
+}
+export interface Derived {
+    readonly apex: string;
+    /** Zone key → FQDN (`mgmt` → `mgmt.<apex>`). */
+    readonly zones: Readonly<Record<string, string>>;
+    /** `<mgmt-zone>`. */
+    readonly mgmtZone: string;
+    readonly vault: DerivedVault;
+    readonly access: DerivedAccess;
+    readonly hosts: Readonly<Record<string, DerivedHost>>;
+    /** Product key → public hostname. */
+    readonly products: Readonly<Record<string, string>>;
+    /** Service key → URL. */
+    readonly services: Readonly<Record<string, string>>;
+    /** Cluster key → member FQDNs, in declared order. */
+    readonly clusters: Readonly<Record<string, readonly string[]>>;
+    /** Every `cloudflare-<alias>-<surface>` mount, in declared order. */
+    readonly cloudflareMounts: readonly string[];
+    /** A zone's FQDN. `"apex"` is the apex itself. */
+    zone(key: string): string;
+    /** A host's FQDN. Throws when the host is unknown or has no zone. */
+    host(key: string): string;
+    /** A host's address on a network. Throws when either is unknown or not a leg. */
+    address(host: string, network: string): string;
+    productHost(key: string): string;
+    /** `https://<productHost>`. */
+    productUrl(key: string): string;
+    serviceUrl(key: string): string;
+    clusterMembers(key: string): readonly string[];
+    /** Throws when the alias is unknown or that account does not list the surface. */
+    cloudflareMount(alias: string, surface: string): string;
+    accountId(alias: string): string;
+}
+export declare function derive(site: Site): Derived;
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

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

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The one error this package throws.
+ *
+ * ★ ONE CLASS, A `code` TO SWITCH ON. Callers mostly print the message and stop; the few
+ *   that branch (a scaffold harness skipping `derive-version` in a dry run, say) branch on
+ *   `code`, which is stable, rather than on message text, which is not.
+ *
+ * ⛔ Messages name paths, keys and the fix — never a value from a live file beyond the
+ *   one being complained about. A site file is private, and an error string ends up in CI
+ *   logs.
+ */
+export type SiteErrorCode = 
+/** The file does not match the schema. `issues` lists `path: problem`. */
+'decode'
+/** A value points at something the file does not declare (a zone, host, network). */
+ | 'reference'
+/** A consumer asked for a product, service, zone, host or pin nobody declared. */
+ | 'unknown-key'
+/** The file was reviewed against a different `@homeflare/site` version. */
+ | 'derive-version'
+/** A non-live site was asked to plan stage `live`. */
+ | 'stage'
+/** The observed vault or account is not the one the site describes. */
+ | 'identity'
+/** The file could not be located, read or parsed. */
+ | 'load'
+/** The file is not committed on `main` and `siteDev` was not set. */
+ | 'checkout'
+/** An environment override was refused. */
+ | 'override';
+export declare class SiteError extends Error {
+    readonly name = "SiteError";
+    readonly code: SiteErrorCode;
+    /** One line per problem, each naming its path. Empty when the message says it all. */
+    readonly issues: readonly string[];
+    constructor(code: SiteErrorCode, message: string, issues?: readonly string[]);
+}
+/** Throw `unknown-key`, listing what IS declared so the fix is one glance away. */
+export declare function unknownKey(kind: string, key: string, declared: Iterable<string>): never;
+/**
+ * Look a key up in a record, or throw `unknown-key`.
+ * ⛔ No fallback, ever. A plausible default host is how a typo becomes a live DNS record.
+ */
+export declare function lookup<V>(kind: string, record: Readonly<Record<string, V>>, key: string): V;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,aAAa;AACvB,0EAA0E;AACxE,QAAQ;AACV,qFAAqF;GACnF,WAAW;AACb,kFAAkF;GAChF,aAAa;AACf,2EAA2E;GACzE,gBAAgB;AAClB,sDAAsD;GACpD,OAAO;AACT,uEAAuE;GACrE,UAAU;AACZ,qDAAqD;GACnD,MAAM;AACR,qEAAqE;GACnE,UAAU;AACZ,2CAA2C;GACzC,UAAU,CAAC;AAEf,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,eAAe;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,YAAY,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,MAAM,EAAO,EAI/E;CACF;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAIvF;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAG3F"}

package/dist/guards.d.ts

@@ -0,0 +1,19 @@
+import type { Site } from './schema.ts';
+/**
+ * Refuse a site reviewed against a different `@homeflare/site` than the one installed.
+ *
+ * ★ WHY EXACT EQUALITY. Derive rules are this package's behaviour. If a new version builds
+ *   one hostname differently, every repo on it would plan a rename — a REPLACE — without
+ *   anyone having looked. Holding `deriveVersion` equal to the installed version makes that
+ *   a deliberate, reviewed one-line bump in the site file instead.
+ */
+export declare function checkDeriveVersion(site: Site, installed: string): void;
+/** Stages as a deploy tool names them. Only `live` is special here. */
+export type Stage = string;
+/**
+ * ⛔ STAGE `live` ONLY WITH A LIVE SITE. An example or testing site can never plan
+ *   against live state — its account ids and cluster name are placeholders, and a plan
+ *   against real state would read every live object as "not declared: delete".
+ */
+export declare function assertStage(site: Site, stage: Stage): void;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQtE;AAED,uEAAuE;AACvE,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAO1D"}

package/dist/identity.d.ts

@@ -0,0 +1,33 @@
+import type { Site } from './schema.ts';
+export interface Identity {
+    /** `cluster_name` from the vault's `sys/health`. */
+    readonly vaultClusterName?: string;
+    /** The namespace the client is using. `''` is the root namespace. */
+    readonly vaultNamespace?: string;
+    /** The Cloudflare account the credential resolves to. */
+    readonly cloudflareAccountId?: string;
+}
+export interface IdentityMismatch {
+    readonly field: keyof Identity;
+    readonly expected: string;
+    /** `undefined` when the caller did not observe it — which is itself a mismatch. */
+    readonly observed: string | undefined;
+}
+export interface ExpectedIdentityOptions {
+    /** The account alias the plan targets. Omit to leave the account out of the compare. */
+    readonly account?: string;
+}
+/** What the site says the live systems are. Throws `unknown-key` for an unknown alias. */
+export declare function expectedIdentity(site: Site, options?: ExpectedIdentityOptions): Identity;
+/**
+ * Every field the expectation sets and the observation does not match.
+ * ⛔ An expected field the caller did not observe COUNTS AS A MISMATCH. "We did not check"
+ *   must never read the same as "it matched".
+ * ⛔ An expectation that sets NO field throws `identity`. Compared field by field, `{}`
+ *   matches every system there is, so a caller that built it by mistake (a wrong spread, a
+ *   renamed key) would pass the guard on any vault and any account.
+ */
+export declare function compareIdentity(expected: Identity, observed: Identity): readonly IdentityMismatch[];
+/** {@link compareIdentity}, throwing `identity` with one line per mismatch. */
+export declare function assertIdentity(expected: Identity, observed: Identity): void;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,QAAQ,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACtC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,uBAA4B,GAAG,QAAQ,CAU5F;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,GACjB,SAAS,gBAAgB,EAAE,CAe7B;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAW3E"}