@impetik/xeer-mcp 0.2.19 → 0.2.20

package/vendor/spec/import-policy.d.ts

@@ -16,6 +16,28 @@
  */
 /** The two module graphs the compiler walks. Test files have their own surface and are not a zone. */
 export type ImportZone = 'client' | 'server';
+/**
+ * The UI providers the platform implements, in the spelling `client.runtime.provider` uses.
+ *
+ * A provider is a whole renderer family — packages, entrypoint classification, JSX runtimes, and
+ * the compat aliases the family does or does not offer — and the client zone's policy is a pure
+ * function of which one the manifest declares ({@link clientImportPolicy}). Adding a provider is
+ * adding a family and a case, never a flag threaded through the consumers: what a specifier means
+ * on the client has exactly one answer per provider, stated here.
+ */
+export declare const CLIENT_RUNTIME_PROVIDERS: readonly ["preact", "react"];
+export type ClientRuntimeProvider = (typeof CLIENT_RUNTIME_PROVIDERS)[number];
+/**
+ * Where the renderer comes from. `platform` is the only implemented source: the platform packages
+ * declare and install the renderer, and applications never do. A future application-owned renderer
+ * would be `application`, which is a different resolution story rather than a different default.
+ */
+export type ClientRuntimeSource = 'platform';
+/** The normalized `client.runtime` block: a provider and where its packages come from. */
+export interface ClientRuntime {
+    readonly provider: ClientRuntimeProvider;
+    readonly source: ClientRuntimeSource;
+}
 /**
  * What one public entrypoint of the managed renderer package is *for*. Admission derives from this:
  * `runtime` and `development` entrypoints may be imported by client application code; `test` and
@@ -27,23 +49,80 @@ export type RendererEntrypointClassification =
 'runtime'
 /** Supported, but exists for development tooling; mutates the renderer's shared options. */
  | 'development'
+/**
+ * A published entrypoint whose bytes are built for a host runtime the client zone is not — React's
+ * Node, Bun, and edge server renderers. Supported by the package and genuinely useful elsewhere,
+ * which is what separates it from an entrypoint that does not exist: refused with its own reason
+ * so the diagnostic can say *why* rather than claim the renderer publishes no such thing.
+ */
+ | 'other-runtime'
 /** Test-only surface. Never a production-client import. */
  | 'test'
 /** A `package.json` subpath: metadata, not code. Pinned during bundling, rejected as an import. */
  | 'metadata';
 /**
- * A package family whose members must resolve to one physical package root regardless of importer —
- * the renderer, on the client. `entrypoints` classifies every public export of the anchor package;
- * `compatAliases` maps the React-ecosystem specifiers onto their `preact/compat` targets, which is
- * React-library compatibility under the Preact provider, not BYO React (#214 owns a real adapter).
+ * Where one entrypoint's TypeScript declarations live — a fact about the published packages, stated
+ * beside the classification that decides whether an application may import them.
+ *
+ * The vocabulary is exactly the cases the two renderers present, and no more. React ships no types
+ * at all and DefinitelyTyped publishes them under a second package name, one subpath per entrypoint;
+ * Preact ships its own inside the package the runtime bytes come from, named by its `exports` map's
+ * `types` condition; and a handful of entrypoints under both providers have declarations *nowhere* —
+ * `scheduler`, `react-dom/profiling`, `preact/compat/scheduler`. That third case is a fact worth
+ * declaring rather than an omission worth tolerating: it is what makes both tools refuse the same
+ * specifier by construction instead of by two people separately deciding not to add a row.
+ *
+ * Declarative on purpose, like the rest of this module. `types-package` carries the specifier
+ * because that name is a published fact; neither case carries a file path, because turning either
+ * into a file is resolution, and resolution happens against the platform's own install on the
+ * compiler side of this seam.
+ */
+export type EntrypointTypesSource = 
+/**
+ * A separate `@types/*` package publishes them, at `specifier`. Also the escape hatch the editor
+ * shims need: a second name for the same declarations, which no `paths` row maps.
+ */
+{
+    readonly kind: 'types-package';
+    readonly specifier: string;
+}
+/** The anchor package ships them itself, named by the `types` condition of its own `exports` map. */
+ | {
+    readonly kind: 'anchor';
+}
+/** Nothing publishes them. Every tool refuses the specifier, and all of them are right. */
+ | {
+    readonly kind: 'none';
+};
+/** One public entrypoint of a managed package: what it is for, and where its declarations live. */
+export interface RendererEntrypoint {
+    readonly classification: RendererEntrypointClassification;
+    readonly types: EntrypointTypesSource;
+}
+/**
+ * A package family whose members must resolve to one physical package root per package, regardless
+ * of importer — the renderer, on the client.
+ *
+ * `anchorPackages` is plural because a renderer family is not always one npm package: Preact ships
+ * its whole surface in `preact`, while React spans `react`, `react-dom`, and `scheduler`, each with
+ * its own installed root and its own `exports` map. Every classified entrypoint belongs to exactly
+ * one of them, derived from the specifier rather than declared twice, and single-root verification
+ * is *per package* — one react root and one react-dom root, not one root for the family.
+ *
+ * `packages` is the wider set: the names the family owns for admission purposes, including the ones
+ * it only owns in order to alias them. `compatAliases` maps the React-ecosystem specifiers onto
+ * their `preact/compat` targets, which is React-library compatibility under the Preact provider and
+ * has no analogue under React, where those specifiers are the renderer itself.
  */
 export interface ManagedPackageFamily {
-    /** The one package whose installed copy anchors every member of the family. */
-    readonly anchorPackage: string;
+    /** The UI provider whose renderer this family is. */
+    readonly provider: ClientRuntimeProvider;
+    /** The packages whose installed copies anchor the family. Each classified entrypoint is in one. */
+    readonly anchorPackages: readonly string[];
     /** Bare package names the family owns; any subpath of these is family territory. */
     readonly packages: readonly string[];
-    /** Every public entrypoint of the anchor package, classified. Keys are full specifiers. */
-    readonly entrypoints: ReadonlyMap<string, RendererEntrypointClassification>;
+    /** Every public entrypoint of every anchored package, described. Keys are full specifiers. */
+    readonly entrypoints: ReadonlyMap<string, RendererEntrypoint>;
     /** Per-subpath React-family aliases onto anchor entrypoints. Keys are full specifiers. */
     readonly compatAliases: ReadonlyMap<string, string>;
     readonly jsx: {
@@ -54,6 +133,13 @@ export interface ManagedPackageFamily {
 }
 export interface ZoneImportPolicy {
     readonly zone: ImportZone;
+    /**
+     * The UI provider this policy was resolved for, or null for a zone that selects no renderer. It
+     * travels with the policy rather than beside it because every consumer that needs the provider
+     * already holds the policy — the bundler's plugins, the type-check host, the dev server's aliases
+     * — and a second parameter threaded alongside is a second thing that can disagree with the first.
+     */
+    readonly provider: ClientRuntimeProvider | null;
     /**
      * `@impetik/xeer/*` subpaths this zone admits. What each one resolves to is the compiler's
      * knowledge — the SDK module targets live beside its resolver, not in this declarative layer.
@@ -84,15 +170,21 @@ export interface ZoneImportPolicy {
     };
 }
 /**
- * The normalized client runtime: the only implemented provider/source combination. `client.runtime`
- * in the manifest is optional and omission normalizes to exactly this value, so declaring it is a
- * statement of the default rather than a choice.
+ * The default client runtime. `client.runtime` in the manifest is optional and omission normalizes
+ * to exactly this value, so an application that says nothing gets the Preact provider it always
+ * had — byte-for-byte, down to the artifact identity.
+ *
+ * The *normalized* runtime of a given application is whatever its manifest declares; this is only
+ * the value omission means. Provenance and compiler facts must derive from the manifest's own
+ * runtime through {@link clientRuntimeId}, never from this constant.
  */
 export declare const NORMALIZED_CLIENT_RUNTIME: Readonly<{
     readonly provider: "preact";
     readonly source: "platform";
 }>;
-/** The normalized client runtime as compiler facts and artifact provenance spell it. */
+/** How a client runtime is spelled in compiler facts and artifact provenance. */
+export declare function clientRuntimeId(runtime: ClientRuntime): string;
+/** The default client runtime as compiler facts and artifact provenance spell it. */
 export declare const CLIENT_RUNTIME_ID: "preact/platform";
 /**
  * Default and advisory budgets for the open client bundle, minified pre-gzip bytes of the single
@@ -104,7 +196,22 @@ export declare const CLIENT_BUNDLE_ERROR_BUDGET_BYTES: number;
 export declare const CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES: number;
 /** The client renderer family under the Preact provider. */
 export declare const PREACT_RENDERER_FAMILY: ManagedPackageFamily;
+/**
+ * The client renderer family under the React provider: React itself, not a compatibility layer.
+ *
+ * No `compatAliases`, and the omission is the point. Under Preact the React-ecosystem specifiers are
+ * aliases onto `preact/compat` so a React library and the renderer stay one instance; under React
+ * they *are* the renderer, and an alias table would be a second name for the same file.
+ */
+export declare const REACT_RENDERER_FAMILY: ManagedPackageFamily;
 export declare const CLIENT_IMPORT_POLICY: ZoneImportPolicy;
+/**
+ * The client zone's policy under one UI provider — a pure function of the normalized manifest's
+ * `client.runtime.provider`, with no state and no first-caller latching. The Preact instance is
+ * returned by identity so consumers that still read {@link CLIENT_IMPORT_POLICY} and consumers that
+ * ask for the default share one object, and so the resolver caches keyed on it stay shared.
+ */
+export declare function clientImportPolicy(provider: ClientRuntimeProvider): ZoneImportPolicy;
 /**
  * The server zone, open to application dependencies since ADR 0005 was accepted (#244).
  *
@@ -124,9 +231,31 @@ export declare const CLIENT_IMPORT_POLICY: ZoneImportPolicy;
  * defensible number for. A per-zone budget is a product decision, not a gap this change may fill.
  */
 export declare const SERVER_IMPORT_POLICY: ZoneImportPolicy;
-export declare function zoneImportPolicy(zone: ImportZone): ZoneImportPolicy;
+/**
+ * One zone's policy. The provider only reaches the client zone — the server has no renderer to
+ * choose — and defaults to the manifest default so a caller with no manifest in hand (documentation,
+ * the server zone) reads exactly what it read before.
+ */
+export declare function zoneImportPolicy(zone: ImportZone, provider?: ClientRuntimeProvider): ZoneImportPolicy;
 /** The bare package name of a specifier: the first segment, or the first two for a scope. */
 export declare function packageNameOfSpecifier(specifier: string): string;
+/**
+ * DefinitelyTyped's name for a package's declarations.
+ *
+ * A naming rule rather than a lookup, and one nobody guesses correctly for a scoped package: the
+ * scope is *flattened into* the name rather than kept, so `@acme/widget` publishes as
+ * `@types/acme__widget`. Computed here, beside the specifier-naming rule it is a sibling of, so the
+ * two places that need it — the repair for a package with no declarations, and the check for whether
+ * an acknowledgment is still true — cannot disagree.
+ *
+ * Computed rather than read out of TypeScript's own TS7016 message, which carries the same name in
+ * English prose. That prose is not contract and has been reworded across releases; a rule this short
+ * is cheaper to state than to parse.
+ *
+ * Whether the package actually exists on the registry is unknowable offline, and nothing in the
+ * compiler contacts one at check time — so a caller quoting this must say it as the convention it is.
+ */
+export declare function definitelyTypedPackage(packageName: string): string;
 /** How a zone's policy answers one authored bare specifier. */
 export type BareImportAdmission = 
 /** An `@impetik/xeer/*` subpath this zone admits. */
@@ -142,7 +271,7 @@ export type BareImportAdmission =
 /** A managed-family specifier this zone deliberately rejects. */
  | {
     kind: 'managed-rejected';
-    reason: 'test-only' | 'metadata' | 'unknown-entrypoint';
+    reason: 'test-only' | 'metadata' | 'other-runtime' | 'unknown-entrypoint';
 }
 /** An application dependency, admitted subject to the declaration invariant. */
  | {
@@ -150,13 +279,14 @@ export type BareImportAdmission =
 }
 /**
  * Rejected on a zone rule rather than on the declaration invariant: a subpath of the platform
- * package this zone does not admit, a package family another zone owns, or a zone that admits no
- * application dependencies at all. Every one of these is *zone-exclusive* — the same specifier is
- * legal somewhere — which is why they are attribution evidence and Node builtins are not.
+ * package this zone does not admit, the provider-specific target of a facade the zone *does*
+ * admit, a package family another zone owns, or a zone that admits no application dependencies at
+ * all. Every one of these is *zone-exclusive* — the same specifier is legal somewhere — which is
+ * why they are attribution evidence and Node builtins are not.
  */
  | {
     kind: 'rejected';
-    reason: 'platform-subpath' | 'foreign-family' | 'closed';
+    reason: 'platform-subpath' | 'provider-facade' | 'foreign-family' | 'closed';
 };
 /**
  * Classifies one bare specifier under a zone's policy. Node builtins and native addons are the
@@ -165,8 +295,28 @@ export type BareImportAdmission =
  * consumer keeps a private copy of the rules.
  */
 export declare function admitBareImport(policy: ZoneImportPolicy, specifier: string): BareImportAdmission;
+/** The managed family that owns a bare package name in a zone, or null. */
+export declare function managedPackageFamily(policy: ZoneImportPolicy, packageName: string): ManagedPackageFamily | null;
+/**
+ * The foreign family that refuses a bare package name in a zone, or null.
+ *
+ * Managed ownership wins, and that precedence is the whole reason this is a function rather than a
+ * lookup each caller writes: under the React provider the foreign Preact family names `react`,
+ * `react-dom`, and `scheduler` among its own compat-alias territory, and those are precisely the
+ * packages the managed React family *is*. Asking managed-first is what lets the two descriptors stay
+ * complete statements about themselves instead of being trimmed to avoid each other.
+ */
+export declare function foreignPackageFamily(policy: ZoneImportPolicy, packageName: string): ManagedPackageFamily | null;
+/**
+ * The package whose installed root one classified entrypoint resolves from. Derived from the
+ * specifier rather than declared a second time, so a family cannot claim an entrypoint it does not
+ * anchor — which is what keeps `entrypoints` and `anchorPackages` from drifting apart.
+ */
+export declare function entrypointAnchorPackage(family: ManagedPackageFamily, specifier: string): string;
 /**
  * The admitted managed-family surface of a zone, alias keys included — what bundling and the dev
  * server must pin to the anchor, and what documentation lists as the renderer surface.
  */
 export declare function managedImportSpecifiers(policy: ZoneImportPolicy): ReadonlyMap<string, string>;
+/** Whether client application code may import an entrypoint with this classification. */
+export declare function isImportableClassification(classification: RendererEntrypointClassification): boolean;