@velarscript/web 0.28.1 → 0.29.0

package/dist/analyzer.js

@@ -1,5 +1,5 @@
 import { mechanicalEdits, mechanicalFix, semanticTypeIdentity } from "@velarscript/compiler";
-import { Analyzer, anyType, boolType, describeType, expressionContainsDirectAwait, invalidType, isInvalidType, isAssignable, isReadonlyView, mutatingCollectionMethods, nullType, nonOptional, numberType, optionalOf, spanIdentity, stringType, unknownType, } from "@velarscript/compiler/extension";
+import { Analyzer, anyType, boolType, describeType, expressionContainsDirectAwait, invalidType, isInvalidType, isAssignable, isReadonlyView, nullType, nonOptional, numberType, optionalOf, spanIdentity, stringType, unknownType, } from "@velarscript/compiler/extension";
 import { BROWSER_TEST_MODULE, BROWSER_TEST_SOURCE_SUFFIX, browserTestImportGuidance } from "./browser-test.js";
 import { cssTokens } from "./css-tokens.js";
 import { LOOK_ABSENT_MEDIA_SUBJECTS, LOOK_ARITHMETIC_HINT, LOOK_ANIMATION_DIRECTIONS, LOOK_ANIMATION_EASINGS, LOOK_ANIMATION_FILLS, LOOK_BORDER_STYLE_NAMES, LOOK_BUILDER_NUMERIC_RANGES, LOOK_BUILDER_SIGNATURES, LOOK_BUILDERS, LOOK_EXCLUDED_PROPERTIES, LOOK_HOOKS, LOOK_CSS_WIDE_KEYWORDS, LOOK_COLOR_KEYWORDS, LOOK_LARGE_KEYWORD_SETS, LOOK_LENGTH_BUILDERS, LOOK_MEDIA_LENGTH_UNITS, LOOK_MEDIA_SUBJECTS, LOOK_NUMERIC_TYPE_NAMES, LOOK_NON_ANIMATABLE_PROPERTIES, LOOK_PARTIAL_KEYWORD_PROPERTIES, LOOK_PROPERTIES, LOOK_PROPERTY_KEYWORDS, LOOK_PROPERTY_VALUE_KINDS, LOOK_SHARED_METRIC_KEYWORDS, LOOK_TARGETS, LOOK_TOKEN_NAME_RULE, LOOK_TOKEN_NO_FALLBACK_GUIDANCE, LOOK_UNIT_TYPES, LOOK_UNITLESS_PROPERTIES, isLookTokenName, isLookVarReference, lookOwnKeywords, lookShorthandOverlap, lookShorthandParts, lookTokenReference, lookVarReferenceName, nearestLookName, } from "./look.js";
@@ -10,6 +10,7 @@ import { dynamicChildLeaves, JSX_SCALAR_TEXT_HINT } from "./emitter.js";
 import { isWebCustomElementName, WEB_ARIA_ATTRIBUTES, WEB_ARIA_ENUMERATED_VALUES, WEB_ARIA_ROLES, WEB_ARIA_ROLE_SYNONYMS, WEB_BOOL_PRESENCE_HTML_ATTRIBUTES, WEB_HTML_ELEMENTS, WEB_MISSPELLED_ATTRIBUTES, WEB_NATIVE_ELEMENTS, } from "./elements.js";
 import { isWebExpression, isWebJsx, isWebKeyframes, isWebLook, isWebStatement, isWebUnit, } from "./ast.js";
 import { isWebComponentConstructor, isWebComponentType, isWebComputedExport, isWebNodeType, normalizeWebComponentType, webComponentConstructor, webComponentHandle, webComponentIntrinsic, webComponentName, webNodeType, WEB_EVENT_TYPE_NAMES, WEB_OWNED_TYPE_NAMES, } from "./types.js";
+import { collectionMutators, collectReactiveWriters, reactivePathOf, reactivePathRoot, reactiveStepsBelow, reactiveWriteCandidate, statementBindsName, topLevelCall, writerWritesPath, } from "./analysis/watch-cycles.js";
 // The canonical nominal identity of the Web RouteContext record. Route checks
 // probe with this identity so they succeed in modules that use route() without
 // importing RouteContext by name.
@@ -1181,169 +1182,6 @@ function watchSubjectPath(expression) {
             return false;
     }
 }
-/**
- * D114 W: a reactive place written as one comparable key, so "the write and the
- * subject name the same place" is one string equality.
- *
- * It is deliberately narrower than `renderWatchSubject`, which reconstructs any
- * expression for a message. A key has to *decide*, so only the parts that name
- * the same place on two evaluations are allowed into one: names, fields, and an
- * index that is either a literal or another such path. `items[next()]` renders
- * perfectly well and answers a different element every call, so it has no key
- * and the shapes below stay silent on it — which is the right answer for a
- * refusal that has to be right every time.
- */
-function reactiveWritePath(expression) {
-    switch (expression.kind) {
-        case "IdentifierExpression":
-            return expression.name;
-        case "MemberExpression": {
-            if (expression.optional)
-                return null;
-            const object = reactiveWritePath(expression.object);
-            return object === null ? null : `${object}.${expression.property}`;
-        }
-        case "IndexExpression": {
-            if (expression.optional)
-                return null;
-            const object = reactiveWritePath(expression.object);
-            if (object === null)
-                return null;
-            const index = expression.index.kind === "LiteralExpression"
-                ? (typeof expression.index.value === "string" ? JSON.stringify(expression.index.value) : expression.index.raw)
-                : reactiveWritePath(expression.index);
-            return index === null ? null : `${object}[${index}]`;
-        }
-        default:
-            return null;
-    }
-}
-/** The root name a reactive path starts from, which is the binding it resolves through. */
-function reactivePathRoot(expression) {
-    switch (expression.kind) {
-        case "IdentifierExpression":
-            return expression.name;
-        case "MemberExpression":
-        case "IndexExpression":
-            return reactivePathRoot(expression.object);
-        default:
-            return null;
-    }
-}
-function bindingPatternBinds(pattern, name) {
-    switch (pattern.kind) {
-        case "NameBindingPattern":
-            return pattern.name === name;
-        case "ObjectBindingPattern":
-            return pattern.rest?.name === name || pattern.entries.some((entry) => bindingPatternBinds(entry.pattern, name));
-        case "ListBindingPattern":
-            return pattern.rest?.name === name
-                || pattern.elements.some((element) => element !== null && bindingPatternBinds(element, name));
-        default:
-            return false;
-    }
-}
-/**
- * D114 W: whether a body statement introduces its own binding of `name`. From
- * that statement on, the spelling names something else, and a write through it
- * is not a write of the watched place. The scan stops there rather than
- * guessing which of the two a later line meant.
- */
-function statementBindsName(statement, name) {
-    switch (statement.kind) {
-        case "VariableDeclaration":
-            return bindingPatternBinds(statement.pattern, name);
-        case "UsingDeclaration":
-        case "FunctionDeclaration":
-        case "ClassDeclaration":
-            return statement.name === name;
-        default:
-            return false;
-    }
-}
-/**
- * D114 W: the call a body statement makes when the statement is nothing but
- * that call. `detach` is included because it is how a synchronous watch body
- * starts asynchronous work — the tour and four charter fences spell the reload
- * that way — so a refusal that only saw the bare call would miss the shape it
- * exists for. Everything else (a call inside an `if`, an argument, an assigned
- * result) is not a plain top-level call and is not offered here.
- */
-function topLevelCall(statement) {
-    const expression = statement.kind === "ExpressionStatement" ? statement.expression
-        : statement.kind === "DetachStatement" ? statement.expression
-            : null;
-    return expression !== null && expression.kind === "CallExpression" ? expression : null;
-}
-/**
- * D114 W: whether one plain body statement writes the reactive place `path`.
- * An assignment or a compound assignment to it is one; so is a call of a
- * mutating collection method on it, because a watch on a collection fires on
- * its deep mutation and `mutating` is the compiler's own roster of the calls
- * that mutate.
- */
-function reactiveWriteOf(statement, path, mutating) {
-    if (statement.kind === "AssignmentStatement")
-        return reactiveWritePath(statement.target) === path;
-    if (mutating === null)
-        return false;
-    const call = statement.kind === "ExpressionStatement" && statement.expression.kind === "CallExpression"
-        ? statement.expression
-        : null;
-    if (call === null || call.callee.kind !== "MemberExpression" || call.callee.optional)
-        return false;
-    return mutating.has(call.callee.property) && reactiveWritePath(call.callee.object) === path;
-}
-/**
- * D114 W A2(b): whether an `action` or `async def` writes `path` at its own top
- * level, unconditionally. One hop: what the callee itself calls is not
- * followed. A parameter of the callee's own that is spelled like the path's
- * root, or a binding it declares before the write, means the write is not of
- * the watched place and the answer is no.
- */
-function writerWritesPath(writer, path, root, mutating) {
-    if (writer.parameters.includes(root))
-        return false;
-    for (const statement of writer.body) {
-        if (statementBindsName(statement, root))
-            return false;
-        if (reactiveWriteOf(statement, path, mutating))
-            return true;
-    }
-    return false;
-}
-function collectReactiveWriters(program) {
-    const writers = new Map();
-    const claim = (name, declaration) => {
-        writers.set(name, writers.has(name) ? null : declaration);
-    };
-    const record = (statements) => {
-        for (const statement of statements) {
-            if (statement.kind === "FunctionDeclaration") {
-                claim(statement.name, statement.asynchronous
-                    ? { spelling: "async def", parameters: statement.parameters.map((parameter) => parameter.name), body: statement.body }
-                    : null);
-                record(statement.body);
-                continue;
-            }
-            if (!isWebStatement(statement))
-                continue;
-            if (statement.kind === "ExtensionStatement:web:action") {
-                claim(statement.name, {
-                    spelling: "action",
-                    parameters: statement.parameters.map((parameter) => parameter.name),
-                    body: statement.body,
-                });
-                record(statement.body);
-                continue;
-            }
-            if (statement.kind === "ExtensionStatement:web:component")
-                record(statement.body);
-        }
-    };
-    record(program.body);
-    return writers;
-}
 /** The escapes a text literal carries back into source (`scanStringEscape`). */
 const WATCH_SUBJECT_TEXT_ESCAPES = {
     "\\": "\\\\",
@@ -2034,11 +1872,19 @@ export class VelarWebAnalyzer extends Analyzer {
      * `builtinTypeNameDeclarationMessage` in packages/compiler/src/analyzer.ts,
      * reported as VEL3007. The rosters differ; the wording is meant to read
      * alike, so a change to either sentence belongs in both.
+     *
+     * `Duration` is on both rosters — Core owns it as a primitive and
+     * `velar/look` republishes it — so a Web module used to report it twice. This
+     * refusal is the more specific of the two, because it names the surface the
+     * author is writing against, so it marks the name refused and Core's stays
+     * unsaid. The mark is Core's own hook, which is what lets this pass take
+     * precedence without either side learning the other's roster.
      */
     rejectWebOwnedTypeNames(program) {
         const reject = (name, errorSpan, noun) => {
             if (!WEB_OWNED_TYPE_NAMES.has(name))
                 return;
+            this.markTypeNameRefused(name);
             this.diagnostics.push(diagnostic("VEL5065", `'${name}' is a Web type name, so it cannot also name ${/^[aeiou]/iu.test(noun) ? "an" : "a"} ${noun}; every use of it in a Web module resolves to the built-in. Rename this declaration`, errorSpan));
         };
         for (const statement of program.body) {
@@ -2659,12 +2505,8 @@ export class VelarWebAnalyzer extends Analyzer {
         const root = reactivePathRoot(subject);
         if (root === null)
             return;
-        const path = reactiveWritePath(subject);
-        const collection = nonOptional(this.expandAliases(watched));
-        const mutating = collection.kind === "list" || collection.kind === "map"
-            || collection.kind === "set" || collection.kind === "record"
-            ? mutatingCollectionMethods(collection.kind)
-            : null;
+        const place = reactivePathOf(subject);
+        const writes = (steps, method) => this.watchSubjectWrite(watched, steps, method);
         // A resource publishes `value`, `loading`, `ready` and `error`, and
         // `reload` is the one member of the five that is not one of them. Asking it
         // that way keeps `analyzeResourceDeclaration`'s field map the only roster:
@@ -2677,14 +2519,9 @@ export class VelarWebAnalyzer extends Analyzer {
         for (const statement of body) {
             if (statementBindsName(statement, root))
                 return;
-            if (path !== null && reactiveWriteOf(statement, path, mutating)) {
-                // A derived value is offered only where it could be declared. A field
-                // or an element has no `computed` spelling of its own, so naming one
-                // would hand the author a line that does not compile.
-                const derived = subject.kind === "IdentifierExpression"
-                    ? `declare 'computed ${path} = ...' instead`
-                    : "write this value where it is produced instead";
-                this.diagnostics.push(diagnostic("VEL5077", `This watch writes its own subject '${path}' at the top of its body, so every run re-triggers it and the runtime stops the loop after 100 rounds; write the condition that ends it, or watch the input this value follows and ${derived}`, statement.span));
+            const selfWrite = place === null ? null : this.watchSelfWrite(subject, place, statement, writes);
+            if (selfWrite !== null) {
+                this.diagnostics.push(diagnostic("VEL5077", selfWrite, statement.span));
                 return;
             }
             const call = topLevelCall(statement);
@@ -2696,15 +2533,104 @@ export class VelarWebAnalyzer extends Analyzer {
                 this.diagnostics.push(diagnostic("VEL5078", `This watch reloads '${resource}' — the resource it watches — so every completed load re-triggers it; watch the input the load reads instead, as 'watch userId:' with 'detach ${resource}.reload()' in its body`, call.span));
                 return;
             }
-            if (path === null || call.callee.kind !== "IdentifierExpression")
+            if (place === null || call.callee.kind !== "IdentifierExpression")
                 continue;
             const writer = this.reactiveWriters.get(call.callee.name) ?? null;
-            if (writer === null || !writerWritesPath(writer, path, root, mutating))
+            const written = writer === null ? null : writerWritesPath(writer, place, writes);
+            if (written === null)
                 continue;
-            this.diagnostics.push(diagnostic("VEL5079", `This watch starts '${call.callee.name}', which writes '${path}' — the reactive value this watch is on — so each completed run re-triggers the watch; make the write conditional, or watch the input '${call.callee.name}' reads`, call.span));
+            // D114 0.28.0 H-D1's other half, in the message family F1 gave VEL5077:
+            // a writer that reaches a *part* of the subject names the part it wrote
+            // and the subject it belongs to, because those are two different places
+            // and the author has to find the one the helper touches.
+            const reached = written.text === place.text
+                ? `'${place.text}' — the reactive value this watch is on`
+                : `'${written.text}', a part of its subject '${place.text}'`;
+            this.diagnostics.push(diagnostic("VEL5079", `This watch starts '${call.callee.name}', which writes ${reached} — so each completed run re-triggers the watch; make the write conditional, or watch the input '${call.callee.name}' reads`, call.span));
             return;
         }
     }
+    /**
+     * D114 0.28.0 H-D1: the VEL5077 message one plain body statement earns, or
+     * null when it earns none.
+     *
+     * §15 says a watch fires on a *deep* change of its subject, so `watch form:
+     * form.name = …` and `watch items: items[0].done = …` are the same ring
+     * `items.append(…)` already is — decided at the top of the body, with no
+     * condition to end it — and were silent until the runtime's 100-round cap
+     * stopped them. The rule is therefore stated on the path rather than on the
+     * spelling: a write whose place is the subject, or any place below it, in an
+     * assignment, a compound assignment, or a mutating call.
+     *
+     * Every existing exclusion stands, because each is answered somewhere else: a
+     * conditional or nested write is not a plain body statement, a rebinding
+     * stops the scan in `rejectWatchCycle`, and a sibling path (`watch form.name:`
+     * writing `form.email`) or a different root fails the step comparison here.
+     */
+    watchSelfWrite(subject, place, statement, writes) {
+        const write = reactiveWriteCandidate(statement);
+        if (write === null)
+            return null;
+        const steps = reactiveStepsBelow(place, write.place);
+        if (steps === null || !writes(steps, write.method))
+            return null;
+        // A derived value is offered only where it could be declared. A field
+        // or an element has no `computed` spelling of its own, so naming one
+        // would hand the author a line that does not compile.
+        const derived = subject.kind === "IdentifierExpression"
+            ? `declare 'computed ${place.text} = ...' instead`
+            : "write this value where it is produced instead";
+        const head = steps.length === 0
+            ? `This watch writes its own subject '${place.text}'`
+            : `This watch writes '${write.place.text}', a part of its subject '${place.text}',`;
+        return `${head} at the top of its body, so every run re-triggers it and the runtime stops the loop after 100`
+            + ` rounds; write the condition that ends it, or watch the input this value follows and ${derived}`;
+    }
+    /**
+     * D114 0.28.0 H-D1: the type of the place `steps` below the watched subject,
+     * or null when the walk cannot reach one.
+     *
+     * Only the steps the reactive graph publishes as part of the subject are
+     * walked — a record field and a collection element — because those are the
+     * writes a watch on the containing value is woken by. A step that leaves them
+     * (a class instance, a capability handle, a field the record does not declare)
+     * is not provably part of the subject, and a refusal that must be right every
+     * time answers no there rather than guessing.
+     */
+    /**
+     * Whether a write `steps` below the watched subject, made the given way, is a
+     * write of the subject — the one definition both the body scan (VEL5077) and
+     * the one-hop writer scan (VEL5079) read. An assignment to a place the walk
+     * can reach is a write; a call is one only when the type at that depth is a
+     * collection and the call is on its own mutating roster.
+     */
+    watchSubjectWrite(watched, steps, method) {
+        const written = this.reactivePlaceType(watched, steps);
+        if (written === null)
+            return false;
+        if (method === null)
+            return true;
+        const mutating = collectionMutators(nonOptional(this.expandAliases(written)));
+        return mutating !== null && mutating.has(method);
+    }
+    reactivePlaceType(subject, steps) {
+        let current = subject;
+        for (const step of steps) {
+            const owner = nonOptional(this.expandAliases(current));
+            const next = step.kind === "field"
+                ? (owner.kind === "object" ? owner.fields.get(step.name) ?? null
+                    : owner.kind === "record" ? owner.value
+                        : owner.kind === "named" ? this.fieldsOf(owner.identity ?? owner.name)?.get(step.name) ?? null
+                            : null)
+                : (owner.kind === "list" || owner.kind === "set" ? owner.element
+                    : owner.kind === "map" || owner.kind === "record" ? owner.value
+                        : null);
+            if (next === null)
+                return null;
+            current = next;
+        }
+        return current;
+    }
     /**
      * D89 A4: records `list = list.map(item => {…})`, React's immutable update,
      * where the callback builds a new record rather than changing a field.