@velarscript/web 0.31.0 → 0.32.0

package/dist/analysis/jsx-detection.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What a function body holds, read from its statements: the first reactive
+ * declaration a 'def' answering WebNode may not carry, whether the body returns
+ * JSX, and the markup roots it returns.
+ *
+ * D115 P4 R3a: these are readings of an AST subtree, not of the analyzer, so
+ * they read as a module.
+ */
+import { type Span } from "@velarscript/compiler";
+import { type Expression, type Statement, type ValueType } from "@velarscript/compiler/extension";
+import { type WebJsxElementExpression as JSXElementExpression } from "../ast.ts";
+/**
+ * The first reactive declaration a body holds, in source order. A nested `def`
+ * or `component` owns its own declarations, so the walk stops at one.
+ */
+export declare function firstReactiveDeclaration(body: readonly Statement[]): {
+    readonly label: string;
+    readonly span: Span;
+} | null;
+/**
+ * Whether a type answers markup. `WebNode` is the value, and `WebNode?` and
+ * `List<WebNode>` are the two shapes markup legitimately travels in — a helper
+ * that answers "this row, or nothing" and one that answers a row per item.
+ * Reading only the bare annotation closed the spelling instead of the sink:
+ * the identical body under `-> WebNode?` reached the same defect unreported.
+ */
+export declare function carriesWebNode(type: ValueType): boolean;
+/**
+ * Whether a body's own `return`s carry JSX. A return type is optional on a
+ * `def`, and an omitted one left the same defective helper unreported, so the
+ * markup the body returns answers for the annotation that was never written.
+ * A nested `def` or `component` owns its own returns, exactly as it owns its
+ * own declarations.
+ */
+export declare function bodyReturnsJsx(body: readonly Statement[]): boolean;
+/**
+ * VEL5075: the JSX elements a body's own `return`s *start* with — the roots of
+ * the returned markup, which is where the emitter decides between an instance
+ * and a child. The walk descends through ordinary expression nodes, `.map(...)`
+ * callbacks included, and stops at the first JSX element on every path: inside
+ * one, every JSX position is a child position and needs no verdict. A nested
+ * `def` or `component` owns its own returns, exactly as it does elsewhere here.
+ */
+export declare function returnedMarkupRoots(body: readonly Statement[]): readonly JSXElementExpression[];
+/** The component spelling of a helper's name: components render as a PascalCase tag. */
+export declare function componentSpelling(name: string): string;
+/** `{ id: item.id }` in a callback over `item`: the field carries its own value over unchanged. */
+export declare function rowFieldPassthrough(value: Expression, row: string, name: string): boolean;
+//# sourceMappingURL=jsx-detection.d.ts.map

package/dist/analysis/jsx-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-detection.d.ts","sourceRoot":"","sources":["../../src/analysis/jsx-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAAE,KAAK,uBAAuB,IAAI,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAkBjF;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAsB3H;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAmBlE;AA0BD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,oBAAoB,EAAE,CAqC/F;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGzF"}

package/dist/analysis/jsx-detection.js

@@ -0,0 +1,196 @@
+/**
+ * What a function body holds, read from its statements: the first reactive
+ * declaration a 'def' answering WebNode may not carry, whether the body returns
+ * JSX, and the markup roots it returns.
+ *
+ * D115 P4 R3a: these are readings of an AST subtree, not of the analyzer, so
+ * they read as a module.
+ */
+import {} from "@velarscript/compiler";
+import {} from "@velarscript/compiler/extension";
+import {} from "../ast.js";
+import { isWebNodeType } from "../types.js";
+/**
+ * The reactive declarations a `def` body may not hold when the `def` answers
+ * `WebNode`. `watch`, `resource` and `action` are already refused outside a
+ * module or component scope (VEL3010/VEL3012/VEL3013); they stay listed because
+ * the defect is the declaration, not which of them the author reached for.
+ */
+const WEB_REACTIVE_DECLARATION_LABELS = new Map([
+    ["ExtensionStatement:web:state", "'state'"],
+    ["ExtensionStatement:web:computed", "'computed'"],
+    ["ExtensionStatement:web:resource", "'resource'"],
+    ["ExtensionStatement:web:watch", "'watch'"],
+    ["ExtensionStatement:web:mounted", "'@mounted'"],
+    ["ExtensionStatement:web:cleanup", "'@cleanup'"],
+]);
+/**
+ * The first reactive declaration a body holds, in source order. A nested `def`
+ * or `component` owns its own declarations, so the walk stops at one.
+ */
+export function firstReactiveDeclaration(body) {
+    let found = null;
+    const pending = [...body];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                pending.push(entry);
+            continue;
+        }
+        if (value === null || typeof value !== "object")
+            continue;
+        const node = value;
+        const kind = typeof node.kind === "string" ? node.kind : null;
+        if (kind === "FunctionDeclaration" || kind === "ExtensionStatement:web:component")
+            continue;
+        const label = kind === null ? undefined : WEB_REACTIVE_DECLARATION_LABELS.get(kind);
+        if (label !== undefined) {
+            const span = node.span;
+            if (found === null || span.start < found.span.start)
+                found = { label, span };
+            continue;
+        }
+        for (const key of Object.keys(node))
+            pending.push(node[key]);
+    }
+    return found;
+}
+/**
+ * Whether a type answers markup. `WebNode` is the value, and `WebNode?` and
+ * `List<WebNode>` are the two shapes markup legitimately travels in — a helper
+ * that answers "this row, or nothing" and one that answers a row per item.
+ * Reading only the bare annotation closed the spelling instead of the sink:
+ * the identical body under `-> WebNode?` reached the same defect unreported.
+ */
+export function carriesWebNode(type) {
+    if (isWebNodeType(type))
+        return true;
+    if (type.kind === "optional")
+        return carriesWebNode(type.inner);
+    if (type.kind === "list")
+        return carriesWebNode(type.element);
+    return false;
+}
+/**
+ * Whether a body's own `return`s carry JSX. A return type is optional on a
+ * `def`, and an omitted one left the same defective helper unreported, so the
+ * markup the body returns answers for the annotation that was never written.
+ * A nested `def` or `component` owns its own returns, exactly as it owns its
+ * own declarations.
+ */
+export function bodyReturnsJsx(body) {
+    const pending = [...body];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                pending.push(entry);
+            continue;
+        }
+        if (value === null || typeof value !== "object")
+            continue;
+        const node = value;
+        const kind = typeof node.kind === "string" ? node.kind : null;
+        if (kind === "FunctionDeclaration" || kind === "ExtensionStatement:web:component")
+            continue;
+        if (kind === "ReturnStatement") {
+            if (subtreeHoldsJsx(node.value))
+                return true;
+            continue;
+        }
+        for (const key of Object.keys(node))
+            pending.push(node[key]);
+    }
+    return false;
+}
+/**
+ * A returned expression that builds markup anywhere inside it — bare, inside a
+ * List, behind a condition, or built by the callback of a `.map(...)` that
+ * answers a row per item. The arrow is walked rather than skipped for the same
+ * reason the optional and List annotations are unwrapped: `rows()` returning
+ * `items.map(item => <li>…</li>)` is a markup helper by every measure except
+ * the one spelling that was being read.
+ */
+function subtreeHoldsJsx(value) {
+    const pending = [value];
+    while (pending.length > 0) {
+        const entry = pending.pop();
+        if (Array.isArray(entry)) {
+            for (const item of entry)
+                pending.push(item);
+            continue;
+        }
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const node = entry;
+        if (node.kind === "ExtensionExpression:web:jsx")
+            return true;
+        for (const key of Object.keys(node))
+            pending.push(node[key]);
+    }
+    return false;
+}
+/**
+ * VEL5075: the JSX elements a body's own `return`s *start* with — the roots of
+ * the returned markup, which is where the emitter decides between an instance
+ * and a child. The walk descends through ordinary expression nodes, `.map(...)`
+ * callbacks included, and stops at the first JSX element on every path: inside
+ * one, every JSX position is a child position and needs no verdict. A nested
+ * `def` or `component` owns its own returns, exactly as it does elsewhere here.
+ */
+export function returnedMarkupRoots(body) {
+    const roots = [];
+    const collect = (value) => {
+        const pending = [value];
+        while (pending.length > 0) {
+            const entry = pending.pop();
+            if (Array.isArray(entry)) {
+                for (const item of entry)
+                    pending.push(item);
+                continue;
+            }
+            if (entry === null || typeof entry !== "object")
+                continue;
+            const node = entry;
+            if (node.kind === "ExtensionExpression:web:jsx") {
+                roots.push(node);
+                continue;
+            }
+            for (const key of Object.keys(node))
+                pending.push(node[key]);
+        }
+    };
+    const pending = [...body];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                pending.push(entry);
+            continue;
+        }
+        if (value === null || typeof value !== "object")
+            continue;
+        const node = value;
+        const kind = typeof node.kind === "string" ? node.kind : null;
+        if (kind === "FunctionDeclaration" || kind === "ExtensionStatement:web:component")
+            continue;
+        if (kind === "ReturnStatement") {
+            collect(node.value);
+            continue;
+        }
+        for (const key of Object.keys(node))
+            pending.push(node[key]);
+    }
+    return roots;
+}
+/** The component spelling of a helper's name: components render as a PascalCase tag. */
+export function componentSpelling(name) {
+    return name.length === 0 ? name : `${name[0].toUpperCase()}${name.slice(1)}`;
+}
+/** `{ id: item.id }` in a callback over `item`: the field carries its own value over unchanged. */
+export function rowFieldPassthrough(value, row, name) {
+    return value.kind === "MemberExpression" && value.property === name
+        && value.object.kind === "IdentifierExpression" && value.object.name === row;
+}
+//# sourceMappingURL=jsx-detection.js.map

package/dist/analysis/jsx-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-detection.js","sourceRoot":"","sources":["../../src/analysis/jsx-detection.ts"],"names":[],"mappings":"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"}

package/dist/analysis/keyed-rebuild.d.ts

@@ -0,0 +1,148 @@
+/**
+ * D89 A4: a 'map' callback that rebuilds its rows instead of carrying them
+ * over, which is what a keyed list stops recognising — what one rebuild records,
+ * and the module reading that decides whether a helper builds fresh records at
+ * all.
+ *
+ * D115 P4 R3a: the advisory is raised from the analyzer's JSX pass, but every
+ * reading it rests on is a reading of the program, so they read as a module.
+ *
+ * D115 P4 R3c: the four rules that record a rebuild and raise the advisory join
+ * them, over a `KeyedRebuildHost`.
+ */
+import { type DiagnosticFix, type Span } from "@velarscript/compiler";
+import { type Expression, type Program, type Statement, type ValueType } from "@velarscript/compiler/extension";
+import { type WebComputedDeclaration as ComputedDeclaration } from "../ast.ts";
+/**
+ * D89 A4: what a `map` callback rebuilds, when it returns a newly built record
+ * instead of the row it was handed. Null is the non-trigger answer the ruling
+ * names — a callback that returns its parameter, or anything else that is not a
+ * record literal, builds nothing and moves no identity. A record is reported
+ * even when no field can be named, because it is the rebuilt row's own identity
+ * that the keyed list stops recognising, not any one field it carries.
+ *
+ * A conditional is read through because the React spelling nearly always
+ * carries one, `t.id == id ? {...t, done: true} : t`, and its `else` branch is
+ * the returns-the-original case rather than a second shape. A branch that names
+ * a field is preferred, since a suggestion that names one is the whole product.
+ */
+export declare function keyedRebuiltRecord(body: Expression, row: string): {
+    readonly field: string | null;
+} | null;
+export type FunctionDeclarationStatement = Extract<Statement, {
+    readonly kind: "FunctionDeclaration";
+}>;
+/**
+ * D89 A4, the wider proven shape: every `def` of the module by name, so a
+ * `computed` whose initializer calls one can be read through to what that call
+ * builds. A name declared twice maps to null — two bodies under one name make
+ * the question unanswerable, and an advisory that cannot prove which body runs
+ * stays silent rather than guessing.
+ */
+export declare function collectModuleFunctions(program: Program): ReadonlyMap<string, FunctionDeclarationStatement | null>;
+/**
+ * D89 A4, the wider proven shape: whether a `def` answers a list it filled with
+ * freshly constructed records — the `for`/`append` builder that spells the same
+ * churn `list = list.map(item => {…})` spells with `map`, and the spelling the
+ * P2b consumer actually wrote.
+ *
+ * Four things are proven, and any one of them missing leaves the advisory
+ * silent, because the whole product is naming a rebuild that really happens:
+ *
+ * 1. the body's last statement returns a name it declared here, initialized to
+ *    an empty list literal — so the list is the `def`'s own, not one handed in;
+ * 2. every value appended to that list is a record literal, so every element is
+ *    a new value on every call. One `append(row)` of a source record is the
+ *    identity-preserving spelling this advisory teaches, and one member call
+ *    the proof cannot read leaves the whole answer unproven;
+ * 3. at least one such record reads a parameter of the `def` or the binding of
+ *    the `for` that appends it. A builder whose records are constant answers
+ *    the same content every call, so nothing it is derived from can move and
+ *    the `computed` over it never recomputes;
+ * 4. nothing else touches the list — it is built and answered, nothing more.
+ */
+export declare function buildsFreshRecords(declaration: FunctionDeclarationStatement): boolean;
+/**
+ * D89 A4: one rebuild of a list's rows, held until the module's JSX is analyzed
+ * so the advisory is raised only where that same list is what a keyed list
+ * renders.
+ *
+ * `kind` names which spelling wrote it, and the two differ only in the remedy
+ * the message ends with. An `assignment` — `list = list.map(item => {…})` — owns
+ * the list it rewrote, so the preserving alternative is the field write next to
+ * it. A `derived` rebuild is a `computed` that builds its rows, and a derived
+ * value owns nothing it could write, so the alternative names the source rows
+ * instead.
+ */
+export interface KeyedListRebuild {
+    readonly kind: "assignment" | "derived";
+    readonly source: string;
+    readonly name: string;
+    /** The rewritten field, or null when the rebuild names none. */
+    readonly field: string | null;
+    readonly span: Span;
+}
+/**
+ * What the rebuild rules ask of the analyzer that hosts them: the two module
+ * tables the walk fills, the module's `def` bodies, and the two analyzer
+ * operations a rebuild is recorded and advised through.
+ *
+ * D115 P4 R3c. `moduleFunctions` is replaced once per program, so it arrives
+ * through a getter and a collaborator reading it mid-walk reads the live one.
+ */
+export interface KeyedRebuildHost {
+    /** D89 A4: every row rebuild of this module — assigned or derived — in source order. */
+    readonly keyedListRebuilds: KeyedListRebuild[];
+    /** D89 A4: the binding identity of every list a keyed `.map(...)` interpolation renders. */
+    readonly keyedListSources: ReadonlySet<string>;
+    /** D89 A4: this module's `def` bodies by name, so a `computed` that calls one can be read through. Replaced per program. */
+    readonly moduleFunctions: ReadonlyMap<string, FunctionDeclarationStatement | null>;
+    advise(code: string, message: string, adviceSpan: Span, fix?: DiagnosticFix): void;
+    lookup(name: string): {
+        readonly span: Span;
+        readonly type: ValueType;
+    } | null;
+}
+/**
+ * D89 A4: records `list = list.map(item => {…})`, React's immutable update,
+ * where the callback builds a new record rather than changing a field.
+ *
+ * D90 R2 stands — `__velarKeyed` compares identity and that does not move,
+ * and the framework does not accommodate the idiom. This channel is not the
+ * framework taking responsibility; it is the compiler telling the author that
+ * the row he is typing into is about to be destroyed. Nothing is reported
+ * yet: the advisory is owed only if the rewritten list is what a keyed list
+ * renders, and the render usually sits below the update.
+ */
+export declare function recordKeyedListRebuild(host: KeyedRebuildHost, statement: Statement): void;
+/**
+ * D89 A4, the wider proven shape: the same churn written as a derived value.
+ * `computed rows = source.map(item => {…})` and `computed rows = build(...)`
+ * over a `for`/`append` builder both hand a keyed position a fresh record for
+ * every row on every recompute, which is exactly what the assignment shape
+ * does — the reconciliation wave compiled both and found only one of them
+ * named. It is one advisory with a wider proof, not a second code: the defect,
+ * the consequence, and the suppression are the same.
+ *
+ * A `const` in a component body is deliberately not here. It is constructed
+ * once, so its records never move, and advising it would be a guess rather
+ * than a proof.
+ */
+export declare function recordDerivedKeyedListRebuild(host: KeyedRebuildHost, statement: ComputedDeclaration): void;
+/**
+ * Whether a derived initializer constructs one fresh record per source
+ * element. Two spellings are proven and everything else is silent: a `map`
+ * whose callback answers a record literal — the same recognizer the
+ * assignment shape uses — and a call to a `def` this module declares whose
+ * whole answer is a list it filled with record literals.
+ */
+export declare function rebuildsRecordsPerElement(host: KeyedRebuildHost, value: Expression): boolean;
+/**
+ * D89 A4: raises the advisory for the rebuilds whose list a keyed position
+ * really renders. The advisory channel cannot reach `this.diagnostics`, so
+ * nothing here fails a build, changes an emitted byte, or moves a semantic
+ * rule; `// velar-allow A4: <reason>` suppresses it where building the rows is
+ * the only spelling, which a `readonly` list or one API response makes it.
+ */
+export declare function adviseKeyedListRebuilds(host: KeyedRebuildHost): void;
+//# sourceMappingURL=keyed-rebuild.d.ts.map

package/dist/analysis/keyed-rebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-rebuild.d.ts","sourceRoot":"","sources":["../../src/analysis/keyed-rebuild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAgB,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAC9H,OAAO,EAAkB,KAAK,sBAAsB,IAAI,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAG/F;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAuB1G;AAED,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAAC,SAAS,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAAC;AAExG;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,4BAA4B,GAAG,IAAI,CAAC,CAgBjH;AA2BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,4BAA4B,GAAG,OAAO,CA8CrF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IAC/C,4FAA4F;IAC5F,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,4HAA4H;IAC5H,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,4BAA4B,GAAG,IAAI,CAAC,CAAC;IAEnF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACnF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;KAAE,GAAG,IAAI,CAAC;CAChF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAuBzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAS1G;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAW5F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAmBpE"}