@impetik/xeer-mcp 0.2.19 → 0.2.21

package/vendor/spec/type-check-profile.js

@@ -16,6 +16,7 @@
  * `"react-jsx"`, `lib` without the `lib.`/`.d.ts` affixes), which is what
  * `ts.convertCompilerOptionsFromJson` reads.
  */
+import { NORMALIZED_CLIENT_RUNTIME, clientImportPolicy, isImportableClassification, } from './import-policy.js';
 export const PLATFORM_TYPE_CHECK_COMPILER_OPTIONS = Object.freeze({
     allowJs: true,
     allowArbitraryExtensions: true,
@@ -35,21 +36,148 @@ export const PLATFORM_TYPE_CHECK_COMPILER_OPTIONS = Object.freeze({
     verbatimModuleSyntax: true,
 });
 /**
- * The React-family editor mappings every scaffolded and template `tsconfig.json` carries. Each
- * target is a shim inside the installed platform package that re-exports the platform's
- * `preact/compat` surface, so the mapping resolves under npm hoisting and pnpm strictness alike.
+ * Where the platform package keeps the editor shims of one provider, relative to `dist/`.
+ *
+ * Published layout, not an implementation detail: every scaffolded `tsconfig.json` names these
+ * directories, so renaming one rewrites every application's file. `compat` is the Preact provider's
+ * because that is where the React-family compatibility shims have always lived.
+ */
+const PROVIDER_SHIM_DIRECTORIES = Object.freeze({
+    preact: 'compat',
+    react: 'react',
+});
+/**
+ * The module inside the platform package each provider's client adapter is published as, relative to
+ * `dist/` and without an extension — the target of the `./client/<provider>` export.
+ */
+const PROVIDER_CLIENT_ADAPTER_MODULES = Object.freeze({
+    preact: 'client',
+    react: 'client-react',
+});
+/** How a `paths` row names a module inside the installed platform package. */
+function installedPlatformModule(module) {
+    return `./node_modules/@impetik/xeer/dist/${module}`;
+}
+/**
+ * The shim file name one specifier's row points at. Derived from the specifier so that the table and
+ * the generator agree by construction rather than by two lists matching: `react-dom/server.browser`
+ * is `react-dom-server-browser`, and nothing anywhere else decides that.
+ */
+function shimModuleName(specifier) {
+    return specifier.replaceAll('/', '-').replaceAll('.', '-');
+}
+/**
+ * Every renderer mapping one provider's editor needs, derived from the family descriptor.
+ *
+ * Two rules, and both are the descriptor's rather than anyone's memory. **Completeness**: every
+ * specifier the import policy admits from the renderer family gets a row, alias keys included,
+ * because the policy is what decides whether an application may write the import and this table is
+ * what decides whether its editor can read it. Five hand-kept rows against twelve admitted
+ * specifiers is how `react-dom/server` came to be a clean `xeer check` beside a TS2307 in the same
+ * file, and ten unmapped `preact/*` entrypoints were the same defect one provider over (#277).
+ * **Honesty**: an entrypoint whose declarations exist nowhere gets no row, so both tools refuse it
+ * by construction — `scheduler` and `react-dom/profiling` under React, `preact/compat/scheduler` and
+ * the two `compat/server` spellings under Preact. A row inventing types for one of those would make
+ * an editor accept what `xeer check` rejects, which is the same divergence pointed the other way.
+ */
+export function rendererEditorRows(provider) {
+    const directory = PROVIDER_SHIM_DIRECTORIES[provider];
+    const rows = [];
+    const add = (specifier, entrypoint, family) => {
+        const described = family.entrypoints.get(entrypoint);
+        if (!described || !isImportableClassification(described.classification))
+            return;
+        if (described.types.kind === 'none')
+            return;
+        rows.push({
+            specifier,
+            entrypoint,
+            types: described.types,
+            module: `${directory}/${shimModuleName(specifier)}`,
+        });
+    };
+    for (const family of clientImportPolicy(provider).managedFamilies) {
+        for (const specifier of family.entrypoints.keys())
+            add(specifier, specifier, family);
+        for (const [alias, target] of family.compatAliases)
+            add(alias, target, family);
+    }
+    return rows;
+}
+/**
+ * The `@impetik/xeer/*` subpaths whose *module* the provider chooses, mapped for the editor.
+ *
+ * The platform package publishes one module for each of these under every provider, and it is the
+ * bundler that picks which renderer they mean: the `client` facade, and the JSX runtime with its dev
+ * twin. The package's own `exports` map answers with the default provider's module, so only a
+ * non-default provider needs rows — which is also why an untouched Preact application's file is
+ * byte-for-byte what it was. Without them a React application's editor would type every element
+ * against Preact's JSX namespace and its `mount`/`useQuery` against the Preact adapter while the
+ * artifact ran React: green on the wrong evidence, the exact failure this profile exists to prevent
+ * (#248).
+ *
+ * The facade row names a published module rather than a generated shim — `./client/<provider>` is a
+ * real export, refused as an application import so that no source file decides the renderer. The JSX
+ * rows point at the very shim the family's own JSX entrypoints resolve to, so one name cannot mean
+ * two files.
+ */
+function providerFacadeRows(provider) {
+    const rows = new Map();
+    if (provider === NORMALIZED_CLIENT_RUNTIME.provider)
+        return rows;
+    rows.set('@impetik/xeer/client', PROVIDER_CLIENT_ADAPTER_MODULES[provider]);
+    const shims = new Map(rendererEditorRows(provider).map((row) => [row.specifier, row.module]));
+    for (const family of clientImportPolicy(provider).managedFamilies) {
+        for (const [subpath, entrypoint] of [
+            ['@impetik/xeer/jsx-runtime', family.jsx.runtime],
+            ['@impetik/xeer/jsx-dev-runtime', family.jsx.devRuntime],
+        ]) {
+            const shim = shims.get(entrypoint);
+            if (shim)
+                rows.set(subpath, shim);
+        }
+    }
+    return rows;
+}
+/**
+ * The editor's resolution table for one UI provider — the `paths` block of a scaffolded
+ * `tsconfig.json`.
  *
  * Not part of {@link PLATFORM_TYPE_CHECK_COMPILER_OPTIONS}: the platform check answers the same
  * question through its module-resolution host instead, so this is the editor's half of one rule
  * rather than a second rule.
+ *
+ * Every target is a module *inside* the installed platform package, because both renderers are
+ * platform-sourced: applications never declare them, and only a path inside the installed package
+ * resolves under npm hoisting and pnpm strictness alike. One rule binds a row to the file it names —
+ * a mapping rewrites *every* matching specifier in the program, including the ones written in the
+ * file it points at, so the file a row names may never import that row's own specifier. It would
+ * resolve back onto itself and answer with an empty module: an editor with no renderer types at all.
+ * The generator in the CLI package is what keeps that true, and `editor-resolution.test.ts` there
+ * type-checks a scaffolded project through its own `tsconfig.json` to prove it.
+ *
+ * Keys are sorted, so the file's bytes depend on which rows exist rather than on the order two
+ * declarations happen to be written in.
  */
-export const REACT_COMPAT_TSCONFIG_PATHS = Object.freeze({
-    'react': ['./node_modules/@impetik/xeer/dist/compat/react'],
-    'react-dom': ['./node_modules/@impetik/xeer/dist/compat/react-dom'],
-    'react-dom/client': ['./node_modules/@impetik/xeer/dist/compat/react-dom-client'],
-    'react/jsx-runtime': ['./node_modules/@impetik/xeer/dist/compat/react-jsx-runtime'],
-    'react/jsx-dev-runtime': ['./node_modules/@impetik/xeer/dist/compat/react-jsx-dev-runtime'],
-});
+export function tsconfigPathsFor(provider) {
+    const rows = new Map(providerFacadeRows(provider));
+    for (const row of rendererEditorRows(provider))
+        rows.set(row.specifier, row.module);
+    return Object.freeze(Object.fromEntries([...rows.keys()].sort()
+        .map((specifier) => [specifier, Object.freeze([installedPlatformModule(rows.get(specifier))])])));
+}
+/**
+ * The editor mappings a `tsconfig.json` carries under the **Preact** provider: the React-family
+ * names an application may write, aliased onto the platform's `preact/compat` surface, and Preact's
+ * own admitted entrypoints, which an application may equally write and whose editor rows were
+ * missing until #277.
+ */
+export const REACT_COMPAT_TSCONFIG_PATHS = tsconfigPathsFor('preact');
+/**
+ * The same mappings under the **React** provider, pointed at the renderer itself rather than at a
+ * compatibility layer — which is the whole point of selecting the provider.
+ */
+export const REACT_PROVIDER_TSCONFIG_PATHS = tsconfigPathsFor('react');
 /**
  * The files an application's `tsconfig.json` type-checks: sources, TypeScript tests, and the
  * generated contract.
@@ -69,10 +197,14 @@ export const APPLICATION_TSCONFIG_INCLUDE = Object.freeze(['src', 'tests/**/*.ts
  * bytes. Serialized here rather than returned as an object because "the file the editor reads" is
  * what has to match, and two callers stringifying the same object with different options would
  * produce two different files.
+ *
+ * The provider changes `paths` and nothing else. Every rule the platform enforces is identical
+ * across providers — the choice is about which renderer a name resolves to, never about how strictly
+ * the code is judged — and the default keeps a Preact application's file byte-for-byte what it was.
  */
-export function applicationTsconfigDocument() {
+export function applicationTsconfigDocument(provider = 'preact') {
     return `${JSON.stringify({
-        compilerOptions: { ...PLATFORM_TYPE_CHECK_COMPILER_OPTIONS, paths: REACT_COMPAT_TSCONFIG_PATHS },
+        compilerOptions: { ...PLATFORM_TYPE_CHECK_COMPILER_OPTIONS, paths: tsconfigPathsFor(provider) },
         include: APPLICATION_TSCONFIG_INCLUDE,
     }, null, 2)}\n`;
 }

package/vendor/spec/types.d.ts

@@ -1,3 +1,4 @@
+import type { ClientRuntime, ClientRuntimeProvider, ClientRuntimeSource } from './import-policy.js';
 import type { PublicAssetsV0 } from './public-assets.js';
 export declare const SOURCE_FORMAT: "xeer.application-source.v0";
 export declare const ARTIFACT_FORMAT: "xeer.application.v0";
@@ -31,6 +32,26 @@ export interface Diagnostic {
      */
     causedBy?: string;
 }
+/**
+ * Whether a set of diagnostics refuses the command that produced it.
+ *
+ * `ok` is "no error", never "no diagnostic": a warning is the platform telling a builder something
+ * while still doing the work, and a command that failed on one would make every advisory a breaking
+ * change. The rule lives here because `check`, `build`, and `doctor` each decide it about the same
+ * diagnostics, and three copies of it is how one of them ends up refusing a warning the other two
+ * report and keep going past.
+ */
+export declare function refusesCompletion(diagnostics: readonly Diagnostic[]): boolean;
+/**
+ * The members of a set that refuse it — the same rule as {@link refusesCompletion}, asked for the
+ * subset rather than the verdict.
+ *
+ * A consumer that *reports* a refusal needs the boolean; a consumer that *shows* one needs to know
+ * which diagnostics it is showing, because a set that mixes a refusal with an advisory is the normal
+ * case rather than the odd one. Deriving the verdict from the subset is what stops the two answers
+ * from ever disagreeing about the same set.
+ */
+export declare function refusingDiagnostics(diagnostics: readonly Diagnostic[]): readonly Diagnostic[];
 /**
  * `ref` is a scalar in the only sense that matters here: it is one TEXT column holding one row id.
  * What distinguishes it is that the column carries a FOREIGN KEY to the declared table it names, so
@@ -182,15 +203,25 @@ export interface ApplicationManifestV0 {
     storage?: StorageConfigV0;
     capabilities?: Capability[];
     /**
-     * The client runtime selection (#212). Optional, and closed: only implemented provider/source
-     * combinations are accepted, and omission normalizes to `{ provider: "preact", source:
-     * "platform" }` with identical semantics and build output. Declaring it is a statement of the
-     * default, not a choice — a future app-owned source would be `"application"`, not `"user"`.
+     * Installed dependencies acknowledged as shipping no TypeScript declarations; see the schema
+     * module, where the rule and its reasoning live. Package names, one per package: the acknowledgment
+     * covers every subpath of the package it names.
+     */
+    untypedDependencies?: string[];
+    /**
+     * The client runtime selection (#212, #214). Optional, and closed: only implemented
+     * provider/source combinations are accepted, and omission normalizes to `{ provider: "preact",
+     * source: "platform" }` with identical semantics and build output.
+     *
+     * The provider is the one line that differs between a Preact application and a React one:
+     * `jsxImportSource` stays `@impetik/xeer` and the sources stay byte-identical, because the import
+     * policy — not the application — decides what the platform's JSX runtime and client facade
+     * resolve to. A future app-owned renderer would be `source: "application"`, not `"user"`.
      */
     client?: {
         runtime?: {
-            provider: 'preact';
-            source?: 'platform';
+            provider: ClientRuntimeProvider;
+            source?: ClientRuntimeSource;
         };
     };
     budgets?: {
@@ -243,12 +274,19 @@ export interface NormalizedApplicationManifestV0 {
      */
     storage: NormalizedStorageConfigV0 | null;
     capabilities: Capability[];
-    /** Always present once normalized: omission and the explicit default are the same statement. */
+    /**
+     * Sorted and deduplicated, `[]` when the manifest declares none. Deliberately absent from the
+     * artifact payload: an acknowledgment is type-space only, so it must not move an `artifactId`.
+     */
+    untypedDependencies: string[];
+    /**
+     * Always present once normalized: omission and the explicit default are the same statement. What
+     * is *declared*, however, is carried through rather than defaulted away — this block is where the
+     * import policy, the type-resolution profile, and the artifact's provenance all read the
+     * application's provider from.
+     */
     client: {
-        runtime: {
-            provider: 'preact';
-            source: 'platform';
-        };
+        runtime: ClientRuntime;
     };
     budgets: {
         queryRows: number;

package/vendor/spec/types.js

@@ -2,6 +2,30 @@ export const SOURCE_FORMAT = 'xeer.application-source.v0';
 export const ARTIFACT_FORMAT = 'xeer.application.v0';
 export const DEV_PROTOCOL = 'xeer.dev.v0';
 export const INSPECT_PROTOCOL = 'xeer.inspect.v0';
+/**
+ * Whether a set of diagnostics refuses the command that produced it.
+ *
+ * `ok` is "no error", never "no diagnostic": a warning is the platform telling a builder something
+ * while still doing the work, and a command that failed on one would make every advisory a breaking
+ * change. The rule lives here because `check`, `build`, and `doctor` each decide it about the same
+ * diagnostics, and three copies of it is how one of them ends up refusing a warning the other two
+ * report and keep going past.
+ */
+export function refusesCompletion(diagnostics) {
+    return refusingDiagnostics(diagnostics).length !== 0;
+}
+/**
+ * The members of a set that refuse it — the same rule as {@link refusesCompletion}, asked for the
+ * subset rather than the verdict.
+ *
+ * A consumer that *reports* a refusal needs the boolean; a consumer that *shows* one needs to know
+ * which diagnostics it is showing, because a set that mixes a refusal with an advisory is the normal
+ * case rather than the odd one. Deriving the verdict from the subset is what stops the two answers
+ * from ever disagreeing about the same set.
+ */
+export function refusingDiagnostics(diagnostics) {
+    return diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+}
 /**
  * The capabilities an application may declare. A capability name in `capabilities[]` and its config
  * block are one declaration in two halves: either both are present or neither is, checked in both