@ingram-tech/nk-dev 0.7.0 → 0.9.0

package/guide.md

@@ -77,6 +77,12 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
   `@ingram-tech/nk-db`'s drift-aware runner (`@ingram-tech/nk-db/migrate`), which
   surfaces the real Postgres error and pre-flights journal drift. Generate **and
   apply** in the same step; don't leave "run the migration" as a handoff.
+- **A migration that moves data asserts how much it moved.** Any backfill /
+  seed / copy counts the rows it expects, compares that to the `row_count` it
+  got (`get diagnostics`), and `raise exception`s on a mismatch — inside the
+  transaction, before commit. A blind move that touches nothing (an RLS mask, a
+  wrong `where`) otherwise reports success, and the drop of the source columns
+  in the same migration makes it unrecoverable.
 - **`drizzle-kit` is GENERATE-ONLY — it must never apply schema.** Use it for
   `drizzle-kit generate` (and `generate --custom` for a package-owned/raw SQL
   migration). Applying is always **`nk-pg-migrate`** (the bin from

package/lib/oxlint-plugins/icu-arguments.js

@@ -0,0 +1,79 @@
+// Shared helper for the `t-*` oxlint rules: extract the ICU MessageFormat
+// argument list from a message.
+//
+// Only depth-0 braces are argument positions. Braces nested inside a
+// plural/select sub-message are ordinary text and must not be read as
+// arguments -- `{count, plural, one {# item} other {# items}}` has exactly one
+// argument, `count`, not three. A brace-depth scan gets this exactly right,
+// which is why this lives in the linter rather than in the package's types:
+// TypeScript template-literal types cannot match brace pairs, so the same check
+// expressed as a type would report `# item` as an argument.
+//
+// A depth-0 brace whose contents do not open with an identifier or a number is
+// not an argument at all -- it is literal text the author wrote. `{"a": 1}`,
+// `{}`, and `body { color: red }` all fall out here and are skipped silently.
+// That bias matters: in this i18n scheme the English source string *is* the
+// catalog key, so an author cannot ICU-escape a stray brace without changing
+// the key and every translation of it. Staying quiet on ambiguous braces is the
+// only behaviour that leaves those messages usable.
+
+// ICU argNameOrNumber, anchored at a brace: an identifier or a number, followed
+// by the argument's `,` separator or its closing `}`.
+const ARGUMENT_HEAD = /^\{\s*([A-Za-z_$][\w$]*|\d+)\s*[,}]/;
+
+/**
+ * The ICU arguments of `message`, in source order.
+ *
+ * Under-reports rather than over-reports. A message using ICU's apostrophe
+ * escaping for a literal brace (`Use '{' here`) leaves the scan's depth
+ * unbalanced, so later arguments go unseen -- a missed lint, never a false one.
+ *
+ * @param {string} message
+ * @returns {{ name: string, positional: boolean }[]}
+ */
+export function icuArguments(message) {
+	const args = [];
+	let depth = 0;
+	for (let index = 0; index < message.length; index++) {
+		const char = message[index];
+		if (char === "}") {
+			if (depth > 0) depth--;
+			continue;
+		}
+		if (char !== "{") continue;
+		if (depth === 0) {
+			const match = ARGUMENT_HEAD.exec(message.slice(index));
+			if (match) {
+				args.push({ name: match[1], positional: /^\d+$/.test(match[1]) });
+			}
+		}
+		depth++;
+	}
+	return args;
+}
+
+/**
+ * Whether `node` is a call to a translator: `t(...)`, by convention throughout
+ * the fleet (`const t = createT(locale, scope)` / `const t = useT({ fr, nl })`).
+ * Gating on the callee name keeps the rules inert everywhere else without
+ * needing to resolve the binding back to `createT`/`useT`.
+ *
+ * @param {{ callee: { type: string, name?: string } }} node
+ */
+export function isTranslatorCall(node) {
+	return node.callee.type === "Identifier" && node.callee.name === "t";
+}
+
+/**
+ * The message literal of a translator call, or `null` when the first argument
+ * is not a plain string literal (a runtime key -- nothing to check statically).
+ *
+ * @param {{ arguments: { type: string, value?: unknown }[] }} node
+ */
+export function messageLiteral(node) {
+	const first = node.arguments[0];
+	if (!first || first.type !== "Literal" || typeof first.value !== "string") {
+		return null;
+	}
+	return first;
+}

package/lib/oxlint-plugins/index.js

@@ -5,8 +5,11 @@
 import baseUi from "./base-ui.js";
 import deferredCurrentTarget from "./deferred-current-target.js";
 import lucideIconSuffix from "./lucide-icon-suffix.js";
+import noCryptoRandomUuid from "./no-crypto-random-uuid.js";
 import noRedirectOnlyPage from "./no-redirect-only-page.js";
 import redundantUseStateType from "./redundant-usestate-type.js";
+import tNoPositionalArgs from "./t-no-positional-args.js";
+import tRequiresValues from "./t-requires-values.js";
 
 export default {
 	meta: { name: "nextkit" },
@@ -14,7 +17,10 @@ export default {
 		...baseUi.rules,
 		...deferredCurrentTarget.rules,
 		...lucideIconSuffix.rules,
+		...noCryptoRandomUuid.rules,
 		...noRedirectOnlyPage.rules,
 		...redundantUseStateType.rules,
+		...tNoPositionalArgs.rules,
+		...tRequiresValues.rules,
 	},
 };

package/lib/oxlint-plugins/no-crypto-random-uuid.js

@@ -0,0 +1,117 @@
+// nextkit oxlint JS plugin rule: keep `crypto.randomUUID()` off the id write
+// path.
+//
+// nextkit ids are UUIDv7: time-ordered, so inserts land at the right edge of the
+// primary-key B-tree instead of scattering across it. `crypto.randomUUID()` is
+// v4 — uniformly random — so a single call site minting a stored id fragments
+// that index while every other row in the table stays ordered. The mismatch is
+// invisible until the table is large, which is exactly when it is expensive to
+// undo.
+//
+// The mint is `uuidGenerateId()` from `@ingram-tech/nk-db/id`, already typed
+// `Uuid`. Most rows need no mint at all: `uuid("id").primaryKey().default(sql`
+// `uuidv7()`)` lets the database do it, and the app only mints when it needs the
+// id *before* the insert (a client-chosen document PK it must also use as the
+// storage object name).
+//
+// Deliberately not autofixable. The right replacement depends on what the value
+// is, and one of the answers is "leave it alone":
+//
+//   - a stored id            -> uuidGenerateId(), or drop it for the column default
+//   - a bearer token / nonce -> keep crypto.randomUUID()
+//
+// v7 is the *wrong* choice for a secret. It spends 48 bits on a millisecond
+// timestamp, leaving 74 random bits against v4's 122, and it leaks its own
+// creation time to whoever holds it. Invitation tokens, OAuth `state`, password
+// reset links and similar unguessable values must stay v4 — silence the rule at
+// those call sites with a justified disable comment rather than "fixing" them:
+//
+//   // oxlint-disable-next-line nextkit/no-crypto-random-uuid -- CSRF nonce, wants v4 entropy
+//
+// Test files are exempt via an override in the shared oxlintrc: test rows are
+// ephemeral, so index locality is meaningless there and `crypto.randomUUID()`
+// stays the zero-import default that keeps fixtures readable.
+
+const NODE_CRYPTO_MODULES = new Set(["crypto", "node:crypto"]);
+
+/** `crypto.randomUUID` or `globalThis.crypto.randomUUID`, and not shadowed. */
+const isGlobalCryptoRandomUuid = (callee, scope) => {
+	if (callee.type !== "MemberExpression") return false;
+	if (callee.computed) return false;
+	if (callee.property.type !== "Identifier") return false;
+	if (callee.property.name !== "randomUUID") return false;
+
+	const object = callee.object;
+	let root;
+	if (object.type === "Identifier" && object.name === "crypto") {
+		root = object;
+	} else if (
+		object.type === "MemberExpression" &&
+		!object.computed &&
+		object.object.type === "Identifier" &&
+		object.object.name === "globalThis" &&
+		object.property.type === "Identifier" &&
+		object.property.name === "crypto"
+	) {
+		// `globalThis.crypto` can't be shadowed by a local binding.
+		return true;
+	} else {
+		return false;
+	}
+
+	// A local `crypto` (a mock, an injected dependency) is not the global one.
+	for (let current = scope; current; current = current.upper) {
+		const variable = current.variables?.find((v) => v.name === root.name);
+		if (!variable) continue;
+		return variable.defs.length === 0;
+	}
+	return true;
+};
+
+const noCryptoRandomUuid = {
+	meta: {
+		type: "problem",
+		docs: {
+			description:
+				"Disallow crypto.randomUUID() (UUIDv4) where nextkit ids are UUIDv7",
+		},
+		messages: {
+			cryptoRandomUuid:
+				"`crypto.randomUUID()` is UUIDv4; stored ids are UUIDv7. Mint with `uuidGenerateId()` from `@ingram-tech/nk-db/id`, or omit the id and let the `uuidv7()` column default apply. If this is a bearer token or nonce, keep v4 and add `// oxlint-disable-next-line nextkit/no-crypto-random-uuid -- <reason>`.",
+		},
+	},
+	create(context) {
+		const sourceCode = context.sourceCode;
+		// Local names bound to `randomUUID` imported from node:crypto.
+		const importedNames = new Set();
+
+		return {
+			ImportDeclaration(node) {
+				if (!NODE_CRYPTO_MODULES.has(node.source.value)) return;
+				for (const specifier of node.specifiers) {
+					if (specifier.type !== "ImportSpecifier") continue;
+					if (specifier.imported.type !== "Identifier") continue;
+					if (specifier.imported.name !== "randomUUID") continue;
+					importedNames.add(specifier.local.name);
+				}
+			},
+			CallExpression(node) {
+				const callee = node.callee;
+				const isImported =
+					callee.type === "Identifier" && importedNames.has(callee.name);
+				if (
+					!isImported &&
+					!isGlobalCryptoRandomUuid(callee, sourceCode.getScope(node))
+				) {
+					return;
+				}
+				context.report({ node, messageId: "cryptoRandomUuid" });
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "no-crypto-random-uuid": noCryptoRandomUuid },
+};

package/lib/oxlint-plugins/t-no-positional-args.js

@@ -0,0 +1,52 @@
+// nextkit oxlint JS plugin rule: forbid positional ICU arguments (`{0}`, `{1}`)
+// in `t()` messages.
+//
+// ICU MessageFormat permits numbered arguments, but they are wrong for this
+// i18n scheme in two ways. The English source string is the catalog key and is
+// what a translator reads, so `{0}` gives them no clue what the value is, and
+// reordering it for another language's word order becomes guesswork. Named
+// arguments carry that context in the key itself.
+//
+// Banning them also lets the runtime stay conservative about what counts as a
+// placeholder: `@ingram-tech/nk-i18n` only treats identifier-headed braces as
+// arguments, so prose and embedded JSON (`t('This is JSON: {"a": 1}')`) are
+// passed through untouched. That heuristic would have to admit digits -- and
+// with them `{2: "x"}` -- if positional arguments were allowed anywhere.
+
+import { icuArguments, isTranslatorCall, messageLiteral } from "./icu-arguments.js";
+
+const tNoPositionalArgs = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Forbid positional ICU arguments in t() messages",
+		},
+		messages: {
+			positionalArgument:
+				"`t()` message uses the positional placeholder `{{{name}}}`. Name it instead -- the English source is the catalog key, so translators read the placeholder and may need to reorder it.",
+		},
+	},
+	create(context) {
+		return {
+			CallExpression(node) {
+				if (!isTranslatorCall(node)) return;
+				const message = messageLiteral(node);
+				if (!message) return;
+
+				for (const arg of icuArguments(message.value)) {
+					if (!arg.positional) continue;
+					context.report({
+						node: message,
+						messageId: "positionalArgument",
+						data: { name: arg.name },
+					});
+				}
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "t-no-positional-args": tNoPositionalArgs },
+};

package/lib/oxlint-plugins/t-requires-values.js

@@ -0,0 +1,92 @@
+// nextkit oxlint JS plugin rule: a `t()` message with ICU placeholders must be
+// passed the values those placeholders need.
+//
+// `@ingram-tech/nk-i18n`'s translator returns the message unformatted when no
+// values argument is given -- it never reaches IntlMessageFormat, so nothing
+// throws and nothing warns. `t("Results for {query}")` therefore ships the
+// literal text `Results for {query}` to users with no runtime signal at all.
+// Every other failure in that package degrades loudly; this one is silent,
+// which makes it the one worth catching at author time.
+//
+// Two reports:
+//   - the values argument is missing entirely, while the message has arguments;
+//   - the values argument is an object literal that omits a required key, which
+//     is what a misspelling looks like (`t("… {query}", { qeury })`).
+//
+// When the values argument is anything other than a plain object literal (a
+// variable, a call, a spread), only the first check applies -- the keys are not
+// statically known and guessing would produce false reports.
+
+import { icuArguments, isTranslatorCall, messageLiteral } from "./icu-arguments.js";
+
+const tRequiresValues = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require values for the ICU placeholders in a t() message",
+		},
+		messages: {
+			missingValues:
+				"`t()` message uses the placeholder{{plural}} {{names}} but no values argument was passed. The placeholder text is rendered to users verbatim.",
+			missingValue:
+				"`t()` values object is missing `{{name}}`, required by the message's `{{{name}}}` placeholder.",
+		},
+	},
+	create(context) {
+		return {
+			CallExpression(node) {
+				if (!isTranslatorCall(node)) return;
+				const message = messageLiteral(node);
+				if (!message) return;
+
+				const args = icuArguments(message.value);
+				if (args.length === 0) return;
+
+				const names = args.map((arg) => arg.name);
+				const values = node.arguments[1];
+				if (!values) {
+					context.report({
+						node,
+						messageId: "missingValues",
+						data: {
+							plural: names.length === 1 ? "" : "s",
+							names: names.map((name) => `\`${name}\``).join(", "),
+						},
+					});
+					return;
+				}
+
+				if (values.type !== "ObjectExpression") return;
+				// A spread can supply anything; the key set is no longer known.
+				if (
+					values.properties.some((property) => property.type !== "Property")
+				) {
+					return;
+				}
+				const provided = new Set();
+				for (const property of values.properties) {
+					if (property.computed) return;
+					if (property.key.type === "Identifier")
+						provided.add(property.key.name);
+					else if (property.key.type === "Literal") {
+						provided.add(String(property.key.value));
+					} else return;
+				}
+
+				for (const name of names) {
+					if (provided.has(name)) continue;
+					context.report({
+						node: values,
+						messageId: "missingValue",
+						data: { name },
+					});
+				}
+			},
+		};
+	},
+};
+
+export default {
+	meta: { name: "nextkit" },
+	rules: { "t-requires-values": tRequiresValues },
+};

package/oxlintrc.json

@@ -10,6 +10,9 @@
 		"nextkit/no-redundant-usestate-type": "warn",
 		"nextkit/lucide-icon-suffix": "warn",
 		"nextkit/no-redirect-only-page": "warn",
+		"nextkit/t-requires-values": "error",
+		"nextkit/t-no-positional-args": "error",
+		"nextkit/no-crypto-random-uuid": "warn",
 		"no-unused-vars": "warn",
 		"typescript/no-non-null-assertion": "error",
 		"typescript/no-explicit-any": "error",
@@ -26,5 +29,13 @@
 		"jsx-a11y/prefer-tag-over-role": "off",
 		"jsx-a11y/no-autofocus": "off",
 		"jsx-a11y/role-has-required-aria-props": "off"
-	}
+	},
+	"overrides": [
+		{
+			"files": ["**/__tests__/**", "**/*.test.*", "**/*.spec.*", "**/test/**"],
+			"rules": {
+				"nextkit/no-crypto-random-uuid": "off"
+			}
+		}
+	]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "The nextkit dev toolchain in one package: the `nk` CLI plus shared oxlint/oxfmt, TypeScript, and Vitest config, the format-on-commit hook, and the AI agent guide. `nk init` scaffolds a site to use it.",
 	"license": "MIT",
 	"type": "module",