@ingram-tech/nk-dev 0.11.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/guide.md CHANGED
@@ -71,6 +71,16 @@ the UI/page tree, and never expose internal plumbing under `/api/`.
71
71
  nanoid. Ids that cross a **public contract** are skinned to `prefix_base58`
72
72
  via `id758` / `@ingram-tech/nk-db/id` (`createIdRegistry`) — never expose a raw UUID.
73
73
  External ids you don't mint (Stripe `cus_`, OAuth) stay `text`.
74
+ - **Application code only ever sees public ids** (`inv_…`); never convert by
75
+ hand. Declare id columns with `idColumn(entity)` from
76
+ `@ingram-tech/nk-db/id/drizzle`: a public id passed to a query is decoded at
77
+ the column, and a row read back is already encoded (typed `Id<"invoice">`).
78
+ In raw SQL and `psql`, the database converts: `where id = id758_decode($1)`,
79
+ `select id758_encode('inv', id)` (functions from `@ingram-tech/nk-db/id/sql`,
80
+ installed in PGlite automatically and in prod by one custom migration). So no
81
+ `ids.x.decode(param)` before a query and no `ids.x.encode(row.id)` after one
82
+ — `nextkit/no-id-codec-in-app-code` flags both; validate input with
83
+ `ids.x.is(param)` instead. At the shell, `bunx id758 decode inv_…`.
74
84
  - **Migrations don't auto-apply on deploy.** Code ships ahead of the prod schema
75
85
  unless someone runs the migration against the target DB — a page that reads a
76
86
  newly-added column 500s in prod until then. Apply migrations with
@@ -6,6 +6,7 @@ import baseUi from "./base-ui.js";
6
6
  import deferredCurrentTarget from "./deferred-current-target.js";
7
7
  import lucideIconSuffix from "./lucide-icon-suffix.js";
8
8
  import noCryptoRandomUuid from "./no-crypto-random-uuid.js";
9
+ import noIdCodecInAppCode from "./no-id-codec-in-app-code.js";
9
10
  import noRedirectOnlyPage from "./no-redirect-only-page.js";
10
11
  import noRedundantNodeCrypto from "./no-redundant-node-crypto.js";
11
12
  import redundantUseStateType from "./redundant-usestate-type.js";
@@ -20,6 +21,7 @@ export default {
20
21
  ...deferredCurrentTarget.rules,
21
22
  ...lucideIconSuffix.rules,
22
23
  ...noCryptoRandomUuid.rules,
24
+ ...noIdCodecInAppCode.rules,
23
25
  ...noRedirectOnlyPage.rules,
24
26
  ...noRedundantNodeCrypto.rules,
25
27
  ...redundantUseStateType.rules,
@@ -0,0 +1,100 @@
1
+ // nextkit oxlint JS plugin rule: keep the id codec out of application code.
2
+ //
3
+ // An id is a raw `uuid` in Postgres and a prefixed base58 string (`inv_…`)
4
+ // everywhere else. The conversion between the two happens in exactly two
5
+ // places — the Drizzle column (`idColumn` decodes on the way in and encodes on
6
+ // the way out) and the database itself (`id758_encode` / `id758_decode`) — so
7
+ // application code only ever handles the public form. A `ids.invoice.decode(x)`
8
+ // before a query, or an `ids.invoice.encode(row.id)` after one, is converting
9
+ // at the wrong layer: at best a no-op, at worst the source of a value that is
10
+ // in the other form from what its neighbour expects, which is exactly the class
11
+ // of bug the column layer exists to remove.
12
+ //
13
+ // Flagged:
14
+ // - the bare codec functions imported from `id758` or `@ingram-tech/nk-db/id`
15
+ // (`encodeId`, `decodeId`, `decodeAnyId`, and the deprecated
16
+ // `toPrefixedId` / `fromPrefixedId`), anywhere;
17
+ // - `.encode(…)`, `.decode(…)` and `.decodeOrNull(…)` called on a member of
18
+ // a binding imported as `ids` — the registry a site exports from `ids.ts`
19
+ // (`ids.invoice.decode(param)`).
20
+ //
21
+ // Not flagged: `.is()` (validating untrusted input is the app's job), `.mint()`,
22
+ // `.prefix`, and anything in `ids.ts` / `id.ts` / `schema.ts` / tests, where
23
+ // the boundary itself is built. A raw-SQL binding wants `sqlUuid(id)` or
24
+ // `id758_decode(…)` in the query, and a raw-SQL read wants `encodedId(…)` or
25
+ // `id758_encode(…)`; both keep the conversion at the boundary.
26
+
27
+ const CODEC_MODULES = new Set(["id758", "@ingram-tech/nk-db/id"]);
28
+ const CODEC_FUNCTIONS = new Set([
29
+ "encodeId",
30
+ "decodeId",
31
+ "decodeAnyId",
32
+ "toPrefixedId",
33
+ "fromPrefixedId",
34
+ ]);
35
+ const HELPER_METHODS = new Set(["encode", "decode", "decodeOrNull"]);
36
+ const BOUNDARY_FILES = /(^|[\\/])(ids?|schema)\.[cm]?[jt]sx?$/;
37
+
38
+ const noIdCodecInAppCode = {
39
+ meta: {
40
+ type: "suggestion",
41
+ docs: {
42
+ description:
43
+ "Disallow converting between public ids and uuids in application code; the column and the database do it",
44
+ },
45
+ messages: {
46
+ codecImport:
47
+ "`{{name}}` converts between a public id and a uuid in application code. A column declared with `idColumn` takes public ids and returns them, and raw SQL has `id758_encode` / `id758_decode` (or `sqlUuid` / `encodedId` from `createIdColumns`). Keep the codec in `ids.ts`.",
48
+ helperCall:
49
+ "`{{callee}}()` converts between a public id and a uuid in application code. Pass the public id straight to the query (an `idColumn` decodes it) and read it back as-is (the column encodes it); validate untrusted input with `.is()`. In raw SQL use `id758_decode(…)` / `id758_encode(…)`.",
50
+ },
51
+ },
52
+ create(context) {
53
+ if (BOUNDARY_FILES.test(context.filename ?? "")) return {};
54
+ // Local names bound to `ids` (the site's registry) by an import.
55
+ const registryNames = new Set();
56
+ return {
57
+ ImportDeclaration(node) {
58
+ for (const specifier of node.specifiers) {
59
+ if (specifier.type !== "ImportSpecifier") continue;
60
+ if (specifier.imported.type !== "Identifier") continue;
61
+ const name = specifier.imported.name;
62
+ if (
63
+ CODEC_MODULES.has(node.source.value) &&
64
+ CODEC_FUNCTIONS.has(name)
65
+ ) {
66
+ context.report({
67
+ node: specifier,
68
+ messageId: "codecImport",
69
+ data: { name },
70
+ });
71
+ }
72
+ if (name === "ids") registryNames.add(specifier.local.name);
73
+ }
74
+ },
75
+ CallExpression(node) {
76
+ const callee = node.callee;
77
+ if (callee.type !== "MemberExpression" || callee.computed) return;
78
+ if (callee.property.type !== "Identifier") return;
79
+ if (!HELPER_METHODS.has(callee.property.name)) return;
80
+ const helper = callee.object;
81
+ if (helper.type !== "MemberExpression" || helper.computed) return;
82
+ if (helper.property.type !== "Identifier") return;
83
+ if (helper.object.type !== "Identifier") return;
84
+ if (!registryNames.has(helper.object.name)) return;
85
+ context.report({
86
+ node,
87
+ messageId: "helperCall",
88
+ data: {
89
+ callee: `${helper.object.name}.${helper.property.name}.${callee.property.name}`,
90
+ },
91
+ });
92
+ },
93
+ };
94
+ },
95
+ };
96
+
97
+ export default {
98
+ meta: { name: "nextkit" },
99
+ rules: { "no-id-codec-in-app-code": noIdCodecInAppCode },
100
+ };
package/oxlintrc.json CHANGED
@@ -13,6 +13,7 @@
13
13
  "nextkit/t-requires-values": "error",
14
14
  "nextkit/t-no-positional-args": "error",
15
15
  "nextkit/no-crypto-random-uuid": "warn",
16
+ "nextkit/no-id-codec-in-app-code": "warn",
16
17
  "nextkit/no-redundant-node-crypto": "warn",
17
18
  "nextkit/satori-css": "warn",
18
19
  "no-unused-vars": "warn",
@@ -36,7 +37,8 @@
36
37
  {
37
38
  "files": ["**/__tests__/**", "**/*.test.*", "**/*.spec.*", "**/test/**"],
38
39
  "rules": {
39
- "nextkit/no-crypto-random-uuid": "off"
40
+ "nextkit/no-crypto-random-uuid": "off",
41
+ "nextkit/no-id-codec-in-app-code": "off"
40
42
  }
41
43
  }
42
44
  ]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-dev",
3
- "version": "0.11.1",
3
+ "version": "0.12.0",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "type": "module",