@starci/eslint-canon-be 3.8.7 → 3.8.11

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/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.8.11 - 2026-10-29
4
+
5
+ - Fixed: `source-suffix` (BE_SOURCE_FORM, R89) admits the one file a file slot names by its path, read from the slot manifest: the lite entity registry `src/modules/platform/database/entities.ts` (slot `be.platform.database.entities`) was refused for having no role suffix.
6
+ - Changed: `no-raw-sql` (R334) exempts its two raw SQL owners by side-relative folder (`RAW_SQL_OWNERS`: `src/modules/platform/database/` and `src/tests/world/`) and keeps refusing raw SQL in integration and e2e specs, builders and fixtures; its messages send a spec author to entities on `world.db.<connection>` or a named world helper. `callDbFunction` with a listed function is allowed in specs as in domain code (ruling lite-test-sql-owner).
7
+ - Fixed: the edition gate (`pluginForEdition`) reads the rule catalog in full too, so a rule whose catalog entries name only lite is inactive in full: `no-raw-sql` (R334, `editions: [lite]`) no longer fires on a full app, whose SQL law is R36. Full used to return every rule without reading the catalog.
8
+ - Changed: the bundled canon pins name hfs 4.11.12, eslint-canon-be 3.8.11, eslint-canon-fe 9.5.13 and the Grammar family 0.15.24.
9
+
10
+ ## 3.8.10 - 2026-10-29
11
+
12
+ - Changed: the bundled canon pins name hfs 4.11.11, eslint-canon-be 3.8.10, eslint-canon-fe 9.5.12 and the Grammar family 0.15.23. No rule changed.
13
+
14
+ ## 3.8.9 - 2026-10-29
15
+
16
+ - Changed: the bundled canon pins name hfs 4.11.10, eslint-canon-be 3.8.9, eslint-canon-fe 9.5.11 and the Grammar family 0.15.22. No rule changed.
17
+
18
+ ## 3.8.8 - 2026-10-29
19
+
20
+ - Changed: the bundled canon pins name hfs 4.11.9, eslint-canon-be 3.8.8, eslint-canon-fe 9.5.10 and the Grammar family 0.15.21. No rule changed.
21
+
3
22
  ## 3.8.7 - 2026-10-29
4
23
 
5
24
  - Changed: the bundled canon pins name hfs 4.11.8, eslint-canon-be 3.8.7, eslint-canon-fe 9.5.9 and the Grammar family 0.15.20. No rule changed.
@@ -11,10 +11,9 @@ import type { CanonPlugin } from "./config.js";
11
11
  /**
12
12
  * The plugin view for one HFS edition.
13
13
  *
14
- * Full is the default edition and the catalog's superset, so it needs no runtime catalog read. This
15
- * keeps the source checkout testable before `sync-runtime` refreshes the generated bundle; lite
16
- * loads the package's bundled catalog in a published installation. Tests may inject a catalog to
17
- * prove the generic filtering independently of generated copies.
14
+ * Both editions read the catalog: full is the default edition, and a rule whose catalog entries name only lite (R334
15
+ * `no-raw-sql`) is inactive there, as a full-only rule is in lite. The bundled catalog is loaded once per lint process;
16
+ * tests may inject a catalog to prove the generic filtering independently of the bundled copy.
18
17
  */
19
18
  export declare const pluginForEdition: <P extends CanonPlugin>({ plugin, hfs, catalog }: {
20
19
  plugin: P;
@@ -19,18 +19,15 @@ const inactive = (rule) => Object.freeze({ ...rule, create: () => ({}) });
19
19
  /**
20
20
  * The plugin view for one HFS edition.
21
21
  *
22
- * Full is the default edition and the catalog's superset, so it needs no runtime catalog read. This
23
- * keeps the source checkout testable before `sync-runtime` refreshes the generated bundle; lite
24
- * loads the package's bundled catalog in a published installation. Tests may inject a catalog to
25
- * prove the generic filtering independently of generated copies.
22
+ * Both editions read the catalog: full is the default edition, and a rule whose catalog entries name only lite (R334
23
+ * `no-raw-sql`) is inactive there, as a full-only rule is in lite. The bundled catalog is loaded once per lint process;
24
+ * tests may inject a catalog to prove the generic filtering independently of the bundled copy.
26
25
  */
27
26
  export const pluginForEdition = ({ plugin, hfs, catalog }) => {
28
27
  const edition = hfs?.edition === undefined ? "full" : hfs.edition;
29
28
  if (edition !== "full" && edition !== "lite") {
30
29
  throw new RangeError(`Unknown HFS edition ${JSON.stringify(edition)}; expected "full" or "lite"`);
31
30
  }
32
- if (edition === "full" && catalog === undefined)
33
- return plugin;
34
31
  const loaded = catalog ?? bundledCatalog();
35
32
  const rules = Object.fromEntries(Object.entries(plugin.rules).map(([id, rule]) => [
36
33
  id,
@@ -1,5 +1,5 @@
1
1
  import type { RuleModule, Recommended } from "./lib/rule.js";
2
- /** No raw SQL in lite domain or feature code: entities on the EntityManager carry every read and write. */
2
+ /** No raw SQL in lite domain, feature or test code: entities on an EntityManager carry every read and write. */
3
3
  export declare const noRawSql: RuleModule;
4
4
  /** The rule of the lite persistence law, by name. */
5
5
  export declare const rules: {
@@ -1,24 +1,31 @@
1
1
  /**
2
- * The lite persistence law (catalog R334 `BE_PERSISTENCE_NO_RAW_SQL`; contexts/code/be/persistence.md BE-PERSISTENCE-1 and -2):
3
- * domain and feature code reads and writes through TypeORM entities on the injected EntityManager (`find`, `save`, `update`,
2
+ * The lite persistence law (catalog R334 `BE_PERSISTENCE_NO_RAW_SQL`; contexts/code/be/persistence.md BE-PERSISTENCE-4):
3
+ * domain, feature and test code reads and writes through TypeORM entities on an EntityManager (`find`, `save`, `update`,
4
4
  * `delete`, `upsert`, `createQueryBuilder(Entity, "alias")` with named parameters), never through raw SQL.
5
5
  *
6
- * - `no-raw-sql` refuses, outside `platform/database`, every `.query(` call and every `sql` tagged template. A database function
7
- * TypeORM cannot express is called through the typed helpers of `platform/database` (`callDbFunction(manager, name, args)`,
8
- * `advisoryXactLock(manager, key)`, `notify(manager, channel, payload)`), and a literal function name handed to
9
- * `callDbFunction` must be one `ruleParams.be.dbFunctions` lists (the canon's pg built-ins, bare, plus every other function
10
- * schema-qualified, `public.job_claim`, including hfs.json `sides.be.dbFunctions`).
11
- * The allow-list governs WHICH functions may be called, the helper WHERE the SQL is built. A query builder names its entity
12
- * (`createQueryBuilder(Entity, "alias")`): a builder over a table-name string, a builder with no entity, and a
13
- * `getRepository(...)` are refused, because they bypass the entity mapping. The rule runs in lite only (the
14
- * catalog's `editions`); full keeps R36.
6
+ * - `no-raw-sql` refuses every `.query(` call and every `sql` tagged template outside the two owners of raw SQL
7
+ * (`RAW_SQL_OWNERS`): `platform/database`, which keeps the migration runner and the database-function helpers, and the test
8
+ * world `src/tests/world`, the owner of test infrastructure, which wraps what entities cannot express (a trigger, a database
9
+ * function, a row-level-security probe, a pgmq queue inspection) in a named, typed helper on the world that specs call.
10
+ * Specs, builders and fixtures outside the world seed and assert through entities on `world.db.<connection>`.
11
+ * A database function TypeORM cannot express is called through the typed helpers of `platform/database`
12
+ * (`callDbFunction(manager, name, args)`, `advisoryXactLock(manager, key)`, `notify(manager, channel, payload)`), in
13
+ * domain and test code alike, and a literal function name handed to `callDbFunction` must be one `ruleParams.be.dbFunctions`
14
+ * lists (the canon's pg built-ins, bare, plus every other function schema-qualified, `public.job_claim`, including hfs.json
15
+ * `sides.be.dbFunctions`). The allow-list governs WHICH functions may be called, the helper WHERE the SQL is built. A query
16
+ * builder names its entity (`createQueryBuilder(Entity, "alias")`): a builder over a table-name string, a builder with no
17
+ * entity, and a `getRepository(...)` are refused outside the owners, because they bypass the entity mapping. The rule runs
18
+ * in lite only (the catalog's `editions`); full keeps R36.
15
19
  *
16
20
  * Schema authority stays `db/migrations/*.sql`; whether the entities match it is `BE_ENTITY_SCHEMA_DRIFT` of `starci app db drift`.
17
21
  */
18
22
  import { staticText } from "./lib/ast.js";
19
23
  import { hfsOf } from "./lib/hfs.js";
20
- /** The owner id (`<tier>/<capability>`) that keeps the migration runner and the database-function helpers. */
21
- const DATABASE_OWNER = "platform/database";
24
+ /**
25
+ * The owners that may hold raw SQL, by side-relative folder: the database capability (the migration runner and the
26
+ * database-function helpers) and the test world (the test infrastructure, whose named helpers wrap what entities cannot express).
27
+ */
28
+ const RAW_SQL_OWNERS = ["src/modules/platform/database/", "src/tests/world/"];
22
29
  /** The helper of platform/database whose second argument names the function it calls. */
23
30
  const CALL_HELPER = "callDbFunction";
24
31
  /** True when a builder's first argument can be an entity class: neither absent nor a string. */
@@ -28,23 +35,23 @@ const namesEntity = (argument) => {
28
35
  const node = argument;
29
36
  return !((node.type === "Literal" && typeof node.value === "string") || node.type === "TemplateLiteral");
30
37
  };
31
- /** No raw SQL in lite domain or feature code: entities on the EntityManager carry every read and write. */
38
+ /** No raw SQL in lite domain, feature or test code: entities on an EntityManager carry every read and write. */
32
39
  export const noRawSql = {
33
40
  meta: {
34
41
  type: "problem",
35
- docs: { description: "Lite domain and feature code uses TypeORM entities on the EntityManager; `.query(` and `sql` templates stay in platform/database, and callDbFunction names only listed functions." },
42
+ docs: { description: "Lite domain, feature and test code uses TypeORM entities on an EntityManager; `.query(` and `sql` templates stay in platform/database and the test world, and callDbFunction names only listed functions." },
36
43
  schema: [],
37
44
  messages: {
38
- query: "`.query(` runs raw SQL outside `platform/database`. Read and write through the entity on the EntityManager (`find`, `save`, `update`, `upsert`, `createQueryBuilder(Entity, \"alias\")` with named parameters); call a database function TypeORM cannot express through `callDbFunction(manager, name, args)` (or `advisoryXactLock`, `notify`) of `platform/database`.",
39
- template: "A `sql` template outside `platform/database`. Lite persistence maps tables with TypeORM entities; build the query with the EntityManager or `createQueryBuilder`, or call a database function through `callDbFunction`.",
45
+ query: "`.query(` runs raw SQL outside `platform/database` and the test world. Read and write through the entity on the EntityManager (`find`, `save`, `update`, `upsert`, `createQueryBuilder(Entity, \"alias\")` with named parameters); a spec, builder or fixture seeds and asserts through entities on `world.db.<connection>`. Call a database function TypeORM cannot express through `callDbFunction(manager, name, args)` (or `advisoryXactLock`, `notify`) of `platform/database`; a test that must reach what entities cannot express (a trigger, a row-level-security probe, a pgmq queue) calls a named helper of `src/tests/world`.",
46
+ template: "A `sql` template outside `platform/database` and the test world. Lite persistence maps tables with TypeORM entities: build the query with the EntityManager or `createQueryBuilder` (in a test, on `world.db.<connection>`), call a database function through `callDbFunction`, or, in a test, call a named helper of `src/tests/world`.",
40
47
  builder: "A query builder must name its entity: `manager.createQueryBuilder(Entity, \"alias\")` on the injected EntityManager. A table-name string, a builder with no entity and a Repository bypass the entity mapping.",
41
48
  unlisted: "`{{name}}` is not a listed database function. Name a function of a migration schema-qualified (`public.job_claim`) and add it to hfs.json `sides.be.dbFunctions` with the reason TypeORM cannot express it; a pg built-in is named bare only when the canon lists it; or map the work with an entity.",
42
49
  },
43
50
  },
44
51
  create(context) {
45
52
  const hfs = hfsOf(context);
46
- const root = hfs.ownerOf(context.filename);
47
- const inDatabase = root !== null && root.split("/").slice(-2).join("/") === DATABASE_OWNER;
53
+ const relative = hfs.relative(context.filename);
54
+ const inOwner = RAW_SQL_OWNERS.some((owner) => relative.startsWith(owner));
48
55
  const listed = new Set((hfs.ruleParams.dbFunctions ?? []).map((entry) => entry.name));
49
56
  return {
50
57
  CallExpression(node) {
@@ -55,7 +62,7 @@ export const noRawSql = {
55
62
  context.report({ node, messageId: "unlisted", data: { name } });
56
63
  return;
57
64
  }
58
- if (inDatabase || callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier")
65
+ if (inOwner || callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier")
59
66
  return;
60
67
  const method = callee.property.name;
61
68
  if (method === "query")
@@ -66,7 +73,7 @@ export const noRawSql = {
66
73
  context.report({ node, messageId: "builder" });
67
74
  },
68
75
  TaggedTemplateExpression(node) {
69
- if (inDatabase || node.tag.type !== "Identifier" || node.tag.name !== "sql")
76
+ if (inOwner || node.tag.type !== "Identifier" || node.tag.name !== "sql")
70
77
  return;
71
78
  context.report({ node, messageId: "template" });
72
79
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.8.7",
3
+ "version": "3.8.11",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,35 +31,35 @@ pins:
31
31
  source: packages/event-stream/package.json
32
32
  why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
33
33
  '@starci/grammar':
34
- version: 0.15.20
34
+ version: 0.15.24
35
35
  group: starci
36
36
  install: registry
37
37
  side: fe
38
38
  source: packages/grammar/package.json
39
39
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
40
40
  '@starci/eslint-canon-be':
41
- version: 3.8.7
41
+ version: 3.8.11
42
42
  group: starci
43
43
  install: registry
44
44
  side: be
45
45
  source: packages/eslint-canon-be/package.json
46
46
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
47
47
  '@starci/eslint-canon-fe':
48
- version: 9.5.9
48
+ version: 9.5.13
49
49
  group: starci
50
50
  install: registry
51
51
  side: fe
52
52
  source: packages/eslint-canon-fe/package.json
53
53
  why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
54
54
  '@starci/eslint-grammar-core':
55
- version: 0.15.20
55
+ version: 0.15.24
56
56
  group: starci
57
57
  install: registry
58
58
  side: fe
59
59
  source: packages/eslint-grammar-core/package.json
60
60
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
61
61
  '@starci/eslint-grammar-offset-pop':
62
- version: 0.15.20
62
+ version: 0.15.24
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
@@ -106,7 +106,7 @@ pins:
106
106
  source: packages/ai-router/package.json
107
107
  why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
108
108
  '@starci/hfs':
109
- version: 4.11.8
109
+ version: 4.11.12
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -5828,7 +5828,7 @@ rules:
5828
5828
  ruling: "Lite entities only map tables the migrations create, so each entity column is checked against the migrated schema by starci app db drift, which CI runs in the build job and the release gate runs as its db-drift row."
5829
5829
  - id: R334
5830
5830
  code: "BE_PERSISTENCE_NO_RAW_SQL"
5831
- law: "Lite domain and feature code reads and writes through TypeORM entities on the injected EntityManager (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside platform/database; a database function TypeORM cannot express is called through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
5831
+ law: "Lite domain, feature and test code reads and writes through TypeORM entities on an EntityManager (domain code the injected one, integration and e2e specs, builders and fixtures the world's `world.db.<connection>`) (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside the two raw SQL owners, platform/database and the test world src/tests/world, which wraps only what entities cannot express (a trigger, a database function, a row-level-security probe, a pgmq queue) in a named, typed world helper specs call; a database function TypeORM cannot express is called, in domain and test code alike, through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
5832
5832
  kinds: [lint]
5833
5833
  gates: [pre-commit, settle, land, ci]
5834
5834
  failureCodes: ["BE_PERSISTENCE_NO_RAW_SQL"]
@@ -29,6 +29,8 @@ function sourceFormContext(file, resolver, suffixes, bannedSuffixes) {
29
29
  const base = path.posix.basename(file);
30
30
  if (FREE_NAMES.has(base)) return null;
31
31
  const slot = resolver.slot(c.slot);
32
+ // A file slot declares its one file by its path (be.platform.database.entities: src/modules/platform/database/entities.ts).
33
+ if (slot?.path === c.path) return null;
32
34
  if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
33
35
  const admitted = allowsFile(resolver, file);
34
36
  // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
@@ -57,8 +59,8 @@ function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuf
57
59
  }
58
60
 
59
61
  /**
60
- * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
61
- * be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
62
+ * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, the one file a file
63
+ * slot names by its path (the lite entity registry src/modules/platform/database/entities.ts), a migration of be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
62
64
  * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
63
65
  * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
64
66
  */