@velarscript/web 0.28.1 → 0.29.1

package/dist/analysis/component-guidance.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What a component's refusals say — the JSX element a call was reaching for,
+ * the contract a `ref` needs, and the four "how many of this section" rules a
+ * body earns once its statements are read.
+ *
+ * D115 §三: these are sentence-building questions about a component's shape,
+ * and none of them needs the analyzer's walk state, so they read as free
+ * functions in their own module rather than as methods in the middle of it.
+ */
+import { type Diagnostic, type Span } from "@velarscript/compiler";
+import { type Expression, type ValueType } from "@velarscript/compiler/extension";
+import { type WebComponentType } from "../types.ts";
+/**
+ * D114 0.29.0 JX-I1: calling a component is one mistake, and a named argument
+ * is how it is spelled rather than a second one. The named form therefore
+ * extends the same sentence with the element the author meant — and only that
+ * sentence, so `Card("a")` and `Card(title="a")` each report once.
+ */
+export declare function componentCallRefusal(name: string | null, arguments_: readonly Expression[], argumentNames: readonly (string | null)[] | undefined, sourceText: string): string;
+/**
+ * D114 0.29.0 LC-I2: two different mistakes used to share one sentence. A
+ * component declared without `exposes` really does expose no Handle. A
+ * one-argument `Component<Props>` contract is a different failure: the
+ * constructor behind it may expose a Handle exactly as its author intended, and
+ * what withholds `ref` is the contract's missing second type argument (§14). So
+ * the contract is answered with the contract it needs, spelling the Handle the
+ * ref binding already declares when it declares one.
+ */
+export declare function componentRefHandleRefusal(tag: string, component: WebComponentType, stored: ValueType): string;
+export interface ComponentSectionCounts {
+    readonly renders: number;
+    readonly mounted: number;
+    readonly cleanup: number;
+    readonly exposes: number;
+}
+/**
+ * D114 0.29.0 JX-I2: VEL5008 names the two ways out, because it is the only
+ * message this shape earns now — a `return` inside a `match` arm or an `if` is
+ * where the count usually goes wrong, and the author who reads "exactly one"
+ * has branches already written that he needs told what to do with.
+ */
+export declare function componentSectionCountDiagnostics(name: string, counts: ComponentSectionCounts, declarationSpan: Span, handleTypeSpan: Span | null): readonly Diagnostic[];
+/**
+ * D114 0.29.0 ST-D1: a `resource` publishes four reactive fields, and the
+ * surface carrying them is not one of them — the handle is built once and never
+ * replaced, so `watch profile:` compiled clean and never ran. The sentence
+ * VEL5064 already had names the answer ("or a resource field"); what was
+ * missing was this shape's place in the criterion, so the fields are spelled
+ * out here.
+ */
+export declare function watchedResourceSurfaceRefusal(name: string): string;
+//# sourceMappingURL=component-guidance.d.ts.map

package/dist/analysis/component-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-guidance.d.ts","sourceRoot":"","sources":["../../src/analysis/component-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAA+B,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAC/G,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,aAAa,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,EACrD,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAO7G;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,sBAAsB,EAC9B,eAAe,EAAE,IAAI,EACrB,cAAc,EAAE,IAAI,GAAG,IAAI,GAC1B,SAAS,UAAU,EAAE,CAiBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlE"}

package/dist/analysis/component-guidance.js

@@ -0,0 +1,103 @@
+/**
+ * What a component's refusals say — the JSX element a call was reaching for,
+ * the contract a `ref` needs, and the four "how many of this section" rules a
+ * body earns once its statements are read.
+ *
+ * D115 §三: these are sentence-building questions about a component's shape,
+ * and none of them needs the analyzer's walk state, so they read as free
+ * functions in their own module rather than as methods in the middle of it.
+ */
+import {} from "@velarscript/compiler";
+import { describeType, isInvalidType } from "@velarscript/compiler/extension";
+import {} from "../types.js";
+const diagnostic = (code, message, sourceSpan) => ({ code, message, span: sourceSpan });
+/**
+ * D114 0.29.0 JX-I1: calling a component is one mistake, and a named argument
+ * is how it is spelled rather than a second one. The named form therefore
+ * extends the same sentence with the element the author meant — and only that
+ * sentence, so `Card("a")` and `Card(title="a")` each report once.
+ */
+export function componentCallRefusal(name, arguments_, argumentNames, sourceText) {
+    const subject = name ? `Render component '${name}' with JSX` : "Render a Component value with JSX";
+    if (!argumentNames?.some((argument) => argument !== null))
+        return subject;
+    const element = componentElementSpelling(name, arguments_, argumentNames, sourceText);
+    return `${subject}${element === null ? "" : ` — write '${element}'`}; components take JSX props rather than named call arguments`;
+}
+/**
+ * The JSX element a named-argument component call was reaching for, or null
+ * when the call does not spell one: an unnamed `Component` value has no tag to
+ * write, and a positional argument has no prop name. A string literal keeps
+ * JSX's quoted attribute form; every other value takes the braces JSX requires,
+ * and both are sliced from the author's own source so the answer is the line he
+ * can paste back.
+ */
+function componentElementSpelling(name, arguments_, argumentNames, sourceText) {
+    if (name === null || arguments_.length === 0)
+        return null;
+    const attributes = [];
+    for (const [index, argument] of arguments_.entries()) {
+        const propName = argumentNames[index] ?? null;
+        const written = sourceText.slice(argument.span.start, argument.span.end);
+        if (propName === null || written === "" || /[\n\r]/u.test(written))
+            return null;
+        const literal = argument.kind === "LiteralExpression" && typeof argument.value === "string";
+        attributes.push(`${propName}=${literal ? written : `{${written}}`}`);
+    }
+    return `<${name} ${attributes.join(" ")} />`;
+}
+/**
+ * D114 0.29.0 LC-I2: two different mistakes used to share one sentence. A
+ * component declared without `exposes` really does expose no Handle. A
+ * one-argument `Component<Props>` contract is a different failure: the
+ * constructor behind it may expose a Handle exactly as its author intended, and
+ * what withholds `ref` is the contract's missing second type argument (§14). So
+ * the contract is answered with the contract it needs, spelling the Handle the
+ * ref binding already declares when it declares one.
+ */
+export function componentRefHandleRefusal(tag, component, stored) {
+    if (component.role !== "contract")
+        return `Component '${tag}' does not expose a Handle`;
+    const known = stored.kind !== "null" && stored.kind !== "unknown" && stored.kind !== "any" && !isInvalidType(stored);
+    const handleType = known ? stored : { kind: "named", name: "Handle" };
+    const widened = describeType({ ...component, arguments: [handleType] });
+    return `The contract on '${tag}' names no Handle, so it does not authorise a component ref — the authority is the contract's second type argument,`
+        + ` not the component behind it; declare the contract as '${widened}'`;
+}
+/**
+ * D114 0.29.0 JX-I2: VEL5008 names the two ways out, because it is the only
+ * message this shape earns now — a `return` inside a `match` arm or an `if` is
+ * where the count usually goes wrong, and the author who reads "exactly one"
+ * has branches already written that he needs told what to do with.
+ */
+export function componentSectionCountDiagnostics(name, counts, declarationSpan, handleTypeSpan) {
+    const reports = [];
+    if (counts.renders !== 1) {
+        reports.push(diagnostic("VEL5008", `Component '${name}' must have exactly one top-level return: assign the branches to a binding — 'let node: WebNode = <span />' written in each arm — and return it once,`
+            + " or move the branching into a 'def' that returns WebNode and return its call", declarationSpan));
+    }
+    if (counts.mounted > 1)
+        reports.push(diagnostic("VEL5009", `Component '${name}' has more than one '@mounted' block`, declarationSpan));
+    if (counts.cleanup > 1)
+        reports.push(diagnostic("VEL5010", `Component '${name}' has more than one '@cleanup' block`, declarationSpan));
+    if (counts.exposes > 1)
+        reports.push(diagnostic("VEL5056", `Component '${name}' has more than one expose declaration`, declarationSpan));
+    if (handleTypeSpan && counts.exposes === 0) {
+        reports.push(diagnostic("VEL5056", `Component '${name}' declares an exposed Handle but does not provide an expose value`, handleTypeSpan));
+    }
+    return reports;
+}
+/**
+ * D114 0.29.0 ST-D1: a `resource` publishes four reactive fields, and the
+ * surface carrying them is not one of them — the handle is built once and never
+ * replaced, so `watch profile:` compiled clean and never ran. The sentence
+ * VEL5064 already had names the answer ("or a resource field"); what was
+ * missing was this shape's place in the criterion, so the fields are spelled
+ * out here.
+ */
+export function watchedResourceSurfaceRefusal(name) {
+    return `This watch subject never changes, so its body can never run — '${name}' is the resource itself rather than one of the fields it publishes;`
+        + " watch a 'state', a 'computed', a prop, or a resource field, or move these statements to where they should run:"
+        + ` 'watch ${name}.value:' for the loaded value, 'watch ${name}.loading:' for the load's progress, or the input the load reads`;
+}
+//# sourceMappingURL=component-guidance.js.map

package/dist/analysis/component-guidance.js.map

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

package/dist/analysis/look-values.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How the visual unit types combine — the rule `+` reads, and the rule the
+ * length-percentage builders read.
+ *
+ * D115 §三: one question about types, asked in two places, so it is written
+ * once here rather than twice in the middle of the Web analyzer.
+ */
+import { type Expression, type ValueType } from "@velarscript/compiler/extension";
+export declare function isLookNumericType(type: ValueType): boolean;
+/**
+ * The type two visual operands add up to: the same kind on both sides keeps it,
+ * and a length beside a percentage widens to the type that carries both.
+ */
+export declare function lookAdditiveType(left: ValueType, right: ValueType, sameIdentity: boolean): ValueType | null;
+/**
+ * D114 0.29.0 LK-C3: `min`, `max` and `clamp` publish the widest of the three
+ * length-percentage types, because a slot takes either. A call whose slots are
+ * all one kind is still that kind, and the fold is the one `+` already makes.
+ * Without it, `clamp(16px, 3vw, 24px)` — the tour's own line, and a legal
+ * `lineHeight` — would have started answering `LengthPercentage` and stopped
+ * assigning.
+ *
+ * `inferSlot` both infers a slot and remembers the answer, because the call's
+ * own analysis reads each argument again straight afterwards and must not
+ * report the argument's diagnostics a second time.
+ */
+export declare function foldedLengthPercentage(expression: Extract<Expression, {
+    kind: "CallExpression";
+}>, builderOf: (name: string) => string | undefined, inferSlot: (argument: Expression) => ValueType, join: (left: ValueType, right: ValueType) => ValueType | null): ValueType | null;
+//# sourceMappingURL=look-values.d.ts.map

package/dist/analysis/look-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"look-values.d.ts","sourceRoot":"","sources":["../../src/analysis/look-values.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAMlF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAO3G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,EAC3D,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC/C,SAAS,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,SAAS,EAC9C,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,SAAS,GAAG,IAAI,GAC5D,SAAS,GAAG,IAAI,CAclB"}

package/dist/analysis/look-values.js

@@ -0,0 +1,61 @@
+/**
+ * How the visual unit types combine — the rule `+` reads, and the rule the
+ * length-percentage builders read.
+ *
+ * D115 §三: one question about types, asked in two places, so it is written
+ * once here rather than twice in the middle of the Web analyzer.
+ */
+import {} from "@velarscript/compiler/extension";
+import { LOOK_BUILDER_SIGNATURES, LOOK_NUMERIC_TYPE_NAMES } from "../look.js";
+const lookLengthPercentage = { kind: "named", name: "LengthPercentage" };
+const lengthPercentageNames = new Set(["Length", "Percentage", "LengthPercentage"]);
+export function isLookNumericType(type) {
+    return type.kind === "named" && LOOK_NUMERIC_TYPE_NAMES.has(type.name);
+}
+/**
+ * The type two visual operands add up to: the same kind on both sides keeps it,
+ * and a length beside a percentage widens to the type that carries both.
+ */
+export function lookAdditiveType(left, right, sameIdentity) {
+    if (!isLookNumericType(left) || !isLookNumericType(right))
+        return null;
+    if (sameIdentity)
+        return left;
+    return left.kind === "named" && right.kind === "named"
+        && lengthPercentageNames.has(left.name) && lengthPercentageNames.has(right.name)
+        ? lookLengthPercentage
+        : null;
+}
+/**
+ * D114 0.29.0 LK-C3: `min`, `max` and `clamp` publish the widest of the three
+ * length-percentage types, because a slot takes either. A call whose slots are
+ * all one kind is still that kind, and the fold is the one `+` already makes.
+ * Without it, `clamp(16px, 3vw, 24px)` — the tour's own line, and a legal
+ * `lineHeight` — would have started answering `LengthPercentage` and stopped
+ * assigning.
+ *
+ * `inferSlot` both infers a slot and remembers the answer, because the call's
+ * own analysis reads each argument again straight afterwards and must not
+ * report the argument's diagnostics a second time.
+ */
+export function foldedLengthPercentage(expression, builderOf, inferSlot, join) {
+    if (expression.callee.kind !== "IdentifierExpression")
+        return null;
+    const builder = builderOf(expression.callee.name);
+    const signature = builder === undefined ? undefined : LOOK_BUILDER_SIGNATURES.get(builder);
+    if (!signature || signature.result !== "length-percentage")
+        return null;
+    if (expression.arguments.length !== signature.parameters.length)
+        return null;
+    let folded = null;
+    for (const argument of expression.arguments) {
+        const slot = inferSlot(argument);
+        if (!isLookNumericType(slot))
+            return null;
+        folded = folded === null ? slot : join(folded, slot);
+        if (folded === null)
+            return null;
+    }
+    return folded;
+}
+//# sourceMappingURL=look-values.js.map

package/dist/analysis/look-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"look-values.js","sourceRoot":"","sources":["../../src/analysis/look-values.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAmC,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE9E,MAAM,oBAAoB,GAAc,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC;AACpF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEpF,MAAM,UAAU,iBAAiB,CAAC,IAAe;IAC/C,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe,EAAE,KAAgB,EAAE,YAAqB;IACvF,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,YAAY;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;WACjD,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;QAChF,CAAC,CAAC,oBAAoB;QACtB,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAA2D,EAC3D,SAA+C,EAC/C,SAA8C,EAC9C,IAA6D;IAE7D,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,KAAK,sBAAsB;QAAE,OAAO,IAAI,CAAC;IACnE,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3F,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,mBAAmB;QAAE,OAAO,IAAI,CAAC;IACxE,IAAI,UAAU,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,UAAU,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,MAAM,GAAqB,IAAI,CAAC;IACpC,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACrD,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IACnC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/analysis/public-config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * D114 0.29.0 LC-D1: `publicConfig(Type)` proved against the manifest that
+ * feeds it.
+ *
+ * A `velar/config` value is a *build input* — the same run reads `velar.json`
+ * and compiles the module, and web-api says the value is "baked into the
+ * content-hashed application entry at build time" — so a manifest that does not
+ * satisfy the declared type is provable before anything runs. It used to be
+ * provable nowhere: `check` and `build` were both silent, and the failure then
+ * arrived during module evaluation, ahead of `velar/app`'s error chain, so not
+ * even the compiler-owned fatal state could render. What the author got was a
+ * blank page and one uncaught host error.
+ *
+ * Runtime validation stays: a manifest a build baked in can be hand-edited
+ * afterwards. This only moves the answer to where the mistake is.
+ *
+ * D115 §三: its own module under `web/analysis/`, because the walk is a
+ * question about a JSON value and a type and needs nothing else from the
+ * analyzer than those two.
+ */
+import { type Diagnostic } from "@velarscript/compiler";
+import { type Expression, type Program, type ValueType } from "@velarscript/compiler/extension";
+/** What the walk asks of the analyzer that hosts it, and nothing more. */
+export interface PublicConfigTypeHost {
+    expandAliases(type: ValueType): ValueType;
+    fieldsOf(identity: string): ReadonlyMap<string, ValueType> | null;
+    describeType(type: ValueType): string;
+}
+/** Local names bound to `publicConfig` from `velar/config`, including aliased imports. */
+export declare function collectPublicConfigNames(program: Program): ReadonlySet<string>;
+/**
+ * The manifest's `web.publicConfig`, or null when this compile read no project
+ * manifest. Null is not "empty": an empty section is a claim the compile may
+ * check, and no manifest is no claim at all.
+ */
+export declare function declaredPublicConfig(webProject: unknown): Readonly<Record<string, unknown>> | null;
+/**
+ * The VEL5080 one `publicConfig(Type)` call earns, or null when this call makes
+ * no build-time claim or the manifest satisfies the type it names.
+ */
+export declare function publicConfigDiagnostic(expression: Extract<Expression, {
+    kind: "CallExpression";
+}>, declared: ValueType, names: ReadonlySet<string>, manifest: Readonly<Record<string, unknown>> | null, host: PublicConfigTypeHost): Diagnostic | null;
+//# sourceMappingURL=public-config.d.ts.map

package/dist/analysis/public-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-config.d.ts","sourceRoot":"","sources":["../../src/analysis/public-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAE/G,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC;IAClE,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;CACvC;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAS9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAMlG;AAYD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,EAC3D,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,EAClD,IAAI,EAAE,oBAAoB,GACzB,UAAU,GAAG,IAAI,CAcnB"}

package/dist/analysis/public-config.js

@@ -0,0 +1,133 @@
+/**
+ * D114 0.29.0 LC-D1: `publicConfig(Type)` proved against the manifest that
+ * feeds it.
+ *
+ * A `velar/config` value is a *build input* — the same run reads `velar.json`
+ * and compiles the module, and web-api says the value is "baked into the
+ * content-hashed application entry at build time" — so a manifest that does not
+ * satisfy the declared type is provable before anything runs. It used to be
+ * provable nowhere: `check` and `build` were both silent, and the failure then
+ * arrived during module evaluation, ahead of `velar/app`'s error chain, so not
+ * even the compiler-owned fatal state could render. What the author got was a
+ * blank page and one uncaught host error.
+ *
+ * Runtime validation stays: a manifest a build baked in can be hand-edited
+ * afterwards. This only moves the answer to where the mistake is.
+ *
+ * D115 §三: its own module under `web/analysis/`, because the walk is a
+ * question about a JSON value and a type and needs nothing else from the
+ * analyzer than those two.
+ */
+import {} from "@velarscript/compiler";
+import { isInvalidType } from "@velarscript/compiler/extension";
+/** Local names bound to `publicConfig` from `velar/config`, including aliased imports. */
+export function collectPublicConfigNames(program) {
+    const names = new Set();
+    for (const statement of program.body) {
+        if (statement.kind !== "ImportDeclaration" || statement.source !== "velar/config" || statement.javascript)
+            continue;
+        for (const specifier of statement.specifiers) {
+            if (!specifier.namespace && specifier.imported === "publicConfig")
+                names.add(specifier.local);
+        }
+    }
+    return names;
+}
+/**
+ * The manifest's `web.publicConfig`, or null when this compile read no project
+ * manifest. Null is not "empty": an empty section is a claim the compile may
+ * check, and no manifest is no claim at all.
+ */
+export function declaredPublicConfig(webProject) {
+    if (webProject === undefined || webProject === null || typeof webProject !== "object")
+        return null;
+    const declared = webProject.publicConfig;
+    return declared && typeof declared === "object" && !Array.isArray(declared)
+        ? declared
+        : {};
+}
+/**
+ * The name a `publicConfig(Type)` argument writes, or null when the argument is
+ * not a written type name. A computed or qualified runtime type carries no
+ * spelling for the diagnostic to quote and no claim the compile can hold to, so
+ * the build-time proof exists only where the type is written out at the call.
+ */
+function runtimeTypeArgumentName(argument) {
+    return argument?.kind === "IdentifierExpression" ? argument.name : null;
+}
+/**
+ * The VEL5080 one `publicConfig(Type)` call earns, or null when this call makes
+ * no build-time claim or the manifest satisfies the type it names.
+ */
+export function publicConfigDiagnostic(expression, declared, names, manifest, host) {
+    if (manifest === null || expression.arguments.length !== 1)
+        return null;
+    if (expression.callee.kind !== "IdentifierExpression" || !names.has(expression.callee.name))
+        return null;
+    const typeName = runtimeTypeArgumentName(expression.arguments[0]);
+    if (typeName === null || declared.kind === "unknown" || declared.kind === "any" || isInvalidType(declared))
+        return null;
+    const reason = publicConfigMismatch(host, declared, manifest, "");
+    if (reason === null)
+        return null;
+    return {
+        code: "VEL5080",
+        message: `Value does not match ${typeName} — ${reason}.`
+            + " 'publicConfig' reads the manifest's 'web.publicConfig', which this build bakes into the application entry,"
+            + " so the value is already known here: add the field to 'web.publicConfig' in velar.json, or widen the declared type",
+        span: expression.span,
+    };
+}
+/**
+ * The first reason the manifest value fails the declared type, in the sentence
+ * the runtime validator uses, or null when nothing is provably wrong. Only a
+ * refusal that is certainly right is reported: a type this walk cannot decide —
+ * a class, a capability, a generic parameter — answers null rather than
+ * guessing, and the runtime keeps that case.
+ */
+function publicConfigMismatch(host, type, value, path) {
+    const expanded = host.expandAliases(type);
+    if (expanded.kind === "optional") {
+        return value === null || value === undefined ? null : publicConfigMismatch(host, expanded.inner, value, path);
+    }
+    if (value === undefined)
+        return path === "" ? "the value is missing" : `field '${path}' is missing`;
+    const fields = expanded.kind === "object"
+        ? expanded.fields
+        : expanded.kind === "named" ? host.fieldsOf(expanded.identity ?? expanded.name) : null;
+    if (fields)
+        return recordMismatch(host, fields, expanded, value, path);
+    if (expanded.kind === "list") {
+        if (!Array.isArray(value))
+            return typeMismatch(host, expanded, path);
+        for (const [index, item] of value.entries()) {
+            const reason = publicConfigMismatch(host, expanded.element, item, `${path}[${index}]`);
+            if (reason !== null)
+                return reason;
+        }
+        return null;
+    }
+    const matches = expanded.kind === "string" ? typeof value === "string"
+        : expanded.kind === "number" ? typeof value === "number"
+            : expanded.kind === "bool" ? typeof value === "boolean"
+                : expanded.kind === "null" ? value === null
+                    : null;
+    return matches === false ? typeMismatch(host, expanded, path) : null;
+}
+function recordMismatch(host, fields, expanded, value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return typeMismatch(host, expanded, path);
+    const record = value;
+    for (const [field, fieldType] of fields) {
+        const reason = publicConfigMismatch(host, fieldType, Object.hasOwn(record, field) ? record[field] : undefined, path ? `${path}.${field}` : field);
+        if (reason !== null)
+            return reason;
+    }
+    return null;
+}
+function typeMismatch(host, type, path) {
+    return path === ""
+        ? `the value does not match ${host.describeType(type)}`
+        : `field '${path}' does not match ${host.describeType(type)}`;
+}
+//# sourceMappingURL=public-config.js.map

package/dist/analysis/public-config.js.map

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

package/dist/analysis/watch-cycles.d.ts

@@ -0,0 +1,176 @@
+/**
+ * D114 W: the reactive places a watch is about — the subject it watches, the
+ * places a body statement writes, and the one-hop `action`/`async def` writers
+ * of this module. Everything here is a question about *paths and statements*;
+ * nothing needs a type, which is why it reads as free functions and why, under
+ * D115 §三's `web/analysis/`, it is its own module rather than 280 lines in the
+ * middle of the Web analyzer.
+ *
+ * What a path *means* — whether the type at a depth is a collection, which of
+ * its calls mutate — stays with the analyzer and arrives as `ReactiveSubjectWrite`.
+ */
+import { type Span } from "@velarscript/compiler";
+import { type Expression, type Program, type Statement, type ValueType } from "@velarscript/compiler/extension";
+/**
+ * D114 W: one step a reactive path takes below its root — a named field, or an
+ * element under a key that names the same element on two evaluations. The steps
+ * are kept beside the rendered text because two questions are asked of a path:
+ * "is this the same place" answers on the text, and "is this place inside that
+ * one" has to walk, both to compare step by step and to descend the subject's
+ * type to the value the write lands on.
+ */
+export type ReactivePathStep = {
+    readonly kind: "field";
+    readonly name: string;
+} | {
+    readonly kind: "index";
+    readonly key: string;
+};
+export interface ReactivePath {
+    readonly root: string;
+    readonly steps: readonly ReactivePathStep[];
+    /** The place as one comparable key, e.g. `items[0].done`. */
+    readonly text: string;
+}
+/**
+ * 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.
+ */
+export declare function reactivePathOf(expression: Expression): ReactivePath | null;
+/**
+ * D114 0.28.0 H-D1: the steps a written place takes *below* the watch subject,
+ * `[]` when the write is the subject itself, and null when it is neither. §15
+ * says a watch fires on a deep change of its subject, so a write of a part of
+ * the subject is the same ring as a write of the subject — and a sibling
+ * (`watch form.name:` writing `form.email`) or a different root is not.
+ */
+export declare function reactiveStepsBelow(subject: ReactivePath, written: ReactivePath): readonly ReactivePathStep[] | null;
+/**
+ * D114 W: the calls that mutate the value at one place, or null where the place
+ * holds no collection. One reading of the compiler's own roster, asked of the
+ * subject and of any place below it alike, so a deep mutating call and a direct
+ * one can never disagree about which methods write.
+ */
+export declare function collectionMutators(place: ValueType): ReadonlySet<string> | null;
+/** The root name a reactive path starts from, which is the binding it resolves through. */
+export declare function reactivePathRoot(expression: Expression): string | null;
+/**
+ * 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.
+ */
+export declare function statementBindsName(statement: Statement, name: string): boolean;
+/**
+ * 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.
+ */
+export declare function topLevelCall(statement: Statement): Extract<Expression, {
+    readonly kind: "CallExpression";
+}> | null;
+/**
+ * D114 W: the reactive place one plain body statement writes, and how. An
+ * assignment or a compound assignment names its target and no method; a call
+ * names its receiver and the method called on it, and the caller decides
+ * whether that method mutates — the roster depends on the kind of value at the
+ * receiver, which only the caller holds a type for.
+ */
+export interface ReactiveWriteCandidate {
+    readonly place: ReactivePath;
+    /** The method called on `place`, or null when the statement is an assignment. */
+    readonly method: string | null;
+}
+export declare function reactiveWriteCandidate(statement: Statement): ReactiveWriteCandidate | null;
+/**
+ * D114 W: whether one plain body statement writes the watched place — the
+ * subject itself, or any place below it. 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 `mutators`
+ * answers the compiler's own roster of the calls that mutate whatever sits at
+ * that depth.
+ *
+ * D114 0.28.0 H-D1's other half: `watch form: rename()` where `rename` writes
+ * `form.name` is the same ring as `watch form: form.name = …`, which F1 already
+ * refuses. The subject and the writer question read one comparison —
+ * `reactiveStepsBelow` — so a deep write cannot be a cycle at one of them and
+ * not at the other.
+ */
+export declare function reactiveWriteOf(statement: Statement, subject: ReactivePath, writes: ReactiveSubjectWrite): ReactivePath | null;
+/**
+ * Whether a write `steps` below the watched subject, made the given way, is a
+ * write of the subject. Only the analyzer can answer it — the roster of
+ * mutating calls depends on the type at that depth — so both the body scan and
+ * the one-hop writer scan are handed the same closure rather than each deciding
+ * what counts as a write.
+ */
+export type ReactiveSubjectWrite = (steps: readonly ReactivePathStep[], method: string | null) => boolean;
+/**
+ * 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.
+ */
+export declare function writerWritesPath(writer: ReactiveWriterDeclaration, subject: ReactivePath, writes: ReactiveSubjectWrite): ReactivePath | null;
+/**
+ * D114 W A2(b): the `action` and `async def` declarations of one module, by
+ * name. A name declared twice — or once as an ordinary `def` — answers `null`,
+ * because the refusal must know exactly which body a call reaches and two
+ * candidates mean it does not.
+ *
+ * The walk is `collectModuleFunctions`'s: module body, component bodies, and
+ * the bodies of the functions themselves, so a nested declaration of a name
+ * makes that name ambiguous here rather than silently resolving to the outer
+ * one.
+ */
+export interface ReactiveWriterDeclaration {
+    readonly spelling: "action" | "async def";
+    readonly parameters: readonly string[];
+    readonly body: readonly Statement[];
+}
+export declare function collectReactiveWriters(program: Program): ReadonlyMap<string, ReactiveWriterDeclaration | null>;
+/**
+ * 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.
+ */
+export declare function watchSelfWrite(subject: Expression, place: ReactivePath, statement: Statement, writes: ReactiveSubjectWrite, position?: string): string | null;
+/**
+ * D114 0.29.0 ST-D2: `finally` is the one nested block a body cannot get out of.
+ * §15 refuses a body whose top level *unconditionally* writes its own subject,
+ * and "nested" had been standing in for "conditional" — but a `for` body may run
+ * zero times, a `try` body may be cut short by a throw and a `match` arm is
+ * chosen by data, while every path through a `try` at the body's top level
+ * passes through its `finally`. So the write there is proved the same way a
+ * top-level write is, and only there: a `try` inside an `if` is a conditional
+ * again and stays the runtime cap's (ST-U1).
+ */
+export declare function finallySelfWrite(subject: Expression, place: ReactivePath, statement: Statement, writes: ReactiveSubjectWrite, root: string): {
+    readonly message: string;
+    readonly span: Span;
+} | null;
+//# sourceMappingURL=watch-cycles.d.ts.map