@ingram-tech/nk-dev 0.7.0 → 0.8.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

@@ -7,6 +7,8 @@ import deferredCurrentTarget from "./deferred-current-target.js";
 import lucideIconSuffix from "./lucide-icon-suffix.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" },
@@ -16,5 +18,7 @@ export default {
 		...lucideIconSuffix.rules,
 		...noRedirectOnlyPage.rules,
 		...redundantUseStateType.rules,
+		...tNoPositionalArgs.rules,
+		...tRequiresValues.rules,
 	},
 };

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,8 @@
 		"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",
 		"no-unused-vars": "warn",
 		"typescript/no-non-null-assertion": "error",
 		"typescript/no-explicit-any": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-dev",
-	"version": "0.7.0",
+	"version": "0.8.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",