@starci/eslint-canon-be 3.6.8 → 3.7.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/CHANGELOG.md +10 -0
- package/dist/app-composition.d.ts +1 -1
- package/dist/app-composition.js +18 -5
- package/dist/auth-passport.d.ts +14 -0
- package/dist/auth-passport.js +106 -0
- package/dist/index.js +4 -0
- package/dist/jwt-alg.js +1 -1
- package/dist/lib/hfs-view.d.ts +5 -0
- package/dist/module-layering.js +6 -2
- package/dist/no-raw-sql.d.ts +9 -0
- package/dist/no-raw-sql.js +78 -0
- package/package.json +1 -1
- package/runtime/knowledge/hfs/canon-pins.yaml +44 -24
- package/runtime/knowledge/hfs/fe-stack.yaml +4 -11
- package/runtime/knowledge/hfs/rules.yaml +177 -155
- package/runtime/knowledge/hfs/slots.yaml +164 -172
- package/runtime/scripts/hfs/architecture/canon-clones.mjs +1 -1
- package/runtime/scripts/hfs/architecture/{supabase-be.mjs → identity.mjs} +45 -15
- package/runtime/scripts/hfs/architecture/index.mjs +2 -3
- package/runtime/scripts/hfs/architecture/{supabase-ast.mjs → jwt-ast.mjs} +2 -103
- package/runtime/scripts/hfs/architecture/register-once.mjs +1 -1
- package/runtime/scripts/hfs/architecture/schema-owner.mjs +29 -4
- package/runtime/scripts/hfs/architecture/server-action.mjs +3 -4
- package/runtime/scripts/hfs/architecture/side-boundary.mjs +1 -1
- package/runtime/scripts/hfs/architecture/{supabase-keys.mjs → sql-keys.mjs} +1 -1
- package/runtime/scripts/hfs/architecture/sql-owner.mjs +25 -27
- package/runtime/scripts/hfs/architecture/transport-owner.mjs +7 -3
- package/runtime/scripts/hfs/declaration-shape.mjs +15 -18
- package/runtime/scripts/hfs/manifest-shape.mjs +4 -4
- package/runtime/scripts/hfs/rule-params-shape.mjs +4 -1
- package/runtime/scripts/hfs/rules/database-constants.mjs +8 -10
- package/runtime/scripts/hfs/rules/database-migrations.mjs +3 -3
- package/runtime/scripts/hfs/slot-app-view.mjs +1 -1
- package/runtime/scripts/hfs/slots.mjs +8 -2
- package/runtime/scripts/lib/secret-patterns.mjs +2 -2
- package/runtime/scripts/hfs/architecture/supabase-tables.mjs +0 -50
- package/runtime/scripts/hfs/architecture/supabase.mjs +0 -226
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.7.0 - 2026-10-29
|
|
4
|
+
|
|
5
|
+
- Added: the `auth-passport` law (contexts/code/be/api-auth.md BE-AUTH-2): `own-jwks-only` (R329 `BE_AUTH_JWT_OWN_JWKS`) refuses `createRemoteJWKSet`, `decodeJwt` and `decodeProtectedHeader` of jose anywhere and `jwtVerify` outside `integrations/passport`; `refresh-token-cookie-only` (R330 `BE_AUTH_REFRESH_COOKIE`) refuses a `refreshToken`/`refresh_token` property or member and a refresh cookie set or cleared outside `integrations/passport`.
|
|
6
|
+
- Added: `no-raw-sql` (R334 `BE_PERSISTENCE_NO_RAW_SQL`, lite): no `.query(` and no `sql` template outside `platform/database`, and `callDbFunction` names only a listed database function.
|
|
7
|
+
- Changed: `no-raw-sql` also refuses a query builder that names no entity (`createQueryBuilder("orders", "o")`, `createQueryBuilder()`) and `getRepository(...)` outside `platform/database`: a builder is `createQueryBuilder(Entity, "alias")` on the injected EntityManager.
|
|
8
|
+
- Changed: `no-folder-reexport` admits, in lite only, a capability's `persistence/entities/index.ts` that declares its `<c>Entities` list (BE-PERSISTENCE-3); the machine `schema-owner` (R35) checks the lite shape (the list and its name in `PRIMARY_ENTITIES`), and the dead-export count already counts `<c>Entities` once `PRIMARY_ENTITIES` names it (spec added).
|
|
9
|
+
- Changed: `app-file-budget` (R246 `BE_APP_COMPOSITION_BUDGET`) counts a slot file's lines excluding import declarations, a multi-line import included, so naming one more capability costs no budget; the numbers are unchanged (`<app>.env.ts` 150 in both editions).
|
|
10
|
+
- Changed: the bundled slot manifest 3.9.0 replaces the lite `app.supabase*` slots with `app.db` (`db/migrations`, `db/migrations/archive`, `db/seed.sql`, the managed `db/bootstrap.sql`), `be.integrations.supabase` with `be.integrations.passport` and `be.integrations.object-storage`, removes `fe.route.callback`, sets lite `schemaAuthority: sql`, gives lite TypeORM entities in `be.persistence`, adds `ruleParams.be.dbFunctions`, and moves the S3 SDKs to `integrations/object-storage` and the identity libraries to `integrations/passport` in `infraOwners` (`@supabase/*`, `minio` and `bcrypt` nowhere); the bundled rule catalog retires R216, R217, R219, R254 and R287 and adds R328-R334, so `infra-import-owner` holds R328 `BE_AUTH_PASSPORT_OWNER` and R331 `BE_STORAGE_OWNER`; R36 runs in full only; `jwt-alg-pinned` reads `architecture/jwt-ast.mjs`; the bundled canon pins name hfs 4.10.0, eslint-canon-be 3.7.0, eslint-canon-fe 9.5.0 and the Grammar family 0.15.11, pin `@nestjs/passport` 11.0.5 (CommonJS on the Nest 11 line), `passport` 0.7.0, `passport-google-oauth20` 2.0.0, `passport-local` 1.0.0, `bcryptjs` 3.0.3 and their types (tokens are signed and verified with `jose`; `@nestjs/jwt` stays allowed in `integrations/passport` but unpinned), and drop `@supabase/ssr`, `@supabase/supabase-js` and the `supabase` CLI.
|
|
11
|
+
|
|
12
|
+
|
|
3
13
|
## 3.6.8 - 2026-10-29
|
|
4
14
|
|
|
5
15
|
- Added: the `ai-gateway` law (contexts/code/be/ai.md). `provider-key-custody` (R326 `BE_AI_KEY_CUSTODY`) refuses an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, the one list: `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and the rest, with their `_FILE` twins) named in a literal, a member or a property anywhere but the gateway's custody owner `integrations/ai-gateway`, specs and the test world included. `ai-client-through-gateway` (R327 `BE_AI_GATEWAY_CLIENT`) lets code build only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai` (found by import), each from an inline options object with no spread, `configuration.baseURL` a member of a `<c>.options.ts` type and `apiKey` the `reveal()` of a `platform/config` `Secret`.
|
|
@@ -7,7 +7,7 @@ export declare const appCompositionTyped: RuleModule;
|
|
|
7
7
|
export declare const appEnvRequired: RuleModule;
|
|
8
8
|
/** R289: module lists in the app root contain only spreads of its own compose groups. */
|
|
9
9
|
export declare const appModuleListInline: RuleModule;
|
|
10
|
-
/** Each composition file of an app stays within the line budget its app slot names. */
|
|
10
|
+
/** Each composition file of an app stays within the line budget its app slot names, counted without its import lines. */
|
|
11
11
|
export declare const appFileBudget: RuleModule;
|
|
12
12
|
/** The rules this law contributes to the plugin. */
|
|
13
13
|
export declare const rules: {
|
package/dist/app-composition.js
CHANGED
|
@@ -14,7 +14,9 @@
|
|
|
14
14
|
* options files and composition groups receive the typed result of `read<App>Env(env: EnvSource)`.
|
|
15
15
|
* - `app-file-budget` (`BE_APP_COMPOSITION_BUDGET`) holds each composition file to the line budget its app slot names
|
|
16
16
|
* (`budget` of the slot, keyed by the same entry: `app.module.ts` 250, `<app>.env.ts` 150, `<app>.options.ts` 200, `compose/<area>.ts` 120,
|
|
17
|
-
* `main.ts` 80)
|
|
17
|
+
* `main.ts` 80), counted in lines EXCLUDING import declarations (a multi-line import counts none of its lines): an import
|
|
18
|
+
* is the cost of naming a capability, not composition. The budget is absolute, not a ratchet: an app root that outgrows it moves
|
|
19
|
+
* an area into a new group.
|
|
18
20
|
*
|
|
19
21
|
* R265 resolves composition from types, including renamed constructors, factories, maps and scheduler tables. All
|
|
20
22
|
* three rules ask the slot view which entry a file matches; none keeps a path of its own.
|
|
@@ -564,14 +566,25 @@ export const appModuleListInline = {
|
|
|
564
566
|
};
|
|
565
567
|
},
|
|
566
568
|
};
|
|
567
|
-
/**
|
|
569
|
+
/** The lines of a source text that no import declaration (`import ...` or `import x = require(...)`) covers, one or many lines each. */
|
|
570
|
+
const linesExcludingImports = (text, body) => {
|
|
571
|
+
const covered = new Set();
|
|
572
|
+
for (const statement of body) {
|
|
573
|
+
if ((statement.type !== "ImportDeclaration" && statement.type !== "TSImportEqualsDeclaration") || !statement.loc)
|
|
574
|
+
continue;
|
|
575
|
+
for (let line = statement.loc.start.line; line <= statement.loc.end.line; line += 1)
|
|
576
|
+
covered.add(line);
|
|
577
|
+
}
|
|
578
|
+
return lineCount(text) - covered.size;
|
|
579
|
+
};
|
|
580
|
+
/** Each composition file of an app stays within the line budget its app slot names, counted without its import lines. */
|
|
568
581
|
export const appFileBudget = {
|
|
569
582
|
meta: {
|
|
570
583
|
type: "problem",
|
|
571
|
-
docs: { description: "`main.ts`, `app.module.ts`, `<app>.env.ts`, `<app>.options.ts` and `compose/<area>.ts` stay within the line budget of their app slot." },
|
|
584
|
+
docs: { description: "`main.ts`, `app.module.ts`, `<app>.env.ts`, `<app>.options.ts` and `compose/<area>.ts` stay within the line budget of their app slot, counted without import lines." },
|
|
572
585
|
schema: [],
|
|
573
586
|
messages: {
|
|
574
|
-
over: "This {{role}} has {{lines}} lines, over its budget of {{max}} (the `budget` of slot {{slot}}). {{fix}}",
|
|
587
|
+
over: "This {{role}} has {{lines}} lines excluding imports, over its budget of {{max}} (the `budget` of slot {{slot}}). {{fix}}",
|
|
575
588
|
},
|
|
576
589
|
},
|
|
577
590
|
create(context) {
|
|
@@ -592,7 +605,7 @@ export const appFileBudget = {
|
|
|
592
605
|
: "Move one area of the composition into its own group `apps/<app>/src/compose/<area>.ts` and spread it in `app.module.ts`.";
|
|
593
606
|
return {
|
|
594
607
|
"Program:exit"(node) {
|
|
595
|
-
const lines =
|
|
608
|
+
const lines = linesExcludingImports((context.sourceCode || context.getSourceCode()).text, node.body);
|
|
596
609
|
if (lines > max)
|
|
597
610
|
context.report({ node, loc: { line: 1, column: 0 }, messageId: "over", data: { role: role.entry, lines, max, slot: role.slot, fix } });
|
|
598
611
|
},
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Recommended, RuleModule } from "./lib/rule.js";
|
|
2
|
+
/** The owner id (`<tier>/<capability>`) of the lite identity integration. */
|
|
3
|
+
export declare const PASSPORT_OWNER = "integrations/passport";
|
|
4
|
+
/** A lite principal comes only from the app's own verified token. */
|
|
5
|
+
export declare const ownJwksOnly: RuleModule;
|
|
6
|
+
/** A refresh token lives only in the integration's httpOnly cookie. */
|
|
7
|
+
export declare const refreshTokenCookieOnly: RuleModule;
|
|
8
|
+
/** The rules of the lite identity law, by name. */
|
|
9
|
+
export declare const rules: {
|
|
10
|
+
"own-jwks-only": RuleModule;
|
|
11
|
+
"refresh-token-cookie-only": RuleModule;
|
|
12
|
+
};
|
|
13
|
+
/** Both rules on at error. */
|
|
14
|
+
export declare const recommended: Recommended;
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The rules of the lite identity (catalog R329 `BE_AUTH_JWT_OWN_JWKS`, R330 `BE_AUTH_REFRESH_COOKIE`; contexts/code/be/api-auth.md
|
|
3
|
+
* BE-AUTH-2 and BE-AUTH-3). Which owner may import the identity and S3 libraries at all is the infrastructure table of the slot
|
|
4
|
+
* manifest (`ruleParams.be.infraOwners`, judged by `infra-import-owner`: R328 `BE_AUTH_PASSPORT_OWNER`, R331 `BE_STORAGE_OWNER`).
|
|
5
|
+
*
|
|
6
|
+
* - `own-jwks-only`: the app verifies only its own access tokens. `createRemoteJWKSet` (a remote identity provider's key set),
|
|
7
|
+
* `decodeJwt` and `decodeProtectedHeader` (a token read without its signature) are refused wherever jose is imported, and
|
|
8
|
+
* `jwtVerify` is imported only by `integrations/passport`. The architecture machine (`own-jwks-principal`) proves the rest:
|
|
9
|
+
* the verifier checks `createLocalJWKSet` over the app's keys with issuer, audience and algorithms pinned.
|
|
10
|
+
* - `refresh-token-cookie-only`: a refresh token never travels in a body. Outside `integrations/passport` no object literal,
|
|
11
|
+
* class property or type member is named `refreshToken` or `refresh_token`, and no `.cookie()`/`.clearCookie()` call names a
|
|
12
|
+
* refresh cookie: the cookie is set, rotated and cleared only by the integration's `setRefreshCookie`/`clearRefreshCookie`.
|
|
13
|
+
* Its attributes (httpOnly, Secure, SameSite=Strict, the refresh path) are `response-cookie-attributes` (R141) and the
|
|
14
|
+
* integration's own spec; rotation with reuse detection is held by the identity domain's spec and review.
|
|
15
|
+
*/
|
|
16
|
+
import { keyName, staticText } from "./lib/ast.js";
|
|
17
|
+
import { hfsOf } from "./lib/hfs.js";
|
|
18
|
+
/** The owner id (`<tier>/<capability>`) of the lite identity integration. */
|
|
19
|
+
export const PASSPORT_OWNER = "integrations/passport";
|
|
20
|
+
/** The jose exports no file uses: a remote key set and the unverified decoders. */
|
|
21
|
+
const FORBIDDEN_JOSE = new Set(["createRemoteJWKSet", "decodeJwt", "decodeProtectedHeader"]);
|
|
22
|
+
const REFRESH_NAME = /^refresh_?token$/i;
|
|
23
|
+
const REFRESH_COOKIE = /refresh/i;
|
|
24
|
+
/** The owner id of a file: the last two segments of its owner root, or null when no owner holds it. */
|
|
25
|
+
const ownerIdOf = (context, filename) => {
|
|
26
|
+
const root = hfsOf(context).ownerOf(filename);
|
|
27
|
+
return root === null ? null : root.split("/").slice(-2).join("/");
|
|
28
|
+
};
|
|
29
|
+
/** A lite principal comes only from the app's own verified token. */
|
|
30
|
+
export const ownJwksOnly = {
|
|
31
|
+
meta: {
|
|
32
|
+
type: "problem",
|
|
33
|
+
docs: { description: "Only integrations/passport verifies a token (jose jwtVerify over the app's own key set); no remote JWKS and no unverified decode anywhere." },
|
|
34
|
+
schema: [],
|
|
35
|
+
messages: {
|
|
36
|
+
forbidden: "`{{name}}` of jose {{why}}. The app verifies only its own access tokens through the token kit of `integrations/passport` (jwtVerify over createLocalJWKSet).",
|
|
37
|
+
verifier: "`jwtVerify` is imported outside `integrations/passport`. Verify a token through the integration's verifier (`OWN_TOKEN_VERIFIER`), which domain/identity turns into the principal.",
|
|
38
|
+
},
|
|
39
|
+
},
|
|
40
|
+
create(context) {
|
|
41
|
+
const owner = ownerIdOf(context, context.filename) === PASSPORT_OWNER;
|
|
42
|
+
return {
|
|
43
|
+
ImportDeclaration(node) {
|
|
44
|
+
if (node.source.value !== "jose")
|
|
45
|
+
return;
|
|
46
|
+
for (const specifier of node.specifiers) {
|
|
47
|
+
if (specifier.type !== "ImportSpecifier")
|
|
48
|
+
continue;
|
|
49
|
+
const name = keyName(specifier.imported);
|
|
50
|
+
if (name !== null && FORBIDDEN_JOSE.has(name)) {
|
|
51
|
+
context.report({ node: specifier, messageId: "forbidden", data: { name, why: name === "createRemoteJWKSet" ? "trusts another issuer's key set" : "reads a token without proving its signature" } });
|
|
52
|
+
}
|
|
53
|
+
else if (name === "jwtVerify" && !owner)
|
|
54
|
+
context.report({ node: specifier, messageId: "verifier" });
|
|
55
|
+
}
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
},
|
|
59
|
+
};
|
|
60
|
+
/** A refresh token lives only in the integration's httpOnly cookie. */
|
|
61
|
+
export const refreshTokenCookieOnly = {
|
|
62
|
+
meta: {
|
|
63
|
+
type: "problem",
|
|
64
|
+
docs: { description: "A refresh token never appears as a body field, and only integrations/passport sets or clears the refresh cookie." },
|
|
65
|
+
schema: [],
|
|
66
|
+
messages: {
|
|
67
|
+
field: "`{{name}}` carries a refresh token in a body. The refresh token lives only in the httpOnly, Secure, SameSite=Strict cookie that `integrations/passport` rotates (`setRefreshCookie`).",
|
|
68
|
+
cookie: "`{{call}}` names the refresh cookie outside `integrations/passport`. Set and clear it only through `setRefreshCookie` and `clearRefreshCookie`.",
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
create(context) {
|
|
72
|
+
if (ownerIdOf(context, context.filename) === PASSPORT_OWNER)
|
|
73
|
+
return {};
|
|
74
|
+
const field = (node, key, computed) => {
|
|
75
|
+
const name = computed ? null : keyName(key);
|
|
76
|
+
if (name !== null && REFRESH_NAME.test(name))
|
|
77
|
+
context.report({ node, messageId: "field", data: { name } });
|
|
78
|
+
};
|
|
79
|
+
return {
|
|
80
|
+
Property(node) {
|
|
81
|
+
field(node, node.key, node.computed);
|
|
82
|
+
},
|
|
83
|
+
PropertyDefinition(node) {
|
|
84
|
+
field(node, node.key, node.computed);
|
|
85
|
+
},
|
|
86
|
+
TSPropertySignature(node) {
|
|
87
|
+
field(node, node.key, node.computed);
|
|
88
|
+
},
|
|
89
|
+
CallExpression(node) {
|
|
90
|
+
if (node.callee.type !== "MemberExpression" || node.callee.computed)
|
|
91
|
+
return;
|
|
92
|
+
const method = keyName(node.callee.property);
|
|
93
|
+
if (method !== "cookie" && method !== "clearCookie")
|
|
94
|
+
return;
|
|
95
|
+
const [first] = node.arguments;
|
|
96
|
+
const name = first === undefined ? null : staticText(first);
|
|
97
|
+
if (name !== null && REFRESH_COOKIE.test(name))
|
|
98
|
+
context.report({ node, messageId: "cookie", data: { call: `.${method}("${name}")` } });
|
|
99
|
+
},
|
|
100
|
+
};
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
/** The rules of the lite identity law, by name. */
|
|
104
|
+
export const rules = { "own-jwks-only": ownJwksOnly, "refresh-token-cookie-only": refreshTokenCookieOnly };
|
|
105
|
+
/** Both rules on at error. */
|
|
106
|
+
export const recommended = { "starci-be/own-jwks-only": "error", "starci-be/refresh-token-cookie-only": "error" };
|
package/dist/index.js
CHANGED
|
@@ -19,6 +19,8 @@
|
|
|
19
19
|
import { buildBeConfig } from "./lib/config.js";
|
|
20
20
|
import { pluginForEdition } from "./lib/edition.js";
|
|
21
21
|
import { recommended as aiGatewayRecommended, rules as aiGatewayRules } from "./ai-gateway.js";
|
|
22
|
+
import { recommended as authPassportRecommended, rules as authPassportRules } from "./auth-passport.js";
|
|
23
|
+
import { recommended as noRawSqlRecommended, rules as noRawSqlRules } from "./no-raw-sql.js";
|
|
22
24
|
import { recommended as ambientIdRecommended, rules as ambientIdRules } from "./ambient-id.js";
|
|
23
25
|
import { recommended as appCompositionRecommended, rules as appCompositionRules } from "./app-composition.js";
|
|
24
26
|
import { recommended as asyncDisciplineRecommended, rules as asyncDisciplineRules } from "./async-discipline.js";
|
|
@@ -74,6 +76,8 @@ import { recommended as sonarParityRecommended, rules as sonarParityRules } from
|
|
|
74
76
|
const CONTRIBUTIONS = [
|
|
75
77
|
{ law: "project-graph", rules: projectGraphRules, recommended: projectGraphRecommended },
|
|
76
78
|
{ law: "ai-gateway", rules: aiGatewayRules, recommended: aiGatewayRecommended },
|
|
79
|
+
{ law: "auth-passport", rules: authPassportRules, recommended: authPassportRecommended },
|
|
80
|
+
{ law: "no-raw-sql", rules: noRawSqlRules, recommended: noRawSqlRecommended },
|
|
77
81
|
{ law: "ambient-id", rules: ambientIdRules, recommended: ambientIdRecommended },
|
|
78
82
|
{ law: "app-composition", rules: appCompositionRules, recommended: appCompositionRecommended },
|
|
79
83
|
{ law: "async-discipline", rules: asyncDisciplineRules, recommended: asyncDisciplineRecommended },
|
package/dist/jwt-alg.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
import ts from "typescript";
|
|
3
3
|
import { typed } from "./lib/types.js";
|
|
4
4
|
import { isDeclarationFile } from "./lib/path.js";
|
|
5
|
-
import { jwtPolicyProblems } from "../runtime/scripts/hfs/architecture/
|
|
5
|
+
import { jwtPolicyProblems } from "../runtime/scripts/hfs/architecture/jwt-ast.mjs";
|
|
6
6
|
/** The text of a module specifier (a string literal), or undefined for any other expression. */
|
|
7
7
|
const specifierText = (specifier) => ("text" in specifier ? specifier.text : undefined);
|
|
8
8
|
/** Recognize jose imports and aliases through their declarations, including namespace imports. */
|
package/dist/lib/hfs-view.d.ts
CHANGED
|
@@ -98,6 +98,11 @@ export interface HfsRuleParams {
|
|
|
98
98
|
readonly logicRoles?: readonly string[];
|
|
99
99
|
readonly valueRoles?: readonly string[];
|
|
100
100
|
readonly thinRoles?: readonly string[];
|
|
101
|
+
/** The database functions `callDbFunction` of platform/database may call, each with its reason (`ruleParams.be.dbFunctions` plus hfs.json `sides.be.dbFunctions`). */
|
|
102
|
+
readonly dbFunctions?: readonly {
|
|
103
|
+
readonly name: string;
|
|
104
|
+
readonly reason: string;
|
|
105
|
+
}[];
|
|
101
106
|
}
|
|
102
107
|
/** The frozen view of one side of an app. */
|
|
103
108
|
export interface HfsView {
|
package/dist/module-layering.js
CHANGED
|
@@ -12,7 +12,9 @@
|
|
|
12
12
|
* - `no-relative-capability-escape` - a relative import never walks out of its own owner.
|
|
13
13
|
* - `no-folder-reexport` - a specifier that names a directory is refused; a nested `index.ts` (any index that is not
|
|
14
14
|
* at its owner's root) is refused; an owner's `index.ts` holds only named `export { }` / `export type { }` lines
|
|
15
|
-
* re-exporting from files, never `export *`, never a declaration, and at most `budget.indexExports` names.
|
|
15
|
+
* re-exporting from files, never `export *`, never a declaration, and at most `budget.indexExports` names. One
|
|
16
|
+
* sanctioned exception, lite only: `<owner>/persistence/entities/index.ts` imports its entity files and declares the
|
|
17
|
+
* owner's `<c>Entities` array, the list `platform/database/entities.ts` names (persistence.md BE-PERSISTENCE-3).
|
|
16
18
|
*
|
|
17
19
|
* "Which owner does this file belong to" is `hfs.ownerOf`; "which owner does this specifier reach" is the same question
|
|
18
20
|
* asked of the file the specifier resolves to. Nothing here touches disk.
|
|
@@ -140,6 +142,8 @@ export const noSelfModuleAlias = {
|
|
|
140
142
|
},
|
|
141
143
|
};
|
|
142
144
|
// -- no-folder-reexport ----------------------------------------------------------------------------
|
|
145
|
+
/** The lite entity list of a capability: `<owner>/persistence/entities/index.ts` (BE-PERSISTENCE-3). */
|
|
146
|
+
const LITE_ENTITY_LIST = /(?:^|\/)persistence\/entities\/index\.ts$/;
|
|
143
147
|
/** Whether a file is an index by its role name. */
|
|
144
148
|
const isIndexFile = (filename) => /^index\.[cm]?[jt]sx?$/.test(baseName(filename));
|
|
145
149
|
/**
|
|
@@ -170,7 +174,7 @@ export const noFolderReexport = {
|
|
|
170
174
|
create(context) {
|
|
171
175
|
const filename = context.filename || context.getFilename();
|
|
172
176
|
const hfs = hfsOf(context);
|
|
173
|
-
const isIndex = isIndexFile(filename);
|
|
177
|
+
const isIndex = isIndexFile(filename) && !(hfs.edition === "lite" && LITE_ENTITY_LIST.test(hfs.relative(filename)));
|
|
174
178
|
const max = indexExportBudget(hfs, filename);
|
|
175
179
|
let count = 0;
|
|
176
180
|
return {
|
|
@@ -0,0 +1,9 @@
|
|
|
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. */
|
|
3
|
+
export declare const noRawSql: RuleModule;
|
|
4
|
+
/** The rule of the lite persistence law, by name. */
|
|
5
|
+
export declare const rules: {
|
|
6
|
+
"no-raw-sql": RuleModule;
|
|
7
|
+
};
|
|
8
|
+
/** On at error; the catalog limits it to lite. */
|
|
9
|
+
export declare const recommended: Recommended;
|
|
@@ -0,0 +1,78 @@
|
|
|
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`,
|
|
4
|
+
* `delete`, `upsert`, `createQueryBuilder(Entity, "alias")` with named parameters), never through raw SQL.
|
|
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 plus hfs.json `sides.be.dbFunctions`).
|
|
10
|
+
* The allow-list governs WHICH functions may be called, the helper WHERE the SQL is built. A query builder names its entity
|
|
11
|
+
* (`createQueryBuilder(Entity, "alias")`): a builder over a table-name string, a builder with no entity, and a
|
|
12
|
+
* `getRepository(...)` are refused, because they bypass the entity mapping. The rule runs in lite only (the
|
|
13
|
+
* catalog's `editions`); full keeps R36.
|
|
14
|
+
*
|
|
15
|
+
* Schema authority stays `db/migrations/*.sql`; whether the entities match it is `BE_ENTITY_SCHEMA_DRIFT` of `starci app db drift`.
|
|
16
|
+
*/
|
|
17
|
+
import { staticText } from "./lib/ast.js";
|
|
18
|
+
import { hfsOf } from "./lib/hfs.js";
|
|
19
|
+
/** The owner id (`<tier>/<capability>`) that keeps the migration runner and the database-function helpers. */
|
|
20
|
+
const DATABASE_OWNER = "platform/database";
|
|
21
|
+
/** The helper of platform/database whose second argument names the function it calls. */
|
|
22
|
+
const CALL_HELPER = "callDbFunction";
|
|
23
|
+
/** True when a builder's first argument can be an entity class: neither absent nor a string. */
|
|
24
|
+
const namesEntity = (argument) => {
|
|
25
|
+
if (argument === undefined || argument === null || typeof argument !== "object")
|
|
26
|
+
return false;
|
|
27
|
+
const node = argument;
|
|
28
|
+
return !((node.type === "Literal" && typeof node.value === "string") || node.type === "TemplateLiteral");
|
|
29
|
+
};
|
|
30
|
+
/** No raw SQL in lite domain or feature code: entities on the EntityManager carry every read and write. */
|
|
31
|
+
export const noRawSql = {
|
|
32
|
+
meta: {
|
|
33
|
+
type: "problem",
|
|
34
|
+
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." },
|
|
35
|
+
schema: [],
|
|
36
|
+
messages: {
|
|
37
|
+
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`.",
|
|
38
|
+
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`.",
|
|
39
|
+
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.",
|
|
40
|
+
unlisted: "`{{name}}` is not a listed database function. Add it to hfs.json `sides.be.dbFunctions` with the reason TypeORM cannot express it, or map the work with an entity.",
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
create(context) {
|
|
44
|
+
const hfs = hfsOf(context);
|
|
45
|
+
const root = hfs.ownerOf(context.filename);
|
|
46
|
+
const inDatabase = root !== null && root.split("/").slice(-2).join("/") === DATABASE_OWNER;
|
|
47
|
+
const listed = new Set((hfs.ruleParams.dbFunctions ?? []).map((entry) => entry.name));
|
|
48
|
+
return {
|
|
49
|
+
CallExpression(node) {
|
|
50
|
+
const callee = node.callee;
|
|
51
|
+
if (callee.type === "Identifier" && callee.name === CALL_HELPER) {
|
|
52
|
+
const name = node.arguments[1] === undefined ? null : staticText(node.arguments[1]);
|
|
53
|
+
if (name !== null && !listed.has(name))
|
|
54
|
+
context.report({ node, messageId: "unlisted", data: { name } });
|
|
55
|
+
return;
|
|
56
|
+
}
|
|
57
|
+
if (inDatabase || callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier")
|
|
58
|
+
return;
|
|
59
|
+
const method = callee.property.name;
|
|
60
|
+
if (method === "query")
|
|
61
|
+
context.report({ node, messageId: "query" });
|
|
62
|
+
else if (method === "getRepository")
|
|
63
|
+
context.report({ node, messageId: "builder" });
|
|
64
|
+
else if (method === "createQueryBuilder" && !namesEntity(node.arguments[0]))
|
|
65
|
+
context.report({ node, messageId: "builder" });
|
|
66
|
+
},
|
|
67
|
+
TaggedTemplateExpression(node) {
|
|
68
|
+
if (inDatabase || node.tag.type !== "Identifier" || node.tag.name !== "sql")
|
|
69
|
+
return;
|
|
70
|
+
context.report({ node, messageId: "template" });
|
|
71
|
+
},
|
|
72
|
+
};
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
/** The rule of the lite persistence law, by name. */
|
|
76
|
+
export const rules = { "no-raw-sql": noRawSql };
|
|
77
|
+
/** On at error; the catalog limits it to lite. */
|
|
78
|
+
export const recommended = { "starci-be/no-raw-sql": "error" };
|
package/package.json
CHANGED
|
@@ -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.
|
|
34
|
+
version: 0.15.11
|
|
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.
|
|
41
|
+
version: 3.7.0
|
|
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.
|
|
48
|
+
version: 9.5.0
|
|
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.
|
|
55
|
+
version: 0.15.11
|
|
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.
|
|
62
|
+
version: 0.15.11
|
|
63
63
|
group: starci
|
|
64
64
|
install: registry
|
|
65
65
|
side: fe
|
|
@@ -85,12 +85,12 @@ pins:
|
|
|
85
85
|
side: both
|
|
86
86
|
source: packages/prettier-config/package.json
|
|
87
87
|
'@starci/jest-preset':
|
|
88
|
-
version: 2.
|
|
88
|
+
version: 2.5.0
|
|
89
89
|
group: starci
|
|
90
90
|
install: registry
|
|
91
91
|
side: be
|
|
92
92
|
source: packages/jest-preset/package.json
|
|
93
|
-
why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
|
|
93
|
+
why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeQueryBuilder, queueQueryBuilders, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
|
|
94
94
|
'@starci/test-world':
|
|
95
95
|
version: 1.2.3
|
|
96
96
|
group: starci
|
|
@@ -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.
|
|
109
|
+
version: 4.10.0
|
|
110
110
|
group: starci
|
|
111
111
|
install: registry
|
|
112
112
|
side: both
|
|
@@ -543,7 +543,7 @@ pins:
|
|
|
543
543
|
version: 3.1150.0
|
|
544
544
|
group: framework
|
|
545
545
|
side: be
|
|
546
|
-
why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces
|
|
546
|
+
why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
|
|
547
547
|
'@aws-sdk/s3-request-presigner':
|
|
548
548
|
version: 3.1150.0
|
|
549
549
|
group: framework
|
|
@@ -594,27 +594,47 @@ pins:
|
|
|
594
594
|
group: framework
|
|
595
595
|
side: be
|
|
596
596
|
why: 'the Express 5 integration @nestjs/apollo loads at boot (R111 nestjs-apollo-express5, knowledge/hfs/peer-integrations.yaml); every api app that serves GraphQL installs it; the latest registry version on 2026-10-13.'
|
|
597
|
-
# ---
|
|
598
|
-
'@
|
|
599
|
-
version: 0.
|
|
597
|
+
# --- lite identity (integrations/passport, ruling lite-self-hosted-postgres-passport-minio)
|
|
598
|
+
'@nestjs/passport':
|
|
599
|
+
version: 11.0.5
|
|
600
600
|
group: framework
|
|
601
|
-
side:
|
|
602
|
-
why:
|
|
603
|
-
|
|
604
|
-
version:
|
|
601
|
+
side: be
|
|
602
|
+
why: 'PassportStrategy of integrations/passport; 11.0.5 is CommonJS on the Nest 11 line (12.0.0 is ESM-only and breaks Nest 11 jest under the CommonJS transform of @starci/jest-preset), as nivo-lite runs it.'
|
|
603
|
+
passport:
|
|
604
|
+
version: 0.7.0
|
|
605
605
|
group: framework
|
|
606
|
-
side:
|
|
607
|
-
why: the
|
|
606
|
+
side: be
|
|
607
|
+
why: the strategy runtime under @nestjs/passport (its peer range ^0.5 || ^0.6 || ^0.7).
|
|
608
|
+
passport-google-oauth20:
|
|
609
|
+
version: 2.0.0
|
|
610
|
+
group: framework
|
|
611
|
+
side: be
|
|
612
|
+
why: Google OAuth 2.0 (authorization code with state and PKCE) of integrations/passport.
|
|
613
|
+
passport-local:
|
|
614
|
+
version: 1.0.0
|
|
615
|
+
group: framework
|
|
616
|
+
side: be
|
|
617
|
+
why: the email and password strategy of integrations/passport.
|
|
618
|
+
bcryptjs:
|
|
619
|
+
version: 3.0.3
|
|
620
|
+
group: framework
|
|
621
|
+
side: be
|
|
622
|
+
why: 'bcrypt in pure JavaScript (no native build on the alpine image); verifies the $2a$/$2b$ hashes auth.users carries over.'
|
|
623
|
+
'@types/passport-google-oauth20':
|
|
624
|
+
version: 2.0.17
|
|
625
|
+
group: framework
|
|
626
|
+
side: be
|
|
627
|
+
why: types of passport-google-oauth20.
|
|
628
|
+
'@types/passport-local':
|
|
629
|
+
version: 1.0.38
|
|
630
|
+
group: framework
|
|
631
|
+
side: be
|
|
632
|
+
why: types of passport-local.
|
|
608
633
|
jose:
|
|
609
634
|
version: 6.2.12
|
|
610
635
|
group: framework
|
|
611
636
|
side: be
|
|
612
|
-
why:
|
|
613
|
-
supabase:
|
|
614
|
-
version: 2.119.0
|
|
615
|
-
group: tooling
|
|
616
|
-
side: both
|
|
617
|
-
why: the root CLI wrapper owns local schema lifecycle and generates the committed database types.
|
|
637
|
+
why: signs the app's own ES256 access tokens and verifies them against its own key set (createLocalJWKSet) in integrations/passport.
|
|
618
638
|
class-transformer:
|
|
619
639
|
version: 0.5.1
|
|
620
640
|
group: framework
|
|
@@ -37,10 +37,10 @@ concerns:
|
|
|
37
37
|
- id: rest
|
|
38
38
|
tier: core
|
|
39
39
|
packages: [axios]
|
|
40
|
-
home: [fe.modules.api]
|
|
40
|
+
home: [fe.modules.api, fe.modules.auth]
|
|
41
41
|
pattern: FE-API-REST
|
|
42
42
|
forbids: [ky, superagent, node-fetch, cross-fetch, isomorphic-fetch]
|
|
43
|
-
why: modules/api/rest/<area>/*.ts for uploads
|
|
43
|
+
why: modules/api/rest/<area>/*.ts for uploads and presigned URLs, and modules/auth/auth-door.ts for the app's own auth doors only; GraphQL carries every other call.
|
|
44
44
|
- id: data
|
|
45
45
|
tier: core
|
|
46
46
|
packages: [swr]
|
|
@@ -99,8 +99,8 @@ concerns:
|
|
|
99
99
|
packages: []
|
|
100
100
|
home: [fe.modules.auth]
|
|
101
101
|
pattern: FE-AUTH
|
|
102
|
-
forbids: []
|
|
103
|
-
why: modules/auth is the
|
|
102
|
+
forbids: ['@supabase/supabase-js', '@supabase/ssr', '@supabase/auth-js']
|
|
103
|
+
why: modules/auth is the session issuer's client (lite - auth-door.ts over the app's own back-end auth doors with the in-memory token store; full - the app's IdP client); it yields the session and the access token for the Apollo link and never reads data.
|
|
104
104
|
- id: i18n
|
|
105
105
|
tier: core
|
|
106
106
|
packages: [next-intl]
|
|
@@ -256,13 +256,6 @@ concerns:
|
|
|
256
256
|
pattern: FE-RULE-OWNERSHIP
|
|
257
257
|
forbids: []
|
|
258
258
|
why: The selected Grammar family's lint package runs beside the universal front-end canon; the family catalog declares the package and factory.
|
|
259
|
-
- id: auth-supabase
|
|
260
|
-
tier: opt
|
|
261
|
-
packages: ['@supabase/supabase-js', '@supabase/ssr']
|
|
262
|
-
home: [fe.modules.auth]
|
|
263
|
-
pattern: FE-AUTH
|
|
264
|
-
forbids: []
|
|
265
|
-
why: the lite auth provider client and PKCE server cookie adapter, confined to modules/auth; data still goes through the back end.
|
|
266
259
|
- id: framework-support
|
|
267
260
|
tier: opt
|
|
268
261
|
packages: [server-only, rxjs]
|