@assembly-js/app-foundation 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -19,6 +19,10 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.14.0
+- [guidance] The build agent now counts related rows per record with `db.$count` or a joined subquery, instead of a raw correlated subselect that drizzle renders without table names and that reads 0 on every row.
+- [behavior] Later edits to the app now catch a per-record count that would always show 0 (for example "0 answers" on every question) before the change is saved, and fix it in the same edit.
+
 ## 0.13.0
 - [new] `<ClientName client={client} />` and `<CompanyName company={company} />` from `@assembly-js/app-foundation/lib-client` render a name that opens the record's CRM page for staff and is plain text for a client viewer.
 - [new] `bun run build` runs `check:linked-names`, which fails when a client's or company's name is rendered by hand instead of through those components. It only runs on apps that carry the platform-links skill.

package/CLAUDE.md

@@ -648,6 +648,14 @@ export const items = pgTable('items', {
 - Use `drizzle-kit push` (not `migrate`) — no migration files; schema is pushed directly.
 - Use `@neondatabase/serverless` with `drizzle-orm/neon-http` — not `pg` or `postgres.js`. It's the standard driver for the Vercel serverless (Node) runtime this app deploys to; `lib/db.ts` already wires it up.
 - **No interactive transactions.** `db.transaction(async (tx) => …)` is unsupported on neon-http and throws (a 500). For atomic multi-writes use `db.batch([...])`; otherwise sequential `await`s. See the `assembly-db-transactions` skill.
+- **Per-row counts: `db.$count` or a joined subquery, never a raw correlated subselect.** In a `.select({ … })` field of a query with no join, drizzle writes the columns inside a `sql` template without table names, so `(select count(*) from ${answers} where ${answers.questionId} = ${questions.id})` compares answers with itself and every row counts 0, with no error. (`.where()` is unaffected.) Use one of:
+  ```ts
+  db.select({ id: questions.id, answerCount: db.$count(answers, and(eq(answers.questionId, questions.id), eq(answers.kind, 'answer'))) }).from(questions);
+
+  const ac = db.select({ questionId: answers.questionId, c: count().as('c') }).from(answers).where(eq(answers.kind, 'answer')).groupBy(answers.questionId).as('ac');
+  db.select({ id: questions.id, answerCount: sql<number>`coalesce(${ac.c}, 0)` }).from(questions).leftJoin(ac, eq(ac.questionId, questions.id));
+  ```
+  `bun run build` fails on the raw form (`check:sql-subselects`).
 - **Create writes every field the create form submits.** If a later save writes nested rows (packages, add-ons, blocks), create calls that same writer with the submitted payload. A success toast and a redirect to the editor do not save. See `assembly-record-writes`.
 - `DATABASE_URL` is already in the shell env. Do NOT hardcode it or write it to `.env.local`.
 - Use `db` from `lib/db.ts` in **server components, server actions, and route handlers only** — never in client components. This is enforced: `lib/db.ts` imports `server-only`, so pulling it (or anything that imports it, e.g. a lib file re-exporting constants) into a `'use client'` module fails `bun run build`. Keep client-shared constants/types in their own file, not next to server queries.

package/bin/check-sql-subselects.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// Fails the build when a raw `sql` template in a drizzle `.select({ … })` field
+// list runs a correlated subselect against another table and the statement has
+// no join. drizzle renders columns embedded in a select field as bare names when
+// the query has a single table, so `where ${answers.questionId} = ${questions.id}`
+// becomes `where "question_id" = "id"`: the inner table is compared with itself,
+// the SQL stays valid, and a per-row count is 0 for every row. A field that names
+// the template through a const in the same file is followed too.
+// Dependency free on purpose: it runs inside the generated app's sandbox before
+// any deps beyond Node are guaranteed.
+//
+// On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
+// update never rewrites an app's queries.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const SOURCE_DIRS = ['app', 'lib', 'components', 'src'];
+const SOURCE_FILE = /\.(tsx|ts|jsx|js|mjs)$/;
+const OPT_OUT = /sql-subselects:\s*qualified/;
+const SELECT_OBJECT = /\.select\s*\(\s*\{/g;
+const SQL_TEMPLATE = /\bsql\s*(?:<[^`;]*?>)?\s*`/g;
+// `const answerCountSql = sql\`…\`` or `const answerCountSql = (…) => sql\`…\``.
+const NAMED_TEMPLATE =
+  /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*(?:\([^)]*\)\s*(?::[^=;]+)?=>\s*)?sql\s*(?:<[^`;]*?>)?\s*`/g;
+const DECLARATION = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g;
+const FIELD_VALUE = /:\s*([A-Za-z_$][\w$]*)\b/g;
+const SUBSELECT = /\(\s*select\b/i;
+const FROM_TABLE = /\bfrom\s+\$\{\s*([A-Za-z_$][\w$]*)\s*\}/gi;
+const COLUMN_REF = /\$\{\s*([A-Za-z_$][\w$]*)\.[A-Za-z_$]/g;
+const JOIN = /\.(?:left|inner|right|full|cross)Join(?:Lateral)?\s*\(/;
+// A line that starts a new statement; without semicolons the next query would
+// otherwise be read as part of this one and its join would excuse this query.
+const NEXT_STATEMENT = /^\n\s*(?:export|const|let|var|function|async|return|await|if|for|while|class|import)\b/;
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (SOURCE_FILE.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Index just past a string, template literal or comment starting at `i`, or `i`
+// when none starts there. Templates recurse through their `${…}` holes.
+function skipLiteral(src, i) {
+  const c = src[i];
+  if (c === '/' && src[i + 1] === '/') {
+    const end = src.indexOf('\n', i);
+    return end === -1 ? src.length : end;
+  }
+  if (c === '/' && src[i + 1] === '*') {
+    const end = src.indexOf('*/', i + 2);
+    return end === -1 ? src.length : end + 2;
+  }
+  if (c === '"' || c === "'") {
+    let j = i + 1;
+    while (j < src.length && src[j] !== c && src[j] !== '\n') j += src[j] === '\\' ? 2 : 1;
+    return j + 1;
+  }
+  if (c === '`') return templateEnd(src, i);
+  return i;
+}
+
+// Index just past the template literal whose opening backtick is at `i`.
+function templateEnd(src, i) {
+  let j = i + 1;
+  while (j < src.length) {
+    if (src[j] === '\\') j += 2;
+    else if (src[j] === '`') return j + 1;
+    else if (src[j] === '$' && src[j + 1] === '{') j = closingIndex(src, j + 1) + 1;
+    else j += 1;
+  }
+  return src.length;
+}
+
+// Index of the bracket that closes the one at `i`.
+function closingIndex(src, i) {
+  let depth = 0;
+  let j = i;
+  while (j < src.length) {
+    const skipped = skipLiteral(src, j);
+    if (skipped !== j) {
+      j = skipped;
+      continue;
+    }
+    const c = src[j];
+    if (c === '(' || c === '[' || c === '{') depth += 1;
+    else if (c === ')' || c === ']' || c === '}') {
+      depth -= 1;
+      if (depth === 0) return j;
+    }
+    j += 1;
+  }
+  return src.length;
+}
+
+// The statement a `.select(` belongs to, from it to the next `;` at depth 0, a
+// new statement on a later line, or the bracket that closes the expression around it.
+function statementTail(src, i) {
+  let depth = 0;
+  let j = i;
+  while (j < src.length) {
+    const skipped = skipLiteral(src, j);
+    if (skipped !== j) {
+      j = skipped;
+      continue;
+    }
+    const c = src[j];
+    if (c === '(' || c === '[' || c === '{') depth += 1;
+    else if (c === ')' || c === ']' || c === '}') {
+      depth -= 1;
+      if (depth < 0) break;
+    } else if (depth === 0 && (c === ';' || (c === '\n' && NEXT_STATEMENT.test(src.slice(j, j + 40))))) break;
+    j += 1;
+  }
+  return src.slice(i, j);
+}
+
+// Bodies of every `sql` template in `text`, with their offset in it.
+function templatesIn(text) {
+  const out = [];
+  for (const m of text.matchAll(SQL_TEMPLATE)) {
+    const start = m.index + m[0].length - 1;
+    out.push({ body: text.slice(start, templateEnd(text, start)), offset: m.index });
+  }
+  return out;
+}
+
+function correlatesAnotherTable(body) {
+  if (!SUBSELECT.test(body)) return false;
+  const inner = new Set([...body.matchAll(FROM_TABLE)].map((m) => m[1]));
+  if (inner.size === 0) return false;
+  return [...body.matchAll(COLUMN_REF)].some((m) => !inner.has(m[1]));
+}
+
+// The source with comments and quoted strings blanked out (newlines and quotes
+// kept, so offsets and line numbers still match), so a query kept in a comment
+// or an example string is never checked. Template literals stay: `sql` is one.
+function withoutComments(src) {
+  let out = '';
+  let i = 0;
+  while (i < src.length) {
+    const end = skipLiteral(src, i);
+    if (end === i) {
+      out += src[i];
+      i += 1;
+      continue;
+    }
+    const chunk = src.slice(i, end);
+    if (src[i] === '/') out += chunk.replace(/[^\n]/g, ' ');
+    else if (src[i] === '`') out += chunk;
+    else out += chunk[0] + chunk.slice(1, -1).replace(/[^\n]/g, ' ') + chunk.slice(-1);
+    i = end;
+  }
+  return out;
+}
+
+function lineAt(src, index) {
+  return src.slice(0, index).split('\n').length;
+}
+
+const files = SOURCE_DIRS.flatMap((dir) => sourceFiles(join(ROOT, dir)));
+const violations = [];
+for (const file of files) {
+  const raw = readFileSync(file, 'utf8');
+  if (!raw.includes('.select(') || OPT_OUT.test(raw)) continue;
+  const src = withoutComments(raw);
+
+  // A name declared more than once in the file cannot be tied to one template
+  // without scope analysis, so it is not followed rather than guessed.
+  const declared = new Map();
+  for (const m of src.matchAll(DECLARATION)) declared.set(m[1], (declared.get(m[1]) ?? 0) + 1);
+  const named = new Map();
+  for (const m of src.matchAll(NAMED_TEMPLATE)) {
+    if (declared.get(m[1]) > 1) continue;
+    const start = m.index + m[0].length - 1;
+    named.set(m[1], src.slice(start, templateEnd(src, start)));
+  }
+
+  for (const m of src.matchAll(SELECT_OBJECT)) {
+    const objStart = m.index + m[0].length - 1;
+    const fields = src.slice(objStart, closingIndex(src, objStart) + 1);
+    const hits = templatesIn(fields)
+      .filter((t) => correlatesAnotherTable(t.body))
+      .map((t) => objStart + t.offset);
+    for (const v of fields.matchAll(FIELD_VALUE)) {
+      const body = named.get(v[1]);
+      if (body && correlatesAnotherTable(body)) hits.push(objStart + v.index);
+    }
+    if (hits.length === 0 || JOIN.test(statementTail(src, m.index))) continue;
+    const rel = relative(ROOT, file).split(sep).join('/');
+    for (const at of hits) violations.push(`${rel}:${lineAt(src, at)}`);
+  }
+}
+
+if (violations.length > 0 && UPDATE_TURN) {
+  console.warn('');
+  console.warn('check-sql-subselects: correlated sql subselect in a single-table select (this update turn is not failed for it):');
+  for (const v of violations) console.warn('  - ' + v);
+  console.warn('');
+} else if (violations.length > 0) {
+  console.error('');
+  console.error('A raw sql subselect in a .select({ … }) field reads another table, and the query has no join:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error('drizzle writes the columns in that template without table names when the query has');
+  console.error('one table, so `${answers.questionId} = ${questions.id}` compares answers with itself');
+  console.error('and the count is 0 on every row. Use db.$count as the field instead:');
+  console.error('  answerCount: db.$count(answers, and(eq(answers.questionId, questions.id), eq(answers.kind, "answer")))');
+  console.error('or group the counts in a subquery (.groupBy(...).as("ac")) and .leftJoin it.');
+  console.error('A template whose names are already qualified (sql.raw) can add the comment');
+  console.error('`// sql-subselects: qualified` to the file.');
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [