supabase-strict-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FishTank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# supabase-strict-check
+
+Checker for PostgREST/Supabase client queries against generated `Database` types.
+
+It walks TypeScript source, resolves `.from()`, `.select()`, filters, inserts/updates, and RPC calls, and reports columns, relations, and payloads that do not match the generated types file.
+
+## Quick start
+
+```bash
+npm install -g supabase-strict-check
+supabase-strict-check --target=src --types=src/types/supabase.ts
+```
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--target` | Directory of TypeScript source to scan (`.ts`, `.tsx`) |
+| `--types` | Path to the generated Supabase types file (`export type Database = { ... }`) |
+
+Omit both flags to be prompted (TTY only).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md)

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+export interface CliPaths {
+    cwd: string;
+    target: string;
+    types: string;
+}
+export declare function resolveCliPaths(argv?: string[]): Promise<CliPaths>;

package/dist/cli.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCliPaths = resolveCliPaths;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:readline/promises"));
+const node_process_1 = require("node:process");
+function flagValue(argv, name) {
+    const eq = `--${name}=`;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith(eq))
+            return arg.slice(eq.length);
+        if (arg === `--${name}`)
+            return argv[i + 1];
+    }
+    return undefined;
+}
+function resolveFromCwd(cwd, value) {
+    return node_path_1.default.resolve(cwd, value);
+}
+async function ask(cwd, kind) {
+    if (!node_process_1.stdin.isTTY || !node_process_1.stdout.isTTY) {
+        throw new Error(kind === "directory"
+            ? "missing --target= (path to directory from pwd)"
+            : "missing --types= (path to supabase types file from pwd)");
+    }
+    const rl = promises_1.default.createInterface({ input: node_process_1.stdin, output: node_process_1.stdout });
+    try {
+        const label = kind === "directory"
+            ? `path to directory (allows '..' and '.', eg: '../../src') 
+      \nFrom \`${cwd}\`
+      \n> `
+            : `path to supabase types (allows '..' and '.', eg: '../../src/types/supabase.types.ts')
+      \nFrom \`${cwd}\`
+      \n> `;
+        const answer = (await rl.question(label)).trim();
+        if (!answer) {
+            throw new Error(kind === "directory" ? "directory path is required" : "types path is required");
+        }
+        return answer;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function resolveCliPaths(argv = process.argv.slice(2)) {
+    const cwd = process.cwd();
+    const targetArg = flagValue(argv, "target") ?? await ask(cwd, "directory");
+    const target = resolveFromCwd(cwd, targetArg);
+    if (!node_fs_1.default.existsSync(target) || !node_fs_1.default.statSync(target).isDirectory()) {
+        throw new Error(`not a directory: ${targetArg} (resolved ${target})`);
+    }
+    console.log(`Targeted directory: ${target}`);
+    const typesArg = flagValue(argv, "types") ?? await ask(cwd, "types");
+    const types = resolveFromCwd(cwd, typesArg);
+    if (!node_fs_1.default.existsSync(types) || !node_fs_1.default.statSync(types).isFile()) {
+        throw new Error(`not a types file: ${typesArg} (resolved ${types})`);
+    }
+    console.log(`Types file: ${types}`);
+    return { cwd, target, types };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): void;

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+/**
+ * Static PostgREST/Supabase checker.
+ *
+ *   npm start -- --target=src --types=src/types/supabase.ts
+ *
+ * Paths are from pwd. Omit flags to be prompted.
+ */
+const run_1 = require("./run");
+function main() {
+    (0, run_1.run)().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}
+main();

package/dist/lib/catalog.d.ts

@@ -0,0 +1,5 @@
+import type { Catalog, Relation, Relationship } from "./types";
+export declare function loadCatalog(typesPath: string): Catalog;
+export declare function resolveRelation(catalog: Catalog, schema: string, name: string): Relation | undefined;
+export declare function lookupTarget(catalog: Catalog, fromSchema: string, referencedRelation: string): Relation | undefined;
+export declare function pointsTo(catalog: Catalog, rel: Relationship, fromSchema: string, target: Relation): boolean;

package/dist/lib/catalog.js

@@ -0,0 +1,293 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCatalog = loadCatalog;
+exports.resolveRelation = resolveRelation;
+exports.lookupTarget = lookupTarget;
+exports.pointsTo = pointsTo;
+const node_fs_1 = __importDefault(require("node:fs"));
+const typescript_1 = __importDefault(require("typescript"));
+const types_1 = require("./types");
+function propName(name) {
+    if (typescript_1.default.isIdentifier(name) || typescript_1.default.isStringLiteral(name) || typescript_1.default.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return null;
+}
+function typeName(member) {
+    if (!typescript_1.default.isPropertySignature(member) || !member.name)
+        return null;
+    return propName(member.name);
+}
+function asTypeLiteral(node) {
+    return node && typescript_1.default.isTypeLiteralNode(node) ? node : null;
+}
+function stringFromType(node) {
+    if (!node)
+        return null;
+    if (typescript_1.default.isLiteralTypeNode(node) && typescript_1.default.isStringLiteral(node.literal))
+        return node.literal.text;
+    return null;
+}
+function boolFromType(node) {
+    if (!node || !typescript_1.default.isLiteralTypeNode(node))
+        return false;
+    return node.literal.kind === typescript_1.default.SyntaxKind.TrueKeyword;
+}
+function stringsFromTuple(node) {
+    if (!node || !typescript_1.default.isTupleTypeNode(node))
+        return [];
+    const out = [];
+    for (const el of node.elements) {
+        const value = stringFromType(el);
+        if (value != null)
+            out.push(value);
+    }
+    return out;
+}
+function memberType(literal, key) {
+    for (const member of literal.members) {
+        if (typeName(member) === key && typescript_1.default.isPropertySignature(member)) {
+            return member.type;
+        }
+    }
+    return undefined;
+}
+function stringLiterals(node) {
+    if (!node)
+        return [];
+    if (typescript_1.default.isLiteralTypeNode(node) && typescript_1.default.isStringLiteral(node.literal))
+        return [node.literal.text];
+    if (typescript_1.default.isUnionTypeNode(node)) {
+        return node.types.flatMap((t) => stringLiterals(t));
+    }
+    if (typescript_1.default.isParenthesizedTypeNode(node))
+        return stringLiterals(node.type);
+    return [];
+}
+/** Database["public"]["Enums"]["status"] */
+function enumIndex(node) {
+    if (!node || !typescript_1.default.isIndexedAccessTypeNode(node))
+        return null;
+    const name = stringFromType(node.indexType);
+    const inner = node.objectType;
+    if (!name || !typescript_1.default.isIndexedAccessTypeNode(inner))
+        return null;
+    const enumsKey = stringFromType(inner.indexType);
+    if (enumsKey !== "Enums")
+        return null;
+    const schemaNode = inner.objectType;
+    if (!typescript_1.default.isIndexedAccessTypeNode(schemaNode))
+        return null;
+    const schema = stringFromType(schemaNode.indexType);
+    if (!schema)
+        return null;
+    return { schema, name };
+}
+function parseRelationships(node) {
+    if (!node || !typescript_1.default.isTupleTypeNode(node))
+        return [];
+    const rels = [];
+    for (const el of node.elements) {
+        const literal = asTypeLiteral(el);
+        if (!literal)
+            continue;
+        const foreignKeyName = stringFromType(memberType(literal, "foreignKeyName"));
+        const referencedRelation = stringFromType(memberType(literal, "referencedRelation"));
+        if (!foreignKeyName || !referencedRelation)
+            continue;
+        rels.push({
+            foreignKeyName,
+            columns: stringsFromTuple(memberType(literal, "columns")),
+            isOneToOne: boolFromType(memberType(literal, "isOneToOne")),
+            referencedRelation,
+            referencedColumns: stringsFromTuple(memberType(literal, "referencedColumns")),
+        });
+    }
+    return rels;
+}
+function parseColumns(row, catalog) {
+    const names = new Set();
+    const required = new Set();
+    const valueDomain = new Map();
+    const literal = asTypeLiteral(row);
+    if (!literal)
+        return { names, required, valueDomain };
+    for (const member of literal.members) {
+        const name = typeName(member);
+        if (!name || !typescript_1.default.isPropertySignature(member))
+            continue;
+        names.add(name);
+        if (!member.questionToken)
+            required.add(name);
+        const domain = stringLiterals(member.type);
+        if (domain.length > 0) {
+            valueDomain.set(name, domain);
+            continue;
+        }
+        const ref = enumIndex(member.type);
+        if (ref) {
+            const values = catalog.enums.get(ref.schema)?.get(ref.name);
+            if (values)
+                valueDomain.set(name, values);
+        }
+    }
+    return { names, required, valueDomain };
+}
+function parseRelationBlock(schema, name, kind, node, catalog) {
+    const literal = asTypeLiteral(node);
+    if (!literal)
+        return null;
+    const row = parseColumns(memberType(literal, "Row"), catalog);
+    const insert = parseColumns(memberType(literal, "Insert"), catalog);
+    const update = parseColumns(memberType(literal, "Update"), catalog);
+    return {
+        schema,
+        name,
+        kind,
+        columns: row.names,
+        insertColumns: insert.names,
+        insertRequired: insert.required,
+        updateColumns: update.names,
+        relationships: parseRelationships(memberType(literal, "Relationships")),
+        valueDomain: row.valueDomain.size ? row.valueDomain : insert.valueDomain,
+    };
+}
+function parseNamedBlock(schema, kind, node, catalog) {
+    const literal = asTypeLiteral(node);
+    if (!literal)
+        return;
+    for (const member of literal.members) {
+        const name = typeName(member);
+        if (!name || !typescript_1.default.isPropertySignature(member) || !member.type)
+            continue;
+        const relation = parseRelationBlock(schema, name, kind, member.type, catalog);
+        if (!relation)
+            continue;
+        catalog.relations.set((0, types_1.relKey)(schema, name), relation);
+        const list = catalog.byName.get(name) ?? [];
+        list.push(relation);
+        catalog.byName.set(name, list);
+    }
+}
+function parseRpc(name, node) {
+    const literal = asTypeLiteral(node);
+    if (!literal)
+        return null;
+    const args = memberType(literal, "Args");
+    if (!args)
+        return { name, argNames: new Set(), requiredArgs: new Set(), argsNever: true };
+    if (args.kind === typescript_1.default.SyntaxKind.NeverKeyword) {
+        return { name, argNames: new Set(), requiredArgs: new Set(), argsNever: true };
+    }
+    const body = asTypeLiteral(args);
+    const argNames = new Set();
+    const requiredArgs = new Set();
+    if (body) {
+        for (const member of body.members) {
+            const arg = typeName(member);
+            if (!arg || !typescript_1.default.isPropertySignature(member))
+                continue;
+            argNames.add(arg);
+            if (!member.questionToken)
+                requiredArgs.add(arg);
+        }
+    }
+    return { name, argNames, requiredArgs, argsNever: false };
+}
+function parseFunctions(schema, node, catalog) {
+    const map = catalog.functions.get(schema) ?? new Map();
+    const literal = asTypeLiteral(node);
+    if (literal) {
+        for (const member of literal.members) {
+            const name = typeName(member);
+            if (!name || !typescript_1.default.isPropertySignature(member) || !member.type)
+                continue;
+            const fn = parseRpc(name, member.type);
+            if (fn)
+                map.set(name, fn);
+        }
+    }
+    catalog.functions.set(schema, map);
+}
+function parseEnums(schema, node, catalog) {
+    const map = catalog.enums.get(schema) ?? new Map();
+    const literal = asTypeLiteral(node);
+    if (literal) {
+        for (const member of literal.members) {
+            const name = typeName(member);
+            if (!name || !typescript_1.default.isPropertySignature(member))
+                continue;
+            const values = stringLiterals(member.type);
+            if (values.length)
+                map.set(name, values);
+        }
+    }
+    catalog.enums.set(schema, map);
+}
+function loadCatalog(typesPath) {
+    const text = node_fs_1.default.readFileSync(typesPath, "utf8");
+    const sf = typescript_1.default.createSourceFile(typesPath, text, typescript_1.default.ScriptTarget.Latest, true, typescript_1.default.ScriptKind.TS);
+    const catalog = {
+        schemas: new Set(),
+        relations: new Map(),
+        byName: new Map(),
+        functions: new Map(),
+        enums: new Map(),
+    };
+    let database = null;
+    for (const stmt of sf.statements) {
+        if (typescript_1.default.isTypeAliasDeclaration(stmt) && stmt.name.text === "Database" && typescript_1.default.isTypeLiteralNode(stmt.type)) {
+            database = stmt.type;
+            break;
+        }
+    }
+    if (!database) {
+        throw new Error(`Could not find 'export type Database = { ... }' in ${typesPath}`);
+    }
+    for (const member of database.members) {
+        const schema = typeName(member);
+        if (!schema || schema === "__InternalSupabase")
+            continue;
+        if (!typescript_1.default.isPropertySignature(member) || !member.type)
+            continue;
+        const body = asTypeLiteral(member.type);
+        if (!body)
+            continue;
+        catalog.schemas.add(schema);
+        parseEnums(schema, memberType(body, "Enums"), catalog);
+    }
+    for (const member of database.members) {
+        const schema = typeName(member);
+        if (!schema || schema === "__InternalSupabase")
+            continue;
+        if (!typescript_1.default.isPropertySignature(member) || !member.type)
+            continue;
+        const body = asTypeLiteral(member.type);
+        if (!body)
+            continue;
+        parseNamedBlock(schema, "table", memberType(body, "Tables"), catalog);
+        parseNamedBlock(schema, "view", memberType(body, "Views"), catalog);
+        parseFunctions(schema, memberType(body, "Functions"), catalog);
+    }
+    if (catalog.relations.size === 0) {
+        throw new Error(`Parsed 0 tables/views from ${typesPath}`);
+    }
+    return catalog;
+}
+function resolveRelation(catalog, schema, name) {
+    return catalog.relations.get((0, types_1.relKey)(schema, name))
+        ?? catalog.byName.get(name)?.find((r) => r.schema === schema)
+        ?? (catalog.byName.get(name)?.length === 1 ? catalog.byName.get(name)[0] : undefined);
+}
+function lookupTarget(catalog, fromSchema, referencedRelation) {
+    return resolveRelation(catalog, fromSchema, referencedRelation);
+}
+function pointsTo(catalog, rel, fromSchema, target) {
+    const referenced = lookupTarget(catalog, fromSchema, rel.referencedRelation);
+    if (referenced)
+        return referenced.schema === target.schema && referenced.name === target.name;
+    return rel.referencedRelation === target.name;
+}

package/dist/lib/checker.d.ts

@@ -0,0 +1,70 @@
+import ts from "typescript";
+import type { Catalog, QueryError, Relation } from "./types";
+export interface PendingAnyPayload {
+    fn: ts.FunctionLikeDeclaration;
+    paramIndex: number;
+    relation: Relation;
+    kind: string;
+    allowed: Set<string>;
+    checkRequired: boolean;
+    origin: ts.Node;
+    hits: number;
+    seenCalls: Set<string>;
+}
+export interface CheckerOptions {
+    catalog: Catalog;
+    sf: ts.SourceFile;
+    consts: Map<string, string>;
+    tsChecker?: ts.TypeChecker;
+    clientNames?: Set<string>;
+    subst?: Map<string, string>;
+    instantiated?: Set<string>;
+    pendingAny?: PendingAnyPayload[];
+    errors?: QueryError[];
+    warnings?: QueryError[];
+}
+export declare class Checker {
+    readonly errors: QueryError[];
+    readonly warnings: QueryError[];
+    private readonly catalog;
+    private readonly sf;
+    private readonly consts;
+    private readonly tsChecker?;
+    private readonly clientNames;
+    private readonly subst;
+    private readonly instantiated;
+    private readonly pendingAny;
+    private resolvingPending;
+    constructor(opts: CheckerOptions);
+    private evalOpts;
+    private str;
+    fail(node: ts.Node, message: string): void;
+    warn(node: ts.Node, message: string): void;
+    checkFile(): void;
+    followAnyPayloads(): void;
+    private spawn;
+    private visit;
+    private maybeInstantiate;
+    private applyPendingAtCall;
+    private queuePending;
+    private substFromCall;
+    private checkTail;
+    private skipGenericParam;
+    private resolvePayload;
+    private collectKeys;
+    private checkRpc;
+    private checkMethod;
+    private checkPayload;
+    private payloadValue;
+    private checkLiteralDomain;
+    private checkOnConflict;
+    private checkMatch;
+    private checkOr;
+    private checkFilterColumn;
+    private checkSelect;
+    private walkSelect;
+    private assertColumnOrPath;
+    private resolveEmbed;
+    private embedCandidates;
+}
+export declare function flushUnhitAnyPayloads(pending: PendingAnyPayload[], errors: QueryError[]): void;