@effectweb/compiler 0.2.3 → 0.3.1

package/README.md

@@ -19,4 +19,32 @@ See [EffectWeb](https://github.com/DerpyCrabs/EffectWeb) for authoring and devel
 
 For editor and CI diagnostics, add `@effectweb/compiler/oxlint` to Oxlint's `jsPlugins` and enable `effectweb/valid-view` as an error. The optional `effectweb/whole-model-dependency` rule reports coarse dependencies. Both use the compiler's Rust analysis; no second purity implementation is maintained. `diagnose` exposes the same structured view diagnostics for other tooling. Invalid syntax still throws and is handled by the host parser.
 
-The Vite plugin enables plain-data snapshot freezing during development and disables it for production builds. This catches accidental mutation without changing object identity or introducing proxies. Published snapshots must remain immutable; opaque mutable objects are outside these checks.
+The runtime freezes published plain objects and arrays in every build without changing their identity or introducing proxies. Opaque mutable resources retain their own lifecycle. The Vite plugin adds source-dependency instrumentation during development; production builds omit that metadata.
+
+Diagnostics include `code`, `category`, `severity`, source `file`/`line`/`column` (one-based UTF-16 columns), and an actionable `remedy`:
+
+| Code   | Category              | Meaning and remedy                                                                                                                                                |
+| ------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| EW1000 | correctness           | Lint could not parse/analyze the file; fix syntax or the native compiler installation.                                                                            |
+| EW1001 | correctness           | Invalid view syntax or impure render work; the message identifies the supported form or command boundary.                                                         |
+| EW1002 | correctness           | A known raw object array is rendered with `.map`; use `entities(items)`, a declared `collection(identity).from(items)`, or explicit positional `sequence(items)`. |
+| EW2001 | unprovable-dependency | A mutable capture is outside snapshot dependencies; pass immutable data through the model. Compilation rejects this.                                              |
+| EW2002 | unprovable-dependency | A query declares a custom `key`; remove it. Every request argument already participates in cache identity. This is a compilation error.                           |
+| EW3001 | performance           | A helper depends on the entire model; optionally pass the individual fields it uses.                                                                              |
+
+`effectweb/valid-view` reports compilation errors; `effectweb/whole-model-dependency` is optional performance advice. `effectweb/query-key` reports rejected custom query keys in `.ts` and `.tsx`. Configure these rules as follows:
+
+```json
+{
+  "jsPlugins": ["@effectweb/compiler/oxlint"],
+  "rules": {
+    "effectweb/valid-view": "error",
+    "effectweb/query-key": "error",
+    "effectweb/whole-model-dependency": "warn"
+  }
+}
+```
+
+Identity checks use conservative same-file evidence: object array literals, typed variables or parameters, explicit `view<Model>`, local non-generic aliases/interfaces, `Array`/`ReadonlyArray`/`readonly` annotations, and common `filter`/`slice` operations. They do not run a TypeScript project checker, resolve imported types, or infer domain keys. Unknown types remain subject to runtime identity checks. Collections validate identities when constructed or shared, including unchanged-array paths; duplicate errors report both zero-based positions.
+
+Query checks recognize imported `query` (including aliases and `effectweb/query`) and reject literal definitions containing `key`. TypeScript and the runtime also reject custom keys, including definitions assembled outside the compiler's static analysis. Pass all request data as arguments and supply services through the Effect environment.

package/dist/compile.d.ts

@@ -4,12 +4,21 @@ export interface Diagnostic {
     readonly column: number;
     readonly message: string;
     readonly severity: 'error' | 'warning';
+    readonly code: string;
+    readonly category: 'correctness' | 'unprovable-dependency' | 'performance';
+    readonly remedy: string;
 }
 export interface CompilerOptions {
     /** The module exporting view and slot. Defaults to effectweb. */
     importSource?: string;
     runtimeModule?: string;
     development?: boolean;
+    /**
+     * Audited render calls, keyed by import specifier and exported member path.
+     * These contracts promise immutable inputs, no observable effects or ambient
+     * reads, and no eager execution of unchecked callbacks. They do not load source.
+     */
+    pureImports?: Readonly<Record<string, readonly string[]>>;
     onDiagnostic?: (diagnostic: Diagnostic) => void;
 }
 export interface CompilerResult {

package/dist/files.d.ts

@@ -0,0 +1 @@
+export declare function isCompilerFile(filename: string): boolean;

package/dist/files.js

@@ -0,0 +1,3 @@
+export function isCompilerFile(filename) {
+    return /\.(?:tsx?|jsx)$/u.test(filename) && !filename.endsWith('.d.ts');
+}

package/dist/oxlint.d.ts

@@ -1,12 +1,11 @@
+import { type CompilerOptions } from './compile.js';
 type Source = {
     text: string;
 };
 type Context = {
     filename: string;
     sourceCode: Source;
-    options: readonly {
-        importSource?: string;
-    }[];
+    options: readonly Pick<CompilerOptions, 'importSource' | 'pureImports'>[];
     report: (diagnostic: {
         loc: {
             line: number;
@@ -29,6 +28,15 @@ declare const _default: {
                         importSource: {
                             type: string;
                         };
+                        pureImports: {
+                            type: string;
+                            additionalProperties: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                            };
+                        };
                     };
                     additionalProperties: boolean;
                 }[];
@@ -46,6 +54,41 @@ declare const _default: {
                         importSource: {
                             type: string;
                         };
+                        pureImports: {
+                            type: string;
+                            additionalProperties: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                            };
+                        };
+                    };
+                    additionalProperties: boolean;
+                }[];
+            };
+            create(context: Context): {
+                Program(): void;
+            };
+        };
+        'query-key': {
+            meta: {
+                type: "problem" | "suggestion";
+                schema: {
+                    type: string;
+                    properties: {
+                        importSource: {
+                            type: string;
+                        };
+                        pureImports: {
+                            type: string;
+                            additionalProperties: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                            };
+                        };
                     };
                     additionalProperties: boolean;
                 }[];

package/dist/oxlint.js

@@ -1,13 +1,20 @@
 import { diagnose } from './compile.js';
+import { isCompilerFile } from './files.js';
 const results = new WeakMap();
-function rule(severity) {
+function rule(category) {
     return {
         meta: {
-            type: severity === 'error' ? 'problem' : 'suggestion',
+            type: category !== 'performance' ? 'problem' : 'suggestion',
             schema: [
                 {
                     type: 'object',
-                    properties: { importSource: { type: 'string' } },
+                    properties: {
+                        importSource: { type: 'string' },
+                        pureImports: {
+                            type: 'object',
+                            additionalProperties: { type: 'array', items: { type: 'string' } },
+                        },
+                    },
                     additionalProperties: false,
                 },
             ],
@@ -15,19 +22,23 @@ function rule(severity) {
         create(context) {
             return {
                 Program() {
-                    if (!context.filename.endsWith('.tsx'))
+                    if (!isCompilerFile(context.filename))
                         return;
                     const importSource = context.options[0]?.importSource ?? 'effectweb';
+                    const pureImports = context.options[0]?.pureImports;
                     let cached = results.get(context.sourceCode);
                     if (!cached || cached.text !== context.sourceCode.text) {
                         cached = { text: context.sourceCode.text, diagnostics: new Map() };
                         results.set(context.sourceCode, cached);
                     }
-                    const key = `${context.filename}\0${importSource}`;
+                    const key = `${context.filename}\0${importSource}\0${JSON.stringify(pureImports)}`;
                     let diagnostics = cached.diagnostics.get(key);
                     if (!diagnostics) {
                         try {
-                            diagnostics = diagnose(context.sourceCode.text, context.filename, { importSource });
+                            diagnostics = diagnose(context.sourceCode.text, context.filename, {
+                                importSource,
+                                ...(pureImports ? { pureImports } : {}),
+                            });
                         }
                         catch (error) {
                             // Parser failures and unavailable native binaries must not silently pass lint.
@@ -37,6 +48,9 @@ function rule(severity) {
                                     line: 1,
                                     column: 1,
                                     severity: 'error',
+                                    code: 'EW1000',
+                                    category: 'correctness',
+                                    remedy: 'Fix the parser error or install the native compiler binary for this platform.',
                                     message: error instanceof Error ? error.message : String(error),
                                 },
                             ];
@@ -44,11 +58,16 @@ function rule(severity) {
                         cached.diagnostics.set(key, diagnostics);
                     }
                     for (const diagnostic of diagnostics) {
-                        if (diagnostic.severity !== severity)
+                        const selected = category === 'unprovable-dependency'
+                            ? diagnostic.code === 'EW2002' || diagnostic.code === 'EW1000'
+                            : category === 'errors'
+                                ? diagnostic.severity === 'error'
+                                : diagnostic.category === category;
+                        if (!selected)
                             continue;
                         context.report({
                             loc: { line: diagnostic.line, column: diagnostic.column - 1 },
-                            message: diagnostic.message,
+                            message: `[${diagnostic.code}] ${diagnostic.message}`,
                         });
                     }
                 },
@@ -58,5 +77,9 @@ function rule(severity) {
 }
 export default {
     meta: { name: 'effectweb' },
-    rules: { 'valid-view': rule('error'), 'whole-model-dependency': rule('warning') },
+    rules: {
+        'valid-view': rule('errors'),
+        'whole-model-dependency': rule('performance'),
+        'query-key': rule('unprovable-dependency'),
+    },
 };

package/dist/vite.js

@@ -1,4 +1,5 @@
 import { compile } from './compile.js';
+import { isCompilerFile } from './files.js';
 export function effectweb(options = {}) {
     let development = false;
     return {
@@ -15,13 +16,13 @@ export function effectweb(options = {}) {
         enforce: 'pre',
         transform(code, id) {
             const filename = id.split('?')[0];
-            if (!filename?.endsWith('.tsx'))
+            if (!filename || !isCompilerFile(filename))
                 return;
             const result = compile(code, filename, {
                 ...options,
                 development,
                 onDiagnostic: options.onDiagnostic ??
-                    ((diagnostic) => this.warn(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} ${diagnostic.message}`)),
+                    ((diagnostic) => this.warn(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.code}] ${diagnostic.message}`)),
             });
             return { code: result.code, map: result.map };
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectweb/compiler",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Native Oxc compiler and Vite plugin for effectweb",
   "homepage": "https://github.com/DerpyCrabs/EffectWeb",
   "bugs": {
@@ -46,11 +46,11 @@
     }
   },
   "optionalDependencies": {
-    "@effectweb/compiler-darwin-arm64": "0.2.3",
-    "@effectweb/compiler-darwin-x64": "0.2.3",
-    "@effectweb/compiler-linux-arm64-gnu": "0.2.3",
-    "@effectweb/compiler-linux-x64-gnu": "0.2.3",
-    "@effectweb/compiler-win32-x64-msvc": "0.2.3"
+    "@effectweb/compiler-darwin-arm64": "0.3.1",
+    "@effectweb/compiler-darwin-x64": "0.3.1",
+    "@effectweb/compiler-linux-arm64-gnu": "0.3.1",
+    "@effectweb/compiler-linux-x64-gnu": "0.3.1",
+    "@effectweb/compiler-win32-x64-msvc": "0.3.1"
   },
   "engines": {
     "node": ">=22.14"