@starci/eslint-canon-be 3.12.0 → 3.14.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 +13 -1
- package/dist/auth-passport.d.ts +2 -4
- package/dist/auth-passport.js +21 -33
- package/dist/index.d.ts +11 -1
- package/dist/index.js +12 -2
- package/dist/lib/config.d.ts +14 -0
- package/dist/lib/config.js +25 -0
- package/dist/lib/cross-file-inputs.js +3 -0
- package/dist/lib/hfs.d.ts +16 -0
- package/dist/lib/hfs.js +17 -1
- package/dist/lib/unit-spec.js +2 -2
- package/dist/module-shape.js +32 -7
- package/dist/testing.js +3 -0
- package/dist/third-party-owner.js +8 -3
- package/package.json +1 -1
- package/runtime/bundle.json +1 -0
- package/runtime/knowledge/hfs/canon-pins.yaml +65 -11
- package/runtime/knowledge/hfs/fe-stack.yaml +9 -9
- package/runtime/knowledge/hfs/rules.yaml +67 -15
- package/runtime/knowledge/hfs/slots.yaml +168 -28
- package/runtime/scripts/hfs/architecture/config.mjs +25 -1
- package/runtime/scripts/hfs/architecture/identity.mjs +18 -83
- package/runtime/scripts/hfs/architecture/module-per-transport.mjs +6 -1
- package/runtime/scripts/hfs/architecture/root-packages.mjs +78 -0
- package/runtime/scripts/hfs/architecture/transport-owner.mjs +3 -6
- package/runtime/scripts/hfs/architecture/type-context.mjs +30 -0
- package/runtime/scripts/hfs/architecture/typescript.mjs +21 -1
- package/runtime/scripts/hfs/explicit-surface-rule.mjs +1 -1
- package/runtime/scripts/hfs/manifest-shape.mjs +1 -1
- package/runtime/scripts/hfs/slots.mjs +1 -1
- package/runtime/scripts/hfs/view.mjs +68 -0
- package/runtime/scripts/lib/declaration-surface.mjs +55 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.14.0 - 2026-11-03
|
|
4
|
+
|
|
5
|
+
- Changed: `@starci/nest-kit` is a framework import like `@nestjs/common` (`third-party-import-owner` lets any module definition import it).
|
|
6
|
+
- Changed: `capability-module-shape` accepts the module definition as one call of `defineCapabilityModule` (a capability's representative module) or `defineConfigurableModule` (every other module) of `@starci/nest-kit`, each stating its options type, beside the typed `ConfigurableModuleBuilder` chains; the runtime copies carry R368's acceptance of that call's destructured export, the module-per-transport confinement of the helpers, the R295 law and the `@starci/nest-kit` and `@starci/next-i18n` pins.
|
|
7
|
+
- Fixed: `third-party-import-owner` (R279) skips a name that the app's root `workspaces` own (`@scope/agent-sdk`): an app-owned workspace package is first-party source, not a third-party SDK; its manifests are cross-file inputs of the rule. The app manifest of a package view is the one at the app root.
|
|
8
|
+
- Added: `starciBePackagesConfig` and `loadPackagesHfs`: the rules of the back end over the back-end subpaths of the root workspace packages (`packages/<pkg>/src/**` but `workbench/` and `public/`, the workbench contract kept), over the package view of the app root, for the managed root `eslint.config.mjs`; the project-graph rules stay with the side folders. `unit-test-colocated` leaves the specs of a package (a spec sits beside any source of a package).
|
|
9
|
+
- Changed: the runtime copy of the slot manifest carries the slots `app.packages`, `app.module-registry` and `app.packages-lint`.
|
|
10
|
+
|
|
11
|
+
## 3.13.0 - 2026-11-03
|
|
12
|
+
|
|
13
|
+
- Changed: the runtime copies of the slot manifest carry the managed sign-in slots and the slot field `managedOnly`.
|
|
14
|
+
- Changed: `own-jwks-only` refuses `jwtVerify`, `decodeJwt`, `decodeProtectedHeader` and `createRemoteJWKSet` of jose in every app file; `refresh-token-cookie-only` no longer exempts `integrations/passport` (the package sets the cookie); the infrastructure table owns the identity libraries by nobody and `@starci/auth` by `integrations/passport` (R328, R329, R330).
|
|
15
|
+
|
|
3
16
|
## 3.12.0
|
|
4
17
|
|
|
5
18
|
- Added: `starci-be/explicit-export-surface` (R368, `HFS_EXPLICIT_EXPORT_SURFACE`) at error: an exported function's return type, an exported variable's type and a parameter's type are written, not inferred from a body or from other files. It reports each export the isolated declaration emit cannot write, at the offending span, and says what to annotate. It reads the classifier the lint result cache reads.
|
|
@@ -249,7 +262,6 @@
|
|
|
249
262
|
- 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).
|
|
250
263
|
- 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.
|
|
251
264
|
|
|
252
|
-
|
|
253
265
|
## 3.6.8 - 2026-10-29
|
|
254
266
|
|
|
255
267
|
- 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`.
|
package/dist/auth-passport.d.ts
CHANGED
|
@@ -1,9 +1,7 @@
|
|
|
1
1
|
import type { Recommended, RuleModule } from "./lib/rule.js";
|
|
2
|
-
/**
|
|
3
|
-
export declare const PASSPORT_OWNER = "integrations/passport";
|
|
4
|
-
/** A lite principal comes only from the app's own verified token. */
|
|
2
|
+
/** A lite principal comes only from the app's own token, verified by the package. */
|
|
5
3
|
export declare const ownJwksOnly: RuleModule;
|
|
6
|
-
/** A refresh token lives only in the
|
|
4
|
+
/** A refresh token lives only in the package's httpOnly cookie. */
|
|
7
5
|
export declare const refreshTokenCookieOnly: RuleModule;
|
|
8
6
|
/** The rules of the lite identity law, by name. */
|
|
9
7
|
export declare const rules: {
|
package/dist/auth-passport.js
CHANGED
|
@@ -1,44 +1,36 @@
|
|
|
1
1
|
/**
|
|
2
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
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`)
|
|
4
|
+
* manifest (`ruleParams.be.infraOwners`, judged by `infra-import-owner`: R328 `BE_AUTH_PASSPORT_OWNER`, R331 `BE_STORAGE_OWNER`): the
|
|
5
|
+
* identity libraries belong to `@starci/auth` and to no app file, and `@starci/auth` itself only to `integrations/passport`.
|
|
5
6
|
*
|
|
6
|
-
* - `own-jwks-only`: the app verifies
|
|
7
|
-
* `
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
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.
|
|
7
|
+
* - `own-jwks-only`: the app verifies no token itself. `createRemoteJWKSet` (a remote identity provider's key set), `decodeJwt`,
|
|
8
|
+
* `decodeProtectedHeader` (a token read without its signature) and `jwtVerify` are refused wherever jose is imported; the package
|
|
9
|
+
* verifies against its own key set. The architecture machine (`own-jwks-principal`) proves the same on the call sites.
|
|
10
|
+
* - `refresh-token-cookie-only`: a refresh token never travels in a body. No object literal, class property or type member is
|
|
11
|
+
* named `refreshToken` or `refresh_token`, and no `.cookie()`/`.clearCookie()` call names a refresh cookie: `@starci/auth` sets,
|
|
12
|
+
* rotates and clears it. Its attributes and rotation with reuse detection are the package's own specs.
|
|
15
13
|
*/
|
|
16
14
|
import { keyName, staticText } from "./lib/ast.js";
|
|
17
|
-
|
|
18
|
-
|
|
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"]);
|
|
15
|
+
/** The jose exports no app file uses: a remote key set, the unverified decoders and the verifier itself. */
|
|
16
|
+
const FORBIDDEN_JOSE = new Set(["createRemoteJWKSet", "decodeJwt", "decodeProtectedHeader", "jwtVerify"]);
|
|
22
17
|
const REFRESH_NAME = /^refresh_?token$/i;
|
|
23
18
|
const REFRESH_COOKIE = /refresh/i;
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
return root === null ? null : root.split("/").slice(-2).join("/");
|
|
19
|
+
const WHY = {
|
|
20
|
+
createRemoteJWKSet: "trusts another issuer's key set",
|
|
21
|
+
jwtVerify: "verifies a token in the app",
|
|
28
22
|
};
|
|
29
|
-
/** A lite principal comes only from the app's own verified
|
|
23
|
+
/** A lite principal comes only from the app's own token, verified by the package. */
|
|
30
24
|
export const ownJwksOnly = {
|
|
31
25
|
meta: {
|
|
32
26
|
type: "problem",
|
|
33
|
-
docs: { description: "
|
|
27
|
+
docs: { description: "No app file verifies or decodes a token with jose: `@starci/auth` verifies the app's own access tokens against its own key set." },
|
|
34
28
|
schema: [],
|
|
35
29
|
messages: {
|
|
36
|
-
forbidden: "`{{name}}` of jose {{why}}. The app verifies only its own access tokens
|
|
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.",
|
|
30
|
+
forbidden: "`{{name}}` of jose {{why}}. The app verifies only its own access tokens, and `@starci/auth` does it (the verifier of `integrations/passport`, `OWN_TOKEN_VERIFIER`, which `domain/identity` turns into the principal).",
|
|
38
31
|
},
|
|
39
32
|
},
|
|
40
33
|
create(context) {
|
|
41
|
-
const owner = ownerIdOf(context, context.filename) === PASSPORT_OWNER;
|
|
42
34
|
return {
|
|
43
35
|
ImportDeclaration(node) {
|
|
44
36
|
if (node.source.value !== "jose")
|
|
@@ -48,29 +40,25 @@ export const ownJwksOnly = {
|
|
|
48
40
|
continue;
|
|
49
41
|
const name = keyName(specifier.imported);
|
|
50
42
|
if (name !== null && FORBIDDEN_JOSE.has(name)) {
|
|
51
|
-
context.report({ node: specifier, messageId: "forbidden", data: { name, why: name
|
|
43
|
+
context.report({ node: specifier, messageId: "forbidden", data: { name, why: WHY[name] ?? "reads a token without proving its signature" } });
|
|
52
44
|
}
|
|
53
|
-
else if (name === "jwtVerify" && !owner)
|
|
54
|
-
context.report({ node: specifier, messageId: "verifier" });
|
|
55
45
|
}
|
|
56
46
|
},
|
|
57
47
|
};
|
|
58
48
|
},
|
|
59
49
|
};
|
|
60
|
-
/** A refresh token lives only in the
|
|
50
|
+
/** A refresh token lives only in the package's httpOnly cookie. */
|
|
61
51
|
export const refreshTokenCookieOnly = {
|
|
62
52
|
meta: {
|
|
63
53
|
type: "problem",
|
|
64
|
-
docs: { description: "A refresh token never appears as a body field, and
|
|
54
|
+
docs: { description: "A refresh token never appears as a body field, and no app file sets or clears the refresh cookie: `@starci/auth` does." },
|
|
65
55
|
schema: [],
|
|
66
56
|
messages: {
|
|
67
|
-
field: "`{{name}}` carries a refresh token in a body. The refresh token lives only in the httpOnly, Secure
|
|
68
|
-
cookie: "`{{call}}` names the refresh cookie
|
|
57
|
+
field: "`{{name}}` carries a refresh token in a body. The refresh token lives only in the httpOnly, Secure cookie that `@starci/auth` sets, rotates and clears.",
|
|
58
|
+
cookie: "`{{call}}` names the refresh cookie in the app. `@starci/auth` sets and clears it through `AuthDoors`; the app never writes it.",
|
|
69
59
|
},
|
|
70
60
|
},
|
|
71
61
|
create(context) {
|
|
72
|
-
if (ownerIdOf(context, context.filename) === PASSPORT_OWNER)
|
|
73
|
-
return {};
|
|
74
62
|
const field = (node, key, computed) => {
|
|
75
63
|
const name = computed ? null : keyName(key);
|
|
76
64
|
if (name !== null && REFRESH_NAME.test(name))
|
package/dist/index.d.ts
CHANGED
|
@@ -50,8 +50,18 @@ export default plugin;
|
|
|
50
50
|
export declare const starciBeConfig: ({ hfs }: {
|
|
51
51
|
hfs?: HfsView | null | undefined;
|
|
52
52
|
}) => Promise<TSESLint.FlatConfig.ConfigArray>;
|
|
53
|
+
/**
|
|
54
|
+
* The flat config of the root workspace packages of an app (`packages/<pkg>/src/**` minus the front-end subpaths), for the managed root
|
|
55
|
+
* `eslint.config.mjs`: `starciBePackagesConfig({ hfs: loadPackagesHfs(import.meta.url) })`. The same rules as `starciBeConfig`, over the package view.
|
|
56
|
+
*
|
|
57
|
+
* @param input - The package view of the app root.
|
|
58
|
+
* @returns The flat config.
|
|
59
|
+
*/
|
|
60
|
+
export declare const starciBePackagesConfig: ({ hfs }: {
|
|
61
|
+
hfs?: HfsView | null | undefined;
|
|
62
|
+
}) => Promise<TSESLint.FlatConfig.ConfigArray>;
|
|
53
63
|
export { linterOptions } from "./lib/config.js";
|
|
54
|
-
export { loadHfs } from "./lib/hfs.js";
|
|
64
|
+
export { loadHfs, loadPackagesHfs } from "./lib/hfs.js";
|
|
55
65
|
export { crossFileInputs } from "./lib/cross-file-inputs.js";
|
|
56
66
|
export type { CrossFileInput } from "./lib/cross-file-inputs.js";
|
|
57
67
|
export { projectGraph, projectGraphSnapshot } from "./project-graph.js";
|
package/dist/index.js
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
* every conversation about the failure. Aliasing one here to match a target's older spelling would
|
|
17
17
|
* leave two names for one rule and no way to tell which a message came from.
|
|
18
18
|
*/
|
|
19
|
-
import { buildBeConfig } from "./lib/config.js";
|
|
19
|
+
import { buildBeConfig, buildBePackagesConfig } 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
22
|
import { recommended as authPassportRecommended, rules as authPassportRules } from "./auth-passport.js";
|
|
@@ -181,8 +181,18 @@ export default plugin;
|
|
|
181
181
|
* @returns The flat config.
|
|
182
182
|
*/
|
|
183
183
|
export const starciBeConfig = ({ hfs }) => buildBeConfig({ hfs, plugin: pluginForEdition({ plugin, hfs }), recommended });
|
|
184
|
+
/** The levels a package is judged by: every rule of the be side but the project-graph rules, which judge the import graph of a side folder (the packages are not part of it). */
|
|
185
|
+
const packageRecommended = Object.fromEntries(Object.entries(recommended).filter(([name]) => !(name in projectGraphRecommended)));
|
|
186
|
+
/**
|
|
187
|
+
* The flat config of the root workspace packages of an app (`packages/<pkg>/src/**` minus the front-end subpaths), for the managed root
|
|
188
|
+
* `eslint.config.mjs`: `starciBePackagesConfig({ hfs: loadPackagesHfs(import.meta.url) })`. The same rules as `starciBeConfig`, over the package view.
|
|
189
|
+
*
|
|
190
|
+
* @param input - The package view of the app root.
|
|
191
|
+
* @returns The flat config.
|
|
192
|
+
*/
|
|
193
|
+
export const starciBePackagesConfig = ({ hfs }) => buildBePackagesConfig({ hfs, plugin: pluginForEdition({ plugin, hfs }), recommended: packageRecommended });
|
|
184
194
|
export { linterOptions } from "./lib/config.js";
|
|
185
|
-
export { loadHfs } from "./lib/hfs.js";
|
|
195
|
+
export { loadHfs, loadPackagesHfs } from "./lib/hfs.js";
|
|
186
196
|
// A12 registration is appended so the shared registry can be union-merged.
|
|
187
197
|
import { recommended as thirdPartyOwnerRecommended, rules as thirdPartyOwnerRules } from "./third-party-owner.js";
|
|
188
198
|
Object.assign(rules, thirdPartyOwnerRules);
|
package/dist/lib/config.d.ts
CHANGED
|
@@ -34,3 +34,17 @@ export declare const buildBeConfig: ({ hfs, plugin, recommended }: {
|
|
|
34
34
|
plugin: CanonPlugin | null | undefined;
|
|
35
35
|
recommended?: Recommended | undefined;
|
|
36
36
|
}) => Promise<TSESLint.FlatConfig.ConfigArray>;
|
|
37
|
+
/** The back-end subpaths of a root workspace package: everything under `src/` but the front-end subpaths `workbench/` and `public/`; the workbench contract (`workbench/contract/`) is React-free and stays back end. */
|
|
38
|
+
export declare const PACKAGE_SOURCE_FILES: readonly string[];
|
|
39
|
+
/** What a package folder never lints: build output, coverage output and installed packages. */
|
|
40
|
+
export declare const PACKAGE_IGNORED: readonly string[];
|
|
41
|
+
/**
|
|
42
|
+
* The flat config of the back-end subpaths of the root workspace packages of an app: the config of a back end, with the files narrowed to
|
|
43
|
+
* `packages/<pkg>/src/**` (the front-end subpaths `workbench/` and `public/` left to the front-end canon, the workbench contract kept). It is
|
|
44
|
+
* the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`), so a module package obeys the laws of the side
|
|
45
|
+
* its subpath belongs to and the infrastructure owners judge what the package imports.
|
|
46
|
+
*
|
|
47
|
+
* @param {object} input - The attachment options of `buildBeConfig`.
|
|
48
|
+
* @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package subpaths.
|
|
49
|
+
*/
|
|
50
|
+
export declare const buildBePackagesConfig: (input: Parameters<typeof buildBeConfig>[0]) => Promise<TSESLint.FlatConfig.ConfigArray>;
|
package/dist/lib/config.js
CHANGED
|
@@ -95,3 +95,28 @@ export const buildBeConfig = async ({ hfs, plugin, recommended }) => {
|
|
|
95
95
|
{ files: [...SOURCE_FILES], ignores: [...OUTSIDE_THE_SCAN_FILES], plugins: { sonarjs, unicorn }, rules: sonarWayRules(sonarjs, "be").rules },
|
|
96
96
|
];
|
|
97
97
|
};
|
|
98
|
+
/** The back-end subpaths of a root workspace package: everything under `src/` but the front-end subpaths `workbench/` and `public/`; the workbench contract (`workbench/contract/`) is React-free and stays back end. */
|
|
99
|
+
export const PACKAGE_SOURCE_FILES = Object.freeze(["packages/*/src/**/*.{ts,mts,cts,js,mjs,cjs}"]);
|
|
100
|
+
const PACKAGE_FRONT_END = Object.freeze(["packages/*/src/workbench/**", "packages/*/src/public/**"]);
|
|
101
|
+
const PACKAGE_CONTRACT_FILES = Object.freeze(["packages/*/src/workbench/contract/**/*.{ts,mts,cts,js,mjs,cjs}"]);
|
|
102
|
+
/** What a package folder never lints: build output, coverage output and installed packages. */
|
|
103
|
+
export const PACKAGE_IGNORED = Object.freeze(["**/dist/**", "**/coverage/**", "**/node_modules/**"]);
|
|
104
|
+
/**
|
|
105
|
+
* The flat config of the back-end subpaths of the root workspace packages of an app: the config of a back end, with the files narrowed to
|
|
106
|
+
* `packages/<pkg>/src/**` (the front-end subpaths `workbench/` and `public/` left to the front-end canon, the workbench contract kept). It is
|
|
107
|
+
* the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`), so a module package obeys the laws of the side
|
|
108
|
+
* its subpath belongs to and the infrastructure owners judge what the package imports.
|
|
109
|
+
*
|
|
110
|
+
* @param {object} input - The attachment options of `buildBeConfig`.
|
|
111
|
+
* @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package subpaths.
|
|
112
|
+
*/
|
|
113
|
+
export const buildBePackagesConfig = async (input) => {
|
|
114
|
+
const [, ...blocks] = await buildBeConfig(input);
|
|
115
|
+
return [
|
|
116
|
+
{ ignores: [...PACKAGE_IGNORED] },
|
|
117
|
+
...blocks.flatMap((block) => [
|
|
118
|
+
{ ...block, files: [...PACKAGE_SOURCE_FILES], ignores: [...(block.ignores ?? []), ...PACKAGE_FRONT_END] },
|
|
119
|
+
{ ...block, files: [...PACKAGE_CONTRACT_FILES] },
|
|
120
|
+
]),
|
|
121
|
+
];
|
|
122
|
+
};
|
|
@@ -37,6 +37,9 @@ export const crossFileInputs = [
|
|
|
37
37
|
// the dependency manifest (the app's, one level above be/); the SDK imports of every integration owner are read only to judge an integration file
|
|
38
38
|
{ rule: "third-party-import-owner", kind: "content", relativeTo: "side", globs: ["package.json", "../package.json"], appliesTo: [`**/*.${SOURCE}`], reader: "third-party-owner.ts" },
|
|
39
39
|
{ rule: "third-party-import-owner", kind: "content", relativeTo: "side", globs: [`**/*.${SOURCE}`], appliesTo: [`**/modules/integrations/**/*.${SOURCE}`], reader: "third-party-owner.ts" },
|
|
40
|
+
// the app's own workspace packages (the folders its `workspaces` name, packages/* and the like) are first-party, not third-party: their names are read from their manifests
|
|
41
|
+
{ rule: "third-party-import-owner", kind: "content", relativeTo: "side", globs: ["../*/package.json", "../*/*/package.json"], appliesTo: [`**/*.${SOURCE}`], reader: "third-party-owner.ts" },
|
|
42
|
+
{ rule: "third-party-import-owner", kind: "exists", relativeTo: "side", globs: ["hfs.json", "../*", "../*/*", "../*/*/package.json"], appliesTo: [`**/*.${SOURCE}`], reader: "third-party-owner.ts" },
|
|
40
43
|
// an over-budget file is compared with its size at the merge-base with the base branch
|
|
41
44
|
{ rule: "file-size-growth", kind: "git", relativeTo: "side", globs: [], minLines: HISTORY_MIN_LINES, appliesTo: [`**/*.${SOURCE}`], reader: "size-budget.ts" },
|
|
42
45
|
];
|
package/dist/lib/hfs.d.ts
CHANGED
|
@@ -8,6 +8,22 @@ export type { HfsAllowsVerdict, HfsApp, HfsClassification, HfsConnection, HfsPar
|
|
|
8
8
|
* @returns The frozen HFS view (profile, apps, connections, ruleParams, slotOf, tierOf, ownerOf).
|
|
9
9
|
*/
|
|
10
10
|
export declare const loadHfs: (configUrl: string) => HfsView;
|
|
11
|
+
/**
|
|
12
|
+
* The HFS view of the root workspace packages of an app, judged by the laws of the be side: the managed root `eslint.config.mjs`
|
|
13
|
+
* (`packages/*` of the app root) calls this. Paths are the app's own; a package file is of the tier `package` and its owner is its folder.
|
|
14
|
+
*
|
|
15
|
+
* @param configUrl - `import.meta.url` of the app root's `eslint.config.mjs`.
|
|
16
|
+
* @returns The frozen HFS view (profile be over the paths of the app root).
|
|
17
|
+
*/
|
|
18
|
+
export declare const loadPackagesHfs: (configUrl: string) => HfsView;
|
|
19
|
+
/**
|
|
20
|
+
* The HFS view of the root packages of an in-memory app declaration, for rule tests.
|
|
21
|
+
*
|
|
22
|
+
* @param declaration - An app `hfs.json` object.
|
|
23
|
+
* @param repoRoot - The absolute app root the linted filenames live under.
|
|
24
|
+
* @returns The frozen HFS view.
|
|
25
|
+
*/
|
|
26
|
+
export declare const packagesHfsFromDeclaration: (declaration: object, repoRoot: string) => HfsView;
|
|
11
27
|
/**
|
|
12
28
|
* The HFS view of the be side of an in-memory app declaration, for rule tests: no file is read except the shipped manifest.
|
|
13
29
|
*
|
package/dist/lib/hfs.js
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import { dirname } from "node:path";
|
|
15
15
|
import { fileURLToPath } from "node:url";
|
|
16
|
-
import { declaredHfsView, openHfsView } from "#runtime/scripts/hfs/view.mjs";
|
|
16
|
+
import { declaredHfsView, declaredPackagesHfsView, openHfsView, openPackagesHfsView } from "#runtime/scripts/hfs/view.mjs";
|
|
17
17
|
import { RUNTIME_ROOT as RUNTIME } from "./runtime-root.js";
|
|
18
18
|
/**
|
|
19
19
|
* The HFS view of the side whose `eslint.config.mjs` (in be/) calls this.
|
|
@@ -22,6 +22,22 @@ import { RUNTIME_ROOT as RUNTIME } from "./runtime-root.js";
|
|
|
22
22
|
* @returns The frozen HFS view (profile, apps, connections, ruleParams, slotOf, tierOf, ownerOf).
|
|
23
23
|
*/
|
|
24
24
|
export const loadHfs = (configUrl) => openHfsView({ runtimeRoot: RUNTIME, repoRoot: dirname(fileURLToPath(configUrl)) });
|
|
25
|
+
/**
|
|
26
|
+
* The HFS view of the root workspace packages of an app, judged by the laws of the be side: the managed root `eslint.config.mjs`
|
|
27
|
+
* (`packages/*` of the app root) calls this. Paths are the app's own; a package file is of the tier `package` and its owner is its folder.
|
|
28
|
+
*
|
|
29
|
+
* @param configUrl - `import.meta.url` of the app root's `eslint.config.mjs`.
|
|
30
|
+
* @returns The frozen HFS view (profile be over the paths of the app root).
|
|
31
|
+
*/
|
|
32
|
+
export const loadPackagesHfs = (configUrl) => openPackagesHfsView({ runtimeRoot: RUNTIME, repoRoot: dirname(fileURLToPath(configUrl)), side: "be" });
|
|
33
|
+
/**
|
|
34
|
+
* The HFS view of the root packages of an in-memory app declaration, for rule tests.
|
|
35
|
+
*
|
|
36
|
+
* @param declaration - An app `hfs.json` object.
|
|
37
|
+
* @param repoRoot - The absolute app root the linted filenames live under.
|
|
38
|
+
* @returns The frozen HFS view.
|
|
39
|
+
*/
|
|
40
|
+
export const packagesHfsFromDeclaration = (declaration, repoRoot) => declaredPackagesHfsView({ runtimeRoot: RUNTIME, declaration, repoRoot, side: "be" });
|
|
25
41
|
/**
|
|
26
42
|
* The HFS view of the be side of an in-memory app declaration, for rule tests: no file is read except the shipped manifest.
|
|
27
43
|
*
|
package/dist/lib/unit-spec.js
CHANGED
|
@@ -49,8 +49,8 @@ const inRoleSlot = (hfs, role, filename) => (role.optional === true ? inCoverage
|
|
|
49
49
|
/** The path of a classified file below the instance root of its slot. */
|
|
50
50
|
const slotRelative = (found) => (found.root !== undefined && found.path.startsWith(`${found.root}/`) ? found.path.slice(found.root.length + 1) : baseOf(found.path));
|
|
51
51
|
/**
|
|
52
|
-
* The optional spec role of a spec beside a logic file its slot declares (`logic`): `passport.
|
|
53
|
-
* `passport.
|
|
52
|
+
* The optional spec role of a spec beside a logic file its slot declares (`logic`): `passport.kit.spec.ts` beside the declared
|
|
53
|
+
* `passport.kit.ts` gives `{ role: "kit", spec: "kit.spec" }`, so the subject resolves as a logic role's does. It holds for that
|
|
54
54
|
* one declared file only, never for another `*.tokens.ts`, and adds no role name to the manifest.
|
|
55
55
|
*/
|
|
56
56
|
const declaredLogicRole = (hfs, filename) => {
|
package/dist/module-shape.js
CHANGED
|
@@ -13,10 +13,12 @@
|
|
|
13
13
|
* import its own modules (a transport module its feature's application module, a representative its sub-modules);
|
|
14
14
|
* the app composes every owner.
|
|
15
15
|
* - `capability-module-shape` holds the definition of every module (owner ruling module-definition-everywhere): the representative
|
|
16
|
-
* `<c>.module-definition.ts` of a capability is
|
|
17
|
-
* and `.build()
|
|
18
|
-
*
|
|
19
|
-
*
|
|
16
|
+
* `<c>.module-definition.ts` of a capability is `defineCapabilityModule<XOptions>()` of `@starci/nest-kit` (or a typed
|
|
17
|
+
* `ConfigurableModuleBuilder` with `.setExtras({ isGlobal: false }, ...)` and `.build()`); every other module's definition (a
|
|
18
|
+
* sub-module, a feature, a transport, a cli group) is `defineConfigurableModule<XOptions>()` (or
|
|
19
|
+
* `.setClassMethodName("register").build()` with no extras); only a representative may override
|
|
20
|
+
* `static register(options: typeof OPTIONS_TYPE): DynamicModule`. The helper states its result type, so the definition is one call that
|
|
21
|
+
* R368 and R21 both accept.
|
|
20
22
|
* - `module-definition-required` holds that every module has one: a `<x>.module.ts` of a feature, capability or projection has a
|
|
21
23
|
* sibling `<x>.module-definition.ts` and `<x>.options.ts`, its class extends the `ConfigurableModuleClass` of that definition,
|
|
22
24
|
* and a module of the product appears in an `imports` array only as `X.register(...)`, never as a bare class
|
|
@@ -388,6 +390,20 @@ const chainFaults = (calls, representative) => {
|
|
|
388
390
|
missing.push("the chain does not end in `.build()`");
|
|
389
391
|
return missing;
|
|
390
392
|
};
|
|
393
|
+
/** The package whose helpers define a module in one call. */
|
|
394
|
+
const NEST_KIT = "@starci/nest-kit";
|
|
395
|
+
/** The reasons a call of a `@starci/nest-kit` function is not the module definition of its kind (an empty list when it is). */
|
|
396
|
+
const helperFaults = (imported, wanted, call) => {
|
|
397
|
+
if (imported !== "defineConfigurableModule" && imported !== "defineCapabilityModule")
|
|
398
|
+
return [`\`${imported ?? "this call"}\` is not a module definition helper`];
|
|
399
|
+
const missing = [];
|
|
400
|
+
if (imported !== wanted)
|
|
401
|
+
missing.push(wanted === "defineCapabilityModule" ? "the representative module of a capability defines itself with `defineCapabilityModule`, which adds the `isGlobal` extra defaulting to false" : "a sub-module, feature, transport or cli group is never global, so it defines itself with `defineConfigurableModule`");
|
|
402
|
+
const typeArguments = call.typeArguments ?? Reflect.get(call, "typeParameters");
|
|
403
|
+
if (!(isNode(typeArguments) && typeArguments.type === "TSTypeParameterInstantiation" && typeArguments.params.length > 0))
|
|
404
|
+
missing.push("the call does not state its options type (`<XOptions>`)");
|
|
405
|
+
return missing;
|
|
406
|
+
};
|
|
391
407
|
/** The module scope of a file: its kind, tier and name when it is a `<x>.module.ts` or `<x>.module-definition.ts` of a product tier, else null. */
|
|
392
408
|
const moduleFileOf = (hfs, filename) => {
|
|
393
409
|
const base = filename.split("/").at(-1) ?? "";
|
|
@@ -428,13 +444,22 @@ export const capabilityModuleShape = {
|
|
|
428
444
|
if (!scope)
|
|
429
445
|
return {};
|
|
430
446
|
if (scope.kind === "definition") {
|
|
447
|
+
const helper = scope.representative ? "defineCapabilityModule" : "defineConfigurableModule";
|
|
431
448
|
const shape = scope.representative
|
|
432
|
-
? "`new ConfigurableModuleBuilder<XOptions>().setExtras({ isGlobal: false }, (d, e) => ({ ...d, global: e.isGlobal })).build()`"
|
|
433
|
-
: '`new ConfigurableModuleBuilder<XOptions>().setClassMethodName("register").build()`';
|
|
449
|
+
? "`defineCapabilityModule<XOptions>()` of `@starci/nest-kit` (or `new ConfigurableModuleBuilder<XOptions>().setExtras({ isGlobal: false }, (d, e) => ({ ...d, global: e.isGlobal })).build()`)"
|
|
450
|
+
: '`defineConfigurableModule<XOptions>()` of `@starci/nest-kit` (or `new ConfigurableModuleBuilder<XOptions>().setClassMethodName("register").build()`)';
|
|
434
451
|
return {
|
|
435
452
|
Program(program) {
|
|
436
453
|
let found = false;
|
|
454
|
+
const kit = importsFrom(program, (source) => source === NEST_KIT);
|
|
437
455
|
walk(program, (node) => {
|
|
456
|
+
if (node.type === "CallExpression" && node.callee.type === "Identifier" && kit.has(node.callee.name)) {
|
|
457
|
+
found = true;
|
|
458
|
+
const missing = helperFaults(kit.get(node.callee.name), helper, node);
|
|
459
|
+
if (missing.length > 0)
|
|
460
|
+
context.report({ node, messageId: "chain", data: { shape, missing: missing.join("; ") } });
|
|
461
|
+
return;
|
|
462
|
+
}
|
|
438
463
|
if (node.type !== "NewExpression" || node.callee.type !== "Identifier" || node.callee.name !== "ConfigurableModuleBuilder")
|
|
439
464
|
return;
|
|
440
465
|
found = true;
|
|
@@ -443,7 +468,7 @@ export const capabilityModuleShape = {
|
|
|
443
468
|
context.report({ node, messageId: "chain", data: { shape, missing: missing.join("; ") } });
|
|
444
469
|
});
|
|
445
470
|
if (!found)
|
|
446
|
-
context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "chain", data: { shape, missing:
|
|
471
|
+
context.report({ node: program, loc: { line: 1, column: 0 }, messageId: "chain", data: { shape, missing: `no \`${helper}<XOptions>()\` is called here` } });
|
|
447
472
|
},
|
|
448
473
|
};
|
|
449
474
|
}
|
package/dist/testing.js
CHANGED
|
@@ -141,6 +141,9 @@ export const unitTestColocated = {
|
|
|
141
141
|
if (BANNED_TEST_FILE.test(name)) {
|
|
142
142
|
return { Program(node) { context.report({ node, messageId: "suffix", data: { name } }); } };
|
|
143
143
|
}
|
|
144
|
+
// A root workspace package keeps a spec beside any source file (slot app.packages, tests: unit-beside): the service-role pairing is the module folders'.
|
|
145
|
+
if (hfs.tierOf(filename) === "package")
|
|
146
|
+
return {};
|
|
144
147
|
if (isUnitSpecFile(hfs, filename)) {
|
|
145
148
|
const door = doorOfSpec(hfs, filename);
|
|
146
149
|
if (door !== null)
|
|
@@ -10,6 +10,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
|
|
|
10
10
|
import { isBuiltin } from "node:module";
|
|
11
11
|
import { dirname, join, resolve } from "node:path";
|
|
12
12
|
import ts from "typescript";
|
|
13
|
+
import { rootPackageNames } from "../runtime/scripts/hfs/architecture/root-packages.mjs";
|
|
13
14
|
import { hfsOf, inTestWorld } from "./lib/hfs.js";
|
|
14
15
|
import { moduleReferences } from "./lib/import-source.js";
|
|
15
16
|
import { isSpecFile } from "./lib/path.js";
|
|
@@ -21,7 +22,7 @@ const PURE = new Set([
|
|
|
21
22
|
const FRAMEWORK = new Set([
|
|
22
23
|
"@nestjs/common", "@nestjs/core", "@nestjs/cqrs", "@nestjs/graphql", "@nestjs/apollo", "@nestjs/platform-express",
|
|
23
24
|
"@nestjs/typeorm", "@nestjs/swagger", "@nestjs/mapped-types", "@nestjs/throttler", "@apollo/server",
|
|
24
|
-
"@as-integrations/express5", "express", "nest-commander", "typeorm",
|
|
25
|
+
"@as-integrations/express5", "express", "nest-commander", "typeorm", "@starci/nest-kit",
|
|
25
26
|
]);
|
|
26
27
|
const TEST_LIBRARIES = new Set(["@nestjs/testing", "@starci/jest-preset", "@starci/test-world", "@jest/globals", "jest", "jest-mock"]);
|
|
27
28
|
const DEPENDENCIES = new WeakMap();
|
|
@@ -69,16 +70,20 @@ const dependenciesOf = (hfs) => {
|
|
|
69
70
|
const cached = DEPENDENCIES.get(hfs);
|
|
70
71
|
if (cached)
|
|
71
72
|
return cached;
|
|
72
|
-
|
|
73
|
+
// A package view (the root workspace packages) has the app root itself as its repoRoot: hfs.json sits there, and so does the one manifest.
|
|
74
|
+
const appManifest = existsSync(join(hfs.repoRoot, "hfs.json")) ? join(hfs.repoRoot, "package.json") : join(dirname(hfs.repoRoot), "package.json");
|
|
73
75
|
const manifest = existsSync(appManifest) ? appManifest : join(hfs.repoRoot, "package.json");
|
|
74
76
|
if (!existsSync(manifest))
|
|
75
77
|
throw new Error("third-party-import-owner needs the app-root package.json beside be/ to derive SDK ownership");
|
|
76
78
|
const declaration = JSON.parse(readFileSync(manifest, "utf8"));
|
|
77
79
|
const dependencies = new Map();
|
|
80
|
+
// The app's own workspace packages (packages/agent-sdk, packages/module-<name>) are first-party source, not third-party libraries: whatever
|
|
81
|
+
// version range the root manifest writes for one of them, it names no SDK to own. What such a package imports is judged in the package.
|
|
82
|
+
const own = rootPackageNames(dirname(manifest));
|
|
78
83
|
for (const section of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
|
|
79
84
|
const declared = typeof declaration === "object" && declaration !== null ? Reflect.get(declaration, section) : undefined;
|
|
80
85
|
for (const [name, version] of Object.entries(declared ?? {})) {
|
|
81
|
-
if (/^(?:workspace:|file:|link:)/.test(String(version)))
|
|
86
|
+
if (/^(?:workspace:|file:|link:)/.test(String(version)) || own.has(name))
|
|
82
87
|
continue;
|
|
83
88
|
const alias = /^npm:((?:@[^/]+\/)?[^@]+)(?:@|$)/.exec(String(version));
|
|
84
89
|
dependencies.set(name, alias?.[1] ?? name);
|
package/package.json
CHANGED
package/runtime/bundle.json
CHANGED
|
@@ -102,6 +102,7 @@
|
|
|
102
102
|
"scripts/hfs/architecture/render-graph.mjs",
|
|
103
103
|
"scripts/hfs/architecture/render-prop-across-server.mjs",
|
|
104
104
|
"scripts/hfs/architecture/required-files.mjs",
|
|
105
|
+
"scripts/hfs/architecture/root-packages.mjs",
|
|
105
106
|
"scripts/hfs/architecture/route-files-thin.mjs",
|
|
106
107
|
"scripts/hfs/architecture/schema-owner.mjs",
|
|
107
108
|
"scripts/hfs/architecture/server-action.mjs",
|