@starci/eslint-canon-be 3.19.0 → 3.19.1
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 +4 -0
- package/README.md +1 -1
- package/dist/lib/hfs-view.d.ts +5 -0
- package/dist/schema-authority.js +66 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.19.1 - 2026-11-05
|
|
4
|
+
|
|
5
|
+
- Added (HR-CORE-BE-3, R34 `BE_SCHEMA_AUTHORITY`, `no-runtime-schema`): a root-package file hfs.json `sides.be.ddlRenderers` lists (`{ path, reason }`, app-root relative, a `*` only in the file name; the hfs runtime merges it into `ruleParams.ddlRenderers`) may hold DDL text, so the renderer `cli entities plan --write` uses to write NEW migration files is no longer flagged. It may only build and return the text: in that file a database client import (typeorm, pg, ...) is refused (`rendererClient`) and so is a `.query/.execute/.exec/.raw/.unsafe` call (`rendererExecutes`); DDL text in any other file, including the rest of the same package and every file of the be side, is still refused; and a file that is neither the cli nor a root package and imports (or re-exports) a symbol the renderer declares, directly or through a package barrel, is refused (`rendererImported`; type-only imports are not). Needs @starci/hfs 5.13.2.
|
|
6
|
+
|
|
3
7
|
## 3.19.0 - 2026-11-05
|
|
4
8
|
|
|
5
9
|
- Changed (decision release-only-what-changed): the canon reads the @starci/hfs runtime (slots, rule catalog, canon pins, failure codes, the architecture machine) from the installed hfs at run time, which it peers by `~5.13.0`, and bundles no copy; `runtime/` keeps only the project graph rule, the jsdoc and sonar helpers and the package-scripts template. The stale forks it kept (slots 3.13.0) are gone, so it lints with the manifest hfs ships.
|
package/README.md
CHANGED
|
@@ -38,7 +38,7 @@ A sample, not the list:
|
|
|
38
38
|
| Area | What the rules hold |
|
|
39
39
|
|---|---|
|
|
40
40
|
| **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain; a root workspace package throws the error base its `package.json` declares (`starci.errorBase`) (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
|
|
41
|
-
| **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration, no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
|
|
41
|
+
| **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration (but the renderer files hfs.json `sides.be.ddlRenderers` declares, which only build and return DDL text and are not reachable from run-time code), no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
|
|
42
42
|
| **Config and secrets** | `process.env` (any form) is allowed in the `platform/config` file declaring `EnvSource`, the test world (slot `be.tests.world`) and the app bootstrap roles `apps/<app>/src/main.ts` and its matching `<app>.env.ts`; only those two app roles may read `EnvSource` or capability parse helpers. Compose groups and `<app>.options.ts` never read `process.env` or `EnvSource`. `@nestjs/config` and `dotenv` are forbidden config paths. A function exported by a `<capability>.config.ts` keeps its existing name and is called only from these bootstrap roles, its own config file or spec, the test world and a provider contract spec (`config-parsed-in-main`). Secrets use `EnvSource.secret()`: `<NAME>_FILE` takes priority for `.starcistacks` custody, and plain `<NAME>` is read only when the file key is absent; a declared file supplies exact contents and an empty or unreadable path fails startup without fallback. No default of any kind for a value typed `Secret` or `Url`; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `config-parsed-in-main`, `no-secret-default`, `secret-compare-timing-safe`) |
|
|
43
43
|
| **Model calls** (R326, R327, R344) | Every model call goes through the `@starci/ai-router` gateway: an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, with its `_FILE` twin) is named only in the gateway's custody owner `integrations/ai-gateway`, specs and the test world included; code builds only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai`, each from an inline options object whose `configuration.baseURL` is read from a `<c>.options.ts` type and whose `apiKey` is a `platform/config` `Secret` revealed; `integrations/ai` reads exactly `STARCI_AI_KEY`, the one virtual key of every client, and the custody owner passes the gateway no `adminToken`. Which owner may import LangChain, `openai`, a provider SDK or an agent framework is the infrastructure table (`provider-key-custody`, `ai-client-through-gateway`, `ai-virtual-key-name`, `infra-import-owner`) |
|
|
44
44
|
| **Ambient ids** (R142) | `randomUUID` of Node's crypto (named, namespace or global), the `v1`, `v4`, `v6` and `v7` generators of `uuid`, `nanoid` and `ulid` are used only inside `platform/ids`, specs included: code asks the injected `Ids` port and a spec provides `fakeIds()`; the generators are found by the module they are imported from, never by a local name (`no-ambient-id`) |
|
package/dist/lib/hfs-view.d.ts
CHANGED
|
@@ -114,6 +114,11 @@ export interface HfsRuleParams {
|
|
|
114
114
|
readonly file: string;
|
|
115
115
|
readonly reason: string;
|
|
116
116
|
}[];
|
|
117
|
+
/** The root-package files that render DDL text only to return it, app-root-relative with a reason (hfs.json `sides.be.ddlRenderers`). */
|
|
118
|
+
readonly ddlRenderers?: readonly {
|
|
119
|
+
readonly path: string;
|
|
120
|
+
readonly reason: string;
|
|
121
|
+
}[];
|
|
117
122
|
}
|
|
118
123
|
/** The frozen view of one side of an app. */
|
|
119
124
|
export interface HfsView {
|
package/dist/schema-authority.js
CHANGED
|
@@ -13,6 +13,10 @@
|
|
|
13
13
|
* `@Entity` (a per-entity switch is a second authority); a lifecycle hook (`onModuleInit`, `onApplicationBootstrap`) that
|
|
14
14
|
* writes rows through an `EntityManager` or `DataSource` (seeding is a cli command); a DDL statement in any string
|
|
15
15
|
* outside the migrations of `persistence/`; and an entity or migration glob. Only the cli (its migrate and seed commands) runs migrations and seeds.
|
|
16
|
+
* One declared exception: a root-package file hfs.json `sides.be.ddlRenderers` lists (the renderer a cli command uses to write NEW
|
|
17
|
+
* migration files) may hold DDL text, but only to build and return it: in that file a database client import (typeorm, pg, ...) and a
|
|
18
|
+
* `.query/.execute/.raw/.unsafe` call are refused, and a file outside the cli and the root packages that imports a symbol the
|
|
19
|
+
* renderer declares (directly or through a package barrel) is refused, so the text never reaches a run-time path.
|
|
16
20
|
* - `no-entity-in-contract` (R37 `BE_ENTITY_IN_CONTRACT`) keeps ORM entities out of the types that cross a boundary:
|
|
17
21
|
* any type whose declaration carries `@Entity` (from `typeorm`), reached through the type arguments and properties of
|
|
18
22
|
* a transport signature, the `execute` of a handler, or a `*.contracts.ts`, `*.command.ts` or `*.query.ts` file; and
|
|
@@ -21,6 +25,7 @@
|
|
|
21
25
|
* Where a file lives is asked of the slot view (`be.persistence` and its `migrations/` folder, the transport slots),
|
|
22
26
|
* never of a path pattern.
|
|
23
27
|
*/
|
|
28
|
+
import path from "node:path";
|
|
24
29
|
import ts from "typescript";
|
|
25
30
|
import { isTransportSlot } from "./lib/transport-slots.js";
|
|
26
31
|
import { keyName, walk } from "./lib/ast.js";
|
|
@@ -47,6 +52,21 @@ const WRITE_METHODS = new Set(["insert", "save", "upsert", "update", "delete", "
|
|
|
47
52
|
const WRITE_SQL = /\b(?:INSERT\s+INTO|UPDATE\s+\S+\s+SET|DELETE\s+FROM|MERGE\s+INTO)\b/i;
|
|
48
53
|
/** The Nest lifecycle hooks that run at boot in every process that composes the provider. */
|
|
49
54
|
const BOOT_HOOKS = new Set(["onModuleInit", "onApplicationBootstrap"]);
|
|
55
|
+
/** Packages whose import in a DDL renderer would let it run the text it builds. */
|
|
56
|
+
const DATABASE_CLIENTS = ["typeorm", "@nestjs/typeorm", "pg", "pg-promise", "postgres", "slonik", "knex", "kysely", "mysql2", "better-sqlite3", "drizzle-orm"];
|
|
57
|
+
/** Calls that run SQL text. */
|
|
58
|
+
const EXECUTING_CALLS = new Set(["query", "execute", "exec", "raw", "unsafe"]);
|
|
59
|
+
/** Whether `rel` (forward slashes) matches a declared renderer path, a `*` only in the file name. */
|
|
60
|
+
const matchesRenderer = (rel, patterns) => patterns.some((pattern) => {
|
|
61
|
+
const cut = pattern.lastIndexOf("/");
|
|
62
|
+
if (rel.slice(0, cut + 1) !== pattern.slice(0, cut + 1))
|
|
63
|
+
return false;
|
|
64
|
+
const name = pattern.slice(cut + 1);
|
|
65
|
+
const expression = new RegExp(`^${name.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")}$`);
|
|
66
|
+
return expression.test(rel.slice(cut + 1));
|
|
67
|
+
});
|
|
68
|
+
/** The app-root-relative paths a declaration file can have under this view (a package view is rooted at the app root, the be view one level below). */
|
|
69
|
+
const appRelatives = (hfs, file) => [path.relative(hfs.repoRoot, file), path.relative(path.dirname(hfs.repoRoot), file)].map((text) => text.split(path.sep).join("/"));
|
|
50
70
|
const isFalse = (node) => node?.type === "Literal" && node.value === false;
|
|
51
71
|
/** The text of every string literal and template chunk under `node`. */
|
|
52
72
|
const stringsUnder = (node) => {
|
|
@@ -137,6 +157,9 @@ export const noRuntimeSchema = {
|
|
|
137
157
|
entitySynchronize: "`synchronize` is set in the options of `@Entity`. A per-entity switch is a second schema authority next to the connection's literal `false`; delete the key.",
|
|
138
158
|
bootSeed: "`{{hook}}` writes rows (`{{call}}`), so every process that composes this provider seeds at boot. Seeding is a cli command, run once per connection.",
|
|
139
159
|
ddl: "A schema-changing statement (`CREATE|ALTER|DROP ...`) outside `persistence/migrations/`. Schema-changing SQL belongs in a migration.",
|
|
160
|
+
rendererClient: "A declared DDL renderer imports `{{source}}`, a database client. A renderer only builds DDL text and returns it; the cli writes it as a new migration file and the migrate command runs it.",
|
|
161
|
+
rendererExecutes: "A declared DDL renderer calls `.{{name}}(...)`, which runs SQL text. A renderer only builds and returns DDL; it is never executed at run time.",
|
|
162
|
+
rendererImported: "`{{name}}` is declared in a DDL renderer (hfs.json sides.be.ddlRenderers) and this file is neither the cli nor a root package. DDL text is rendered by the cli entities command and written as a new migration file, never reached from run-time code.",
|
|
140
163
|
glob: "`{{key}}` is found by glob. List the entities and migrations explicitly from each capability's `index.ts` so what runs is what was reviewed.",
|
|
141
164
|
},
|
|
142
165
|
},
|
|
@@ -147,7 +170,46 @@ export const noRuntimeSchema = {
|
|
|
147
170
|
const hfs = hfsOf(context);
|
|
148
171
|
const migration = isMigrationFile(hfs, filename);
|
|
149
172
|
const migrationHost = isMigrationHost(hfs, filename);
|
|
173
|
+
const patterns = (hfs.ruleParams.ddlRenderers ?? []).map((entry) => entry.path);
|
|
174
|
+
const renderer = patterns.length > 0 && matchesRenderer(hfs.relative(filename), patterns);
|
|
175
|
+
// a file may reach a renderer's symbols only from the cli and from the root packages (the renderer's own package, its barrel and specs)
|
|
176
|
+
const mayReachRenderer = renderer || inCli(hfs, filename) || hfs.tierOf(filename) === "package";
|
|
177
|
+
/** Reports an import or re-export of a symbol a declared renderer declares, from a file that may not reach it. */
|
|
178
|
+
const checkRendererImport = (node) => {
|
|
179
|
+
if (patterns.length === 0 || mayReachRenderer || !node.source)
|
|
180
|
+
return;
|
|
181
|
+
if ((node.type === "ImportDeclaration" && node.importKind === "type") || (node.type === "ExportNamedDeclaration" && node.exportKind === "type"))
|
|
182
|
+
return;
|
|
183
|
+
const { checker, toTs } = typed(context);
|
|
184
|
+
const tsNode = toTs(node);
|
|
185
|
+
const specifier = tsNode && (ts.isImportDeclaration(tsNode) || ts.isExportDeclaration(tsNode)) ? tsNode.moduleSpecifier : undefined;
|
|
186
|
+
const moduleSymbol = specifier ? checker.getSymbolAtLocation(specifier) : undefined;
|
|
187
|
+
if (!moduleSymbol)
|
|
188
|
+
return;
|
|
189
|
+
const declaredIn = (symbol) => {
|
|
190
|
+
const target = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
|
|
191
|
+
return (target.declarations ?? []).some((declaration) => matchesRenderer(appRelatives(hfs, declaration.getSourceFile().fileName).find((text) => text.startsWith("packages/")) ?? "", patterns));
|
|
192
|
+
};
|
|
193
|
+
const exported = checker.getExportsOfModule(moduleSymbol);
|
|
194
|
+
const named = node.type === "ImportDeclaration"
|
|
195
|
+
? node.specifiers.filter((item) => !(item.type === "ImportSpecifier" && item.importKind === "type")).flatMap((item) => (item.type === "ImportSpecifier" ? [item.imported.type === "Identifier" ? item.imported.name : String(item.imported.value)] : item.type === "ImportDefaultSpecifier" ? ["default"] : null))
|
|
196
|
+
: node.type === "ExportNamedDeclaration" ? node.specifiers.map((item) => (item.local.type === "Identifier" ? item.local.name : String(item.local.value))) : null;
|
|
197
|
+
const hits = named === null || named.includes(null)
|
|
198
|
+
? exported.filter(declaredIn)
|
|
199
|
+
: exported.filter((symbol) => named.includes(symbol.name) && declaredIn(symbol));
|
|
200
|
+
const first = hits[0];
|
|
201
|
+
if (first)
|
|
202
|
+
context.report({ node, messageId: "rendererImported", data: { name: first.name } });
|
|
203
|
+
};
|
|
150
204
|
return {
|
|
205
|
+
ImportDeclaration(node) {
|
|
206
|
+
if (renderer && DATABASE_CLIENTS.some((client) => String(node.source.value) === client || String(node.source.value).startsWith(`${client}/`))) {
|
|
207
|
+
context.report({ node, messageId: "rendererClient", data: { source: String(node.source.value) } });
|
|
208
|
+
}
|
|
209
|
+
checkRendererImport(node);
|
|
210
|
+
},
|
|
211
|
+
ExportNamedDeclaration: checkRendererImport,
|
|
212
|
+
ExportAllDeclaration: checkRendererImport,
|
|
151
213
|
ObjectExpression(node) {
|
|
152
214
|
if (isOptionsObject(context, node) && !hasKey(node, "synchronize"))
|
|
153
215
|
context.report({ node, messageId: "synchronizeMissing" });
|
|
@@ -196,6 +258,8 @@ export const noRuntimeSchema = {
|
|
|
196
258
|
if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier")
|
|
197
259
|
return;
|
|
198
260
|
const name = callee.property.name;
|
|
261
|
+
if (renderer && EXECUTING_CALLS.has(name))
|
|
262
|
+
context.report({ node, messageId: "rendererExecutes", data: { name } });
|
|
199
263
|
if (SCHEMA_OPERATIONS.has(name)) {
|
|
200
264
|
if (isPackageType(context, callee.object, "DataSource", "typeorm"))
|
|
201
265
|
context.report({ node, messageId: "synchronizeCall", data: { name } });
|
|
@@ -214,11 +278,11 @@ export const noRuntimeSchema = {
|
|
|
214
278
|
}
|
|
215
279
|
},
|
|
216
280
|
Literal(node) {
|
|
217
|
-
if (!migration && typeof node.value === "string" && DDL.test(node.value))
|
|
281
|
+
if (!migration && !renderer && typeof node.value === "string" && DDL.test(node.value))
|
|
218
282
|
context.report({ node, messageId: "ddl" });
|
|
219
283
|
},
|
|
220
284
|
TemplateElement(node) {
|
|
221
|
-
if (!migration && DDL.test(node.value.cooked ?? ""))
|
|
285
|
+
if (!migration && !renderer && DDL.test(node.value.cooked ?? ""))
|
|
222
286
|
context.report({ node, messageId: "ddl" });
|
|
223
287
|
},
|
|
224
288
|
};
|
package/package.json
CHANGED