@kedge/cli 0.0.0-stage → 0.10.0

package/src/plugin-lint.ts

@@ -0,0 +1,145 @@
+// Lints everything a plugin will run as SQL, not only its migration files:
+// acquire bodies, checkout reads and statements, and release handlers. The
+// functions that build runtime SQL are called with a representative input,
+// since the linter needs their text, not their values.
+import type { PluginDefinition, ScheduleDescriptor, SqlStatement } from "@kedge/core";
+import {
+  entityTable,
+  entityWriteProblems,
+  errorSources,
+  isTimerDescriptor,
+  type LintIssue,
+  type LintOptions,
+  lintSql,
+  type Owner,
+  trackSql,
+} from "@kedge/core";
+
+type Context = LintOptions["context"];
+
+const sample = {
+  cartId: "cart_lint",
+  email: "lint@example.com",
+  customerId: "cus_lint",
+  currency: "USD",
+  variantIds: ["var_lint"],
+};
+
+/** The SQL a plugin builds at runtime, from sample inputs, with where each came from. */
+export function collect<O>(def: PluginDefinition<O>, options: O): { sql: string; context: Context; where: string }[] {
+  const out: { sql: string; context: Context; where: string }[] = [];
+  // Timer descriptors beside a contribution's SQL are core's to write (p0.6a §3.2): nothing to lint.
+  const push = (where: string, context: Context, ss: readonly (SqlStatement | ScheduleDescriptor)[] | undefined) => {
+    for (const s of ss ?? []) if (!isTimerDescriptor(s)) out.push({ sql: s.sql, context, where });
+  };
+  for (const [key, body] of Object.entries(def.acquire ?? {}))
+    out.push({ sql: body as string, context: "acquire", where: `acquire ${key}` });
+  out.push(...trackSql(def, options));
+  const c = def.checkout;
+  if (c?.reads) push("checkout.reads", "read", Object.values(c.reads(sample, options)));
+  if (c?.statements) {
+    // Cite every declared fact under a sample key, so conditional statements are produced.
+    const facts = Object.fromEntries(
+      Object.keys(c.facts ?? {}).map((n) => [n, new Proxy({}, { get: () => "cfa_lint" })]),
+    );
+    push(
+      "checkout.statements",
+      "contribution",
+      c.statements({
+        orderId: "ord_lint",
+        email: sample.email,
+        customerId: sample.customerId,
+        currency: sample.currency,
+        options,
+        claim: {},
+        lines: [
+          {
+            id: "ordl_lint",
+            variantId: "var_lint",
+            sku: "S",
+            title: "T",
+            quantity: 1,
+            unitAmount: 100,
+            lineTotal: 100,
+            kind: "item",
+            parentId: null,
+            chargeClass: "revenue",
+            taxable: true,
+            discountable: true,
+            periodStart: null,
+            periodEnd: null,
+            custom: {},
+          },
+        ],
+        facts,
+        fees: [{ code: "lint", amount: 1 }],
+        adjustments: [{ code: "lint", amount: -1 }],
+      }),
+    );
+  }
+  for (const [key, handler] of Object.entries(def.release ?? {})) {
+    if (!handler) continue;
+    push(
+      `release ${key}`,
+      "statement",
+      handler(
+        {
+          uid: "ord_lint:expired",
+          aggregate: "order",
+          aggregateId: "ord_lint",
+          fromState: "pending_payment",
+          toState: "expired",
+        },
+        options,
+      ),
+    );
+  }
+  return out;
+}
+
+export function lintPlugin<O>(def: PluginDefinition<O>, options: O): LintIssue[] {
+  const owner: Owner = { kind: "plugin", name: def.name };
+  const issues: LintIssue[] = [];
+  const texts: string[] = [];
+  for (const m of def.migrations ?? []) {
+    texts.push(m.sql);
+    for (const i of lintSql(owner, m.sql, { context: "migration" })) issues.push({ ...i, at: `${m.id}: ${i.at}` });
+  }
+  let runtime: ReturnType<typeof collect>;
+  try {
+    runtime = collect(def, options);
+  } catch (e) {
+    issues.push({
+      rule: "unlintable",
+      message: `building the plugin's SQL with sample input threw: ${(e as Error).message}`,
+      at: def.name,
+    });
+    runtime = [];
+  }
+  for (const r of runtime) {
+    texts.push(r.sql);
+    const factTables = Object.values(def.checkout?.facts ?? {}).map((f) => f.table);
+    for (const i of lintSql(owner, r.sql, { context: r.context, factTables }))
+      issues.push({ ...i, at: `${r.where}: ${i.at}` });
+  }
+  // Only core writes an entity table (§4.2), from every SQL source a plugin has:
+  // a migration's trigger, an acquire body core installs as a trigger, a
+  // consequence, a release (codex code r6).
+  const entityTables = Object.keys(def.entities ?? {}).map((e) => entityTable(def.name, e));
+  const sources = [
+    ...(def.migrations ?? []).map((m) => ({ where: `migration ${m.id}`, sql: m.sql })),
+    ...runtime.map((r) => ({ where: r.where, sql: r.sql })),
+  ];
+  for (const s of sources)
+    for (const message of entityWriteProblems(s.sql, entityTables))
+      issues.push({ rule: "entity-write", message, at: s.where });
+
+  // The error-map check: every named CHECK and RAISE text maps to a code.
+  const mapped = new Set(Object.keys(def.errors ?? {}));
+  const { checks, raises } = errorSources(texts.join(";\n"));
+  for (const key of [...checks, ...raises]) {
+    if (!mapped.has(key))
+      issues.push({ rule: "error-map", message: `"${key}" has no entry in the plugin's error map`, at: def.name });
+  }
+  return issues;
+}