@velarscript/web 0.28.1 → 0.29.1

package/dist/analyzer.js

@@ -1,15 +1,19 @@
 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";
 import { collectLookStaticValues, evaluateLookStaticExpression, isLookStaticValue, lookStaticCss } from "./look-static.js";
 import { keyframeCssValue } from "./keyframes.js";
+import { componentCallRefusal, componentRefHandleRefusal, componentSectionCountDiagnostics, watchedResourceSurfaceRefusal } from "./analysis/component-guidance.js";
+import { foldedLengthPercentage, isLookNumericType, lookAdditiveType } from "./analysis/look-values.js";
+import { collectPublicConfigNames, declaredPublicConfig, publicConfigDiagnostic } from "./analysis/public-config.js";
 import { byCodeUnit } from "./stable-order.js";
 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, finallySelfWrite, reactivePathOf, reactivePathRoot, statementBindsName, topLevelCall, watchSelfWrite, 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.
@@ -1000,9 +1004,6 @@ function firstRelativeCssAssetAddress(source) {
     }
     return null;
 }
-function isLookNumericType(type) {
-    return type.kind === "named" && LOOK_NUMERIC_TYPE_NAMES.has(type.name);
-}
 /** True when a property's declared domain includes a spelled visual unit type. */
 function mentionsLookUnitType(type) {
     if (type.kind === "named")
@@ -1020,17 +1021,7 @@ function lookLiteralZero(expression) {
         return lookLiteralZero(expression.operand);
     return isWebUnit(expression) && expression.value === 0;
 }
-function lookAdditiveType(left, right) {
-    if (!isLookNumericType(left) || !isLookNumericType(right))
-        return null;
-    if (semanticTypeIdentity(left) === semanticTypeIdentity(right))
-        return left;
-    const lengthPercentageNames = new Set(["Length", "Percentage", "LengthPercentage"]);
-    if (left.kind === "named" && right.kind === "named"
-        && lengthPercentageNames.has(left.name) && lengthPercentageNames.has(right.name))
-        return lookLengthPercentage;
-    return null;
-}
+const lookJoin = (left, right) => lookAdditiveType(left, right, semanticTypeIdentity(left) === semanticTypeIdentity(right));
 function containsCssImport(source) {
     for (const token of cssTokens(source)) {
         if (token.kind === "at-keyword" && token.name.toLowerCase() === "import")
@@ -1181,169 +1172,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 = {
     "\\": "\\\\",
@@ -1971,11 +1799,17 @@ export class VelarWebAnalyzer extends Analyzer {
     webSourceText;
     /** D74: only props whose authors wrote a readonly contract receive prop-specific guidance. */
     explicitReadonlyPropBindings = new Map();
+    /** D114 0.29.0 LC-D1: the manifest's `web.publicConfig`, or null when this compile read no project manifest — an empty section is a claim the compile may check, and no manifest is no claim at all. */
+    webPublicConfig;
+    publicConfigNames = new Set();
+    /** velar/look builder calls this compile refused on their own arguments (D114 0.29.0 LK-I2). */
+    refusedBuilderCalls = [];
     constructor(context = {}, extensions = []) {
         super(context, extensions);
         this.webModulePath = context.path ?? null;
         this.webSourceText = context.sourceText ?? "";
         this.resources = context.resources ?? new Map();
+        this.webPublicConfig = declaredPublicConfig(context.extensionProjectConfig?.get("@velarscript/web"));
         const webImports = [...(context.extensionImports?.get("@velarscript/web") ?? [])];
         this.importedLookStaticValues = new Map(webImports.filter((entry) => isLookStaticValue(entry[1])));
         this.importedComputedNames = new Set(webImports.filter(([, value]) => isWebComputedExport(value)).map(([name]) => name));
@@ -1983,6 +1817,7 @@ export class VelarWebAnalyzer extends Analyzer {
     analyze(program) {
         this.lookStaticValues = collectLookStaticValues(program, this.importedLookStaticValues);
         this.lookBuilderNames = collectLookBuilderNames(program);
+        this.publicConfigNames = collectPublicConfigNames(program);
         this.lookImport = collectLookImportSite(program);
         this.lookDeclarations = collectLookDeclarations(program);
         for (const name of collectDerivedReactiveNames(program))
@@ -2034,11 +1869,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) {
@@ -2380,7 +2223,7 @@ export class VelarWebAnalyzer extends Analyzer {
                 this.probedOperandTypes.set(spanIdentity(expression.right.span), right);
             }
             else {
-                const additive = expression.operator === "+" || expression.operator === "-" ? lookAdditiveType(left, right) : null;
+                const additive = expression.operator === "+" || expression.operator === "-" ? lookJoin(left, right) : null;
                 const result = additive
                     ?? ((expression.operator === "*" || expression.operator === "/") && isLookNumericType(left) && right.kind === "number" ? left : null)
                     ?? (expression.operator === "*" && left.kind === "number" && isLookNumericType(right) ? right : null);
@@ -2467,11 +2310,23 @@ export class VelarWebAnalyzer extends Analyzer {
             if (retired)
                 return RETIRED_ACCESSOR_TYPE;
         }
+        const folded = expression.kind !== "CallExpression" ? null
+            : foldedLengthPercentage(expression, (name) => this.lookBuilderNames.get(name), (argument) => this.probedSlotType(argument), lookJoin);
         const result = super.inferExpression(expression, contextualType);
         if (expression.kind === "CallExpression") {
             this.checkLookBuilderCall(expression);
+            // D114 0.29.0 LC-D1: the manifest this build bakes in, proved against the declared type.
+            const report = publicConfigDiagnostic(expression, result, this.publicConfigNames, this.webPublicConfig, { expandAliases: (type) => this.expandAliases(type), fieldsOf: (identity) => this.fieldsOf(identity), describeType });
+            if (report)
+                this.diagnostics.push(report);
         }
-        return result;
+        return folded ?? result;
+    }
+    /** Infers one builder slot and parks the answer in the probe cache, so the call's own analysis reads it back. */
+    probedSlotType(argument) {
+        const inferred = this.inferExpression(argument);
+        this.probedOperandTypes.set(spanIdentity(argument.span), inferred);
+        return this.expandAliases(inferred);
     }
     // A name refers to writable reactive state only when ordinary lexical lookup
     // still resolves it to the state binding; a shadowing local wins instead.
@@ -2606,6 +2461,11 @@ export class VelarWebAnalyzer extends Analyzer {
             this.diagnostics.push(diagnostic("VEL5064", `'${name}' is the reader itself, so watching it watches a value that never changes; declare the derived value — 'computed name = ${name}()' — then 'watch name:'`, expression.span));
             return false;
         }
+        // ST-D1: the resource surface is answered ahead of the frozen rule, because it is a reactive value whose *own* handle never moves.
+        if (name !== null && this.isResourceBinding(name)) {
+            this.diagnostics.push(diagnostic("VEL5064", watchedResourceSurfaceRefusal(name), expression.span));
+            return false;
+        }
         if (this.frozenWatchSubject(expression)) {
             this.diagnostics.push(diagnostic("VEL5064", `This watch subject never changes, so its body can never run${name === null ? "" : ` — '${name}' is not a reactive source`}; watch a 'state', a 'computed', a prop, or a resource field, or move these statements to where they should run`, expression.span));
             return false;
@@ -2659,12 +2519,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 +2533,14 @@ 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 : watchSelfWrite(subject, place, statement, writes);
+            if (selfWrite !== null) {
+                this.diagnostics.push(diagnostic("VEL5077", selfWrite, statement.span));
+                return;
+            }
+            const inFinally = place === null ? null : finallySelfWrite(subject, place, statement, writes, root);
+            if (inFinally !== null) {
+                this.diagnostics.push(diagnostic("VEL5077", inFinally.message, inFinally.span));
                 return;
             }
             const call = topLevelCall(statement);
@@ -2696,15 +2552,68 @@ 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 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.
@@ -2981,11 +2890,7 @@ export class VelarWebAnalyzer extends Analyzer {
     inferExtensionCall(callee, arguments_, argumentNames, callSpan) {
         if (!isWebComponentType(callee))
             return undefined;
-        const name = webComponentName(callee);
-        this.typeError(name ? `Render component '${name}' with JSX` : "Render a Component value with JSX", callSpan);
-        if (argumentNames?.some((argument) => argument !== null)) {
-            this.typeError("Components use JSX props rather than named call arguments", callSpan);
-        }
+        this.typeError(componentCallRefusal(webComponentName(callee), arguments_, argumentNames, this.webSourceText), callSpan);
         for (const argument of arguments_)
             this.inferExpression(argument);
         return webNodeType;
@@ -3056,6 +2961,17 @@ export class VelarWebAnalyzer extends Analyzer {
         }
         return super.ownershipScopeRejection();
     }
+    /**
+     * D114 0.29.0 JX-I2: a component body has no function frame, so a `return` nested
+     * inside it — in a `match` arm, an `if`, a `for` — used to earn VEL3003 next to
+     * VEL5008 ("exactly one top-level return"), two rules its author can only read as
+     * contradicting each other. A lifecycle hook and a watch body are inside the same
+     * component and are *not* it: neither returns anything, so a `return` there keeps
+     * VEL3003.
+     */
+    extensionOwnsFunctionlessReturn() {
+        return this.componentBodyDepth > 0 && this.mountedDepth === 0 && this.cleanupDepth === 0 && this.watchBodyDepth === 0;
+    }
     invalidExtensionAwaitContext() {
         return this.synchronousReactiveDepth > 0 || this.jsxDepth > 0
             || (this.componentStates !== null && this.mountedDepth === 0);
@@ -3253,16 +3169,7 @@ export class VelarWebAnalyzer extends Analyzer {
                 this.analyzeStatement(item);
             }
         }
-        if (renders !== 1)
-            this.diagnostics.push(diagnostic("VEL5008", `Component '${statement.name}' must have exactly one top-level return`, statement.span));
-        if (mounted > 1)
-            this.diagnostics.push(diagnostic("VEL5009", `Component '${statement.name}' has more than one '@mounted' block`, statement.span));
-        if (cleanup > 1)
-            this.diagnostics.push(diagnostic("VEL5010", `Component '${statement.name}' has more than one '@cleanup' block`, statement.span));
-        if (exposes > 1)
-            this.diagnostics.push(diagnostic("VEL5056", `Component '${statement.name}' has more than one expose declaration`, statement.span));
-        if (statement.handleType && exposes === 0)
-            this.diagnostics.push(diagnostic("VEL5056", `Component '${statement.name}' declares an exposed Handle but does not provide an expose value`, statement.handleType.span));
+        this.diagnostics.push(...componentSectionCountDiagnostics(statement.name, { renders, mounted, cleanup, exposes }, statement.span, statement.handleType?.span ?? null));
         if (renderValue && isWebJsx(renderValue))
             this.validateComponentHost(renderValue, statement);
         this.componentStates = previousStates;
@@ -3486,6 +3393,7 @@ export class VelarWebAnalyzer extends Analyzer {
         // table: `rgba(0, 0, 0, alpha=2)` compiled clean while `rgba(0, 0, 0, 2)`
         // was refused.
         const parameters = LOOK_BUILDER_SIGNATURES.get(builder)?.parameters;
+        const before = this.diagnostics.length;
         for (const [index, argument] of expression.arguments.entries()) {
             const named = expression.argumentNames?.[index] ?? null;
             const position = named === null ? index : parameters?.indexOf(named) ?? -1;
@@ -3536,6 +3444,9 @@ export class VelarWebAnalyzer extends Analyzer {
         if (builder === "filters" && expression.arguments.length > 64) {
             this.diagnostics.push(diagnostic("VEL5042", "filters cannot compose more than 64 values", expression.span));
         }
+        // D114 0.29.0 LK-I2: a call its own argument check refused is recorded so a `keyframes:` stop can drop the consequence. The record is the call rather than the code, because a bad token name and a stop's one-declaration rule are two facts about one value (D103-2) and both are still reported.
+        if (this.diagnostics.length > before)
+            this.refusedBuilderCalls.push(expression.span);
     }
     /**
      * D103 rules 1 and 5 — what a checked token reference has to be at the site
@@ -3676,7 +3587,11 @@ export class VelarWebAnalyzer extends Analyzer {
                 const expected = LOOK_PROPERTY_TYPES.get(entry.name) ?? stringType;
                 const actual = this.inferExpression(entry.value, expected);
                 this.reportKeyframeSnapshotReads(entry.value);
-                if (keyframeCssValue(entry.value, this.lookStaticValues) === null) {
+                // LK-I2: a builder that failed its own argument check has already been told what
+                // is wrong with it, and "does not resolve to static CSS" is only the consequence —
+                // a sentence that sends its author looking for a rule against named arguments in
+                // a stop, which there is not (`spread=2px` in range compiles).
+                if (keyframeCssValue(entry.value, this.lookStaticValues) === null && !this.refusedBuilderCallWithin(entry.value.span)) {
                     this.diagnostics.push(diagnostic("VEL5060", "A keyframe value must resolve to static CSS from literals, unit values, arithmetic, velar/look builders, or const bindings — local or imported — that hold any of those, and the text it resolves to must read as one declaration value: no ';', '{', '}', or '@' outside a string, with parentheses, strings, and comments all closed", entry.value.span));
                 }
                 if (mentionsLookUnitType(expected) && lookLiteralZero(entry.value))
@@ -3688,6 +3603,10 @@ export class VelarWebAnalyzer extends Analyzer {
             }
         }
     }
+    /** Whether a builder call this compile refused on its own arguments lies inside `sourceSpan`. */
+    refusedBuilderCallWithin(sourceSpan) {
+        return this.refusedBuilderCalls.some((call) => call.start >= sourceSpan.start && call.end <= sourceSpan.end);
+    }
     reportKeyframeSnapshotReads(expression) {
         const visit = (value) => {
             if (Array.isArray(value)) {
@@ -4448,7 +4367,8 @@ export class VelarWebAnalyzer extends Analyzer {
         }
         const handle = webComponentHandle(component);
         if (!handle) {
-            this.diagnostics.push(diagnostic("VEL5057", `Component '${expression.tag}' does not expose a Handle`, attribute.span));
+            const stored = nonOptional(this.expandAliases(this.lookup(value.name)?.declaredType ?? unknownType));
+            this.diagnostics.push(diagnostic("VEL5057", componentRefHandleRefusal(expression.tag, component, stored), attribute.span));
             return;
         }
         const bindingType = this.lookup(value.name).type;