@atscript/db 0.1.161 → 0.1.162

package/dist/{validation-utils-CtLNlBtB.cjs → view-validation-D50KWU7O.cjs}

@@ -1,16 +1,59 @@
-const require_search_fields = require("./search-fields-CT_UZ9fg.cjs");
+const require_aggregate_fns = require("./aggregate-fns-DupYzFD7.cjs");
+const require_search_fields = require("./search-fields-Bi1n-pB1.cjs");
 let _atscript_core = require("@atscript/core");
 //#region src/shared/annotation-utils.ts
-/** Asserts the field carrying this annotation does not also carry any of `others`. */
-function validateExclusiveWith(token, selfName, others) {
+/**
+* Names of a field's effective annotations: its own plus the ones it inherits
+* through its type ref (`price: Order.price`), with the `passedWhenReferred:
+* false` ones dropped — the set codegen writes into the field's runtime
+* metadata (`AtscriptDoc.evalAnnotationsForNode`). Compile checks that mirror
+* a runtime metadata check read this, not the own-only `countAnnotations`.
+* @since 0.1.162
+*/
+function effectiveAnnotationNames(field, doc) {
+	const names = new Set(field.annotations?.map((a) => a.name));
+	for (const a of doc.evalAnnotationsForNode(field) ?? []) names.add(a.name);
+	return names;
+}
+/**
+* Asserts the field carrying this annotation does not also carry any of
+* `others` — its own or inherited through its type ref (since 0.1.162).
+*/
+function validateExclusiveWith(token, selfName, others, doc) {
 	const errors = [];
 	const field = token.parentNode;
-	for (const { key, displayName } of others) if (field.countAnnotations(key) > 0) errors.push({
-		message: `${selfName} cannot coexist with ${displayName ?? `@${key}`} on the same field — pick one form, not both`,
+	const effective = effectiveAnnotationNames(field, doc);
+	for (const { key, displayName } of others) {
+		if (!effective.has(key)) continue;
+		const inherited = field.countAnnotations(key) === 0;
+		errors.push({
+			message: inherited ? `${selfName} cannot coexist with ${displayName ?? `@${key}`}, which this field inherits from its type reference — pick one form, not both` : `${selfName} cannot coexist with ${displayName ?? `@${key}`} on the same field — pick one form, not both`,
+			severity: 1,
+			range: token.range
+		});
+	}
+	return errors;
+}
+/**
+* Reports each of `pairs` (`[annotation, why]`) the field carrying `token`
+* also carries — its own or inherited through its type ref (the field's
+* effective annotations, what the runtime mirror reads off the metadata):
+* `${tag} cannot coexist with @${annotation} — ${why}`.
+* @since 0.1.162
+*/
+function validateIncompatible(token, tag, pairs, doc) {
+	const effective = effectiveAnnotationNames(token.parentNode, doc);
+	return pairs.filter(([name]) => effective.has(name)).map(([name, why]) => ({
+		message: `${tag} cannot coexist with @${name} — ${why}`,
 		severity: 1,
 		range: token.range
-	});
-	return errors;
+	}));
+}
+/** Whether a prop is a field of a view interface (`@db.view` / `@db.view.for`). */
+function isViewField(field) {
+	const struct = field.ownerNode;
+	const owner = struct && (0, _atscript_core.isStructure)(struct) ? struct.ownerNode : void 0;
+	return !!owner && (0, _atscript_core.isInterface)(owner) && (owner.countAnnotations("db.view") > 0 || owner.countAnnotations("db.view.for") > 0);
 }
 /** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
 function primitiveBaseType(def) {
@@ -52,15 +95,19 @@ function searchFieldVerdict(field, doc) {
 	const leaf = doc.unwindType(def.id, def.chain)?.def;
 	const base = primitiveBaseType(leaf);
 	if (base === void 0) return { kind: "other" };
+	const effective = effectiveAnnotationNames(field, doc);
 	const kind = require_search_fields.searchKindOf({
 		base,
 		tags: (0, _atscript_core.isPrimitive)(leaf) ? leaf.tags : void 0,
-		expectInt: field.countAnnotations("expect.int") > 0,
-		increment: field.countAnnotations("db.default.increment") > 0,
-		now: field.countAnnotations("db.default.now") > 0,
-		precision: field.countAnnotations("db.column.precision") > 0
+		expectInt: effective.has("expect.int"),
+		increment: effective.has("db.default.increment"),
+		now: effective.has("db.default.now"),
+		precision: effective.has("db.column.precision")
 	});
-	if (typeof kind === "object") return kind;
+	if (typeof kind === "object") {
+		if (kind.problem === require_search_fields.SEARCH_PROBLEM.float && isViewField(field)) return { problem: require_search_fields.SEARCH_PROBLEM.floatViewField };
+		return kind;
+	}
 	return { kind: kind === "integer" ? "integer" : base === "string" ? "string" : "other" };
 }
 /**
@@ -173,12 +220,7 @@ function getAnnotationAlias(prop, annotationName) {
 */
 function refActionAnnotation(name) {
 	return new _atscript_core.AnnotationSpec({
-		description: `Referential action when the target ${name === "onDelete" ? "row is deleted" : "key is updated"}. Only valid on @db.rel.FK fields.\n\n**Example:**
-\`\`\`atscript
-@db.rel.FK
-@db.rel.${name} "cascade"\nauthorId: User.id
-\`\`\`
-`,
+		description: (0, _atscript_core.annotationExample)(`Referential action when the target ${name === "onDelete" ? "row is deleted" : "key is updated"}. Only valid on @db.rel.FK fields.`, "@db.rel.FK", `@db.rel.${name} "cascade"`, "authorId: User.id"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -468,18 +510,356 @@ function forEachFieldRef(expr, fn) {
 	}
 }
 //#endregion
+//#region src/shared/view-validation.ts
+/** `@db.agg.*` annotations that are never NULL (the counts: 0 over no value). */
+const NULL_SAFE_AGG_ANNOTATIONS = require_aggregate_fns.SUPPORTED_AGGREGATE_FNS.filter((fn) => !require_aggregate_fns.NULL_WHEN_EMPTY_AGGREGATE_FNS.has(fn)).map((fn) => `db.agg.${fn}`);
+/**
+* Walks a chain ref step by step (`Order.payload`, `Order.payload.customer`, …)
+* and reports the JSON root, arrays, encryption, optionality and the leaf type.
+* A chain shorter than 2 is not a field path (`resolved: false`).
+* @since 0.1.141
+*/
+function jsonChainInfo(ref, doc) {
+	const typeName = ref.id ?? "";
+	const chain = ref.chain.map((t) => t.text);
+	const info = {
+		typeName,
+		chain,
+		resolved: false,
+		viaArray: false,
+		viaEncrypted: false,
+		optional: false
+	};
+	if (!typeName || chain.length < 2) return info;
+	for (let i = 1; i <= chain.length; i++) {
+		const step = doc.unwindType(typeName, chain.slice(0, i));
+		if (!step) return info;
+		const node = step.node;
+		const prop = node && (0, _atscript_core.isProp)(node) ? node : void 0;
+		if (prop?.has("optional")) info.optional = true;
+		if (prop && prop.countAnnotations("db.encrypted") > 0) info.viaEncrypted = true;
+		const isJsonProp = prop !== void 0 && prop.countAnnotations("db.json") > 0;
+		const isArr = (0, _atscript_core.isArray)(step.def);
+		if (isArr) info.viaArray = true;
+		if (info.jsonRoot === void 0 && (isJsonProp || isArr)) info.jsonRoot = i;
+		if (i === chain.length) info.leafType = primitiveBaseType(step.def);
+	}
+	info.resolved = true;
+	return info;
+}
+/**
+* The read seals a view field takes from the source field it reads, as the
+* compiler sees them (compile-time mirror of the runtime `sourceFieldSeals`,
+* which stamps them onto the view column — these annotations are
+* `passedWhenReferred: false`, so they are not in the field's own metadata):
+* - `writeOnly` — the source path or an ancestor object is `@db.writeOnly`;
+* - `encrypted` — the source path or an ancestor object is `@db.encrypted`.
+*
+* (A `@db.json` source is no seal: a view reads a primitive JSON column's
+* typed value, and an object one needs its own `@db.json`.)
+*
+* The source is the chain ref (`pin?: Account.pin`), or else the entry table's
+* same-named field (or an aggregate's field) of a `@db.view.for` view. A source
+* field that is itself a view field passes on its own seals. Computed fields
+* and fields of anything but a view report no seal.
+* @since 0.1.162
+*/
+function viewFieldSeals(field, doc, depth = 0) {
+	const seals = {
+		writeOnly: false,
+		encrypted: false
+	};
+	if (depth > 8 || !isViewField(field) || field.countAnnotations("db.compute") > 0) return seals;
+	let typeName;
+	let path;
+	const def = field.getDefinition();
+	if (def && (0, _atscript_core.isRef)(def) && def.hasChain) {
+		typeName = def.id;
+		path = def.chain.map((t) => t.text);
+	} else {
+		const view = field.ownerNode.ownerNode;
+		typeName = getAnnotationAlias(view, "db.view.for");
+		const agg = field.annotations?.find((a) => require_aggregate_fns.AGG_ANNOTATIONS.includes(a.name));
+		const aggField = agg?.args[0]?.text;
+		if (agg && (!aggField || aggField === "*")) return seals;
+		path = (aggField ?? field.id ?? "").split(".");
+	}
+	if (!typeName || !path.length || !path[0]) return seals;
+	let step = doc.unwindType(typeName, [path[0]]);
+	for (let i = 1; step; i++) {
+		const node = step.node;
+		if (node && (0, _atscript_core.isProp)(node)) {
+			if (node.countAnnotations("db.writeOnly") > 0) seals.writeOnly = true;
+			if (node.countAnnotations("db.encrypted") > 0) seals.encrypted = true;
+			const inner = viewFieldSeals(node, step.doc, depth + 1);
+			seals.writeOnly ||= inner.writeOnly;
+			seals.encrypted ||= inner.encrypted;
+		}
+		if (i === path.length) break;
+		step = propStep(step, path[i]);
+	}
+	return seals;
+}
+/** The step to the `name` prop of `step`'s object definition — its type ref resolved. */
+function propStep(step, name) {
+	const def = step.def;
+	const prop = (0, _atscript_core.isInterface)(def) || (0, _atscript_core.isStructure)(def) ? def.props.get(name) : void 0;
+	const propDef = prop?.getDefinition();
+	if (!prop || !propDef) return void 0;
+	if (!(0, _atscript_core.isRef)(propDef)) return {
+		doc: step.doc,
+		node: prop,
+		def: propDef
+	};
+	const unwound = step.doc.unwindType(propDef.id, propDef.chain);
+	return unwound && {
+		doc: unwound.doc,
+		node: prop,
+		def: unwound.def
+	};
+}
+/** {@link viewFieldSeals} of `field`, computed on first use. */
+function lazySeals(field, doc) {
+	let seals;
+	return () => seals ??= viewFieldSeals(field, doc);
+}
+/**
+* A search annotation (`@db.column.searchable` / `@db.index.fulltext`) on a
+* view field whose source is `@db.writeOnly` — a search hit would reveal the
+* sealed value (the runtime refuses it at sync and on every query), or
+* `undefined`. The field's own `@db.writeOnly` is reported by that spec.
+* @since 0.1.162
+*/
+function viewSourceSealProblem(token, doc, annotation, seals = lazySeals(token.parentNode, doc)) {
+	const field = token.parentNode;
+	if (field.countAnnotations("db.writeOnly") > 0) return void 0;
+	if (!seals().writeOnly) return void 0;
+	return {
+		message: `${annotation} on "${field.id}", which reads a @db.writeOnly source field — search results would reveal the sealed value`,
+		severity: 1,
+		range: token.range
+	};
+}
+/**
+* A search / index feature (`@db.column.searchable`, `@db.index.fulltext`,
+* `@db.index.geo`, `@db.search.vector`, `@db.search.filter`) on a field that
+* would read ciphertext: a field inside an `@db.encrypted` object, or a view
+* field over an encrypted source — or `undefined`. The field's own
+* `@db.encrypted` is reported by that spec.
+* @since 0.1.162
+*/
+function encryptedSearchProblem(token, doc, annotation) {
+	return encryptedProblem(token, annotation, lazySeals(token.parentNode, doc));
+}
+function encryptedProblem(token, annotation, seals) {
+	const field = token.parentNode;
+	if (field.countAnnotations("db.encrypted") > 0) return void 0;
+	const where = encryptedAncestorName(field);
+	const why = where !== void 0 ? `it is inside the @db.encrypted field "${where}"` : seals().encrypted ? "it reads a @db.encrypted source field" : void 0;
+	if (!why) return void 0;
+	return {
+		message: `${annotation} on "${field.id}" — ${why}; search over ciphertext is impossible`,
+		severity: 1,
+		range: token.range
+	};
+}
+/**
+* {@link viewSourceSealProblem}, else {@link encryptedSearchProblem} — the
+* view field's source seals computed once.
+*/
+function sealedSearchProblem(token, doc, annotation) {
+	const seals = lazySeals(token.parentNode, doc);
+	return viewSourceSealProblem(token, doc, annotation, seals) ?? encryptedProblem(token, annotation, seals);
+}
+/**
+* An annotation's `validate` refusing it on a field that reads ciphertext
+* ({@link encryptedSearchProblem}) — for the search features of sibling
+* adapter plugins too.
+* @since 0.1.162
+*/
+function refuseCiphertext(annotation) {
+	return (token, _args, doc) => {
+		const problem = encryptedSearchProblem(token, doc, annotation);
+		return problem ? [problem] : [];
+	};
+}
+/**
+* Navigation relation annotations — a navigation field holds another table's
+* rows, never part of this table's stored value.
+* @since 0.1.162
+*/
+const NAV_ANNOTATIONS = [
+	"db.rel.to",
+	"db.rel.from",
+	"db.rel.via"
+];
+/** Whether a prop is a navigation field ({@link NAV_ANNOTATIONS}). */
+function isNavProp(prop) {
+	return NAV_ANNOTATIONS.some((key) => prop.countAnnotations(key) > 0);
+}
+/**
+* Walks the fields stored in `root` (an interface, a structure or a type ref)
+* depth-first — nested objects and type refs included, navigation fields and
+* arrays skipped — and returns the first non-`undefined` result of `visit`.
+* `path` is the field's dotted path below `prefix`; `viaRef` tells whether
+* a type ref was followed to reach it.
+* @since 0.1.162
+*/
+function findStoredField(root, doc, visit, prefix = "") {
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (def, defDoc, viaRef, prefix) => {
+		if (!def || seen.has(def)) return void 0;
+		seen.add(def);
+		if ((0, _atscript_core.isRef)(def)) {
+			const unwound = defDoc.unwindType(def.id, def.chain);
+			return unwound ? walk(unwound.def, unwound.doc, true, prefix) : void 0;
+		}
+		const props = (0, _atscript_core.isInterface)(def) || (0, _atscript_core.isStructure)(def) ? def.props : void 0;
+		if (!props) return void 0;
+		for (const [name, prop] of props) {
+			if (isNavProp(prop)) continue;
+			const path = prefix ? `${prefix}.${name}` : name;
+			const found = visit(prop, path, viaRef) ?? walk(prop.getDefinition(), defDoc, viaRef, path);
+			if (found !== void 0) return found;
+		}
+	};
+	return walk(root, doc, false, prefix);
+}
+/**
+* A search feature ({@link ENCRYPTED_SEARCH_FEATURES}) declared inside the
+* TYPE of the `@db.encrypted` field carrying `token`, reached through a type
+* ref (`@db.encrypted profile: Address`, where `Address` has
+* `@db.index.fulltext city`) — the shared type's own annotations cannot see
+* that this use encrypts them. Fields declared inline are reported by their
+* own annotation (see {@link encryptedSearchProblem}).
+* @since 0.1.162
+*/
+function encryptedTypeSearchProblem(token, doc) {
+	const field = token.parentNode;
+	const found = findStoredField(field.getDefinition(), doc, (prop, path, viaRef) => {
+		if (!viaRef) return void 0;
+		const feature = require_search_fields.ENCRYPTED_SEARCH_FEATURES.find((key) => prop.countAnnotations(key) > 0);
+		return feature ? {
+			path,
+			feature
+		} : void 0;
+	}, field.id ?? "");
+	if (!found) return void 0;
+	return {
+		message: `@db.encrypted on "${field.id}" — its type declares @${found.feature} on "${found.path}"; search over ciphertext is impossible`,
+		severity: 1,
+		range: token.range
+	};
+}
+/** Name of the nearest `@db.encrypted` prop enclosing `field` (inline nested objects), if any. */
+function encryptedAncestorName(field) {
+	for (let node = field.ownerNode; node; node = node.ownerNode) if ((0, _atscript_core.isProp)(node) && node.countAnnotations("db.encrypted") > 0) return node.id;
+}
+/** Props of a view interface (its own structure; views don't use `extends`). */
+function viewProps(owner) {
+	if ((0, _atscript_core.isInterface)(owner)) return owner.props;
+	const def = owner.getDefinition();
+	return def && (0, _atscript_core.isStructure)(def) ? def.props : void 0;
+}
+/**
+* VW8: a chain ref that passes through a `@db.json` or array node reads a
+* JSON leaf, which views can only extract as a string / number / boolean.
+* Intermediate nodes that `unwindType` can't reach are skipped (sync-time
+* resolution reports them).
+*/
+function validateJsonChain(fieldName, ref, doc, range) {
+	const info = jsonChainInfo(ref, doc);
+	if (!info.resolved || info.jsonRoot === void 0 || info.jsonRoot >= info.chain.length) return [];
+	if (info.leafType !== void 0 && require_search_fields.JSON_LEAF_TYPES.has(info.leafType)) return [];
+	return [{
+		message: `Field "${fieldName}" reads "${info.typeName}.${info.chain.join(".")}" inside a JSON-stored field — it must end at a string, number or boolean leaf`,
+		severity: 1,
+		range
+	}];
+}
+/**
+* Whole-view checks, run once per `@db.view.for` interface:
+*
+* - VW7 — a field reading from a left-joined table must be optional (the
+*   join yields NULL for unmatched rows); `@db.agg.count` / `countDistinct`
+*   fields are exempt (they count 0, never NULL).
+* - VW8 — a chain ref through a `@db.json` or array node must end at a
+*   primitive string / number / boolean leaf.
+* @since 0.1.136
+*/
+function validateViewInterface(owner, doc) {
+	const errors = [];
+	const props = viewProps(owner);
+	if (!props) return errors;
+	const leftJoined = /* @__PURE__ */ new Set();
+	for (const join of viewJoins(owner)) {
+		const target = join.args[0]?.text;
+		if (target && join.args[2]?.text === "left") leftJoined.add(target);
+	}
+	for (const [fieldName, prop] of props) {
+		const def = prop.getDefinition();
+		if (!def || !(0, _atscript_core.isRef)(def)) continue;
+		const ref = def;
+		const range = (prop.token("identifier") ?? ref.token("identifier"))?.range;
+		if (!range) continue;
+		if (ref.id && leftJoined.has(ref.id) && !prop.has("optional") && !NULL_SAFE_AGG_ANNOTATIONS.some((name) => prop.countAnnotations(name) > 0)) errors.push({
+			message: `Field "${fieldName}" reads from left-joined "${ref.id}" and must be optional (${fieldName}?: …)`,
+			severity: 1,
+			range
+		});
+		errors.push(...validateJsonChain(fieldName, ref, doc, range));
+	}
+	return errors;
+}
+//#endregion
+Object.defineProperty(exports, "NAV_ANNOTATIONS", {
+	enumerable: true,
+	get: function() {
+		return NAV_ANNOTATIONS;
+	}
+});
 Object.defineProperty(exports, "earlierJoinTargets", {
 	enumerable: true,
 	get: function() {
 		return earlierJoinTargets;
 	}
 });
+Object.defineProperty(exports, "effectiveAnnotationNames", {
+	enumerable: true,
+	get: function() {
+		return effectiveAnnotationNames;
+	}
+});
+Object.defineProperty(exports, "encryptedAncestorName", {
+	enumerable: true,
+	get: function() {
+		return encryptedAncestorName;
+	}
+});
+Object.defineProperty(exports, "encryptedSearchProblem", {
+	enumerable: true,
+	get: function() {
+		return encryptedSearchProblem;
+	}
+});
+Object.defineProperty(exports, "encryptedTypeSearchProblem", {
+	enumerable: true,
+	get: function() {
+		return encryptedTypeSearchProblem;
+	}
+});
 Object.defineProperty(exports, "findFKFieldsPointingTo", {
 	enumerable: true,
 	get: function() {
 		return findFKFieldsPointingTo;
 	}
 });
+Object.defineProperty(exports, "findStoredField", {
+	enumerable: true,
+	get: function() {
+		return findStoredField;
+	}
+});
 Object.defineProperty(exports, "findViewCycle", {
 	enumerable: true,
 	get: function() {
@@ -546,18 +926,36 @@ Object.defineProperty(exports, "isDbSourceDecl", {
 		return isDbSourceDecl;
 	}
 });
+Object.defineProperty(exports, "isNavProp", {
+	enumerable: true,
+	get: function() {
+		return isNavProp;
+	}
+});
 Object.defineProperty(exports, "isNullableUnion", {
 	enumerable: true,
 	get: function() {
 		return isNullableUnion;
 	}
 });
+Object.defineProperty(exports, "isViewField", {
+	enumerable: true,
+	get: function() {
+		return isViewField;
+	}
+});
 Object.defineProperty(exports, "joinTargets", {
 	enumerable: true,
 	get: function() {
 		return joinTargets;
 	}
 });
+Object.defineProperty(exports, "jsonChainInfo", {
+	enumerable: true,
+	get: function() {
+		return jsonChainInfo;
+	}
+});
 Object.defineProperty(exports, "primitiveBaseType", {
 	enumerable: true,
 	get: function() {
@@ -570,6 +968,18 @@ Object.defineProperty(exports, "refActionAnnotation", {
 		return refActionAnnotation;
 	}
 });
+Object.defineProperty(exports, "refuseCiphertext", {
+	enumerable: true,
+	get: function() {
+		return refuseCiphertext;
+	}
+});
+Object.defineProperty(exports, "sealedSearchProblem", {
+	enumerable: true,
+	get: function() {
+		return sealedSearchProblem;
+	}
+});
 Object.defineProperty(exports, "searchFieldVerdict", {
 	enumerable: true,
 	get: function() {
@@ -588,6 +998,12 @@ Object.defineProperty(exports, "validateFieldBaseType", {
 		return validateFieldBaseType;
 	}
 });
+Object.defineProperty(exports, "validateIncompatible", {
+	enumerable: true,
+	get: function() {
+		return validateIncompatible;
+	}
+});
 Object.defineProperty(exports, "validateQueryScope", {
 	enumerable: true,
 	get: function() {
@@ -606,12 +1022,30 @@ Object.defineProperty(exports, "validateSiblingStringField", {
 		return validateSiblingStringField;
 	}
 });
+Object.defineProperty(exports, "validateViewInterface", {
+	enumerable: true,
+	get: function() {
+		return validateViewInterface;
+	}
+});
+Object.defineProperty(exports, "viewFieldSeals", {
+	enumerable: true,
+	get: function() {
+		return viewFieldSeals;
+	}
+});
 Object.defineProperty(exports, "viewJoins", {
 	enumerable: true,
 	get: function() {
 		return viewJoins;
 	}
 });
+Object.defineProperty(exports, "viewProps", {
+	enumerable: true,
+	get: function() {
+		return viewProps;
+	}
+});
 Object.defineProperty(exports, "viewScopeTypes", {
 	enumerable: true,
 	get: function() {