@effectweb/compiler 0.3.0 → 0.4.0

package/README.md

@@ -11,28 +11,33 @@ export default defineConfig({ plugins: [effectweb()] });
 
 Install `effectweb` and its required Effect version in the application. Set TypeScript `jsx` to `preserve` and `jsxImportSource` to `effectweb`.
 
-For direct compilation, import `compile` from `@effectweb/compiler`; the result contains generated code, a source map, and diagnostics. The Vite plugin reports diagnostics and enables development instrumentation during serve.
+For direct compilation, import `compile` from `@effectweb/compiler`; the result contains generated code, a source map, and diagnostics. The Vite plugin reports syntax diagnostics and enables development instrumentation during serve.
+
+The compiler lowers JSX syntax. Calls, callbacks, local variables, control flow, and JSX helpers retain ordinary JavaScript behavior. `view` is an executable runtime function; the compiler does not prove render purity, infer model dependencies, memoize helpers, or reinterpret `.map` as keyed rendering. Use the runtime's explicit `list(rows, render)` operation for keyed lists.
+
+Files opt in by importing `effectweb` or one of its subpaths, or by declaring `/** @jsxImportSource effectweb */`. A different `@jsxImportSource` pragma leaves the file to its chosen JSX runtime. `compile` returns other files unchanged. `importSource` and `runtimeModule` options customize these module names. The package also supports the standard automatic JSX transform through `effectweb/jsx-runtime`; the native compiler adds source metadata in development.
 
 Requires Node.js 22.14+. Optional packages provide binaries for glibc Linux x64/arm64, macOS x64/arm64, and Windows x64. Keep optional dependencies enabled. Installation does not compile Rust. Framework contributors build from source using Rust 1.96+.
 
 See [EffectWeb](https://github.com/DerpyCrabs/EffectWeb) for authoring and development instructions.
 
-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.
+For editor and CI diagnostics, add `@effectweb/compiler/oxlint` to Oxlint's `jsPlugins`. `effectweb/valid-view` checks supported JSX syntax, and `diagnose` exposes the same structured diagnostics without emitting code. Parser failures throw.
 
-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.
+`effectweb/render-safety` is an optional heuristic lint rule for suspicious render work and captures. The separate `lint` API exposes these checks. They never participate in compilation or change generated code, and they are not a proof of purity. The former `whole-model-dependency` rule and collection-identity inference have been removed.
+
+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. Development instrumentation labels actual text and attribute expressions and their evaluated values; production builds omit that metadata. It does not derive model-field dependency paths.
 
 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.                                                                              |
+| Code   | Category              | Meaning and remedy                                                                                                                                                 |
+| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| EW1000 | correctness           | Lint could not parse the file or load the native compiler. Fix syntax or installation.                                                                             |
+| EW1001 | correctness           | Unsupported intrinsic JSX syntax, such as `key`, `ref`, or `innerHTML`. Use explicit lists or owned DOM bindings.                                                  |
+| EW1003 | correctness           | Optional render-safety lint found potentially impure work. Review it and move side effects into owned work.                                                        |
+| EW2001 | unprovable-dependency | Optional render-safety lint found a potentially mutable capture. Review its ownership; compilation itself accepts ordinary JavaScript captures.                    |
+| EW2002 | unprovable-dependency | Query-key lint found a custom `key`. Remove it; every request argument participates in cache identity. The public query types and runtime also reject custom keys. |
 
-`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:
+`effectweb/query-key` recognizes imported `query` definitions, including aliases and `effectweb/query`, with literal custom keys. Types and the runtime cover definitions assembled outside that lint analysis. Supply service instances through the Effect environment. For example:
 
 ```json
 {
@@ -40,11 +45,9 @@ Diagnostics include `code`, `category`, `severity`, source `file`/`line`/`column
   "rules": {
     "effectweb/valid-view": "error",
     "effectweb/query-key": "error",
-    "effectweb/whole-model-dependency": "warn"
+    "effectweb/render-safety": "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.
+Remove `effectweb/render-safety` when heuristic advice is not wanted. TypeScript checks props, snapshots, and Effect service/error contracts; the compiler does not load or check the consumer's TypeScript project. See the [0.4.0 migration guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/migration-0.4.0.md) for list and lifecycle changes.

package/dist/compile.d.ts

@@ -21,5 +21,8 @@ export interface CompilerResult {
     readonly diagnostics: readonly Diagnostic[];
 }
 export declare function compile(source: string, filename: string, options?: CompilerOptions): CompilerResult;
-/** Run the same view analysis as compilation, collecting one error per invalid view. */
+/** Collect compiler syntax diagnostics without emitting code. */
 export declare function diagnose(source: string, filename: string, options?: Omit<CompilerOptions, 'onDiagnostic'>): readonly Diagnostic[];
+export type LintOptions = Pick<CompilerOptions, 'importSource'>;
+/** Optional heuristic lint checks. These never participate in compilation. */
+export declare function lint(source: string, filename: string, options?: LintOptions): readonly Diagnostic[];

package/dist/compile.js

@@ -6,12 +6,20 @@ export function compile(source, filename, options = {}) {
         onDiagnostic?.(diagnostic);
     return result;
 }
-/** Run the same view analysis as compilation, collecting one error per invalid view. */
+/** Collect compiler syntax diagnostics without emitting code. */
 export function diagnose(source, filename, options = {}) {
+    return diagnostics(source, filename, options, false);
+}
+/** Optional heuristic lint checks. These never participate in compilation. */
+export function lint(source, filename, options = {}) {
+    return diagnostics(source, filename, options, true);
+}
+function diagnostics(source, filename, options, lint) {
     return JSON.parse(nativeCompile(source, filename, JSON.stringify({
         importSource: 'effectweb',
         ...options,
         development: true,
         diagnosticsOnly: true,
+        lint,
     }))).diagnostics;
 }

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/index.d.ts

@@ -1 +1 @@
-export { compile, diagnose, type CompilerOptions, type CompilerResult, type Diagnostic, } from './compile.js';
+export { compile, diagnose, lint, type LintOptions, type CompilerOptions, type CompilerResult, type Diagnostic, } from './compile.js';

package/dist/index.js

@@ -1 +1 @@
-export { compile, diagnose, } from './compile.js';
+export { compile, diagnose, lint, } from './compile.js';

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'>[];
     report: (diagnostic: {
         loc: {
             line: number;
@@ -37,7 +36,7 @@ declare const _default: {
                 Program(): void;
             };
         };
-        'whole-model-dependency': {
+        'render-safety': {
             meta: {
                 type: "problem" | "suggestion";
                 schema: {

package/dist/oxlint.js

@@ -1,4 +1,5 @@
-import { diagnose } from './compile.js';
+import { diagnose, lint } from './compile.js';
+import { isCompilerFile } from './files.js';
 const results = new WeakMap();
 function rule(category) {
     return {
@@ -15,7 +16,7 @@ function rule(category) {
         create(context) {
             return {
                 Program() {
-                    if (!/\.tsx?$/u.test(context.filename) || context.filename.endsWith('.d.ts'))
+                    if (!isCompilerFile(context.filename))
                         return;
                     const importSource = context.options[0]?.importSource ?? 'effectweb';
                     let cached = results.get(context.sourceCode);
@@ -23,11 +24,12 @@ function rule(category) {
                         cached = { text: context.sourceCode.text, diagnostics: new Map() };
                         results.set(context.sourceCode, cached);
                     }
-                    const key = `${context.filename}\0${importSource}`;
+                    const heuristic = category === 'render-safety' || category === 'unprovable-dependency';
+                    const key = `${context.filename}\0${importSource}\0${heuristic}`;
                     let diagnostics = cached.diagnostics.get(key);
                     if (!diagnostics) {
                         try {
-                            diagnostics = diagnose(context.sourceCode.text, context.filename, { importSource });
+                            diagnostics = (heuristic ? lint : diagnose)(context.sourceCode.text, context.filename, { importSource });
                         }
                         catch (error) {
                             // Parser failures and unavailable native binaries must not silently pass lint.
@@ -47,11 +49,13 @@ function rule(category) {
                         cached.diagnostics.set(key, diagnostics);
                     }
                     for (const diagnostic of diagnostics) {
-                        const selected = category === 'unprovable-dependency'
-                            ? diagnostic.code === 'EW2002' || diagnostic.code === 'EW1000'
-                            : category === 'errors'
-                                ? diagnostic.severity === 'error'
-                                : diagnostic.category === category;
+                        const selected = category === 'render-safety'
+                            ? ['EW1000', 'EW1003', 'EW2001'].includes(diagnostic.code)
+                            : category === 'unprovable-dependency'
+                                ? diagnostic.code === 'EW2002' || diagnostic.code === 'EW1000'
+                                : category === 'errors'
+                                    ? diagnostic.severity === 'error'
+                                    : diagnostic.category === category;
                         if (!selected)
                             continue;
                         context.report({
@@ -68,7 +72,7 @@ export default {
     meta: { name: 'effectweb' },
     rules: {
         'valid-view': rule('errors'),
-        'whole-model-dependency': rule('performance'),
+        'render-safety': rule('render-safety'),
         'query-key': rule('unprovable-dependency'),
     },
 };

package/dist/vite.js

@@ -1,11 +1,13 @@
 import { compile } from './compile.js';
+import { isCompilerFile } from './files.js';
 export function effectweb(options = {}) {
     let development = false;
     return {
         config(_config, environment) {
             return {
                 define: { __EFFECTWEB_DEV__: JSON.stringify(environment.command === 'serve') },
-                resolve: { dedupe: ['effect'] },
+                resolve: { dedupe: ['effect', 'effectweb'] },
+                optimizeDeps: { exclude: ['effectweb'] },
             };
         },
         configResolved(config) {
@@ -15,7 +17,7 @@ export function effectweb(options = {}) {
         enforce: 'pre',
         transform(code, id) {
             const filename = id.split('?')[0];
-            if (!filename || !/\.tsx?$/u.test(filename) || filename.endsWith('.d.ts'))
+            if (!filename || !isCompilerFile(filename))
                 return;
             const result = compile(code, filename, {
                 ...options,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectweb/compiler",
-  "version": "0.3.0",
+  "version": "0.4.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.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"
+    "@effectweb/compiler-darwin-arm64": "0.4.0",
+    "@effectweb/compiler-darwin-x64": "0.4.0",
+    "@effectweb/compiler-linux-arm64-gnu": "0.4.0",
+    "@effectweb/compiler-linux-x64-gnu": "0.4.0",
+    "@effectweb/compiler-win32-x64-msvc": "0.4.0"
   },
   "engines": {
     "node": ">=22.14"