@starci/eslint-canon-be 3.13.0 → 3.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -1
- 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/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 +43 -10
- package/runtime/knowledge/hfs/fe-stack.yaml +3 -3
- package/runtime/knowledge/hfs/rules.yaml +13 -9
- package/runtime/knowledge/hfs/slots.yaml +101 -10
- package/runtime/scripts/hfs/architecture/config.mjs +25 -1
- 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/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/view.mjs +68 -0
- package/runtime/scripts/lib/declaration-surface.mjs +55 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.14.1 - 2026-11-03
|
|
4
|
+
|
|
5
|
+
- Changed: the runtime copies carry the canon pins of `@starci/auth` 0.2.1, `@starci/auth-oidc` 0.1.1, the Grammar family 0.21.16 and `@starci/hfs` 5.4.0.
|
|
6
|
+
|
|
7
|
+
## 3.14.0 - 2026-11-03
|
|
8
|
+
|
|
9
|
+
- Changed: `@starci/nest-kit` is a framework import like `@nestjs/common` (`third-party-import-owner` lets any module definition import it).
|
|
10
|
+
- 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.
|
|
11
|
+
- 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.
|
|
12
|
+
- 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).
|
|
13
|
+
- Changed: the runtime copy of the slot manifest carries the slots `app.packages`, `app.module-registry` and `app.packages-lint`.
|
|
14
|
+
|
|
3
15
|
## 3.13.0 - 2026-11-03
|
|
4
16
|
|
|
5
17
|
- Changed: the runtime copies of the slot manifest carry the managed sign-in slots and the slot field `managedOnly`.
|
|
@@ -254,7 +266,6 @@
|
|
|
254
266
|
- 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).
|
|
255
267
|
- 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.
|
|
256
268
|
|
|
257
|
-
|
|
258
269
|
## 3.6.8 - 2026-10-29
|
|
259
270
|
|
|
260
271
|
- 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/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/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",
|
|
@@ -38,42 +38,49 @@ pins:
|
|
|
38
38
|
source: packages/next-data/package.json
|
|
39
39
|
why: 'the SWR data helpers of every front end (fe-stack data, owner:next-data-package): pollingRestart, the viewer and tenant key helpers, viewerSwrConfig and the viewer cache; each operation hook stays in the app and the package holds no component.'
|
|
40
40
|
'@starci/grammar':
|
|
41
|
-
version: 0.21.
|
|
41
|
+
version: 0.21.16
|
|
42
42
|
group: starci
|
|
43
43
|
install: registry
|
|
44
44
|
side: fe
|
|
45
45
|
source: packages/grammar/package.json
|
|
46
46
|
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.'
|
|
47
|
+
'@starci/next-i18n':
|
|
48
|
+
version: 0.1.0
|
|
49
|
+
group: starci
|
|
50
|
+
install: registry
|
|
51
|
+
side: fe
|
|
52
|
+
source: packages/next-i18n/package.json
|
|
53
|
+
why: 'the next-intl stack of every front end (fe-stack i18n, owner:next-i18n-package): defineI18n over the locales of the app, the locale-negotiating proxy, the locale-aware navigation, the request config that loads the catalogs of the app and the locale read of the [locale] layout; the app keeps its message catalogs and writes none of the stack.'
|
|
47
54
|
'@starci/eslint-canon-be':
|
|
48
|
-
version: 3.
|
|
55
|
+
version: 3.14.1
|
|
49
56
|
group: starci
|
|
50
57
|
install: registry
|
|
51
58
|
side: be
|
|
52
59
|
source: packages/eslint-canon-be/package.json
|
|
53
60
|
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.'
|
|
54
61
|
'@starci/eslint-canon-fe':
|
|
55
|
-
version: 9.
|
|
62
|
+
version: 9.12.1
|
|
56
63
|
group: starci
|
|
57
64
|
install: registry
|
|
58
65
|
side: fe
|
|
59
66
|
source: packages/eslint-canon-fe/package.json
|
|
60
67
|
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.'
|
|
61
68
|
'@starci/eslint-grammar-core':
|
|
62
|
-
version: 0.21.
|
|
69
|
+
version: 0.21.16
|
|
63
70
|
group: starci
|
|
64
71
|
install: registry
|
|
65
72
|
side: fe
|
|
66
73
|
source: packages/eslint-grammar-core/package.json
|
|
67
74
|
why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
|
|
68
75
|
'@starci/eslint-grammar-offset-pop':
|
|
69
|
-
version: 0.21.
|
|
76
|
+
version: 0.21.16
|
|
70
77
|
group: starci
|
|
71
78
|
install: registry
|
|
72
79
|
side: fe
|
|
73
80
|
source: packages/eslint-grammar-offset-pop/package.json
|
|
74
81
|
why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
|
|
75
82
|
'@starci/stylelint-canon':
|
|
76
|
-
version: 2.
|
|
83
|
+
version: 2.6.0
|
|
77
84
|
group: starci
|
|
78
85
|
install: registry
|
|
79
86
|
side: fe
|
|
@@ -92,7 +99,7 @@ pins:
|
|
|
92
99
|
side: both
|
|
93
100
|
source: packages/prettier-config/package.json
|
|
94
101
|
'@starci/jest-preset':
|
|
95
|
-
version: 2.6.
|
|
102
|
+
version: 2.6.2
|
|
96
103
|
group: starci
|
|
97
104
|
install: registry
|
|
98
105
|
side: be
|
|
@@ -112,13 +119,27 @@ pins:
|
|
|
112
119
|
side: be
|
|
113
120
|
source: packages/ai-router/package.json
|
|
114
121
|
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.'
|
|
115
|
-
'@starci/
|
|
122
|
+
'@starci/nest-kit':
|
|
116
123
|
version: 0.1.0
|
|
117
124
|
group: starci
|
|
118
125
|
install: registry
|
|
126
|
+
side: be
|
|
127
|
+
source: packages/nest-kit/package.json
|
|
128
|
+
why: 'the module definition of every back-end module: defineConfigurableModule and defineCapabilityModule return the module base class, the options token and the options types with their types stated, so a <x>.module-definition.ts is one call that the lint on stated export types (R368) and the duplicate-code check (R21) both accept; @starci/jest-preset compiles it as an ESM-only dependency.'
|
|
129
|
+
'@starci/auth':
|
|
130
|
+
version: 0.2.1
|
|
131
|
+
group: starci
|
|
132
|
+
install: registry
|
|
119
133
|
side: both
|
|
120
134
|
source: packages/auth/package.json
|
|
121
135
|
why: 'the lite sign-in: the NestJS module (EdDSA access tokens with a multi-key JWKS, passwords, Google OAuth with state and PKCE, rotating refresh sessions, the sign-in budget, the refresh cookie), the front-end client and its React bindings, the door contracts and test doubles; the one importer of the identity libraries, reached by a back end only through integrations/passport; @starci/jest-preset compiles it as an ESM-only dependency.'
|
|
136
|
+
'@starci/auth-oidc':
|
|
137
|
+
version: 0.1.1
|
|
138
|
+
group: starci
|
|
139
|
+
install: registry
|
|
140
|
+
side: both
|
|
141
|
+
source: packages/auth-oidc/package.json
|
|
142
|
+
why: 'the full sign-in: the OIDC client of the identity provider (Keycloak) behind the PrincipalVerifier of @starci/auth, so guards do not change between editions: the NestJS module (issuer discovery, the JWKS with caching and rotation, algorithm-pinned token checks, role mapping, the authorization code flow with PKCE and nonce), the front-end client (PKCE redirect, one shared refresh, tokens in memory) and the fake issuer for tests; the one importer of jose in a full app, reached by a back end only through integrations/keycloak; @starci/jest-preset compiles it as an ESM-only dependency.'
|
|
122
143
|
'@starci/object-storage':
|
|
123
144
|
version: 0.1.0
|
|
124
145
|
group: starci
|
|
@@ -126,8 +147,15 @@ pins:
|
|
|
126
147
|
side: be
|
|
127
148
|
source: packages/object-storage/package.json
|
|
128
149
|
why: 'object storage of a back end: a NestJS module and the ObjectStorage port over S3-compatible storage (presigned PUT and GET that sign the content type and size, head, get, put, list, delete, bucket setup, size and content-type limits, coded errors), with @starci/object-storage/testing for its specs; the only importer of @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner (R331).'
|
|
150
|
+
'@starci/mail':
|
|
151
|
+
version: 0.1.0
|
|
152
|
+
group: starci
|
|
153
|
+
install: registry
|
|
154
|
+
side: be
|
|
155
|
+
source: packages/mail/package.json
|
|
156
|
+
why: 'outgoing mail of a back end: a NestJS module and the Mailer port over SMTP (connect, greeting, socket and total timeouts, STARTTLS required by default, recipient, message and attachment checks, a shared SMTP target policy, coded errors, typed escaping render helpers returning { subject, text, html }), with @starci/mail/testing for its specs; the only importer of nodemailer (R90).'
|
|
129
157
|
'@starci/hfs':
|
|
130
|
-
version: 5.
|
|
158
|
+
version: 5.4.0
|
|
131
159
|
group: starci
|
|
132
160
|
install: registry
|
|
133
161
|
side: both
|
|
@@ -570,6 +598,11 @@ pins:
|
|
|
570
598
|
group: framework
|
|
571
599
|
side: be
|
|
572
600
|
why: 'signs the presigned PUT and GET inside @starci/object-storage locally, the same release as client-s3; no app file imports it.'
|
|
601
|
+
nodemailer:
|
|
602
|
+
version: 10.1.7
|
|
603
|
+
group: framework
|
|
604
|
+
side: be
|
|
605
|
+
why: 'the SMTP client inside @starci/mail, which depends on it at exactly this version and which no app file imports; 10.1.7 is the release of 2026-10-18, chosen over newer ones that had not aged two weeks.'
|
|
573
606
|
'@apollo/server':
|
|
574
607
|
version: 5.5.1
|
|
575
608
|
group: framework
|
|
@@ -670,7 +703,7 @@ pins:
|
|
|
670
703
|
version: 6.2.12
|
|
671
704
|
group: framework
|
|
672
705
|
side: be
|
|
673
|
-
why: signs the app's own
|
|
706
|
+
why: signs the app's own access tokens and verifies them against its own key set inside @starci/auth, and verifies the identity provider's tokens against its JWKS inside @starci/auth-oidc; no app file imports it.
|
|
674
707
|
class-transformer:
|
|
675
708
|
version: 0.5.1
|
|
676
709
|
group: framework
|
|
@@ -96,18 +96,18 @@ concerns:
|
|
|
96
96
|
hand-written reader (read-event-stream.ts) and no second SSE library is installed.
|
|
97
97
|
- id: auth
|
|
98
98
|
tier: core
|
|
99
|
-
packages: ['@starci/auth']
|
|
99
|
+
packages: ['@starci/auth', '@starci/auth-oidc']
|
|
100
100
|
home: [fe.modules.auth]
|
|
101
101
|
pattern: FE-AUTH
|
|
102
102
|
forbids: ['@supabase/supabase-js', '@supabase/ssr', '@supabase/auth-js', jose, jwt-decode, next-auth, '@auth/core', keycloak-js, oidc-client-ts]
|
|
103
103
|
why: modules/auth is the session issuer's client (one @starci/auth client instance over the app's own back-end auth doors, the access token in its memory; 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
|
-
packages: [next-intl]
|
|
106
|
+
packages: [next-intl, '@starci/next-i18n']
|
|
107
107
|
home: [fe.modules.i18n]
|
|
108
108
|
pattern: FE-I18N
|
|
109
109
|
forbids: [i18next, react-i18next, next-i18next, react-intl, '@lingui/react']
|
|
110
|
-
why: useTranslations for copy and the next-intl formatter for numbers, fixed dates and currency; FE-DATE owns live time display.
|
|
110
|
+
why: useTranslations for copy and the next-intl formatter for numbers, fixed dates and currency; FE-DATE owns live time display. The routing, the proxy, the navigation, the request config and the locale read of the layout are @starci/next-i18n's (owner next-i18n-package); an app calls no defineRouting, createNavigation, getRequestConfig or createMiddleware.
|
|
111
111
|
- id: ui
|
|
112
112
|
tier: core
|
|
113
113
|
packages: ['@heroui/react', '@heroui/styles', tailwindcss, '@starci/grammar', react-aria-components]
|
|
@@ -133,8 +133,8 @@ rules:
|
|
|
133
133
|
- {path: packages/hfs/src/hfs-managed-file-drift.spec.mjs, edition: full, codes: [HFS_MANAGED_FILE_DRIFT]}
|
|
134
134
|
- id: R06
|
|
135
135
|
code: "HFS_PLAINTEXT_SECRET"
|
|
136
|
-
law: "Secrets exist only as `.starcistacks/<env>/secrets/<slug>.enc`."
|
|
137
|
-
kinds: [check, design]
|
|
136
|
+
law: "Secrets exist only as `.starcistacks/<env>/secrets/<slug>.enc`; the committed check cache (`.starcistacks/cache/check/secrets/`) holds codes, paths, positions and digests only, and is judged by what it holds."
|
|
137
|
+
kinds: [check, design, codemod]
|
|
138
138
|
gates: [pre-commit, land, ci]
|
|
139
139
|
failureCodes: ["HFS_PLAINTEXT_SECRET"]
|
|
140
140
|
enforcers:
|
|
@@ -143,7 +143,7 @@ rules:
|
|
|
143
143
|
editions: [lite, full]
|
|
144
144
|
docs: [docs/legacy-managed-rule-coverage.md#r06-plaintext-secrets]
|
|
145
145
|
templateNa: "Encrypted secrets are supplied by the app secret command; plaintext secret files are forbidden and are never scaffolded."
|
|
146
|
-
proves: [packages/hfs/src/hfs-plaintext-secret.spec.mjs]
|
|
146
|
+
proves: [packages/hfs/src/hfs-plaintext-secret.spec.mjs, packages/hfs/src/check-cache-secret-records.spec.mjs]
|
|
147
147
|
exemplifiedBy:
|
|
148
148
|
- {path: packages/hfs/src/hfs-plaintext-secret.spec.mjs, editions: [lite, full]}
|
|
149
149
|
witness:
|
|
@@ -1216,7 +1216,7 @@ rules:
|
|
|
1216
1216
|
code: "FE_I18N_PLACEMENT"
|
|
1217
1217
|
editions: [lite, full]
|
|
1218
1218
|
docs: [docs/architecture.md#r59]
|
|
1219
|
-
law: "`next-intl` with `[locale]`;
|
|
1219
|
+
law: "`next-intl` with `[locale]`; the stack (routing, proxy, navigation, request config, the layout's locale read) is built by `@starci/next-i18n` over the app's `defineI18n` description and by no product source. A single app keeps the description and its request config in `modules/i18n` and builds its navigation with `createI18nNavigation` in the `modules/routes` public entry; apps that share a product share one `fe/packages/<family>-i18n` workspace package that holds the description and composes the package's factories through `createAppI18n`. The proxy is `createProxy` of `@starci/next-i18n/proxy` and never evaluates navigation runtime."
|
|
1220
1220
|
kinds: [check, codemod, lint]
|
|
1221
1221
|
gates: [settle, land, ci]
|
|
1222
1222
|
failureCodes: ["FE_I18N_PLACEMENT", "FE_I18N_NAVIGATION", "FE_I18N_FORMATTER"]
|
|
@@ -1269,6 +1269,7 @@ rules:
|
|
|
1269
1269
|
- {kind: stylelint, id: raw-brand-value}
|
|
1270
1270
|
- {kind: stylelint, id: no-apply-raw}
|
|
1271
1271
|
- {kind: stylelint, id: no-important}
|
|
1272
|
+
- {kind: stylelint, id: no-self-reference}
|
|
1272
1273
|
- {kind: stylelint, id: globals-shape}
|
|
1273
1274
|
- {kind: stylelint, id: globals-import-order}
|
|
1274
1275
|
- {kind: stylelint, id: no-token-redefinition}
|
|
@@ -4263,7 +4264,7 @@ rules:
|
|
|
4263
4264
|
editionWhy: "owner:lite-backing-services makes the db service lite's database; application-role and forced-RLS requirements apply to that backing."
|
|
4264
4265
|
docs: [docs/microservices.md#r255]
|
|
4265
4266
|
templateNa: "Application roles and table ownership are product-authored db migration content, rather than a scaffolded SQL surface."
|
|
4266
|
-
law: "The declared back-end database role (app_be by default) has only the privileges it needs: role declarations refuse superuser and bypassrls, require noinherit and nobypassrls,
|
|
4267
|
+
law: "The declared back-end database role (app_be by default) has only the privileges it needs: role declarations refuse superuser and bypassrls, require noinherit and nobypassrls, never grant all schema or table privileges, and leave it with no grant after the last migration on schema auth, on a table or sequence in it, or by default privilege for it (accounts are reached through SECURITY DEFINER doors; a later migration that revokes a grant clears it). Tables owned by that role enable and force row level security by default; a forceRls exemption identifies the table and carries a nonempty reason. This applies to every edition that declares Supabase."
|
|
4267
4268
|
kinds: [check]
|
|
4268
4269
|
gates: [settle, land, ci]
|
|
4269
4270
|
failureCodes: ["DB_APP_ROLE", "DB_FORCE_RLS_DEFAULT"]
|
|
@@ -4773,7 +4774,7 @@ rules:
|
|
|
4773
4774
|
|
|
4774
4775
|
- id: R279
|
|
4775
4776
|
code: "BE_THIRD_PARTY_OWNER"
|
|
4776
|
-
law: "Third-party SDK ownership is derived from the app's package.json dependencies rather than a finite SDK table. A dependency outside the pure-library and framework allowlists is imported only by one integrations/<provider> capability; domain services call that integration's public API. Existing infrastructure owner restrictions remain in force."
|
|
4777
|
+
law: "Third-party SDK ownership is derived from the app's package.json dependencies rather than a finite SDK table. A dependency outside the pure-library and framework allowlists is imported only by one integrations/<provider> capability; domain services call that integration's public API. A workspace package of the app itself (a folder the root workspaces of package.json name) is first-party source and no SDK; what it imports is judged over its own files. Existing infrastructure owner restrictions remain in force."
|
|
4777
4778
|
kinds: [lint]
|
|
4778
4779
|
gates: [pre-commit, settle, land, ci]
|
|
4779
4780
|
failureCodes: ["BE_THIRD_PARTY_OWNER"]
|
|
@@ -5083,7 +5084,7 @@ rules:
|
|
|
5083
5084
|
- {path: packages/hfs/src/hfs-stacks-deploy.spec.mjs, editions: [lite, full]}
|
|
5084
5085
|
- id: R295
|
|
5085
5086
|
code: "BE_MODULE_DEFINITION_MISSING"
|
|
5086
|
-
law: "Every NestJS module of the product has a module definition (owner ruling 2026-10-15, owner:module-definition-everywhere): capability modules, sub-modules, features, transport modules and cli groups alike. For a module `<x>` the folder holds `<x>.module-definition.ts` (`export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
|
|
5087
|
+
law: "Every NestJS module of the product has a module definition (owner ruling 2026-10-15, owner:module-definition-everywhere): capability modules, sub-modules, features, transport modules and cli groups alike. For a module `<x>` the folder holds `<x>.module-definition.ts` (`export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = defineConfigurableModule<XOptions>()` of `@starci/nest-kit`, which states the exported types so the file is neither an inferred surface (R368) nor a clone of its neighbour (R21); the representative module of a capability calls `defineCapabilityModule<XOptions>()`, which adds the `isGlobal` extra defaulting to `false`; `starci app codemod module-definition` rewrites a definition written with `ConfigurableModuleBuilder`), `<x>.options.ts` (`export type XOptions`, `Record<string, never>` with a one-line doc when it takes nothing yet) and `<x>.module.ts` (`@Module({...}) export class XModule extends ConfigurableModuleClass {}`, no `register` override except the capability representative's). A module appears in an `imports` array or in an app composition group only as `XModule.register({...})`, never as a bare class. The `AppModule` of an app root and the test world are composition roots and are not judged."
|
|
5087
5088
|
kinds: [lint, codemod]
|
|
5088
5089
|
gates: [pre-commit, settle, land, ci]
|
|
5089
5090
|
failureCodes: ["BE_MODULE_DEFINITION_MISSING"]
|
|
@@ -5697,20 +5698,23 @@ rules:
|
|
|
5697
5698
|
ruling: "A model call made straight from code uses LangChain with retrieved context, through the ai-router gateway (owner ruling be-ai-langchain-gateway): the LangChain clients point at the gateway's base URL with its virtual key."
|
|
5698
5699
|
- id: R328
|
|
5699
5700
|
code: "BE_AUTH_PASSPORT_OWNER"
|
|
5700
|
-
law: "The identity libraries (@nestjs/passport, passport, passport-google-oauth20, passport-local, @nestjs/jwt, jose and bcryptjs) are the dependencies of @starci/auth and are imported by no app file; @starci/auth/server is imported only by integrations/passport,
|
|
5701
|
+
law: "The identity libraries (@nestjs/passport, passport, passport-google-oauth20, passport-local, @nestjs/jwt, jose and bcryptjs) are the dependencies of @starci/auth (lite) and of @starci/auth-oidc (full, which owns jose for its provider tokens) and are imported by no app file; @starci/auth/server is imported only by integrations/passport and @starci/auth-oidc/server only by integrations/keycloak, each package's one glue. bcrypt and every Supabase client are owned nowhere."
|
|
5701
5702
|
kinds: [lint]
|
|
5702
5703
|
gates: [pre-commit, settle, land, ci]
|
|
5703
5704
|
failureCodes: ["BE_AUTH_PASSPORT_OWNER"]
|
|
5704
5705
|
enforcers:
|
|
5705
5706
|
- {kind: eslint-be, id: infra-import-owner}
|
|
5706
|
-
editions: [lite]
|
|
5707
|
+
editions: [lite, full]
|
|
5707
5708
|
docs: [contexts/code/be/api-auth.md]
|
|
5708
5709
|
proves:
|
|
5709
5710
|
- packages/eslint-canon-be/src/auth-passport.spec.ts
|
|
5711
|
+
- packages/eslint-canon-be/src/auth-oidc-package.spec.ts
|
|
5710
5712
|
exemplifiedBy:
|
|
5711
5713
|
- {path: packages/hfs/templates/be/skeleton-lite/src/modules/integrations/passport/passport.tokens.ts, edition: lite}
|
|
5714
|
+
- {path: packages/auth-oidc/src/server/index.ts, edition: full}
|
|
5712
5715
|
witness:
|
|
5713
5716
|
- {path: packages/eslint-canon-be/src/auth-passport.spec.ts, edition: lite, codes: [BE_AUTH_PASSPORT_OWNER]}
|
|
5717
|
+
- {path: packages/eslint-canon-be/src/auth-oidc-package.spec.ts, edition: full, codes: [BE_AUTH_PASSPORT_OWNER]}
|
|
5714
5718
|
cases:
|
|
5715
5719
|
- id: case-1
|
|
5716
5720
|
date: "2026-10-29"
|
|
@@ -240,6 +240,8 @@ ruleParams:
|
|
|
240
240
|
"@aws-sdk/s3-request-presigner": []
|
|
241
241
|
"@starci/object-storage": [integrations/object-storage] # the ObjectStorage port: one S3 adapter for MinIO, S3 and Spaces (R331)
|
|
242
242
|
minio: [] # storage goes through @starci/object-storage
|
|
243
|
+
nodemailer: [] # the SMTP client is a dependency of @starci/mail alone; no app file imports it
|
|
244
|
+
"@starci/mail": [integrations/mail] # outgoing mail: the Mailer port, parsed and registered by its one glue
|
|
243
245
|
"@supabase": [] # no Supabase client in a back end
|
|
244
246
|
"@nestjs/passport": [] # the identity libraries are @starci/auth's dependencies, never an app's (R328)
|
|
245
247
|
passport: []
|
|
@@ -248,8 +250,15 @@ ruleParams:
|
|
|
248
250
|
"@nestjs/jwt": []
|
|
249
251
|
jose: []
|
|
250
252
|
bcryptjs: []
|
|
253
|
+
jsonwebtoken: [] # no other JWT or OIDC client library in a back end: the tokens of an identity provider are verified by @starci/auth-oidc (R328)
|
|
254
|
+
jwks-rsa: []
|
|
255
|
+
jwt-decode: []
|
|
256
|
+
passport-jwt: []
|
|
257
|
+
openid-client: []
|
|
251
258
|
"@starci/auth": [integrations/passport] # the lite sign-in package: its server entry is reached only through integrations/passport (R328)
|
|
252
259
|
"@starci/auth/testing": [integrations/passport] # its test doubles, for the glue's specs
|
|
260
|
+
"@starci/auth-oidc": [integrations/keycloak] # the full sign-in package (jose is its dependency, imported by no app file): its server entry is reached only through integrations/keycloak (R328)
|
|
261
|
+
"@starci/auth-oidc/testing": [integrations/keycloak] # its fake issuer, for the glue's specs
|
|
253
262
|
bcrypt: []
|
|
254
263
|
cache-manager: [integrations/cache, integrations/redis]
|
|
255
264
|
"@nestjs/cache-manager": [integrations/cache, integrations/redis] # the CACHE_MANAGER token: caching goes through the cache capability
|
|
@@ -463,6 +472,14 @@ ruleParams:
|
|
|
463
472
|
- {name: public.event_bus_bury, reason: "platform/event-bus (add webhook, lite): the move of an exhausted or malformed message to its consumer's dead-letter queue"}
|
|
464
473
|
- {name: public.event_bus_dead_letters, reason: "platform/event-bus (add webhook, lite): the operator read of a consumer's dead-letter queue"}
|
|
465
474
|
- {name: public.event_bus_requeue, reason: "platform/event-bus (add webhook, lite): the operator requeue of one dead letter"}
|
|
475
|
+
- {name: public.be_auth_user_by_email, reason: "domain/identity (lite sign-in): the account of an exact sign-in address with its bcrypt hash, through the account-doors definer of the baseline"}
|
|
476
|
+
- {name: public.be_auth_user_by_id, reason: "domain/identity (lite sign-in): the standing of one account by id (a refresh), through the account-doors definer"}
|
|
477
|
+
- {name: public.be_auth_user_by_google, reason: "domain/identity (lite sign-in): the account a Google subject is linked to, through the account-doors definer"}
|
|
478
|
+
- {name: public.be_auth_create_user, reason: "domain/identity (lite sign-in): the account a first Google sign-in creates, through the account-doors definer"}
|
|
479
|
+
- {name: public.be_auth_link_google, reason: "domain/identity (lite sign-in): the link of a Google subject to an account, through the account-doors definer"}
|
|
480
|
+
- {name: public.be_auth_touch_user, reason: "domain/identity (lite sign-in): the sign-in record of an account and its profile keys, through the account-doors definer"}
|
|
481
|
+
- {name: public.be_auth_confirm_user, reason: "domain/identity (lite sign-in): the confirmation stamp of a mailbox whose link was spent, through the account-doors definer"}
|
|
482
|
+
- {name: public.be_auth_set_password, reason: "domain/identity (lite sign-in): the new password hash of a spent reset link (and the mailbox it proved), through the account-doors definer"}
|
|
466
483
|
# R334 (lite): the only `.query(` outside platform/database's composer and the test world is the pass-through of a file listed here
|
|
467
484
|
# (or in hfs.json sides.be.sqlPassThrough), whose SQL text is not the app's own. Paths are relative to the side folder.
|
|
468
485
|
sqlPassThrough:
|
|
@@ -590,13 +607,24 @@ slots:
|
|
|
590
607
|
- id: app.tool-config-local
|
|
591
608
|
since: 3.1.0
|
|
592
609
|
profiles: [app]
|
|
593
|
-
path: "{tsconfig.json,.eslintrc,.eslintrc.*,.eslintignore,eslint.config
|
|
610
|
+
path: "{tsconfig.json,.eslintrc,.eslintrc.*,.eslintignore,eslint.config.js,eslint.config.cjs,eslint.config.ts,eslint.config.mts,eslint.config.cts,.stylelintrc,.stylelintrc.*,.stylelintignore,stylelint.config.*,.prettierrc.*,prettier.config.*,jest.config.*,lint-staged.config.*,.lintstagedrc*}"
|
|
594
611
|
presence: forbidden
|
|
595
612
|
tracked: external
|
|
596
613
|
tier: none
|
|
597
614
|
tests: none
|
|
598
|
-
goesTo: "nowhere at the app root: each side holds exactly its managed tool configuration (be.tool-config, fe.tool-config) and the root only the formatter (app.format-config)"
|
|
615
|
+
goesTo: "nowhere at the app root: each side holds exactly its managed tool configuration (be.tool-config, fe.tool-config) and the root only the formatter (app.format-config) and the eslint config of its root packages (app.packages-lint)"
|
|
599
616
|
rules: [HFS_TOOL_CONFIG_LOCAL]
|
|
617
|
+
- id: app.packages-lint
|
|
618
|
+
since: 3.17.0
|
|
619
|
+
profiles: [app]
|
|
620
|
+
# The one eslint config at the app root: `starci app sync` renders it when the app has root workspace packages (app.packages), and it lints their
|
|
621
|
+
# source by subpath (the back-end canon, the front-end canon and the Grammar family each over their own subpaths). No other tool config lives here.
|
|
622
|
+
path: eslint.config.mjs
|
|
623
|
+
presence: optional
|
|
624
|
+
tracked: tracked
|
|
625
|
+
tier: none
|
|
626
|
+
tests: none
|
|
627
|
+
rules: [HFS_MANAGED_FILE_DRIFT]
|
|
600
628
|
- id: app.quality-config
|
|
601
629
|
since: 3.1.0
|
|
602
630
|
profiles: [app]
|
|
@@ -828,6 +856,31 @@ slots:
|
|
|
828
856
|
rules: [HFS_PLAINTEXT_SECRET, HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK]
|
|
829
857
|
exemplifiedBy:
|
|
830
858
|
- {path: packages/hfs/src/hfs-slot-ownership.spec.mjs, editions: [lite, full]}
|
|
859
|
+
- id: app.packages
|
|
860
|
+
since: 3.17.0
|
|
861
|
+
profiles: [app]
|
|
862
|
+
editionWhy: Lite and full share the slot; a product's agent SDK and its agent modules are workspace packages in both.
|
|
863
|
+
# A workspace package of the app ROOT (packages/agent-sdk, packages/module-<name>): first-party source that both sides import through its
|
|
864
|
+
# package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
|
|
865
|
+
path: "packages/{agent-sdk,module-<name>}/"
|
|
866
|
+
presence: optional
|
|
867
|
+
tracked: tracked
|
|
868
|
+
tier: none
|
|
869
|
+
requires: [package.json, tsconfig.json, src/index.ts]
|
|
870
|
+
tests: unit-beside
|
|
871
|
+
rules: [HFS_UNUSED_EXPORT]
|
|
872
|
+
- id: app.module-registry
|
|
873
|
+
since: 3.17.0
|
|
874
|
+
profiles: [app]
|
|
875
|
+
editionWhy: Lite and full share the slot; the registry lists the module packages of the app.
|
|
876
|
+
path: packages/modules/
|
|
877
|
+
presence: optional
|
|
878
|
+
tracked: tracked
|
|
879
|
+
tier: none
|
|
880
|
+
requires: [package.json, src/index.ts]
|
|
881
|
+
allows: [package.json, tsconfig.json, tsconfig.build.json, src/index.ts, src/template/index.ts, src/manifest/index.ts]
|
|
882
|
+
tests: none
|
|
883
|
+
rules: [HFS_MANAGED_FILE_DRIFT]
|
|
831
884
|
- id: app.sides
|
|
832
885
|
since: 3.1.0
|
|
833
886
|
profiles: [app]
|
|
@@ -2003,8 +2056,8 @@ slots:
|
|
|
2003
2056
|
profiles: [be]
|
|
2004
2057
|
editions: [lite]
|
|
2005
2058
|
editionWhy: "lite signs people in with the package @starci/auth, so its sign-in glue is rendered, not written (owner ruling auth-package); full uses its identity provider."
|
|
2006
|
-
# The identity capability's sign-in glue over @starci/auth: the entities of the session, attempt and
|
|
2007
|
-
path: "{src/modules/domain/identity/account-directory.service.spec.ts,src/modules/domain/identity/account-directory.service.ts,src/modules/domain/identity/authenticator.service.spec.ts,src/modules/domain/identity/authenticator.service.ts,src/modules/domain/identity/
|
|
2059
|
+
# The identity capability's sign-in glue over @starci/auth: the entities of the session, attempt, refresh-token and email-token tables, the account doors over auth.users and auth.identities, the stores the package asks for (sessions, accounts, rate counter), the authenticator and the service the doors call, with their specs. `starci app sync` renders them; a hand edit is drift.
|
|
2060
|
+
path: "{src/modules/domain/identity/account-directory.service.spec.ts,src/modules/domain/identity/account-directory.service.ts,src/modules/domain/identity/authenticator.service.spec.ts,src/modules/domain/identity/authenticator.service.ts,src/modules/domain/identity/identity-email.log-events.ts,src/modules/domain/identity/identity-email.service.spec.ts,src/modules/domain/identity/identity-email.service.ts,src/modules/domain/identity/identity-sign-in.log-events.ts,src/modules/domain/identity/persistence/account-doors.port.ts,src/modules/domain/identity/persistence/entities/identity-attempt.entity.ts,src/modules/domain/identity/persistence/entities/identity-email-token.entity.ts,src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts,src/modules/domain/identity/persistence/entities/identity-session.entity.ts,src/modules/domain/identity/persistence/entities/index.ts,src/modules/domain/identity/rate-counter.service.spec.ts,src/modules/domain/identity/rate-counter.service.ts,src/modules/domain/identity/session-store.service.spec.ts,src/modules/domain/identity/session-store.service.ts,src/modules/domain/identity/sign-in.service.spec.ts,src/modules/domain/identity/sign-in.service.ts,src/tests/fixtures/builders/identity.builder.ts}"
|
|
2008
2061
|
presence: optional
|
|
2009
2062
|
tracked: tracked
|
|
2010
2063
|
tier: inherit
|
|
@@ -2019,7 +2072,7 @@ slots:
|
|
|
2019
2072
|
editions: [lite]
|
|
2020
2073
|
editionWhy: "lite signs people in with the package @starci/auth, so its sign-in glue is rendered, not written (owner ruling auth-package); full uses its identity provider."
|
|
2021
2074
|
# The auth feature: the REST doors under /auth (login, refresh, session, logout, Google start and callback, jwks) over IdentitySignInService, one command or query and handler per door.
|
|
2022
|
-
path: "{src/features/api/auth/application/auth.contracts.ts,src/features/api/auth/application/get-jwks.handler.ts,src/features/api/auth/application/get-jwks.query.ts,src/features/api/auth/application/google-begin.command.ts,src/features/api/auth/application/google-begin.handler.ts,src/features/api/auth/application/google-complete.command.ts,src/features/api/auth/application/google-complete.handler.ts,src/features/api/auth/application/login.command.ts,src/features/api/auth/application/login.handler.ts,src/features/api/auth/application/logout.command.ts,src/features/api/auth/application/logout.handler.ts,src/features/api/auth/application/refresh.command.ts,src/features/api/auth/application/refresh.handler.ts,src/features/api/auth/application/session.command.ts,src/features/api/auth/application/session.handler.ts,src/features/api/auth/auth.module-definition.ts,src/features/api/auth/auth.module.ts,src/features/api/auth/auth.options.ts,src/features/api/auth/index.ts,src/features/api/auth/transport/http/auth-http.module-definition.ts,src/features/api/auth/transport/http/auth-http.module.ts,src/features/api/auth/transport/http/auth-http.options.ts,src/features/api/auth/transport/http/auth.controller.ts,src/features/api/auth/transport/http/dto/google-start.request.ts,src/features/api/auth/transport/http/dto/login.request.ts}"
|
|
2075
|
+
path: "{src/features/api/auth/application/auth.contracts.ts,src/features/api/auth/application/confirm.command.ts,src/features/api/auth/application/confirm.handler.ts,src/features/api/auth/application/forgot.command.ts,src/features/api/auth/application/forgot.handler.ts,src/features/api/auth/application/get-jwks.handler.ts,src/features/api/auth/application/get-jwks.query.ts,src/features/api/auth/application/google-begin.command.ts,src/features/api/auth/application/google-begin.handler.ts,src/features/api/auth/application/google-complete.command.ts,src/features/api/auth/application/google-complete.handler.ts,src/features/api/auth/application/login.command.ts,src/features/api/auth/application/login.handler.ts,src/features/api/auth/application/logout.command.ts,src/features/api/auth/application/logout.handler.ts,src/features/api/auth/application/refresh.command.ts,src/features/api/auth/application/refresh.handler.ts,src/features/api/auth/application/resend.command.ts,src/features/api/auth/application/resend.handler.ts,src/features/api/auth/application/reset.command.ts,src/features/api/auth/application/reset.handler.ts,src/features/api/auth/application/session.command.ts,src/features/api/auth/application/session.handler.ts,src/features/api/auth/application/signup.command.ts,src/features/api/auth/application/signup.handler.ts,src/features/api/auth/auth.module-definition.ts,src/features/api/auth/auth.module.ts,src/features/api/auth/auth.options.ts,src/features/api/auth/index.ts,src/features/api/auth/transport/http/auth-http.module-definition.ts,src/features/api/auth/transport/http/auth-http.module.ts,src/features/api/auth/transport/http/auth-http.options.ts,src/features/api/auth/transport/http/auth.controller.ts,src/features/api/auth/transport/http/dto/forgot.request.ts,src/features/api/auth/transport/http/dto/google-start.request.ts,src/features/api/auth/transport/http/dto/login.request.ts,src/features/api/auth/transport/http/dto/resend.request.ts,src/features/api/auth/transport/http/dto/reset.request.ts,src/features/api/auth/transport/http/dto/signup.request.ts,src/features/api/auth/transport/http/dto/token.request.ts}"
|
|
2023
2076
|
presence: optional
|
|
2024
2077
|
tracked: tracked
|
|
2025
2078
|
tier: inherit
|
|
@@ -2028,6 +2081,25 @@ slots:
|
|
|
2028
2081
|
managedBy: auth-lite
|
|
2029
2082
|
managedOnly: true # lists files sync renders; the slot owning the path judges them
|
|
2030
2083
|
rules: [HFS_MANAGED_FILE_DRIFT]
|
|
2084
|
+
- id: be.integrations.mail
|
|
2085
|
+
profiles: [be]
|
|
2086
|
+
editions: [lite]
|
|
2087
|
+
exemplifiedBy:
|
|
2088
|
+
- packages/hfs/templates/be/skeleton-lite/src/modules/integrations/mail/
|
|
2089
|
+
# The glue of @starci/mail, the owner of the SMTP client (nodemailer): this folder parses the settings (the server, the sender and the
|
|
2090
|
+
# link lifetimes of the confirmation and reset mails), registers the module and names the injectors; no app file imports nodemailer,
|
|
2091
|
+
# and no other module imports the package. The words and layout of each mail belong to the domain that sends it.
|
|
2092
|
+
path: "src/modules/integrations/mail/"
|
|
2093
|
+
presence: required
|
|
2094
|
+
tracked: tracked
|
|
2095
|
+
tier: integrations
|
|
2096
|
+
owner: true
|
|
2097
|
+
requires: [index.ts, mail.config.ts, mail.options.ts, mail.decorators.ts, mail.module-definition.ts, mail.module.ts]
|
|
2098
|
+
allows: [index.ts, mail.config.ts, mail.options.ts, mail.decorators.ts, mail.module-definition.ts, mail.module.ts, errors/]
|
|
2099
|
+
tests: unit-beside
|
|
2100
|
+
rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER]
|
|
2101
|
+
coverage: required
|
|
2102
|
+
since: 5.3.0
|
|
2031
2103
|
- id: be.integrations.object-storage
|
|
2032
2104
|
profiles: [be]
|
|
2033
2105
|
exemplifiedBy:
|
|
@@ -2047,6 +2119,25 @@ slots:
|
|
|
2047
2119
|
rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_STORAGE_OWNER]
|
|
2048
2120
|
coverage: required
|
|
2049
2121
|
since: 3.9.0
|
|
2122
|
+
- id: be.integrations.keycloak
|
|
2123
|
+
profiles: [be]
|
|
2124
|
+
editions: [full]
|
|
2125
|
+
# The glue of @starci/auth-oidc, the OIDC client of the full edition's identity provider (Keycloak): discovery, the provider's JWKS,
|
|
2126
|
+
# algorithm-pinned token checks and the authorization code flow with PKCE and nonce behind the PrincipalVerifier of @starci/auth.
|
|
2127
|
+
# This folder parses the typed options, hands the package the app's bounded HTTP client and clock, and names the injectors;
|
|
2128
|
+
# no app file imports jose, and no other module imports the package (ruleParams.be.infraOwners).
|
|
2129
|
+
path: "src/modules/integrations/keycloak/"
|
|
2130
|
+
presence: optional
|
|
2131
|
+
tracked: tracked
|
|
2132
|
+
tier: integrations
|
|
2133
|
+
owner: true
|
|
2134
|
+
requires: [index.ts, keycloak.config.ts, keycloak.options.ts, keycloak.decorators.ts, keycloak.registration.ts]
|
|
2135
|
+
allows: [index.ts, keycloak.config.ts, keycloak.options.ts, keycloak.decorators.ts, keycloak.registration.ts, errors/, messages/]
|
|
2136
|
+
tests: unit-beside
|
|
2137
|
+
rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_INTEGRATION_SPEC_MISSING]
|
|
2138
|
+
coverage: required
|
|
2139
|
+
since: 3.17.0
|
|
2140
|
+
|
|
2050
2141
|
|
|
2051
2142
|
# ----- BE: tests (owner test layout 2026-09-30). Unit specs are <name>.service.spec.ts beside their service and nothing else; everything else
|
|
2052
2143
|
# lives under src/tests/, one folder per kind, and the folder and the file suffix always agree (a file whose suffix does
|
|
@@ -2520,9 +2611,9 @@ slots:
|
|
|
2520
2611
|
presence: required
|
|
2521
2612
|
tracked: tracked
|
|
2522
2613
|
tier: foundation
|
|
2523
|
-
# The app's
|
|
2524
|
-
#
|
|
2525
|
-
#
|
|
2614
|
+
# The app's description of its languages (defineI18n of @starci/next-i18n), its request config and catalogs, or its adapter to the
|
|
2615
|
+
# shared i18n workspace package. A single app builds its navigation (createI18nNavigation) in fe.modules.routes, keeping this
|
|
2616
|
+
# public entry safe for its proxy. A description shared by several apps belongs to fe.package.i18n.
|
|
2526
2617
|
requires: [index.ts]
|
|
2527
2618
|
tests: none
|
|
2528
2619
|
rules: [FE_I18N_PLACEMENT, FE_I18N_CATALOG]
|
|
@@ -2592,7 +2683,7 @@ slots:
|
|
|
2592
2683
|
editions: [lite]
|
|
2593
2684
|
editionWhy: "lite signs people in with the package @starci/auth, so its auth client is rendered, not written (owner ruling auth-package); full wires its identity provider."
|
|
2594
2685
|
# The AuthClient every edition shares, implemented by one @starci/auth/client instance over the app's own back-end auth doors.
|
|
2595
|
-
path: "apps/web/src/modules/auth/client.ts"
|
|
2686
|
+
path: "apps/web/src/modules/auth/{client.ts,email-doors.ts,index.ts}"
|
|
2596
2687
|
presence: optional
|
|
2597
2688
|
tracked: tracked
|
|
2598
2689
|
tier: inherit
|
|
@@ -2674,7 +2765,7 @@ slots:
|
|
|
2674
2765
|
owner: true
|
|
2675
2766
|
requires: [package.json, src/index.ts, tsconfig.json]
|
|
2676
2767
|
tests: none
|
|
2677
|
-
why: the
|
|
2768
|
+
why: the product's languages (defineI18n of @starci/next-i18n) written once and composed into the createAppI18n factory every app calls; the next-intl stack itself is the package's
|
|
2678
2769
|
rules: [FE_I18N_PLACEMENT, FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
|
|
2679
2770
|
|
|
2680
2771
|
# Checks that read this manifest (all ship from .claude; none keeps its own path list)
|
|
@@ -3,7 +3,8 @@ import path from 'node:path';
|
|
|
3
3
|
import { slash } from '../../lib/path-key.mjs';
|
|
4
4
|
import { readJsonFile as readJson } from '../../lib/json.mjs';
|
|
5
5
|
import { isInside } from '../../lib/walk.mjs';
|
|
6
|
-
import { openHfs } from '../slots.mjs';
|
|
6
|
+
import { createSlotResolver, openHfs, readRepoDeclaration } from '../slots.mjs';
|
|
7
|
+
import { ROOT_PACKAGE_SLOTS, rootPackageRecord, rootWorkspaceDirectories } from './root-packages.mjs';
|
|
7
8
|
import { byCodeUnit } from '../../lib/list.mjs';
|
|
8
9
|
import { grammarContractFor } from '../../lib/grammar-lint.mjs';
|
|
9
10
|
/** A file's identity: its resolved real path, or the resolved path when it does not exist. */
|
|
@@ -182,6 +183,28 @@ function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side =
|
|
|
182
183
|
}
|
|
183
184
|
return [...directories].sort(byCodeUnit);
|
|
184
185
|
}
|
|
186
|
+
/**
|
|
187
|
+
* The workspace packages of the app root that no side owns: the `workspaces` patterns of the app's one package.json that do not start
|
|
188
|
+
* with a side folder (`packages/*`), and the directories the slots `app.packages` and `app.module-registry` place under `packages/`
|
|
189
|
+
* even when the manifest forgot to list them. A side imports them as first-party packages (through their entry points), never as
|
|
190
|
+
* "outside the side". A side of the app is judged here; the app root itself already counts them among its workspaces.
|
|
191
|
+
*/
|
|
192
|
+
function rootPackageRecords(root, packageRoot, side, opened) {
|
|
193
|
+
if (side === null)
|
|
194
|
+
return [];
|
|
195
|
+
const candidates = new Set(rootWorkspaceDirectories(packageRoot));
|
|
196
|
+
if (opened.manifest && existingDirectory(packageRoot, 'packages')) {
|
|
197
|
+
const resolver = createSlotResolver(opened.manifest, readRepoDeclaration(opened.manifest, packageRoot));
|
|
198
|
+
const container = path.join(packageRoot, 'packages');
|
|
199
|
+
for (const entry of fs.readdirSync(container, { withFileTypes: true }).filter(item => item.isDirectory())) {
|
|
200
|
+
const slot = resolver.classifyPath(`packages/${entry.name}`).slot;
|
|
201
|
+
if (slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot))
|
|
202
|
+
candidates.add(path.join(container, entry.name));
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
return [...candidates].sort(byCodeUnit).filter(candidate => !isInside(root, candidate))
|
|
206
|
+
.flatMap(candidate => rootPackageRecord(packageRoot, candidate, canonical) ?? []);
|
|
207
|
+
}
|
|
185
208
|
function discoveredProjects(root, workspaces) {
|
|
186
209
|
const projects = [];
|
|
187
210
|
if (fs.existsSync(path.join(root, 'tsconfig.json')))
|
|
@@ -373,6 +396,7 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
|
|
|
373
396
|
kinds,
|
|
374
397
|
projects,
|
|
375
398
|
workspaces,
|
|
399
|
+
rootPackages: rootPackageRecords(root, packageRoot, side, opened),
|
|
376
400
|
apps: apps.map(app => ({ name: app.name, kind: app.kind })),
|
|
377
401
|
hfs: opened,
|
|
378
402
|
owners: derivedOwners(root, opened),
|
|
@@ -11,7 +11,7 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
|
|
|
11
11
|
*
|
|
12
12
|
* - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts` that is
|
|
13
13
|
* not the sibling of the application module or of the transport module of its own folder, and an `@Module` class (or a
|
|
14
|
-
* `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a feature file that is neither the application module, the
|
|
14
|
+
* `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use or a `defineConfigurableModule`/`defineCapabilityModule` call of `@starci/nest-kit`) in a feature file that is neither the application module, the
|
|
15
15
|
* transport module of its own folder nor that module's definition are refused;
|
|
16
16
|
* - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
|
|
17
17
|
* in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts
|
|
@@ -99,6 +99,8 @@ function reportModuleClassLocation(file, name, place, composedModuleOf, report)
|
|
|
99
99
|
if (file.rel !== own)
|
|
100
100
|
report(file, name, `${name.text} is a Nest module declared in ${file.rel}; a feature declares exactly its application module (${place.feature}.module.ts) and one module per transport folder (${place.feature}-<protocol>.module.ts), never a module per operation.`, { feature: place.feature });
|
|
101
101
|
}
|
|
102
|
+
/** The module-definition helpers of @starci/nest-kit: each builds the definition of one module, like `ConfigurableModuleBuilder`. */
|
|
103
|
+
const DEFINITION_HELPERS = ['defineConfigurableModule', 'defineCapabilityModule'];
|
|
102
104
|
function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
|
|
103
105
|
const own = ownModuleOf(place, file.rel, env.composedModuleOf);
|
|
104
106
|
const isDefinition = file.rel === definitionOf(own);
|
|
@@ -106,6 +108,9 @@ function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
|
|
|
106
108
|
if (ts.isNewExpression(node) && kit.isImportOf(checker, node.expression, 'ConfigurableModuleBuilder', '@nestjs/common') && !isDefinition) {
|
|
107
109
|
env.report(file, node, `ConfigurableModuleBuilder builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
|
|
108
110
|
}
|
|
111
|
+
else if (ts.isCallExpression(node) && !isDefinition && DEFINITION_HELPERS.some(name => kit.isImportOf(checker, node.expression, name, '@starci/nest-kit'))) {
|
|
112
|
+
env.report(file, node, `${node.expression.getText(file.sourceFile)} builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
|
|
113
|
+
}
|
|
109
114
|
else if (ts.isHeritageClause(node) && file.rel !== own) {
|
|
110
115
|
for (const type of node.types)
|
|
111
116
|
if (kit.isImportOf(checker, type.expression, 'ConfigurableModuleClass', '@nestjs/common')) {
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// root-packages.mjs - the workspace packages of an app ROOT (packages/agent-sdk, packages/module-<name>, the managed packages/modules).
|
|
2
|
+
// They lie outside both side folders and belong to no side; both sides import them by package name, through their package entry points
|
|
3
|
+
// (the `exports` of the manifest), so the import graph reads them as first-party packages and the back-end canon never reads them as
|
|
4
|
+
// a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder
|
|
5
|
+
// (`fe/apps/*`) are that side's own workspaces and are not read here.
|
|
6
|
+
import fs from 'node:fs';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import { readJsonFile as readJson } from '../../lib/json.mjs';
|
|
9
|
+
import { byCodeUnit } from '../../lib/list.mjs';
|
|
10
|
+
import { isInside } from '../../lib/walk.mjs';
|
|
11
|
+
import { slash } from '../../lib/path-key.mjs';
|
|
12
|
+
/** The slots whose directories at the app root are first-party packages of the app (agent SDK, module packages, the managed registry). */
|
|
13
|
+
export const ROOT_PACKAGE_SLOTS = new Set(['app.packages', 'app.module-registry']);
|
|
14
|
+
const SIDE_PREFIX = /^(?:be|fe)\//;
|
|
15
|
+
/** A workspace pattern this reader expands (a literal path, or `*` as a whole segment); the others are judged by the workspace rules. */
|
|
16
|
+
const expandablePattern = (written) => !path.isAbsolute(written) && written.split('/').every(segment => segment !== '..' && (!segment.includes('*') || segment === '*'));
|
|
17
|
+
function expandSegment(base, segment) {
|
|
18
|
+
if (segment !== '*')
|
|
19
|
+
return [path.join(base, segment)];
|
|
20
|
+
if (!fs.existsSync(base) || !fs.lstatSync(base).isDirectory())
|
|
21
|
+
return [];
|
|
22
|
+
return fs.readdirSync(base, { withFileTypes: true }).filter(item => item.isDirectory()).sort((a, b) => byCodeUnit(a.name, b.name)).map(item => path.join(base, item.name));
|
|
23
|
+
}
|
|
24
|
+
/** A package folder with a regular package.json (a link is not one). */
|
|
25
|
+
export function packageDirectory(absolute) {
|
|
26
|
+
try {
|
|
27
|
+
if (!fs.lstatSync(absolute).isDirectory())
|
|
28
|
+
return false;
|
|
29
|
+
const manifest = fs.lstatSync(path.join(absolute, 'package.json'));
|
|
30
|
+
return manifest.isFile() && !manifest.isSymbolicLink();
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
/** The folders the `workspaces` of the app root's package.json name that no side owns, as absolute paths in code-unit order. */
|
|
37
|
+
export function rootWorkspaceDirectories(packageRoot) {
|
|
38
|
+
const manifest = readJson(path.join(packageRoot, 'package.json'));
|
|
39
|
+
const declared = manifest?.workspaces;
|
|
40
|
+
const patterns = Array.isArray(declared) ? declared : declared?.packages;
|
|
41
|
+
const found = new Set();
|
|
42
|
+
for (const pattern of Array.isArray(patterns) ? patterns : []) {
|
|
43
|
+
if (typeof pattern !== 'string' || !pattern.trim())
|
|
44
|
+
continue;
|
|
45
|
+
const written = slash(pattern.trim()).replace(/^\.\//, '');
|
|
46
|
+
if (SIDE_PREFIX.test(written) || !expandablePattern(written))
|
|
47
|
+
continue;
|
|
48
|
+
let bases = [packageRoot];
|
|
49
|
+
for (const segment of written.split('/'))
|
|
50
|
+
bases = bases.flatMap(base => expandSegment(base, segment));
|
|
51
|
+
for (const base of bases)
|
|
52
|
+
found.add(path.resolve(base));
|
|
53
|
+
}
|
|
54
|
+
return [...found].sort(byCodeUnit);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The record of one package folder of the app root, or null when it is no named package inside the app root.
|
|
58
|
+
* `canonical` is the file-identity function of the caller (the real path), so a record agrees with the files the graph reads.
|
|
59
|
+
*/
|
|
60
|
+
export function rootPackageRecord(packageRoot, directory, canonical) {
|
|
61
|
+
if (!packageDirectory(directory) || !isInside(packageRoot, directory))
|
|
62
|
+
return null;
|
|
63
|
+
const manifest = readJson(path.join(directory, 'package.json'));
|
|
64
|
+
const name = manifest?.['name'];
|
|
65
|
+
if (manifest === null || typeof name !== 'string' || !name)
|
|
66
|
+
return null;
|
|
67
|
+
return { root: canonical(directory), relative: slash(path.relative(packageRoot, directory)), name, exports: manifest['exports'], manifest, workspace: true, app: false };
|
|
68
|
+
}
|
|
69
|
+
/** The names of the workspace packages of the app root: what the back-end canon must not read as third-party libraries. */
|
|
70
|
+
export function rootPackageNames(packageRoot) {
|
|
71
|
+
const names = new Set();
|
|
72
|
+
for (const directory of rootWorkspaceDirectories(packageRoot)) {
|
|
73
|
+
const record = rootPackageRecord(packageRoot, directory, (file) => file);
|
|
74
|
+
if (record !== null)
|
|
75
|
+
names.add(record.name);
|
|
76
|
+
}
|
|
77
|
+
return names;
|
|
78
|
+
}
|
|
@@ -241,8 +241,38 @@ function appendEdge(from, sourceFile, project, owningWorkspace, reference, actua
|
|
|
241
241
|
errors.push(helpers.boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_EXPORT_BYPASS', 'Cross-package imports must use the target package name and a declared package export.'));
|
|
242
242
|
}
|
|
243
243
|
}
|
|
244
|
+
/**
|
|
245
|
+
* An import of one of the app's root workspace packages (`@scope/agent-sdk`, `@scope/agent-sdk/workbench`). The package lies outside the side
|
|
246
|
+
* folder, yet it is first-party source both sides may import: through its package entry points (the `exports` of its manifest) and never past
|
|
247
|
+
* them. An entry point is no import that leaves the side and adds no edge (the package is not part of this side's graph; the package's own
|
|
248
|
+
* lint judges its files); a path into the package's source is refused. Returns true when the reference was settled here.
|
|
249
|
+
*/
|
|
250
|
+
function rootPackageReference(sourceFile, project, reference, state) {
|
|
251
|
+
const { config, errors, helpers, host, ts } = state;
|
|
252
|
+
if (!config.rootPackages?.length)
|
|
253
|
+
return false;
|
|
254
|
+
const item = helpers.rootPackageOf(config, reference.specifier);
|
|
255
|
+
if (item === null)
|
|
256
|
+
return false;
|
|
257
|
+
if (!helpers.rootPackageEntryDeclared(item, reference.specifier)) {
|
|
258
|
+
errors.push({
|
|
259
|
+
ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
|
|
260
|
+
project: project.relative,
|
|
261
|
+
path: helpers.relativePath(config.root, sourceFile.fileName),
|
|
262
|
+
...helpers.sourceLocation(sourceFile, reference.node),
|
|
263
|
+
specifier: reference.specifier,
|
|
264
|
+
message: `Internal import ${reference.specifier} reaches into the package ${item.name} past its package entry points; import ${helpers.rootPackageEntries(item).join(', ')} instead.`,
|
|
265
|
+
});
|
|
266
|
+
return true;
|
|
267
|
+
}
|
|
268
|
+
// An entry point that a path alias sends outside the package is no entry point: the ordinary boundary judges it.
|
|
269
|
+
const resolved = helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));
|
|
270
|
+
return resolved === undefined || helpers.isInside(item.root, helpers.canonical(resolved));
|
|
271
|
+
}
|
|
244
272
|
function processReference(from, sourceFile, project, owningWorkspace, reference, state) {
|
|
245
273
|
const { config, ts, workspaceNames, workspaces, host, errors, helpers } = state;
|
|
274
|
+
if (rootPackageReference(sourceFile, project, reference, state))
|
|
275
|
+
return;
|
|
246
276
|
// A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
|
|
247
277
|
const workspaceTarget = workspaces.filter(item => item.root !== helpers.canonical(config.root)).map(item => helpers.workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
|
|
248
278
|
const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));
|
|
@@ -385,6 +385,26 @@ function packageExported(ts, workspace, specifier, actualTarget) {
|
|
|
385
385
|
return expected === canonical(actualTarget) || sourceOfTarget(ts, workspace, target) === canonical(actualTarget);
|
|
386
386
|
});
|
|
387
387
|
}
|
|
388
|
+
/** The root workspace package of the app (`packages/agent-sdk`) a specifier names, its name or a subpath of it; the longest name when several match. */
|
|
389
|
+
export function rootPackageOf(config, specifier) {
|
|
390
|
+
let found = null;
|
|
391
|
+
for (const item of config.rootPackages ?? [])
|
|
392
|
+
if (sameOrUnder(specifier, item.name) && (found === null || item.name.length > found.name.length))
|
|
393
|
+
found = item;
|
|
394
|
+
return found;
|
|
395
|
+
}
|
|
396
|
+
/** Whether a specifier into a root package names one of its entry points: a subpath its `exports` declare, or its root through `exports`, `main`/`types` or `src/index`. A path into its source is not an entry point. */
|
|
397
|
+
export function rootPackageEntryDeclared(item, specifier) {
|
|
398
|
+
if (exportCandidates(item, specifier).length > 0)
|
|
399
|
+
return true;
|
|
400
|
+
return specifier === item.name && !item.exports && (manifestEntryTargets(item.manifest).length > 0 || packageIndexSource(item) !== null);
|
|
401
|
+
}
|
|
402
|
+
/** The subpaths a root package declares for import (`.` first), for the message of a refused deep import. */
|
|
403
|
+
export function rootPackageEntries(item) {
|
|
404
|
+
const declaration = item.exports;
|
|
405
|
+
const keys = declaration && typeof declaration === 'object' && !Array.isArray(declaration) ? Object.keys(declaration).filter(key => key.startsWith('.')) : ['.'];
|
|
406
|
+
return (keys.length ? keys : ['.']).map(key => (key === '.' ? item.name : `${item.name}${key.slice(1)}`));
|
|
407
|
+
}
|
|
388
408
|
function boundaryViolation(root, edge, fromWorkspace, toWorkspace, ruleId, message) {
|
|
389
409
|
return {
|
|
390
410
|
ruleId,
|
|
@@ -413,7 +433,7 @@ function typeScriptContext(config, loaded, paths) {
|
|
|
413
433
|
canonical, compilerError, isInside, slash, readTypeScriptProject, typeScriptProjectReferencePath,
|
|
414
434
|
sameOrUnder, createTypeScriptProgram, isProductionSource, sourceLocation, workspaceMetadata, workspaceOf,
|
|
415
435
|
pathAliasMatches, moduleReferences, workspaceSourceEntry, resolveTypeScriptModule, crossesSide, assetExtension: ASSET_EXTENSION,
|
|
416
|
-
relativePath, packageExported, boundaryViolation,
|
|
436
|
+
relativePath, packageExported, boundaryViolation, rootPackageOf, rootPackageEntryDeclared, rootPackageEntries,
|
|
417
437
|
});
|
|
418
438
|
}
|
|
419
439
|
export function relativePath(root, fileName) {
|
|
@@ -6,7 +6,7 @@ const HINTS = {
|
|
|
6
6
|
'parameter type': 'Give the parameter a type: `(value: Input)`.',
|
|
7
7
|
'property type': 'Give the property a type: `name: Result = ...`.',
|
|
8
8
|
'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
|
|
9
|
-
'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name
|
|
9
|
+
'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`; a module definition is `export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<XOptions>()` (or `defineConfigurableModule`) of @starci/nest-kit, which states the types (`starci app codemod module-definition` writes it).',
|
|
10
10
|
'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
|
|
11
11
|
};
|
|
12
12
|
/** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
import path from 'node:path';
|
|
6
6
|
import { allowsFile } from './allows.mjs';
|
|
7
7
|
import { openHfs } from './slots.mjs';
|
|
8
|
+
import { ROOT_PACKAGE_SLOTS } from './architecture/root-packages.mjs';
|
|
8
9
|
const posix = (p) => String(p).replaceAll('\\', '/');
|
|
9
10
|
const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
|
|
10
11
|
/**
|
|
@@ -69,3 +70,70 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
|
|
|
69
70
|
* @returns {object} The frozen view.
|
|
70
71
|
*/
|
|
71
72
|
export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
|
|
73
|
+
/**
|
|
74
|
+
* The view of the root workspace packages of an app (`packages/<pkg>/src/**`, slots app.packages and app.module-registry), as the lint of one
|
|
75
|
+
* side sees them: the rule parameters, the apps and the Grammar of `side` (a package is judged by the laws of the side whose subpath a file
|
|
76
|
+
* sits in), and the paths of the APP ROOT (`repoRoot` is the app root, not a side folder). The slots answer for the root paths; a file of a
|
|
77
|
+
* package is of the tier `package` and has no owner: the owner laws (one `index.ts` per owner root) are the module folders', a package's public
|
|
78
|
+
* surface being the `exports` of its manifest.
|
|
79
|
+
*
|
|
80
|
+
* @param {object} opened - The result of `openHfs` for the app root (profile app, both sides resolved).
|
|
81
|
+
* @param {string} repoRoot - The absolute app root.
|
|
82
|
+
* @param {string} side - `be` or `fe`: the side whose laws the file is judged by.
|
|
83
|
+
* @returns {object} The frozen view: the profile of the side over the paths of the app root.
|
|
84
|
+
*/
|
|
85
|
+
function packagesView(opened, repoRoot, side) {
|
|
86
|
+
const scope = opened.sides?.[side];
|
|
87
|
+
const sideRepo = opened.repo.sides?.[side];
|
|
88
|
+
if (scope === undefined || sideRepo === undefined)
|
|
89
|
+
throw new Error('the view of the root packages needs the declaration of an app with both sides');
|
|
90
|
+
const rel = (file) => {
|
|
91
|
+
const text = posix(file);
|
|
92
|
+
return isAbsoluteAny(text) ? posix(path.relative(repoRoot, file)) : text.replace(/^\.\//, '');
|
|
93
|
+
};
|
|
94
|
+
const cache = new Map();
|
|
95
|
+
const classify = (file) => {
|
|
96
|
+
const key = rel(file);
|
|
97
|
+
if (!cache.has(key))
|
|
98
|
+
cache.set(key, opened.classifyPath(key));
|
|
99
|
+
return cache.get(key);
|
|
100
|
+
};
|
|
101
|
+
const packageOf = (file) => {
|
|
102
|
+
const slot = classify(file).slot;
|
|
103
|
+
const relative = rel(file);
|
|
104
|
+
return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
|
|
105
|
+
};
|
|
106
|
+
return Object.freeze({
|
|
107
|
+
repoRoot,
|
|
108
|
+
profile: side,
|
|
109
|
+
side,
|
|
110
|
+
edition: opened.repo.edition ?? 'full',
|
|
111
|
+
...(sideRepo.grammar === undefined ? {} : { grammar: sideRepo.grammar }),
|
|
112
|
+
apps: sideRepo.apps,
|
|
113
|
+
connections: sideRepo.connections,
|
|
114
|
+
patterns: Object.freeze([...(sideRepo.patterns ?? [])]),
|
|
115
|
+
ruleParams: scope.ruleParams(),
|
|
116
|
+
relative: rel,
|
|
117
|
+
classify,
|
|
118
|
+
slotOf: (file) => classify(file).slot ?? null,
|
|
119
|
+
tierOf: (file) => (packageOf(file) === null ? null : 'package'),
|
|
120
|
+
// A package is no owner of the module laws (one index.ts at the owner root): its public surface is the `exports` of its manifest, so no file of it has an owner.
|
|
121
|
+
ownerOf: () => null,
|
|
122
|
+
allows: (file) => allowsFile(opened, rel(file)),
|
|
123
|
+
slot: (id) => opened.slot(id),
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* The view of the root packages of the app at `repoRoot` (the app root, where the root `eslint.config.mjs` lives), for the laws of `side`.
|
|
128
|
+
*
|
|
129
|
+
* @param {{ runtimeRoot: string, repoRoot: string, side: string }} input - Where the manifest copy lives, the app root, and the side whose laws apply.
|
|
130
|
+
* @returns {object} The frozen view.
|
|
131
|
+
*/
|
|
132
|
+
export const openPackagesHfsView = ({ runtimeRoot, repoRoot, side }) => packagesView(openHfs({ root: runtimeRoot, repoRoot }), repoRoot, side);
|
|
133
|
+
/**
|
|
134
|
+
* The view of the root packages of an in-memory app declaration (rule tests): no file is read except the manifest.
|
|
135
|
+
*
|
|
136
|
+
* @param {{ runtimeRoot: string, declaration: object, repoRoot: string, side: string }} input - Manifest root, the app hfs.json object, the app root and the side.
|
|
137
|
+
* @returns {object} The frozen view.
|
|
138
|
+
*/
|
|
139
|
+
export const declaredPackagesHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => packagesView(openHfs({ root: runtimeRoot, declaration }), repoRoot, side);
|
|
@@ -55,6 +55,52 @@ function returnsOnlyJsx(ts, source, start) {
|
|
|
55
55
|
ts.forEachChild(fn.body, visit);
|
|
56
56
|
return only;
|
|
57
57
|
}
|
|
58
|
+
/** The package whose module-definition helpers return a type they state in their own declaration (R368 accepts a destructured export of their call). */
|
|
59
|
+
export const STATED_SURFACE_PACKAGE = '@starci/nest-kit';
|
|
60
|
+
/** The helpers of that package: each is called with the options type as a type argument and returns the explicitly typed definition. */
|
|
61
|
+
export const STATED_SURFACE_HELPERS = new Set(['defineConfigurableModule', 'defineCapabilityModule']);
|
|
62
|
+
/** The local names under which `source` imports a stated-surface helper from its package (`import { defineConfigurableModule as define }` gives `define`). */
|
|
63
|
+
function statedHelperNames(ts, source) {
|
|
64
|
+
const names = new Set();
|
|
65
|
+
for (const statement of source.statements) {
|
|
66
|
+
if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== STATED_SURFACE_PACKAGE)
|
|
67
|
+
continue;
|
|
68
|
+
const bindings = statement.importClause?.namedBindings;
|
|
69
|
+
if (bindings === undefined || !ts.isNamedImports(bindings))
|
|
70
|
+
continue;
|
|
71
|
+
for (const element of bindings.elements)
|
|
72
|
+
if (STATED_SURFACE_HELPERS.has((element.propertyName ?? element.name).text))
|
|
73
|
+
names.add(element.name.text);
|
|
74
|
+
}
|
|
75
|
+
return names;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Whether the destructured export the diagnostic at `start` points at is `export const { A, B } = helper<Options>()` for a stated-surface helper:
|
|
79
|
+
* each name has the type the helper's declaration gives it, written there, so the file states its surface by naming the helper and the options
|
|
80
|
+
* type, exactly as `export const A: Host["A"] = built.A` states it through `Host`.
|
|
81
|
+
*/
|
|
82
|
+
function statesSurfaceThroughHelper(ts, source, start) {
|
|
83
|
+
const helpers = statedHelperNames(ts, source);
|
|
84
|
+
if (helpers.size === 0)
|
|
85
|
+
return null;
|
|
86
|
+
let innermost = source;
|
|
87
|
+
const descend = (node) => {
|
|
88
|
+
if (start < node.getFullStart() || start >= node.end)
|
|
89
|
+
return;
|
|
90
|
+
innermost = node;
|
|
91
|
+
ts.forEachChild(node, descend);
|
|
92
|
+
};
|
|
93
|
+
ts.forEachChild(source, descend);
|
|
94
|
+
for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
|
|
95
|
+
if (!ts.isVariableDeclaration(node))
|
|
96
|
+
continue;
|
|
97
|
+
const call = node.initializer;
|
|
98
|
+
const stated = ts.isObjectBindingPattern(node.name) && call !== undefined && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && helpers.has(call.expression.text)
|
|
99
|
+
&& (call.typeArguments?.length ?? 0) > 0 && node.name.elements.every((element) => ts.isIdentifier(element.name) && element.dotDotDotToken === undefined);
|
|
100
|
+
return stated && call !== undefined ? call.getText(source) : null;
|
|
101
|
+
}
|
|
102
|
+
return null;
|
|
103
|
+
}
|
|
58
104
|
/** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
|
|
59
105
|
const ANNOTATE = new Map([
|
|
60
106
|
[9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
|
|
@@ -98,7 +144,14 @@ export function declarationSurface(ts, file, text, module) {
|
|
|
98
144
|
return { outputText: declared.outputText, problems: [] };
|
|
99
145
|
const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
|
|
100
146
|
const problems = [];
|
|
147
|
+
// The emit writes `any` for a destructured export; the call that states its type joins the digest, so a change of the options type reaches the importers.
|
|
148
|
+
const stated = new Set();
|
|
101
149
|
for (const diagnostic of diagnostics) {
|
|
150
|
+
const call = diagnostic.code === 9019 && diagnostic.start !== undefined ? statesSurfaceThroughHelper(ts, source, diagnostic.start) : null;
|
|
151
|
+
if (call !== null) {
|
|
152
|
+
stated.add(call);
|
|
153
|
+
continue;
|
|
154
|
+
}
|
|
102
155
|
const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
|
|
103
156
|
if (exempt)
|
|
104
157
|
continue;
|
|
@@ -108,5 +161,6 @@ export function declarationSurface(ts, file, text, module) {
|
|
|
108
161
|
reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
|
|
109
162
|
});
|
|
110
163
|
}
|
|
111
|
-
|
|
164
|
+
const outputText = stated.size === 0 ? declared.outputText : `${declared.outputText}${[...stated].sort().map((call) => `// stated by ${call}\n`).join('')}`;
|
|
165
|
+
return { outputText, problems };
|
|
112
166
|
}
|