@effectweb/compiler 0.2.2 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 TeleVecha contributors
+Copyright (c) 2026 EffectWeb contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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. See the authoring guide for the readonly type contract, opaque values, and explicit test configuration.
+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,6 +4,9 @@ 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. */
@@ -17,7 +20,6 @@ export interface CompilerResult {
     readonly map: string | null;
     readonly diagnostics: readonly Diagnostic[];
 }
-/** JSX analysis and lowering run in Rust/Oxc; this boundary only transports options and results. */
 export declare function compile(source: string, filename: string, options?: CompilerOptions): CompilerResult;
 /** Run the same view analysis as compilation, collecting one error per invalid view. */
 export declare function diagnose(source: string, filename: string, options?: Omit<CompilerOptions, 'onDiagnostic'>): readonly Diagnostic[];

package/dist/compile.js

@@ -1,5 +1,4 @@
 import { compile as nativeCompile } from '../native.cjs';
-/** JSX analysis and lowering run in Rust/Oxc; this boundary only transports options and results. */
 export function compile(source, filename, options = {}) {
     const { onDiagnostic, ...nativeOptions } = { importSource: 'effectweb', ...options };
     const result = JSON.parse(nativeCompile(source, filename, JSON.stringify(nativeOptions)));

package/dist/oxlint.d.ts

@@ -54,6 +54,23 @@ declare const _default: {
                 Program(): void;
             };
         };
+        'query-key': {
+            meta: {
+                type: "problem" | "suggestion";
+                schema: {
+                    type: string;
+                    properties: {
+                        importSource: {
+                            type: string;
+                        };
+                    };
+                    additionalProperties: boolean;
+                }[];
+            };
+            create(context: Context): {
+                Program(): void;
+            };
+        };
     };
 };
 export default _default;

package/dist/oxlint.js

@@ -1,9 +1,9 @@
 import { diagnose } from './compile.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',
@@ -15,7 +15,7 @@ function rule(severity) {
         create(context) {
             return {
                 Program() {
-                    if (!context.filename.endsWith('.tsx'))
+                    if (!/\.tsx?$/u.test(context.filename) || context.filename.endsWith('.d.ts'))
                         return;
                     const importSource = context.options[0]?.importSource ?? 'effectweb';
                     let cached = results.get(context.sourceCode);
@@ -37,6 +37,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 +47,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 +66,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.d.ts

@@ -1,5 +1,4 @@
 import type { Plugin } from 'vite';
 import { type CompilerOptions } from './compile.js';
-/** Rust/Oxc lowers snapshot JSX before Vite's TypeScript pass. */
 export declare function effectweb(options?: CompilerOptions): Plugin;
 export default effectweb;

package/dist/vite.js

@@ -1,5 +1,4 @@
 import { compile } from './compile.js';
-/** Rust/Oxc lowers snapshot JSX before Vite's TypeScript pass. */
 export function effectweb(options = {}) {
     let development = false;
     return {
@@ -16,13 +15,13 @@ export function effectweb(options = {}) {
         enforce: 'pre',
         transform(code, id) {
             const filename = id.split('?')[0];
-            if (!filename?.endsWith('.tsx'))
+            if (!filename || !/\.tsx?$/u.test(filename) || filename.endsWith('.d.ts'))
                 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.2",
+  "version": "0.3.0",
   "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.2",
-    "@effectweb/compiler-darwin-x64": "0.2.2",
-    "@effectweb/compiler-linux-arm64-gnu": "0.2.2",
-    "@effectweb/compiler-linux-x64-gnu": "0.2.2",
-    "@effectweb/compiler-win32-x64-msvc": "0.2.2"
+    "@effectweb/compiler-darwin-arm64": "0.3.0",
+    "@effectweb/compiler-darwin-x64": "0.3.0",
+    "@effectweb/compiler-linux-arm64-gnu": "0.3.0",
+    "@effectweb/compiler-linux-x64-gnu": "0.3.0",
+    "@effectweb/compiler-win32-x64-msvc": "0.3.0"
   },
   "engines": {
     "node": ">=22.14"