@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/lint/post-synth/clickhouse-type-check.js

@@ -0,0 +1,162 @@
+/**
+ * Checking a ClickHouse column type against the pinned catalog, for SQLCH121
+ * (the family), SQLCH122 (its parameters) and SQLCH123 (a wrapper the server
+ * refuses). One walk over the type answers all three; each check keeps the
+ * findings with its own id.
+ *
+ * Families come from `system.data_type_families` (`TYPE_FAMILIES`): a name is
+ * case-sensitive unless the catalog marks it case-insensitive, and an alias
+ * resolves to its family. Parameters come from the `TYPE_PARAMETERS` overlay.
+ * The walk goes into every parameter that is itself a type, so `UInt46`
+ * inside `Array(Map(String, UInt46))` is found.
+ */
+import { CLICKHOUSE_VERSION, TYPE_FAMILIES } from "../../generated/clickhouse.js";
+import { TYPE_PARAMETERS } from "../../clickhouse/overlays/types.js";
+import { numericParam, readType, typeTokens } from "../../clickhouse/type-syntax.js";
+import { clickhouseObjects } from "./sql-helpers.js";
+const FAMILIES = TYPE_FAMILIES;
+const FOLDED = new Map();
+const BY_LOWER = new Map();
+for (const [name, spec] of Object.entries(FAMILIES)) {
+    if (spec?.caseInsensitive)
+        FOLDED.set(name.toLowerCase(), spec);
+    BY_LOWER.set(name.toLowerCase(), name);
+}
+/** A family by name as the server resolves it: exactly, or in any case when the catalog marks it case-insensitive. */
+export function familyOf(name) {
+    return FAMILIES[name] ?? FOLDED.get(name.toLowerCase());
+}
+/** The MySQL-compatible words the parser keeps after a type (`INT(11) UNSIGNED`); the server ignores them. */
+const MODIFIERS = new Set(["UNSIGNED", "SIGNED", "AUTO_INCREMENT", "ZEROFILL"]);
+/**
+ * What `Nullable(...)` cannot hold. `Tuple` is not here: the pinned server
+ * takes `Nullable(Tuple(...))` when `enable_nullable_tuple_type` is on, a
+ * setting of the server's profile that the build cannot see.
+ */
+const NOT_INSIDE_NULLABLE = {
+    Array: "make the elements Nullable instead, Array(Nullable(T)), or drop Nullable: an empty array stands for no value",
+    Map: "make the values Nullable instead, Map(K, Nullable(V)), or drop Nullable",
+    Nested: "make the fields Nullable instead",
+    LowCardinality: "write LowCardinality(Nullable(T)) instead",
+    Variant: "drop Nullable: a Variant already holds NULL",
+    Nullable: "drop one Nullable",
+};
+/** Families whose parameters are settings or expressions rather than types and literals; left to the server. */
+const OPAQUE = new Set(["JSON", "Dynamic"]);
+/** Families whose one repeated parameter needs at least one value. */
+const NEEDS_ONE = new Set(["Enum", "Enum8", "Enum16", "Nested", "Variant"]);
+const isName = (t) => t?.kind === "ident" || t?.kind === "qident";
+/** Every finding for one column type, in the order the walk meets them. */
+export function typeFindings(type, version) {
+    const tokens = typeTokens(type);
+    if (!tokens)
+        return [];
+    const out = [];
+    walk(tokens, version, out);
+    return out;
+}
+function walk(tokens, version, out, named = false) {
+    const syntax = readType(tokens);
+    if (!syntax)
+        return undefined;
+    let words = syntax.words;
+    // A named tuple or Nested element, `a String`: the first word is the element's name.
+    if (named && words.length >= 2 && !familyOf(words.map((w) => w.text).join(" "))) {
+        const at = tokens.indexOf(words[0]);
+        return walk(tokens.slice(at + 1), version, out);
+    }
+    if (words.some((w) => w.kind !== "ident"))
+        return undefined;
+    // `INT UNSIGNED` is a family of its own; `Int32 UNSIGNED` is Int32 with a modifier the server ignores.
+    let spec = familyOf(words.map((w) => w.text).join(" "));
+    while (!spec && words.length > 1 && MODIFIERS.has(words[words.length - 1].text.toUpperCase())) {
+        words = words.slice(0, -1);
+        spec = familyOf(words.map((w) => w.text).join(" "));
+    }
+    const written = words.map((w) => w.text).join(" ");
+    if (!spec) {
+        const other = BY_LOWER.get(written.toLowerCase());
+        const hint = other ? ` (it has ${other}, and that name is case-sensitive)` : "";
+        out.push({ checkId: "SQLCH121", detail: `${written} is not a type family ClickHouse ${version} has${hint}` });
+        return undefined;
+    }
+    const family = spec.canonical;
+    if (OPAQUE.has(family))
+        return family;
+    const expected = TYPE_PARAMETERS[family] ?? [];
+    let params = syntax.params;
+    const say = (detail) => out.push({ checkId: "SQLCH122", detail });
+    if (params === undefined) {
+        const required = expected.filter((p) => !p.optional && !p.repeated);
+        if (required.length > 0)
+            say(`${written} needs its ${required.map((p) => p.name).join(" and ")}`);
+        else if (NEEDS_ONE.has(family))
+            say(`${written} needs at least one ${expected[0].name}`);
+        return family;
+    }
+    // `AggregateFunction(1, uniq, UInt64)`: a leading number is the function's state version.
+    if (family === "AggregateFunction" && params[0] && numericParam(params[0]) !== undefined)
+        params = params.slice(1);
+    if (expected.length === 0) {
+        if (params.length > 0)
+            say(`${written} takes no parameters, and ${written}(${params.map((p) => p.text).join(", ")}) gives ${params.length}`);
+        return family;
+    }
+    const repeated = expected[expected.length - 1].repeated === true;
+    if (!repeated && params.length > expected.length) {
+        say(`${written} takes at most ${expected.length} parameter${expected.length === 1 ? "" : "s"} (${expected.map((p) => p.name).join(", ")}), and is given ${params.length}`);
+        return family;
+    }
+    const required = expected.filter((p) => !p.optional && !p.repeated).length;
+    if (params.length < required) {
+        say(`${written} needs its ${expected.slice(params.length, required).map((p) => p.name).join(" and ")}`);
+        return family;
+    }
+    if (params.length === 0 && NEEDS_ONE.has(family)) {
+        say(`${written} needs at least one ${expected[0].name}`);
+        return family;
+    }
+    params.forEach((param, i) => {
+        const p = expected[Math.min(i, expected.length - 1)];
+        checkParam(written, family, p, param, version, out);
+    });
+    return family;
+}
+function checkParam(written, family, p, param, version, out) {
+    if (p.kind === "number" && p.range) {
+        const value = numericParam(param);
+        if (value !== undefined && (value < p.range[0] || value > p.range[1])) {
+            out.push({ checkId: "SQLCH122", detail: `${written} ${p.name} ${param.text} is outside ${p.range[0]} to ${p.range[1]}` });
+        }
+        return;
+    }
+    if (p.kind !== "type" && p.kind !== "named-type")
+        return;
+    const inner = walk(param.tokens, version, out, p.kind === "named-type" && isName(param.tokens.find((t) => t.kind !== "ws" && t.kind !== "comment")));
+    if (family === "Nullable" && inner !== undefined && NOT_INSIDE_NULLABLE[inner]) {
+        out.push({ checkId: "SQLCH123", detail: `Nullable cannot hold ${inner}; ${NOT_INSIDE_NULLABLE[inner]}` });
+    }
+}
+/** Each declared column type in the build: tables, views that list their columns, and dictionary attributes. */
+export function* columnTypes(objects) {
+    for (const o of objects) {
+        if (!/^ClickHouse::(Table|View|MaterializedView|Dictionary)$/.test(o.type))
+            continue;
+        const columns = (o.columns ?? []);
+        for (const c of columns)
+            if (c.type)
+                yield { object: o, column: c.name, type: c.type };
+    }
+}
+/** The body of one of the three type checks: every column type's findings with that id. */
+export function reportTypeFindings(id) {
+    return (ctx, report) => {
+        for (const { object, column, type } of columnTypes(clickhouseObjects(ctx))) {
+            for (const f of typeFindings(type, CLICKHOUSE_VERSION)) {
+                if (f.checkId !== id)
+                    continue;
+                report({ severity: "error", message: `${object.export} (${object.name}): column ${column} ${type}: ${f.detail}`, entity: object.export });
+            }
+        }
+    };
+}

package/dist/lint/post-synth/index.js

@@ -0,0 +1,112 @@
+import { sql101 } from "./sql101.js";
+import { sql102 } from "./sql102.js";
+import { sqlch101 } from "./sqlch101.js";
+import { sqlch102 } from "./sqlch102.js";
+import { sqlch103 } from "./sqlch103.js";
+import { sqlch104 } from "./sqlch104.js";
+import { sqlch105 } from "./sqlch105.js";
+import { sqlch106 } from "./sqlch106.js";
+import { sqlch107 } from "./sqlch107.js";
+import { sqlch108 } from "./sqlch108.js";
+import { sqlch109 } from "./sqlch109.js";
+import { sqlch110 } from "./sqlch110.js";
+import { sqlch111 } from "./sqlch111.js";
+import { sqlch112 } from "./sqlch112.js";
+import { sqlch113 } from "./sqlch113.js";
+import { sqlch114 } from "./sqlch114.js";
+import { sqlch115 } from "./sqlch115.js";
+import { sqlch116 } from "./sqlch116.js";
+import { sqlch117 } from "./sqlch117.js";
+import { sqlch118 } from "./sqlch118.js";
+import { sqlch119 } from "./sqlch119.js";
+import { sqlch120 } from "./sqlch120.js";
+import { sqlch121 } from "./sqlch121.js";
+import { sqlch122 } from "./sqlch122.js";
+import { sqlch123 } from "./sqlch123.js";
+import { sqlch124 } from "./sqlch124.js";
+import { sqlch125 } from "./sqlch125.js";
+import { sqlch126 } from "./sqlch126.js";
+import { sqlch127 } from "./sqlch127.js";
+import { sqlpg101 } from "./sqlpg101.js";
+import { sqlpg102 } from "./sqlpg102.js";
+import { sqlpg103 } from "./sqlpg103.js";
+import { sqlpg104 } from "./sqlpg104.js";
+import { sqlpg105 } from "./sqlpg105.js";
+import { sqlpg106 } from "./sqlpg106.js";
+import { sqlpg107 } from "./sqlpg107.js";
+import { sqlpg108 } from "./sqlpg108.js";
+import { sqlpg109 } from "./sqlpg109.js";
+import { sqlpg110 } from "./sqlpg110.js";
+import { sqlpg111 } from "./sqlpg111.js";
+import { sqlpg112 } from "./sqlpg112.js";
+import { sqlpg113 } from "./sqlpg113.js";
+import { sqlpg114 } from "./sqlpg114.js";
+import { sqlpg115 } from "./sqlpg115.js";
+import { sqlpg116 } from "./sqlpg116.js";
+import { sqlpg117 } from "./sqlpg117.js";
+import { sqlpg118 } from "./sqlpg118.js";
+import { sqlpg119 } from "./sqlpg119.js";
+import { sqlpg120 } from "./sqlpg120.js";
+import { sqlpg121 } from "./sqlpg121.js";
+import { sqlpg122 } from "./sqlpg122.js";
+import { sqlpg123 } from "./sqlpg123.js";
+import { sqlpg124 } from "./sqlpg124.js";
+import { sqlpg125 } from "./sqlpg125.js";
+import { sqlpg126 } from "./sqlpg126.js";
+export const postSynthChecks = [
+    sql101,
+    sql102,
+    sqlch101,
+    sqlch102,
+    sqlch103,
+    sqlch104,
+    sqlch105,
+    sqlch106,
+    sqlch107,
+    sqlch108,
+    sqlch109,
+    sqlch110,
+    sqlch111,
+    sqlch112,
+    sqlch113,
+    sqlch114,
+    sqlch115,
+    sqlch116,
+    sqlch117,
+    sqlch118,
+    sqlch119,
+    sqlch120,
+    sqlch121,
+    sqlch122,
+    sqlch123,
+    sqlch124,
+    sqlch125,
+    sqlch126,
+    sqlch127,
+    sqlpg101,
+    sqlpg102,
+    sqlpg103,
+    sqlpg104,
+    sqlpg105,
+    sqlpg106,
+    sqlpg107,
+    sqlpg108,
+    sqlpg109,
+    sqlpg110,
+    sqlpg111,
+    sqlpg112,
+    sqlpg113,
+    sqlpg114,
+    sqlpg115,
+    sqlpg116,
+    sqlpg117,
+    sqlpg118,
+    sqlpg119,
+    sqlpg120,
+    sqlpg121,
+    sqlpg122,
+    sqlpg123,
+    sqlpg124,
+    sqlpg125,
+    sqlpg126,
+];

package/dist/lint/post-synth/postgres-audit-entries.js

@@ -0,0 +1,35 @@
+/**
+ * Audit metadata for the Postgres post-synth checks (SQLPG1xx). Spread into
+ * `sqlAuditCatalog` by ../audit-catalog.ts. Deprecation checks are filed under
+ * best-practice or correctness: the audit categories have no deprecation of
+ * their own.
+ */
+import { auditRule } from "@intentius/chant/audit/catalog";
+export const postgresPostSynthAuditEntries = {
+    SQLPG101: auditRule("SQLPG101", "merge-worthy", "guidance", "A table declares no primary key", "Add a primary key, or a UNIQUE constraint over NOT NULL columns.", { category: "best-practice" }),
+    SQLPG102: auditRule("SQLPG102", "report-only", "guidance", "A foreign key's referencing columns have no index", "Create an index whose leading columns are the foreign key's columns.", { category: "best-practice" }),
+    SQLPG103: auditRule("SQLPG103", "report-only", "guidance", "A serial column where an identity column is preferred", "Declare the column GENERATED ALWAYS AS IDENTITY.", { category: "best-practice" }),
+    SQLPG104: auditRule("SQLPG104", "report-only", "guidance", "A timestamp column without time zone", "Use timestamptz.", { category: "correctness" }),
+    SQLPG105: auditRule("SQLPG105", "report-only", "guidance", "A json column where jsonb fits", "Use jsonb unless the exact text must be kept.", { category: "best-practice" }),
+    SQLPG106: auditRule("SQLPG106", "report-only", "guidance", "A char(n) column", "Use text, or varchar(n) for a length rule.", { category: "best-practice" }),
+    SQLPG107: auditRule("SQLPG107", "report-only", "guidance", "A money column", "Use numeric(p, s) and a currency column.", { category: "correctness" }),
+    SQLPG108: auditRule("SQLPG108", "report-only", "guidance", "A varchar(n) column with a habitual length limit", "Use text, with a CHECK where the length is a rule.", { category: "best-practice" }),
+    SQLPG109: auditRule("SQLPG109", "report-only", "guidance", "An index duplicates a constraint or another index", "Drop the duplicate index.", { category: "best-practice" }),
+    SQLPG110: auditRule("SQLPG110", "report-only", "guidance", "A btree index is a prefix of another index", "Drop the prefix index; the wider one serves the same queries.", { category: "best-practice" }),
+    SQLPG111: auditRule("SQLPG111", "report-only", "guidance", "A materialized view has no unique index, so it cannot refresh concurrently", "Add a unique index over plain columns.", { category: "correctness" }),
+    SQLPG112: auditRule("SQLPG112", "report-only", "guidance", "A secret- or PII-named column with no comment on it or its table", "Add a COMMENT saying what it holds and how it is protected.", { category: "security" }),
+    SQLPG113: auditRule("SQLPG113", "report-only", "guidance", "An object is in the public schema though the project declares schemas", "Qualify the object with a declared schema.", { category: "best-practice" }),
+    SQLPG114: auditRule("SQLPG114", "merge-worthy", "guidance", "A storage parameter the object's kind or the target major does not accept", "Fix the parameter name, or use one from the target major's catalog.", { category: "correctness" }),
+    SQLPG115: auditRule("SQLPG115", "report-only", "guidance", "A feature newer than the target major", "Avoid the feature, or raise sql.postgresMajor.", { category: "correctness" }),
+    SQLPG116: auditRule("SQLPG116", "merge-worthy", "guidance", "An extension the target major no longer ships", "Remove the extension, or set sql.postgresMajor to an older major.", { category: "best-practice" }),
+    SQLPG117: auditRule("SQLPG117", "report-only", "guidance", "A view without security_invoker runs with its owner's privileges", "Set security_invoker = true in the view's WITH options.", { category: "security" }),
+    SQLPG118: auditRule("SQLPG118", "report-only", "guidance", "A table uses INHERITS where declarative partitioning replaced it", "Use PARTITION BY and PARTITION OF.", { category: "best-practice" }),
+    SQLPG119: auditRule("SQLPG119", "merge-worthy", "guidance", "A column, domain or sequence type the target major does not have", "Fix the type name, declare the type, or declare the extension that provides it.", { category: "correctness" }),
+    SQLPG120: auditRule("SQLPG120", "merge-worthy", "guidance", "A type modifier that does not fit the type", "Drop the modifier, or bring it into the type's range.", { category: "correctness" }),
+    SQLPG121: auditRule("SQLPG121", "merge-worthy", "guidance", "An identity column whose type is not smallint, integer or bigint", "Declare the identity column smallint, integer or bigint.", { category: "correctness" }),
+    SQLPG122: auditRule("SQLPG122", "merge-worthy", "guidance", "A table declares a column twice, or an enum lists a label twice", "Remove or rename the repeated column or label.", { category: "correctness" }),
+    SQLPG123: auditRule("SQLPG123", "merge-worthy", "guidance", "A key, index or grant column list names a column the table does not declare", "Fix the column name, or write it as ${table.columns.name}.", { category: "correctness" }),
+    SQLPG124: auditRule("SQLPG124", "merge-worthy", "guidance", "A foreign key names a column the referenced table lacks, or one of another type category", "Reference a declared column, and give the referencing column a type of the same category.", { category: "correctness" }),
+    SQLPG125: auditRule("SQLPG125", "merge-worthy", "guidance", "An index access method or operator class the target major does not have, or not for that method", "Use a method and operator class the target major has, or declare the extension that provides them.", { category: "correctness" }),
+    SQLPG126: auditRule("SQLPG126", "merge-worthy", "guidance", "An expression calls a function the target major does not have", "Fix the function name, declare the function, or declare the extension that provides it.", { category: "correctness" }),
+};

package/dist/lint/post-synth/postgres-helpers.js

@@ -0,0 +1,65 @@
+/**
+ * Reading the Postgres objects in the sql build output for post-synth checks:
+ * typed views of the serialized objects and the small scanners the checks
+ * share. Expressions are kept as written; the scanners answer narrow questions
+ * ("is this a bare column"), not what an expression evaluates to.
+ */
+import { POSTGRES_MAJORS, VERSION_RANGES } from "../../generated/postgres.js";
+import { readPostgres } from "../../read/postgres.js";
+import { postgresMajorOf } from "./sql-helpers.js";
+export const isTable = (o) => o.type === "Postgres::Table";
+export const isIndex = (o) => o.type === "Postgres::Index";
+export const isView = (o) => o.type === "Postgres::View";
+export const isMaterializedView = (o) => o.type === "Postgres::MaterializedView";
+export const tablesOf = (ctx) => readPostgres(ctx).tables;
+export const indexesOf = (ctx) => readPostgres(ctx).indexes;
+/** The major the build targets (`postgresMajor` in the output), else the newest pinned. */
+export const targetMajor = (ctx) => postgresMajorOf(ctx, PINNED_MAJOR);
+/** The newest and oldest majors the lexicon carries a catalog for. */
+export const PINNED_MAJOR = POSTGRES_MAJORS[POSTGRES_MAJORS.length - 1];
+export const OLDEST_MAJOR = POSTGRES_MAJORS[0];
+/** The version range the generated catalog records for `name` in `table`, if it is not in every major. */
+export function rangeOf(table, name) {
+    return VERSION_RANGES[table][name];
+}
+/** A column type's leading words, lower-cased, without a length or array suffix: `timestamp(3)[]` is `timestamp`. */
+export function baseType(type) {
+    return (type ?? "").toLowerCase().replace(/\[.*$/, "").replace(/\(.*?\)/g, "").replace(/\s+/g, " ").trim();
+}
+/** The `name = value` pairs of a `(a = 1, b)` storage parameter list, names lower-cased. */
+export function storageParams(text) {
+    const out = new Map();
+    const inner = (text ?? "").trim().replace(/^\(/, "").replace(/\)$/, "");
+    for (const part of inner.split(",")) {
+        const [k, ...v] = part.split("=");
+        const name = k.trim().toLowerCase();
+        if (name)
+            out.set(name, v.join("=").trim());
+    }
+    return out;
+}
+/** The leading bare-column elements of an index, in order; stops at the first expression. */
+export const leadingColumns = (index) => index.columns;
+/** A check over the build's Postgres objects, so each check file holds its rule. */
+export function checkOf(meta, run) {
+    return {
+        ...meta,
+        check(ctx) {
+            const out = [];
+            run(ctx, (d) => out.push({ checkId: meta.id, lexicon: "sql", ...d }));
+            return out;
+        },
+    };
+}
+/** A table that owns its columns: not a partition, not typed (`OF type`), not temporary. */
+export const ownsColumns = (t) => t.partitionOf === undefined && t.ofType === undefined && t.persistence !== "temporary";
+/** The catalog's relation kind for a storage-parameter list on this object, as `STORAGE_PARAMETERS.targets` spells it. */
+export function storageTarget(o) {
+    switch (o.type) {
+        case "Postgres::Table": return "table";
+        case "Postgres::View": return "view";
+        case "Postgres::MaterializedView": return "materialized view";
+        case "Postgres::Index": return `index:${o.method ?? "btree"}`;
+        default: return undefined;
+    }
+}