@supatype/cli 0.1.6 → 0.1.7

package/dist/type-extractor.js

@@ -14,7 +14,7 @@ export function extractSchemaAstFromTypes(schemaPath, cwd = process.cwd()) {
     const bucketAliases = new Map();
     const bucketsById = new Map();
     for (const sourceFile of sourceFiles) {
-        const bucketContext = collectBucketContext(sourceFile);
+        const bucketContext = collectBucketContext(sourceFile, resolveCtx);
         for (const [alias, bucketId] of bucketContext.aliases) {
             bucketAliases.set(alias, bucketId);
         }
@@ -64,8 +64,8 @@ export function extractSchemaAstFromTypes(schemaPath, cwd = process.cwd()) {
                     continue;
                 fields[name] = parseFieldType(name, member.type, sourceFile, blockAliases, bucketAliases, bucketsById, fieldContext, resolveCtx);
             }
-            const { tableName, access, options, indexes } = parseModelMeta(metaArg, sourceFile, stmt.name.text, fieldsArg, fields);
-            models.push(emitModel(stmt.name.text, fields, options, tableName, access, indexes));
+            const { tableName, access, options, indexes, hooks } = parseModelMeta(metaArg, sourceFile, stmt.name.text, fieldsArg, fields, resolveCtx);
+            models.push(emitModel(stmt.name.text, fields, options, tableName, access, indexes, hooks));
         }
     }
     if (models.length === 0)
@@ -713,8 +713,19 @@ function parseScalarType(typeNode, sourceFile, blockAliases, bucketAliases, buck
                 return scalar("tsVector");
             case "Money":
                 return scalar("money");
-            case "Decimal":
-                return scalar("decimal");
+            case "Decimal": {
+                // `Decimal<10, 2>` names a precision and a scale, and the engine renders `NUMERIC(p, s)`
+                // from them — but nothing used to read the type arguments, so every Decimal became an
+                // unbounded NUMERIC. Silently, which is the worst way to lose a constraint on a money column.
+                const precision = parseNumericTypeArg(typeNode.typeArguments?.[0], sourceFile);
+                const scale = parseNumericTypeArg(typeNode.typeArguments?.[1], sourceFile);
+                return scalar("decimal", {
+                    kernel: {
+                        ...(precision !== undefined && { precision }),
+                        ...(scale !== undefined && { scale }),
+                    },
+                });
+            }
             case "DateOnly":
                 return scalar("date");
             case "Date":
@@ -736,7 +747,35 @@ function parseScalarType(typeNode, sourceFile, blockAliases, bucketAliases, buck
             case "Button":
                 return scalar("button", { db: { pgType: "JSONB" } });
             case "Duration":
-                return scalar("json", { db: { pgType: "JSONB" } });
+                return scalar("json", {
+                    db: { pgType: "JSONB" },
+                    platform: { editor: "duration" },
+                    kernel: { tsType: "{ ms: number }" },
+                });
+            // `Code` and `Currency` each carry two values, so a scalar column would have to drop one:
+            // JSONB keeps `lang` with its `source`, and an amount with the currency it is denominated in.
+            // `tsType` is what stops the generated client row from flattening them to an opaque object.
+            case "Code": {
+                const lang = literalStringType(typeNode.typeArguments?.[0]);
+                return scalar("json", {
+                    db: { pgType: "JSONB" },
+                    // `editor` picks the Studio widget. Without it a code snippet and a money amount both get
+                    // the raw JSON editor, because the widget is otherwise chosen from the column kind alone
+                    // and both of these are JSONB.
+                    platform: { editor: "code" },
+                    kernel: { tsType: `{ lang: ${lang !== null ? JSON.stringify(lang) : "string"}; source: string }` },
+                });
+            }
+            case "Currency": {
+                const currencyCode = literalStringType(typeNode.typeArguments?.[0]);
+                return scalar("json", {
+                    db: { pgType: "JSONB" },
+                    platform: { editor: "currency" },
+                    kernel: {
+                        tsType: `{ amount: string; code: ${currencyCode !== null ? JSON.stringify(currencyCode) : "string"} }`,
+                    },
+                });
+            }
             case "GeoPoint":
             case "Geo":
                 return scalar("geo", { kernel: { geoType: "point", srid: 4326 } });
@@ -842,7 +881,7 @@ function parseStringLiteralTuple(node, sourceFile) {
     }
     return out;
 }
-function collectBucketContext(sourceFile) {
+function collectBucketContext(sourceFile, resolveCtx) {
     const aliases = new Map();
     const bucketsById = new Map();
     for (const stmt of sourceFile.statements) {
@@ -858,7 +897,7 @@ function collectBucketContext(sourceFile) {
         const id = nameArg.literal.text;
         aliases.set(stmt.name.text, id);
         const parsed = configArg && ts.isTypeLiteralNode(configArg)
-            ? parseBucketTypeLiteral(configArg, sourceFile)
+            ? parseBucketTypeLiteral(configArg, sourceFile, id, resolveCtx)
             : {};
         const next = buildExtractedBucketAst(id, parsed);
         const existing = bucketsById.get(id);
@@ -886,7 +925,7 @@ function buildExtractedBucketAst(id, parsed) {
     };
     return row;
 }
-function parseBucketTypeLiteral(lit, sourceFile) {
+function parseBucketTypeLiteral(lit, sourceFile, bucketId, resolveCtx) {
     const out = {};
     for (const member of lit.members) {
         if (!ts.isPropertySignature(member) || !member.type)
@@ -915,7 +954,7 @@ function parseBucketTypeLiteral(lit, sourceFile) {
             continue;
         }
         if (key === "access") {
-            const acc = parsePartialBucketAccess(member.type, sourceFile);
+            const acc = parsePartialBucketAccess(member.type, sourceFile, bucketId, resolveCtx);
             if (acc !== undefined && Object.keys(acc).length > 0)
                 out.access = acc;
             continue;
@@ -971,17 +1010,26 @@ function parseMimeAcceptList(typeNode, sourceFile) {
     }
     return undefined;
 }
-function parsePartialBucketAccess(typeNode, sourceFile) {
-    if (!ts.isTypeLiteralNode(typeNode))
-        return undefined;
+function parsePartialBucketAccess(typeNode, sourceFile, bucketId, resolveCtx) {
+    // Same hazard as model access: silently dropping these rules publishes a
+    // bucket with no read/write restrictions, so an alias must resolve and an
+    // unresolvable annotation must fail rather than degrade to "no rules".
+    const literal = resolveAccessLiteral(typeNode, sourceFile, resolveCtx);
+    if (!literal) {
+        throw new Error(`Bucket "${bucketId}": could not resolve its \`access\` rules from ` +
+            `\`${typeNode.getText(sourceFile)}\`.\n` +
+            `  access must be an object type, or a type alias for one, e.g.\n` +
+            `    export type MediaAccess = { read: Public; create: Authenticated }\n` +
+            `  Refusing to continue: an unresolved access block would leave this bucket unrestricted.`);
+    }
     const access = {};
-    for (const member of typeNode.members) {
+    for (const member of literal.members) {
         if (!ts.isPropertySignature(member) || !member.type)
             continue;
         const key = getPropertyName(member.name);
         if (key !== "read" && key !== "create" && key !== "delete")
             continue;
-        access[key] = parseAccessRule(member.type, sourceFile);
+        access[key] = parseAccessRule(member.type, sourceFile, resolveCtx);
     }
     return access;
 }
@@ -1249,7 +1297,7 @@ function hasCompositeWrapper(typeNode, wrapperName) {
     }
     return false;
 }
-function parseModelMeta(metaArg, sourceFile, modelName, fieldsArg, fields) {
+function parseModelMeta(metaArg, sourceFile, modelName, fieldsArg, fields, resolveCtx) {
     const literal = parseMetaLiteral(metaArg, sourceFile);
     const singleton = literal.singleton === true;
     const tableName = literal.tableName ?? (singleton ? `_global_${toSnakeCase(modelName)}` : toSnakeCase(modelName));
@@ -1269,9 +1317,76 @@ function parseModelMeta(metaArg, sourceFile, modelName, fieldsArg, fields) {
         options.autoLocalize = true;
     return {
         tableName,
-        access: parseModelAccess(metaArg, sourceFile),
+        access: parseModelAccess(metaArg, sourceFile, modelName, fields, resolveCtx),
         options,
         indexes: parseModelIndexes(metaArg, sourceFile, fields),
+        hooks: parseModelHooks(metaArg, sourceFile),
+    };
+}
+const HOOK_EVENTS = ["beforeChange", "afterChange", "beforeDelete", "afterDelete"];
+/**
+ * Read `hooks` from a model's meta.
+ *
+ * Deliberately strict: an entry that is neither a string nor an object with a `function` name is
+ * **dropped**, and `validateModelHooks` then reports the model whose hook did not survive. A hook
+ * silently not firing is the failure this feature cannot have, so an unreadable declaration must
+ * fail the push rather than extract to nothing.
+ */
+function parseModelHooks(metaArg, sourceFile) {
+    if (!metaArg || !ts.isTypeLiteralNode(metaArg))
+        return {};
+    const hooksProp = metaArg.members.find((member) => ts.isPropertySignature(member) && getPropertyName(member.name) === "hooks");
+    if (!hooksProp || !ts.isPropertySignature(hooksProp) || !hooksProp.type)
+        return {};
+    if (!ts.isTypeLiteralNode(hooksProp.type))
+        return {};
+    const hooks = {};
+    for (const member of hooksProp.type.members) {
+        if (!ts.isPropertySignature(member) || !member.type)
+            continue;
+        const event = getPropertyName(member.name);
+        if (!event || !HOOK_EVENTS.includes(event))
+            continue;
+        const parsed = parseModelHookValue(member.type, sourceFile);
+        if (parsed !== null)
+            hooks[event] = parsed;
+    }
+    return hooks;
+}
+function parseModelHookValue(node, sourceFile) {
+    const literal = literalStringType(node);
+    if (literal !== null) {
+        return literal.trim().length > 0 ? { function: literal } : null;
+    }
+    if (!ts.isTypeLiteralNode(node))
+        return null;
+    let fn;
+    let timeout;
+    let onUnavailable;
+    for (const member of node.members) {
+        if (!ts.isPropertySignature(member) || !member.type)
+            continue;
+        const key = getPropertyName(member.name);
+        if (key === "function") {
+            const value = literalStringType(member.type);
+            if (value !== null && value.trim().length > 0)
+                fn = value;
+        }
+        else if (key === "timeout") {
+            timeout = parseNumericTypeArg(member.type, sourceFile);
+        }
+        else if (key === "onUnavailable") {
+            const value = literalStringType(member.type);
+            if (value === "reject" || value === "log")
+                onUnavailable = value;
+        }
+    }
+    if (fn === undefined)
+        return null;
+    return {
+        function: fn,
+        ...(timeout !== undefined && { timeout }),
+        ...(onUnavailable !== undefined && { onUnavailable }),
     };
 }
 function parseModelIndexes(metaArg, sourceFile, fields) {
@@ -1327,28 +1442,236 @@ function resolveIndexFieldName(fieldName, fields) {
     }
     return fieldName;
 }
-function parseModelAccess(metaArg, sourceFile) {
+/**
+ * Resolve an `access:` annotation to its rule object.
+ *
+ * `access` may be written inline (`access: { read: Public }`) or factored into a
+ * shared type alias (`access: CmsPublicReadAdminWrite`) — the latter is the
+ * natural way to reuse one policy set across many models, so it has to resolve
+ * through aliases and intersections, not just literals.
+ *
+ * Anything unresolvable throws. Returning `{}` here means "no access rules",
+ * which the differ treats as "emit no RLS policies" — so a typo or an
+ * unsupported shape silently published a table with no row-level protection at
+ * all. Failing the extract is the only safe outcome.
+ */
+function parseModelAccess(metaArg, sourceFile, modelName, fields, resolveCtx) {
     if (!metaArg || !ts.isTypeLiteralNode(metaArg))
         return {};
     const accessProp = metaArg.members.find((member) => ts.isPropertySignature(member) && getPropertyName(member.name) === "access");
-    if (!accessProp || !ts.isPropertySignature(accessProp) || !accessProp.type || !ts.isTypeLiteralNode(accessProp.type)) {
+    if (!accessProp || !ts.isPropertySignature(accessProp) || !accessProp.type) {
         return {};
     }
+    const literal = resolveAccessLiteral(accessProp.type, sourceFile, resolveCtx);
+    if (!literal) {
+        throw new Error(`Model "${modelName}": could not resolve its \`access\` rules from ` +
+            `\`${accessProp.type.getText(sourceFile)}\`.\n` +
+            `  access must be an object type, or a type alias for one:\n` +
+            `    export type PublicReadAdminWrite = { read: Public; create: Role<"admin"> }\n` +
+            `  A \`const … as const\` value cannot be used here — access is read from types, and\n` +
+            `  rule names like Public / Role are types, not values.\n` +
+            `  Refusing to continue: an unresolved access block would publish this table with no RLS.`);
+    }
     const access = {};
-    for (const member of accessProp.type.members) {
+    for (const member of literal.members) {
         if (!ts.isPropertySignature(member) || !member.type)
             continue;
         const key = getPropertyName(member.name);
         if (!key)
             continue;
-        access[key] = parseAccessRule(member.type, sourceFile);
+        // `update: { using, check }` splits which rows may be changed from what they
+        // may be changed into. Flattened here into the two AST fields the engine
+        // renders, so the engine never has to know about the sugar.
+        if (key === "update") {
+            const split = parseUpdateSplit(member.type, sourceFile, resolveCtx);
+            if (split) {
+                access["update"] = split.using;
+                if (split.check !== undefined)
+                    access["updateCheck"] = split.check;
+                continue;
+            }
+        }
+        if (key === "fields") {
+            const fieldRules = parseFieldAccess(member.type, sourceFile, modelName, fields, resolveCtx);
+            if (Object.keys(fieldRules).length > 0)
+                access["fields"] = fieldRules;
+            continue;
+        }
+        access[key] = parseAccessRule(member.type, sourceFile, resolveCtx);
+    }
+    if (Object.keys(access).length === 0) {
+        throw new Error(`Model "${modelName}": \`access\` resolved to an empty rule set ` +
+            `(from \`${accessProp.type.getText(sourceFile)}\`). Remove \`access\` if the table is ` +
+            `intentionally unrestricted, or declare at least one of read/create/update/delete.`);
     }
     return access;
 }
-function parseAccessRule(typeNode, sourceFile) {
+/**
+ * `fields: { [column]: { read?, write? } }` — per-column narrowing of the table rules.
+ *
+ * Any rule the DSL can express is allowed. Enforcement is a query rewrite that
+ * evaluates the rule per row with the caller's claims, so ownership, membership and
+ * application roles all work here — none of which a column privilege could express.
+ */
+function parseFieldAccess(typeNode, sourceFile, modelName, fields, resolveCtx) {
+    const literal = resolveCtx
+        ? resolveAccessLiteral(typeNode, sourceFile, resolveCtx)
+        : ts.isTypeLiteralNode(typeNode)
+            ? typeNode
+            : null;
+    if (!literal) {
+        throw new Error(`Model "${modelName}": could not resolve \`access.fields\` from ` +
+            `\`${typeNode.getText(sourceFile)}\`. It must be an object type, or a type ` +
+            `alias for one: \`fields: { salary: { read: Private } }\`.`);
+    }
+    const out = {};
+    for (const member of literal.members) {
+        if (!ts.isPropertySignature(member) || !member.type)
+            continue;
+        const declared = getPropertyName(member.name);
+        if (!declared)
+            continue;
+        // A privilege is granted on a column, and a relation field is not one --
+        // `author` is stored as `author_id`. Same mapping the index builder uses.
+        // Names that match nothing are passed through rather than rejected: composite
+        // wrappers expand into columns this map never sees, so a hard error here would
+        // refuse valid schemas. Postgres rejects the unknown column at push instead.
+        const column = resolveIndexFieldName(declared, fields) ?? declared;
+        const columnLiteral = resolveCtx
+            ? resolveAccessLiteral(member.type, sourceFile, resolveCtx)
+            : ts.isTypeLiteralNode(member.type)
+                ? member.type
+                : null;
+        if (!columnLiteral) {
+            throw new Error(`Model "${modelName}": \`access.fields.${column}\` must be an object with ` +
+                `\`read\` and/or \`write\`, found \`${member.type.getText(sourceFile)}\`.`);
+        }
+        const rules = {};
+        for (const opMember of columnLiteral.members) {
+            if (!ts.isPropertySignature(opMember) || !opMember.type)
+                continue;
+            const operation = getPropertyName(opMember.name);
+            if (operation !== "read" && operation !== "write") {
+                throw new Error(`Model "${modelName}": \`access.fields.${column}\` may only contain ` +
+                    `\`read\` and \`write\`, found "${operation}".`);
+            }
+            rules[operation] = parseAccessRule(opMember.type, sourceFile, resolveCtx);
+        }
+        // An empty `{}` reads as "this column is restricted" but restricts nothing.
+        if (Object.keys(rules).length === 0) {
+            throw new Error(`Model "${modelName}": \`access.fields.${column}\` declares no rules. ` +
+                `Give it a \`read\` or a \`write\`, or remove the entry.`);
+        }
+        out[column] = rules;
+    }
+    return out;
+}
+/**
+ * `update: { using: …, check: … }`, or null when `update` is a plain rule.
+ *
+ * An update policy has two halves: `USING` picks which existing rows may be
+ * modified, `WITH CHECK` constrains what they may become. One rule for both is the
+ * right default and what every existing schema means — but it makes "an editor may
+ * move a post between their own sites" inexpressible, because the row they are
+ * changing and the row they are changing it into are judged by the same predicate.
+ */
+function parseUpdateSplit(typeNode, sourceFile, resolveCtx) {
+    const literal = resolveCtx
+        ? resolveAccessLiteral(typeNode, sourceFile, resolveCtx)
+        : ts.isTypeLiteralNode(typeNode)
+            ? typeNode
+            : null;
+    if (!literal)
+        return null;
+    let using;
+    let check;
+    for (const member of literal.members) {
+        if (!ts.isPropertySignature(member) || !member.type)
+            continue;
+        const name = getPropertyName(member.name);
+        if (name === "using")
+            using = member.type;
+        else if (name === "check")
+            check = member.type;
+        else if (name !== undefined) {
+            throw new Error(`\`update\` may only contain \`using\` and \`check\`, found "${name}".`);
+        }
+    }
+    // Not the split form at all — an object with neither key is some other shape.
+    if (!using && !check)
+        return null;
+    if (!using) {
+        throw new Error("`update: { check }` needs a `using` rule too — without it no row is " +
+            "selectable for update, so the check can never apply.");
+    }
+    const parsed = {
+        using: parseAccessRule(using, sourceFile, resolveCtx),
+    };
+    if (check)
+        parsed.check = parseAccessRule(check, sourceFile, resolveCtx);
+    return parsed;
+}
+/** Walk aliases/intersections down to the object type holding the access rules. */
+function resolveAccessLiteral(typeNode, sourceFile, resolveCtx, depth = 0) {
+    if (depth > 16)
+        return null;
+    if (ts.isTypeLiteralNode(typeNode))
+        return typeNode;
+    if (ts.isIntersectionTypeNode(typeNode)) {
+        const members = [];
+        for (const part of typeNode.types) {
+            const resolved = resolveAccessLiteral(part, sourceFile, resolveCtx, depth + 1);
+            if (!resolved)
+                return null;
+            members.push(...resolved.members);
+        }
+        return ts.factory.createTypeLiteralNode(members);
+    }
+    if (ts.isTypeReferenceNode(typeNode)) {
+        const expanded = tryResolveTypeReference(typeNode, sourceFile, resolveCtx);
+        if (expanded)
+            return resolveAccessLiteral(expanded, sourceFile, resolveCtx, depth + 1);
+    }
+    if (needsChecker(typeNode)) {
+        const resolved = resolveTypeNode(typeNode, sourceFile, resolveCtx);
+        if (resolved !== typeNode) {
+            return resolveAccessLiteral(resolved, sourceFile, resolveCtx, depth + 1);
+        }
+    }
+    return null;
+}
+/**
+ * `access` rules may be declared in a different file from the model (a shared
+ * alias), and `getText(file)` reads the given file's text at the node's offsets
+ * — so passing the model's file for a node owned by another one yielded garbage
+ * and every rule silently fell through to `private`. Always read a node's text
+ * from the file that actually owns it.
+ */
+function ownerText(node, fallback) {
+    const own = node.pos >= 0 ? node.getSourceFile() : undefined;
+    return node.getText(own ?? fallback);
+}
+function parseAccessRule(typeNode, sourceFile, resolveCtx, depth = 0) {
+    // Reuse a single rule from a shared set: `access: { read: Rules["read"] }`.
+    if (ts.isIndexedAccessTypeNode(typeNode) && resolveCtx) {
+        const member = resolveIndexedAccessRule(typeNode, sourceFile, resolveCtx);
+        if (member)
+            return parseAccessRule(member, sourceFile, resolveCtx);
+        throw new Error(`Could not resolve access rule from \`${ownerText(typeNode, sourceFile)}\`. ` +
+            `Reference a rule set member as \`Rules["read"]\`, where Rules is a type alias.`);
+    }
     if (!ts.isTypeReferenceNode(typeNode))
         return { type: "private" };
-    const ref = typeNode.typeName.getText(sourceFile);
+    // `Rules.read` is a qualified name (namespace lookup), not a member of a type
+    // alias — TypeScript rejects it, and it used to fall through to `private`,
+    // silently denying an operation the author meant to grant.
+    if (ts.isQualifiedName(typeNode.typeName)) {
+        const text = ownerText(typeNode.typeName, sourceFile);
+        const [head, ...rest] = text.split(".");
+        throw new Error(`Access rule \`${text}\` is not valid: a member of a rule-set type must be written ` +
+            `\`${head}["${rest.join(".")}"]\`, not \`${text}\`.`);
+    }
+    const ref = ownerText(typeNode.typeName, sourceFile);
     switch (ref) {
         case "Public":
         case "BucketPublic":
@@ -1365,24 +1688,389 @@ function parseAccessRule(typeNode, sourceFile) {
             const args = typeNode.typeArguments ?? [];
             const keyArg = args.length >= 2 ? args[1] : args[0];
             // Must match engine `AccessRule::Owner { field }` (see supatype-schema-engine parser/ast.rs).
-            return { type: "owner", field: keyArg?.getText(sourceFile).replace(/['"]/g, "") ?? "user_id" };
+            return {
+                type: "owner",
+                field: keyArg ? ownerText(keyArg, sourceFile).replace(/['"]/g, "") : "user_id",
+            };
         }
         case "OwnerFrom": {
             const relationArg = typeNode.typeArguments?.[0];
-            const relationField = relationArg?.getText(sourceFile).replace(/['"]/g, "") ?? "owner";
+            const relationField = relationArg
+                ? ownerText(relationArg, sourceFile).replace(/['"]/g, "")
+                : "owner";
             return { type: "owner", field: relationField };
         }
-        case "Role": {
-            const roleArg = typeNode.typeArguments?.[0];
-            return { type: "role", roles: [roleArg?.getText(sourceFile).replace(/['"]/g, "") ?? "admin"] };
-        }
+        case "Role":
         case "BucketRole": {
             const roleArg = typeNode.typeArguments?.[0];
-            return { type: "role", roles: [roleArg?.getText(sourceFile).replace(/['"]/g, "") ?? "admin"] };
+            return {
+                type: "role",
+                roles: [roleArg ? ownerText(roleArg, sourceFile).replace(/['"]/g, "") : "admin"],
+            };
+        }
+        case "Any": {
+            const listArg = typeNode.typeArguments?.[0];
+            if (!listArg || !ts.isTupleTypeNode(listArg)) {
+                throw new Error(`\`Any<>\` takes a tuple of rules, as in ` +
+                    `\`Any<[Role<"admin">, Owner<"author_id">]>\`.`);
+            }
+            // An empty list would compile to a policy that grants nothing while
+            // reading like a grant — the exact silent-denial failure the unknown-rule
+            // branch below exists to prevent.
+            if (listArg.elements.length === 0) {
+                throw new Error("`Any<[]>` grants nothing. List the rules that should allow access, or " +
+                    "use `Private` if denying is the intent.");
+            }
+            return {
+                type: "any",
+                rules: listArg.elements.map((element) => parseAccessRule(element, sourceFile, resolveCtx)),
+            };
+        }
+        case "All": {
+            const listArg = typeNode.typeArguments?.[0];
+            if (!listArg || !ts.isTupleTypeNode(listArg)) {
+                throw new Error('`All<>` takes a tuple of rules, as in `All<[Role<"editor">, NotNull<"published_at">]>`.');
+            }
+            // Unlike `Any<[]>`, an empty `All` grants *everything* — an empty AND is
+            // true. Reading as a restriction while imposing none is worse than an error.
+            if (listArg.elements.length === 0) {
+                throw new Error("`All<[]>` restricts nothing and grants everything. List the rules that " +
+                    "must hold, or use `Public` if that is the intent.");
+            }
+            return {
+                type: "all",
+                rules: listArg.elements.map((element) => parseAccessRule(element, sourceFile, resolveCtx)),
+            };
+        }
+        case "Not": {
+            const inner = typeNode.typeArguments?.[0];
+            if (!inner) {
+                throw new Error('`Not<>` takes one rule, as in `Not<Role<"banned">>`.');
+            }
+            return { type: "not", rule: parseAccessRule(inner, sourceFile, resolveCtx) };
+        }
+        case "Eq":
+        case "Neq":
+        case "Gt":
+        case "Gte":
+        case "Lt":
+        case "Lte":
+        case "Like": {
+            const args = typeNode.typeArguments ?? [];
+            if (args.length !== 2) {
+                throw new Error(`\`${ref}<>\` takes two operands, as in \`${ref}<"author_id", AuthUid>\`.`);
+            }
+            return {
+                type: "compare",
+                op: ref.toLowerCase(),
+                left: parseAccessOperand(args[0], sourceFile),
+                right: parseAccessOperand(args[1], sourceFile),
+            };
+        }
+        case "IsNull":
+        case "NotNull": {
+            const operand = typeNode.typeArguments?.[0];
+            if (!operand) {
+                throw new Error(`\`${ref}<>\` takes one operand, as in \`${ref}<"deleted_at">\`.`);
+            }
+            return {
+                type: "nullCheck",
+                operand: parseAccessOperand(operand, sourceFile),
+                isNull: ref === "IsNull",
+            };
+        }
+        case "Exists": {
+            const source = typeNode.typeArguments?.[0];
+            if (!source) {
+                throw new Error('`Exists<>` takes a source, as in `Exists<MySites>`.');
+            }
+            return {
+                type: "exists",
+                source: parseMembershipSource(source, sourceFile, resolveCtx),
+            };
+        }
+        case "In": {
+            const args = typeNode.typeArguments ?? [];
+            if (args.length !== 2) {
+                throw new Error('`In<>` takes a column and a source, as in `In<"site_id", MySites>`.');
+            }
+            const column = parseAccessOperand(args[0], sourceFile);
+            if (column["kind"] !== "column") {
+                throw new Error("`In<>`'s first argument must be a column name — the membership test is " +
+                    "about a column of the row being checked.");
+            }
+            return {
+                type: "in",
+                column: column["name"],
+                source: parseMembershipSource(args[1], sourceFile, resolveCtx),
+            };
+        }
+        default: {
+            // A named alias — possibly parameterised — standing for a rule. Expanded
+            // before giving up, so `SiteAccess<"site_id">` works.
+            if (resolveCtx && depth < 16) {
+                const expanded = resolveAccessAliasNode(typeNode, sourceFile, resolveCtx);
+                if (expanded)
+                    return parseAccessRule(expanded, sourceFile, resolveCtx, depth + 1);
+            }
+            // Falling back to `private` here would silently deny an operation the
+            // author believed they had granted — and with deny-by-default there is no
+            // longer any need for a permissive guess. Name the offending rule instead.
+            throw new Error(`Unknown access rule "${ref}". Supported: Public, Private, LoggedIn, ` +
+                `Owner<"field">, OwnerFrom<"relation">, Role<"name">, ` +
+                `Any<[rule, …]>, All<[rule, …]>, Not<rule>, ` +
+                `Eq/Neq/Gt/Gte/Lt/Lte/Like<left, right>, IsNull<operand>, NotNull<operand>` +
+                ` (buckets also accept BucketPublic, BucketPrivate, BucketLoggedIn, BucketOwner, BucketRole).`);
+        }
+    }
+}
+/**
+ * Expands a named alias to the type it stands for.
+ *
+ * This is what makes rules parameterisable — the type-level equivalent of
+ * Payload's access-control factory:
+ *
+ * ```typescript
+ * type SiteAccess<F extends string> = Any<[Role<"admin">, In<F, MySites>]>
+ * access: { update: SiteAccess<"site_id"> }
+ * ```
+ *
+ * Without it a rule had to be written inline at every use, and any alias — even an
+ * unparameterised one — was reported as an unknown rule.
+ */
+function resolveAccessAliasNode(typeNode, sourceFile, resolveCtx) {
+    const expanded = tryResolveTypeReference(typeNode, sourceFile, resolveCtx);
+    if (expanded && expanded !== typeNode)
+        return expanded;
+    if (needsChecker(typeNode)) {
+        const resolved = resolveTypeNode(typeNode, sourceFile, resolveCtx);
+        if (resolved !== typeNode)
+            return resolved;
+    }
+    return undefined;
+}
+/**
+ * The set on the right of an `In<>`.
+ *
+ * Resolved through the same alias machinery as rules, so a shared
+ * `type MySites = Rows<…>` can be reused across models — the parameterisation the
+ * plan calls the type-level equivalent of Payload's access factory.
+ */
+function parseMembershipSource(typeNode, sourceFile, resolveCtx) {
+    if (ts.isIndexedAccessTypeNode(typeNode) && resolveCtx) {
+        const member = resolveIndexedAccessRule(typeNode, sourceFile, resolveCtx);
+        if (member)
+            return parseMembershipSource(member, sourceFile, resolveCtx);
+    }
+    if (ts.isTypeReferenceNode(typeNode) && !ts.isQualifiedName(typeNode.typeName)) {
+        const ref = ownerText(typeNode.typeName, sourceFile);
+        const args = typeNode.typeArguments ?? [];
+        if (ref === "Claim") {
+            return parseAccessOperand(typeNode, sourceFile);
+        }
+        if (ref === "Rows") {
+            const table = stringLiteralArg(args[0], "Rows", "table name");
+            const column = stringLiteralArg(args[1], "Rows", "column name");
+            const source = { kind: "rows", table, column };
+            // The third argument narrows the source rows. Absent means "every row",
+            // which is a lookup rather than a membership check — allowed, but rarely
+            // what was meant, so it stays explicit rather than being defaulted.
+            if (args[2]) {
+                source["where"] = parseAccessRule(args[2], sourceFile, resolveCtx);
+            }
+            return source;
+        }
+        if (ref === "Values") {
+            const listArg = args[0];
+            if (!listArg || !ts.isTupleTypeNode(listArg)) {
+                throw new Error('`Values<>` takes a tuple, as in `Values<["draft", "review"]>`.');
+            }
+            if (listArg.elements.length === 0) {
+                throw new Error("`Values<[]>` matches nothing. List the values, or use `Private`.");
+            }
+            // Not `parseAccessOperand`: there, a bare string is a *column*, which is
+            // right for a comparison and wrong here. Inside a value list a string can
+            // only be a value, so it is read as one — no `Literal<>` wrapper needed.
+            return {
+                kind: "literal",
+                values: listArg.elements.map((element) => literalFromNode(element, sourceFile)),
+            };
+        }
+        // A named alias for a source: `type MySites = Rows<…>`.
+        if (resolveCtx) {
+            const resolved = resolveAccessAliasNode(typeNode, sourceFile, resolveCtx);
+            if (resolved)
+                return parseMembershipSource(resolved, sourceFile, resolveCtx);
         }
-        default:
-            return { type: "private" };
     }
+    throw new Error(`\`${ownerText(typeNode, sourceFile)}\` is not a valid membership source. Use ` +
+        `Rows<"table", "column", Where>, Claim<"path"> or Values<[…]>.`);
+}
+/** Interval units, matching `TimeUnit` in `@supatype/types` and the engine. */
+const TIME_UNITS = [
+    "seconds",
+    "minutes",
+    "hours",
+    "days",
+    "weeks",
+    "months",
+    "years",
+];
+/** Granularities for `StartOf<>`. */
+const TRUNC_UNITS = ["day", "week", "month", "year"];
+/**
+ * `Ago<30, "days">` / `FromNow<7, "days">`.
+ *
+ * The amount and unit are validated here and the interval is re-assembled from the
+ * parsed integer and the matched keyword, so no author-supplied text reaches
+ * Postgres. That is what keeps this from being a small escape hatch: a permissive
+ * `"30 days"` string would be raw SQL by another name.
+ */
+function parseDurationOperand(ref, args, sourceFile) {
+    if (args.length !== 2) {
+        throw new Error(`\`${ref}<>\` takes an amount and a unit, as in \`${ref}<30, "days">\`.`);
+    }
+    const amountNode = args[0];
+    const opposite = ref === "Ago" ? "FromNow" : "Ago";
+    // A negative literal is a prefix-unary expression in the TypeScript AST, not a
+    // numeric literal, so it has to be recognised separately — otherwise `Ago<-5, …>`
+    // is refused for the wrong reason and the message misses the real advice.
+    if (ts.isLiteralTypeNode(amountNode) &&
+        ts.isPrefixUnaryExpression(amountNode.literal) &&
+        amountNode.literal.operator === ts.SyntaxKind.MinusToken) {
+        throw new Error(`\`${ref}<>\` does not take a negative amount. For the other direction use ` +
+            `\`${opposite}<>\`, which reads correctly instead of relying on a double negative.`);
+    }
+    if (!ts.isLiteralTypeNode(amountNode) || !ts.isNumericLiteral(amountNode.literal)) {
+        throw new Error(`\`${ref}<>\` needs a number literal amount, as in \`${ref}<30, "days">\`.`);
+    }
+    const amount = Number(amountNode.literal.text);
+    if (!Number.isInteger(amount)) {
+        throw new Error(`\`${ref}<${amount}, …>\` must be a whole number of units — Postgres intervals ` +
+            `take integers, so a fraction would be silently truncated or rejected.`);
+    }
+    const unit = stringLiteralArg(args[1], ref, "unit");
+    if (!TIME_UNITS.includes(unit)) {
+        throw new Error(`\`${ref}<${amount}, "${unit}">\` is not a valid unit. Use one of: ` +
+            `${TIME_UNITS.join(", ")} (plural).`);
+    }
+    void sourceFile;
+    return { kind: ref === "Ago" ? "ago" : "fromNow", amount, unit };
+}
+/** A string, number or boolean literal as its plain JS value. */
+function literalFromNode(node, sourceFile) {
+    if (ts.isLiteralTypeNode(node)) {
+        const literal = node.literal;
+        if (ts.isStringLiteral(literal))
+            return literal.text;
+        if (ts.isNumericLiteral(literal))
+            return Number(literal.text);
+        if (literal.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (literal.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+    }
+    throw new Error(`\`${ownerText(node, sourceFile)}\` is not a string, number or boolean literal.`);
+}
+function stringLiteralArg(node, owner, what) {
+    if (!node || !ts.isLiteralTypeNode(node) || !ts.isStringLiteral(node.literal)) {
+        throw new Error(`\`${owner}<>\` needs a ${what} as a string literal.`);
+    }
+    const value = node.literal.text.trim();
+    // Rendered as a SQL identifier, so refuse anything that is not one.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+        throw new Error(`"${value}" is not a valid ${what}.`);
+    }
+    return value;
+}
+/**
+ * One side of a comparison.
+ *
+ * A bare string literal is a **column** on the model the rule is attached to.
+ * That is the common case by a wide margin, and making it the default keeps
+ * `Eq<"author_id", AuthUid>` readable; a constant is written `Literal<"x">` so the
+ * two can never be confused. Numbers and booleans are unambiguous, so they are
+ * taken as constants directly.
+ */
+function parseAccessOperand(typeNode, sourceFile) {
+    if (ts.isLiteralTypeNode(typeNode)) {
+        const literal = typeNode.literal;
+        if (ts.isStringLiteral(literal)) {
+            const name = literal.text.trim();
+            if (name === "") {
+                throw new Error("An empty column name is not a valid operand.");
+            }
+            // Rendered into SQL as an identifier, so refuse anything that is not one
+            // rather than letting it through to the policy.
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+                throw new Error(`"${name}" is not a valid column name. Use \`Literal<"${name}">\` for a ` +
+                    `constant, or quote a real column.`);
+            }
+            return { kind: "column", name };
+        }
+        if (ts.isNumericLiteral(literal)) {
+            return { kind: "literal", value: Number(literal.text) };
+        }
+        if (literal.kind === ts.SyntaxKind.TrueKeyword)
+            return { kind: "literal", value: true };
+        if (literal.kind === ts.SyntaxKind.FalseKeyword)
+            return { kind: "literal", value: false };
+    }
+    if (ts.isTypeReferenceNode(typeNode) && !ts.isQualifiedName(typeNode.typeName)) {
+        const ref = ownerText(typeNode.typeName, sourceFile);
+        const operandArgs = typeNode.typeArguments ?? [];
+        switch (ref) {
+            case "AuthUid":
+                return { kind: "authUid" };
+            case "AuthRole":
+                return { kind: "authRole" };
+            case "Now":
+                return { kind: "now" };
+            case "StartOf": {
+                const unit = stringLiteralArg(operandArgs[0], "StartOf", "unit");
+                if (!TRUNC_UNITS.includes(unit)) {
+                    throw new Error(`\`StartOf<"${unit}">\` is not a valid granularity. Use one of: ` +
+                        `${TRUNC_UNITS.join(", ")}.`);
+                }
+                return { kind: "startOf", unit };
+            }
+            case "Ago":
+            case "FromNow":
+                return parseDurationOperand(ref, operandArgs, sourceFile);
+            case "Claim": {
+                const pathArg = typeNode.typeArguments?.[0];
+                if (!pathArg || !ts.isLiteralTypeNode(pathArg) || !ts.isStringLiteral(pathArg.literal)) {
+                    throw new Error('`Claim<>` takes a dotted path literal, as in `Claim<"app_metadata.tier">`.');
+                }
+                const path = pathArg.literal.text.trim();
+                // The path is split on dots to walk the claims object, so an empty
+                // segment would silently look up a key that cannot exist.
+                if (path === "" || path.split(".").some((segment) => segment.trim() === "")) {
+                    throw new Error(`\`Claim<"${path}">\` is not a valid claim path — use dotted segments, ` +
+                        `as in \`Claim<"app_metadata.tier">\`.`);
+                }
+                return { kind: "claim", path };
+            }
+            case "Literal": {
+                const valueArg = typeNode.typeArguments?.[0];
+                if (!valueArg || !ts.isLiteralTypeNode(valueArg)) {
+                    throw new Error('`Literal<>` takes a string, number or boolean, as in `Literal<"published">`.');
+                }
+                const literal = valueArg.literal;
+                if (ts.isStringLiteral(literal))
+                    return { kind: "literal", value: literal.text };
+                if (ts.isNumericLiteral(literal))
+                    return { kind: "literal", value: Number(literal.text) };
+                if (literal.kind === ts.SyntaxKind.TrueKeyword)
+                    return { kind: "literal", value: true };
+                if (literal.kind === ts.SyntaxKind.FalseKeyword)
+                    return { kind: "literal", value: false };
+                throw new Error('`Literal<>` takes a string, number or boolean.');
+            }
+        }
+    }
+    throw new Error(`\`${ownerText(typeNode, sourceFile)}\` is not a valid operand. Use a column name ` +
+        `("author_id"), AuthUid, AuthRole, Claim<"path"> or Literal<value>.`);
 }
 function parseRelationOptions(optsArg, sourceFile) {
     const out = {};
@@ -1453,4 +2141,20 @@ function relationForeignKeyFromField(fieldName) {
     const base = snake.replace(/_id$/i, "");
     return `${base}_id`;
 }
+/** Resolve `Rules["read"]` to the rule type declared for that member. */
+function resolveIndexedAccessRule(node, sourceFile, resolveCtx) {
+    const literal = resolveAccessLiteral(node.objectType, sourceFile, resolveCtx);
+    if (!literal)
+        return undefined;
+    if (!ts.isLiteralTypeNode(node.indexType) || !ts.isStringLiteral(node.indexType.literal)) {
+        return undefined;
+    }
+    const key = node.indexType.literal.text;
+    for (const member of literal.members) {
+        if (ts.isPropertySignature(member) && getPropertyName(member.name) === key) {
+            return member.type;
+        }
+    }
+    return undefined;
+}
 //# sourceMappingURL=type-extractor.js.map