@webjsdev/server 0.8.31 → 0.8.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.31",
+  "version": "0.8.33",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/check.js

@@ -5,6 +5,7 @@ import {
   redactStringsAndTemplates,
   extractWebComponentClassBodies,
   matchClosingBrace,
+  parsePropEntries,
 } from './js-scan.js';
 import { buildModuleGraph, transitiveDeps } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
@@ -74,9 +75,19 @@ export const RULES = [
       'A custom-element tag name must be registered exactly once across the app. Two `Class.register(\'tag\')` / `customElements.define(\'tag\', …)` calls for the SAME tag resolve INCONSISTENTLY at runtime: SSR overwrites the registry (last registration wins) while the browser keeps the first native upgrade, so the rendered element and the webjs registry disagree. Rename one tag.',
   },
   {
-    name: 'reactive-props-use-declare',
+    name: 'no-static-properties',
     description:
-      'Reactive properties listed in `static properties = { … }` must be typed with `declare propName: Type` (no value), and have their default set in `constructor()`. Plain class-field initializers (`prop = value` or `prop: Type = value`) compile to Object.defineProperty *after* super() under modern class-field semantics, clobbering the framework\'s reactive accessor and silently breaking re-renders.',
+      'Reactive properties must be declared via the `extends WebComponent({ … })` factory, never a hand-written `static properties = { … }` field in the class body. The factory types each field for you (no `declare` needed) and the runtime throws on a direct `static properties`. Migrate `class X extends WebComponent { static properties = { count: { type: Number } } }` to `class X extends WebComponent({ count: Number })`; use the `prop()` helper for options (`prop(Number, { reflect: true })`) and set defaults via the `default` option or in the constructor.',
+  },
+  {
+    name: 'reactive-props-no-class-field',
+    description:
+      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field initializer (`count = 0` or `count: number = 0`) in the class body. Under modern class-field semantics that initializer runs Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default via the `default` property option (`prop(Number, { default: 0 })`) or by assigning in the constructor after super().',
+  },
+  {
+    name: 'array-prop-uses-array-type',
+    description:
+      'An array-typed reactive property declared via the `extends WebComponent({ … })` factory must pass the `Array` runtime constructor, not `Object`: `count: prop<Tag[]>(Array)`, never `prop<Tag[]>(Object)`. The two share one converter (both JSON-encode the value), so the wrong one does not crash, but `Object` misstates the prop contract to the next reader and diverges from the documented built-in set (String/Number/Boolean/Object/Array). Fires only when the factory generic is itself an array type (`T[]`, `readonly T[]`, `Array<T>`, `ReadonlyArray<T>`) AND the constructor argument is `Object`; a bare `foo: Object` with no generic is never flagged. Fix: change the constructor to `Array`.',
   },
   {
     name: 'shell-in-non-root-layout',
@@ -166,58 +177,6 @@ function isComponentFile(relPath) {
   return segments.includes('components');
 }
 
-/**
- * Find every `<key>:` entry inside the first `static properties = { … }`
- * literal in `classBody`. Returns the bare property names: the keys
- * we'll then look up as class fields.
- *
- * @param {string} classBody
- * @returns {Set<string>}
- */
-function extractStaticPropertyNames(classBody) {
-  /** @type {Set<string>} */
-  const names = new Set();
-  const m = /static\s+properties\s*=\s*\{/.exec(classBody);
-  if (!m) return names;
-  const objStart = m.index + m[0].length;
-  const objEnd = matchClosingBrace(classBody, objStart);
-  if (objEnd === -1) return names;
-  const obj = classBody.slice(objStart, objEnd);
-  // Match keys at the top level of the object literal. A nested `{ … }`
-  // (the per-property declaration) is skipped via brace counting.
-  let i = 0;
-  while (i < obj.length) {
-    // Skip whitespace and commas.
-    while (i < obj.length && /[\s,]/.test(obj[i])) i++;
-    if (i >= obj.length) break;
-    // Read the identifier or string-literal key.
-    let key = '';
-    if (obj[i] === '"' || obj[i] === "'") {
-      const quote = obj[i++];
-      while (i < obj.length && obj[i] !== quote) { key += obj[i++]; }
-      i++; // closing quote
-    } else {
-      while (i < obj.length && /[A-Za-z0-9_$]/.test(obj[i])) key += obj[i++];
-    }
-    // Skip whitespace, then expect `:`.
-    while (i < obj.length && /\s/.test(obj[i])) i++;
-    if (obj[i] !== ':') break;
-    i++;
-    // Skip whitespace, then skip the value (either a `{ … }` literal or
-    // a single token like `String`).
-    while (i < obj.length && /\s/.test(obj[i])) i++;
-    if (obj[i] === '{') {
-      const valEnd = matchClosingBrace(obj, i + 1);
-      if (valEnd === -1) break;
-      i = valEnd + 1;
-    } else {
-      while (i < obj.length && obj[i] !== ',' && obj[i] !== '}') i++;
-    }
-    if (key) names.add(key);
-  }
-  return names;
-}
-
 /**
  * Scan a class body for class-field initializers naming any of `props`.
  * "Class-field" means: at the top of the class body (brace depth 0
@@ -231,6 +190,38 @@ function extractStaticPropertyNames(classBody) {
  * @param {Set<string>} props
  * @returns {string[]}
  */
+/**
+ * True when a factory prop value is an array-typed `prop<…>(…)` whose
+ * runtime constructor argument is `Object`. The generic and the
+ * constructor sit in the same call, so it is decidable from the value
+ * text alone. The match is greedy on the generic so a nested generic
+ * (`prop<Array<X>>(Object)`) closes at the outer `>` that precedes the
+ * `(Object` call. A bare constructor (`Object`, with no generic) or a
+ * non-array generic (`prop<Foo>(Object)`) returns false.
+ *
+ * @param {string} value the raw prop value text, e.g. `prop<Tag[]>(Object)`
+ * @returns {boolean}
+ */
+function arrayPropUsesObject(value) {
+  const m = /^prop\s*<([\s\S]*)>\s*\(\s*Object\s*[,)]/.exec(value.trim());
+  if (!m) return false;
+  return isArrayTypeText(m[1]);
+}
+
+/**
+ * True when a TypeScript type expression denotes an array: `T[]`,
+ * `readonly T[]`, `T[][]`, `Array<T>`, or `ReadonlyArray<T>`.
+ *
+ * @param {string} type
+ * @returns {boolean}
+ */
+function isArrayTypeText(type) {
+  const bare = type.trim().replace(/^readonly\s+/, '');
+  if (/\[\s*\]$/.test(bare)) return true;
+  if (/^(?:Readonly)?Array\s*<[\s\S]*>$/.test(bare)) return true;
+  return false;
+}
+
 function findFieldInitializers(classBody, props) {
   /** @type {string[]} */
   const out = [];
@@ -440,23 +431,78 @@ export async function checkConventions(appDir) {
     }
   }
 
-  // --- Rule: reactive-props-use-declare ---
+  // --- Rule: no-static-properties ---
+  // A hand-written `static properties = { … }` in a WebComponent class body is
+  // no longer supported: reactive properties are declared via the
+  // `extends WebComponent({ … })` factory (the runtime throws on a direct
+  // `static properties`). Flag it statically so the editor catches it before
+  // the page 500s.
   {
     for (const { rel, scan } of files) {
-      // Use redacted source so test-fixture-style strings like
-      // `class X extends WebComponent { x = 0 }` inside template
-      // literals don't trip the rule. Real declarations live at
+      // Use redacted source so fixture-style strings like
+      // `class X extends WebComponent { static properties = {…} }` inside
+      // template literals don't trip the rule. Real declarations live at
       // top-level code where the redactor leaves them alone.
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
-      for (const body of extractWebComponentClassBodies(scan)) {
-        const propNames = extractStaticPropertyNames(body);
-        if (propNames.size === 0) continue;
-        for (const bad of findFieldInitializers(body, propNames)) {
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        if (!/static\s+properties\s*=\s*\{/.test(body)) continue;
+        violations.push({
+          rule: 'no-static-properties',
+          file: rel,
+          message:
+            '`static properties = { … }` is no longer supported; declare reactive properties via the `extends WebComponent({ … })` factory instead.',
+          fix: 'Move the properties into the factory call: `class X extends WebComponent({ count: Number })`. Use `prop(Number, { reflect: true })` for options and set defaults via the `default` option or the constructor. Delete the `static properties` block and any `declare` fields for those props.',
+        });
+      }
+    }
+  }
+
+  // --- Rule: reactive-props-no-class-field ---
+  // A reactive property declared via the factory must not also carry a plain
+  // class-field initializer: it runs Object.defineProperty after super() and
+  // clobbers the framework's reactive accessor (silent broken re-renders).
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body, factoryProps } of extractWebComponentClassBodies(scan)) {
+        if (factoryProps.size === 0) continue;
+        for (const bad of findFieldInitializers(body, factoryProps)) {
           violations.push({
-            rule: 'reactive-props-use-declare',
+            rule: 'reactive-props-no-class-field',
             file: rel,
             message: `Reactive prop \`${bad}\` uses a class-field initializer; this clobbers the framework's reactive accessor under modern class-field semantics.`,
-            fix: `Replace with \`declare ${bad}: <Type>;\` and set the default inside \`constructor()\` after \`super()\`.`,
+            fix: `Remove the class-field initializer and set the default via the \`default\` option (\`prop(<Type>, { default: <value> })\`) or by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
+          });
+        }
+      }
+    }
+  }
+
+  // --- Rule: array-prop-uses-array-type ---
+  // An array-typed reactive prop declared via the factory should pass the
+  // `Array` runtime constructor, not `Object`. Both share one converter
+  // (JSON encode/decode), so `Object` does not crash, but it misstates the
+  // prop contract and diverges from the documented built-in set. Fires only
+  // when the factory generic is itself an array type AND the constructor is
+  // `Object`; a bare `foo: Object` (no generic to prove array-ness) is left
+  // alone to avoid false positives. Uses the redacted `scan`, so a
+  // `prop<X[]>(Object)` shown inside an html`` example string never fires.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { factoryArg } of extractWebComponentClassBodies(scan)) {
+        const objStart = factoryArg.indexOf('{');
+        if (objStart === -1) continue;
+        const objEnd = matchClosingBrace(factoryArg, objStart + 1);
+        if (objEnd === -1) continue;
+        const objContent = factoryArg.slice(objStart + 1, objEnd);
+        for (const { key, value } of parsePropEntries(objContent)) {
+          if (!arrayPropUsesObject(value)) continue;
+          violations.push({
+            rule: 'array-prop-uses-array-type',
+            file: rel,
+            message: `Array-typed reactive prop \`${key}\` is declared with the \`Object\` constructor (\`prop<…[]>(Object)\`); use \`Array\` so the runtime converter matches the declared shape.`,
+            fix: `Change the constructor to \`Array\`: \`${key}: prop<…[]>(Array)\`. Object and Array share one converter so behaviour is unchanged, but \`Array\` states the prop's shape correctly.`,
           });
         }
       }
@@ -473,7 +519,7 @@ export async function checkConventions(appDir) {
   {
     for (const { rel, scan } of files) {
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
-      for (const body of extractWebComponentClassBodies(scan)) {
+      for (const { body } of extractWebComponentClassBodies(scan)) {
         for (const method of ['constructor', 'willUpdate', 'render']) {
           const code = methodBodyOf(body, method);
           if (!code) continue;
@@ -661,7 +707,7 @@ export async function checkConventions(appDir) {
         // modifiers immediately followed by an identifier inside the
         // constructor's parameter list.
         regex: /constructor[ \t]*\([^)]*\b(?:public|private|protected|readonly)[ \t]+\w+/,
-        fix: 'Replace `constructor(public x: number)` with `x: number; constructor(x: number) { this.x = x; }`. The reactive-props-use-declare rule has the framework-specific shape: `declare x: number;` (no value) plus the assignment in the constructor body.',
+        fix: 'Replace `constructor(public x: number)` with `x: number; constructor(x: number) { this.x = x; }`.',
       },
       {
         name: 'import = require',