@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 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`.
@@ -1,9 +1,7 @@
1
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. */
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 integration's httpOnly cookie. */
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: {
@@ -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 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.
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
- 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"]);
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
- /** 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("/");
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 token. */
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: "Only integrations/passport verifies a token (jose jwtVerify over the app's own key set); no remote JWKS and no unverified decode anywhere." },
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 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.",
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 === "createRemoteJWKSet" ? "trusts another issuer's key set" : "reads a token without proving its signature" } });
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 integration's httpOnly cookie. */
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 only integrations/passport sets or clears the refresh cookie." },
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, 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`.",
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);
@@ -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>;
@@ -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
  *
@@ -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.tokens.spec.ts` beside the declared
53
- * `passport.tokens.ts` gives `{ role: "tokens", spec: "tokens.spec" }`, so the subject resolves as a logic role's does. It holds for that
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) => {
@@ -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 a typed `ConfigurableModuleBuilder` with `.setExtras({ isGlobal: false }, ...)`
17
- * and `.build()`; every other module's definition (a sub-module, a feature, a transport, a cli group) is
18
- * `.setClassMethodName("register").build()` with no extras; only a representative may override
19
- * `static register(options: typeof OPTIONS_TYPE): DynamicModule`.
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: "no `new ConfigurableModuleBuilder<XOptions>()` is built here" } });
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
- const appManifest = join(dirname(hfs.repoRoot), "package.json");
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.12.0",
3
+ "version": "3.14.0",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -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",