@starci/eslint-canon-be 3.14.1 → 3.15.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 +10 -0
- package/README.md +1 -1
- package/dist/error-handling.js +14 -8
- package/dist/lib/declared.d.ts +8 -3
- package/dist/lib/declared.js +10 -3
- package/dist/lib/hfs-view.d.ts +12 -0
- package/dist/lib/hfs.d.ts +1 -1
- package/dist/third-party-owner.js +1 -1
- package/package.json +1 -1
- package/runtime/knowledge/hfs/canon-pins.yaml +12 -12
- package/runtime/knowledge/hfs/rules.yaml +15 -2
- package/runtime/knowledge/hfs/slots.yaml +3 -3
- package/runtime/scripts/hfs/architecture/root-packages.mjs +1 -1
- package/runtime/scripts/hfs/declaration-shape.mjs +3 -1
- package/runtime/scripts/hfs/slots.mjs +1 -0
- package/runtime/scripts/hfs/view.mjs +41 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.15.1 - 2026-11-04
|
|
4
|
+
|
|
5
|
+
- Changed: the runtime copy of the laws carries the R187 wording of `@starci/hfs` 5.5.1, and the canon pins name the release-3 versions.
|
|
6
|
+
|
|
7
|
+
## 3.15.0 - 2026-11-03
|
|
8
|
+
|
|
9
|
+
- Changed: `throw-domain-error` and `error-home` judge a root workspace package by the error base its `package.json` declares (`starci.errorBase: { name, file }`), the way they judge an app by `DomainError` of `platform/errors`; a raw `Error` and an undeclared `Error` subclass stay refused, and a malformed declaration stops the lint. Specs: `src/packages-config.spec.ts`.
|
|
10
|
+
- Changed: the runtime copies carry the root-packages view (`readPackageContract`, the `modules` declaration), the R187 build-context law, the seed rules (R375, R332) and the canon pins of this release.
|
|
11
|
+
- Changed: the package's slot manifest places any root workspace package `packages/<name>/` in `app.packages` (a block library such as `packages/blocks-core` beside the agent SDK and the module packages), so the root packages config lints it.
|
|
12
|
+
|
|
3
13
|
## 3.14.1 - 2026-11-03
|
|
4
14
|
|
|
5
15
|
- 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.
|
package/README.md
CHANGED
|
@@ -37,7 +37,7 @@ A sample, not the list:
|
|
|
37
37
|
|
|
38
38
|
| Area | What the rules hold |
|
|
39
39
|
|---|---|
|
|
40
|
-
| **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
|
|
40
|
+
| **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain; a root workspace package throws the error base its `package.json` declares (`starci.errorBase`) (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
|
|
41
41
|
| **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration, no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
|
|
42
42
|
| **Config and secrets** | `process.env` (any form) is allowed in the `platform/config` file declaring `EnvSource`, the test world (slot `be.tests.world`) and the app bootstrap roles `apps/<app>/src/main.ts` and its matching `<app>.env.ts`; only those two app roles may read `EnvSource` or capability parse helpers. Compose groups and `<app>.options.ts` never read `process.env` or `EnvSource`. `@nestjs/config` and `dotenv` are forbidden config paths. A function exported by a `<capability>.config.ts` keeps its existing name and is called only from these bootstrap roles, its own config file or spec, the test world and a provider contract spec (`config-parsed-in-main`). Secrets use `EnvSource.secret()`: `<NAME>_FILE` takes priority for `.starcistacks` custody, and plain `<NAME>` is read only when the file key is absent; a declared file supplies exact contents and an empty or unreadable path fails startup without fallback. No default of any kind for a value typed `Secret` or `Url`; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `config-parsed-in-main`, `no-secret-default`, `secret-compare-timing-safe`) |
|
|
43
43
|
| **Model calls** (R326, R327, R344) | Every model call goes through the `@starci/ai-router` gateway: an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, with its `_FILE` twin) is named only in the gateway's custody owner `integrations/ai-gateway`, specs and the test world included; code builds only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai`, each from an inline options object whose `configuration.baseURL` is read from a `<c>.options.ts` type and whose `apiKey` is a `platform/config` `Secret` revealed; `integrations/ai` reads exactly `STARCI_AI_KEY`, the one virtual key of every client, and the custody owner passes the gateway no `adminToken`. Which owner may import LangChain, `openai`, a provider SDK or an agent framework is the infrastructure table (`provider-key-custody`, `ai-client-through-gateway`, `ai-virtual-key-name`, `infra-import-owner`) |
|
package/dist/error-handling.js
CHANGED
|
@@ -16,12 +16,16 @@
|
|
|
16
16
|
* (`AbstractException`, a framework `HttpException` subclass, a bare `extends Error`) is refused.
|
|
17
17
|
* - `throw-domain-error` refuses a `throw` whose type does not derive from `DomainError` (`throw new Error`, the Nest
|
|
18
18
|
* `HttpException` family, a thrown string or object), and a domain owner that throws a platform error outward.
|
|
19
|
+
*
|
|
20
|
+
* The error base of a file is `DomainError` of `platform/errors`; a root workspace package, which cannot import an app owner, declares
|
|
21
|
+
* its own base in its manifest (`starci.errorBase`: `{ name, file }`), and both rules read that class, in that file, as its `DomainError`:
|
|
22
|
+
* the base itself is its host and a package has no owner layout to place its subclasses in.
|
|
19
23
|
* - `error-family-shape` holds the one shape of `errors/<c>.error.ts`: a `<C>ErrorCode` string enum, a
|
|
20
24
|
* `<C>_ERROR_KINDS: Record<<C>ErrorCode, ErrorKind>` table, and an empty `<C>Error extends DomainError<<C>ErrorCode>`.
|
|
21
25
|
* Code uniqueness across the repository is the architecture machine's job, not a single file's.
|
|
22
26
|
*/
|
|
23
27
|
import { nameOrValue, some, walk } from "./lib/ast.js";
|
|
24
|
-
import { derives, derivesFromBuiltinError,
|
|
28
|
+
import { derives, derivesFromBuiltinError, derivesFromErrorBase, errorHomeOf, isOwnedBy, isOwnedType, ownerName, packageErrorBaseOf, partsOf, typeOf, } from "./lib/declared.js";
|
|
25
29
|
import { hfsOf } from "./lib/hfs.js";
|
|
26
30
|
import { normalizePath } from "./lib/path.js";
|
|
27
31
|
import { typed } from "./lib/types.js";
|
|
@@ -241,7 +245,7 @@ export const errorHome = {
|
|
|
241
245
|
schema: [],
|
|
242
246
|
messages: {
|
|
243
247
|
place: "`{{name}}` derives from `DomainError` but is not declared in `errors/{{owner}}.error.ts` of its owner. An owner has one error class, in that file; move it there.",
|
|
244
|
-
mustExtendDomainError: "`{{name}}` derives from the built-in `Error` without deriving from `DomainError` (`AbstractException`, a framework exception or a bare `extends Error`). Extend `DomainError` from `platform/errors` in the owner's `errors/<capability>.error.ts
|
|
248
|
+
mustExtendDomainError: "`{{name}}` derives from the built-in `Error` without deriving from `DomainError` (`AbstractException`, a framework exception or a bare `extends Error`). Extend `DomainError` from `platform/errors` in the owner's `errors/<capability>.error.ts`; in a root workspace package, extend the error base its `package.json` declares (`starci.errorBase`).",
|
|
245
249
|
},
|
|
246
250
|
},
|
|
247
251
|
create(context) {
|
|
@@ -253,11 +257,13 @@ export const errorHome = {
|
|
|
253
257
|
const type = typeOf(context, node.id);
|
|
254
258
|
if (!type)
|
|
255
259
|
return;
|
|
256
|
-
const
|
|
257
|
-
|
|
260
|
+
const packageBase = packageErrorBaseOf(hfs, filename);
|
|
261
|
+
const isErrorBaseHost = (node.id.name === "DomainError" && isOwnedBy(hfs, filename, "platform", "errors")) ||
|
|
262
|
+
(packageBase !== null && node.id.name === packageBase.name && hfs.relative(filename) === packageBase.file);
|
|
263
|
+
if (isErrorBaseHost)
|
|
258
264
|
return;
|
|
259
|
-
if (
|
|
260
|
-
if (isWorldErrorHome(hfs, filename))
|
|
265
|
+
if (derivesFromErrorBase(context, type)) {
|
|
266
|
+
if (packageBase !== null || isWorldErrorHome(hfs, filename))
|
|
261
267
|
return;
|
|
262
268
|
// A spec-local subclass of the abstract base is a test double for code that takes any DomainError, not an error family.
|
|
263
269
|
if (isSpecLocalClass(filename, node))
|
|
@@ -308,7 +314,7 @@ export const throwDomainError = {
|
|
|
308
314
|
messages: {
|
|
309
315
|
bareError: "`throw new Error(...)` carries a sentence and no code, so nothing downstream can group or map it. Throw the `<C>Error` of the owning capability with one of its codes.",
|
|
310
316
|
framework: "`throw new {{name}}(...)` carries an HTTP status and no identity. Throw the `<C>Error` of the owning capability; the one filter of `platform/errors` maps its code to a status.",
|
|
311
|
-
notDomainError: "This `throw` does not throw a `DomainError`. Throw the `<C>Error` of the owning capability with one of its codes, or return an `Outcome` and let the transport unwrap it.",
|
|
317
|
+
notDomainError: "This `throw` does not throw a `DomainError`. Throw the `<C>Error` of the owning capability with one of its codes, or return an `Outcome` and let the transport unwrap it; a root workspace package throws the error base its `package.json` declares (`starci.errorBase`).",
|
|
312
318
|
platformThrown: "A domain owner throws `{{name}}`, an error of a platform owner. Translate it into the error of this capability so platform details do not cross the boundary.",
|
|
313
319
|
},
|
|
314
320
|
},
|
|
@@ -326,7 +332,7 @@ export const throwDomainError = {
|
|
|
326
332
|
return;
|
|
327
333
|
const type = typeOf(context, thrown);
|
|
328
334
|
const parts = partsOf(type);
|
|
329
|
-
const foreign = parts.find((part) => !
|
|
335
|
+
const foreign = parts.find((part) => !derivesFromErrorBase(context, part));
|
|
330
336
|
if (parts.length === 0 || foreign) {
|
|
331
337
|
if (foreign && isHttpException(foreign)) {
|
|
332
338
|
context.report({ node: thrown, messageId: "framework", data: { name: foreign.getSymbol()?.name ?? "HttpException" } });
|
package/dist/lib/declared.d.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
import ts from "typescript";
|
|
7
7
|
import type { TSESTree } from "@typescript-eslint/utils";
|
|
8
8
|
import type { Context, Node } from "./rule.js";
|
|
9
|
-
import type { HfsView } from "./hfs.js";
|
|
9
|
+
import type { HfsPackageDeclaredType, HfsView } from "./hfs.js";
|
|
10
10
|
import type { TypeOrigin } from "./types.js";
|
|
11
11
|
/** The last segment of an owner root (`src/modules/platform/errors` gives `errors`), or null when there is no owner. */
|
|
12
12
|
export declare const ownerName: (root: string | null | undefined) => string | null | undefined;
|
|
@@ -60,8 +60,13 @@ export declare const presentParts: (type: ts.Type | null | undefined) => ts.Type
|
|
|
60
60
|
*/
|
|
61
61
|
export declare const derives: (checker: ts.TypeChecker, type: ts.Type | null | undefined, test: (name: string, file: string) => boolean, depth?: number) => boolean;
|
|
62
62
|
export declare const derivesFromBuiltinError: (context: Context, type: ts.Type | null | undefined) => boolean;
|
|
63
|
-
/**
|
|
64
|
-
export declare const
|
|
63
|
+
/** The error base a root package declares for the linted file (`starci.errorBase` of its manifest), or null outside a package or without one. */
|
|
64
|
+
export declare const packageErrorBaseOf: (hfs: HfsView, filename: string) => HfsPackageDeclaredType | null;
|
|
65
|
+
/**
|
|
66
|
+
* True when the type is (or extends) the error base of the linted file: `DomainError` as declared by the repository's `platform/errors`
|
|
67
|
+
* owner, or, in a root workspace package (which cannot import `platform/errors`), the error base its manifest declares, in its declared file.
|
|
68
|
+
*/
|
|
69
|
+
export declare const derivesFromErrorBase: (context: Context, type: ts.Type | null | undefined) => boolean;
|
|
65
70
|
/**
|
|
66
71
|
* The owner-relative `errors/<capability>.error.ts` home of an error family, or null for a file that is not one.
|
|
67
72
|
*
|
package/dist/lib/declared.js
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import ts from "typescript";
|
|
7
7
|
import { hfsOf } from "./hfs.js";
|
|
8
|
+
import { normalizePath } from "./path.js";
|
|
8
9
|
import { typeOrigins, typed } from "./types.js";
|
|
9
10
|
/** The last segment of an owner root (`src/modules/platform/errors` gives `errors`), or null when there is no owner. */
|
|
10
11
|
export const ownerName = (root) => (root ? root.split("/").at(-1) : null);
|
|
@@ -119,11 +120,17 @@ export const derivesFromBuiltinError = (context, type) => {
|
|
|
119
120
|
return source ? program.isSourceFileDefaultLibrary(source) : false;
|
|
120
121
|
});
|
|
121
122
|
};
|
|
122
|
-
/**
|
|
123
|
-
export const
|
|
123
|
+
/** The error base a root package declares for the linted file (`starci.errorBase` of its manifest), or null outside a package or without one. */
|
|
124
|
+
export const packageErrorBaseOf = (hfs, filename) => hfs.packageContract?.(filename)?.errorBase ?? null;
|
|
125
|
+
/**
|
|
126
|
+
* True when the type is (or extends) the error base of the linted file: `DomainError` as declared by the repository's `platform/errors`
|
|
127
|
+
* owner, or, in a root workspace package (which cannot import `platform/errors`), the error base its manifest declares, in its declared file.
|
|
128
|
+
*/
|
|
129
|
+
export const derivesFromErrorBase = (context, type) => {
|
|
124
130
|
const hfs = hfsOf(context);
|
|
125
131
|
const { checker } = typed(context);
|
|
126
|
-
|
|
132
|
+
const own = packageErrorBaseOf(hfs, normalizePath(context.filename));
|
|
133
|
+
return derives(checker, type, (name, file) => (name === "DomainError" && isOwnedBy(hfs, file, "platform", "errors")) || (own !== null && name === own.name && hfs.relative(file) === own.file));
|
|
127
134
|
};
|
|
128
135
|
/**
|
|
129
136
|
* The owner-relative `errors/<capability>.error.ts` home of an error family, or null for a file that is not one.
|
package/dist/lib/hfs-view.d.ts
CHANGED
|
@@ -140,4 +140,16 @@ export interface HfsView {
|
|
|
140
140
|
allows(file: string): HfsAllowsVerdict | null;
|
|
141
141
|
/** A slot definition by id. */
|
|
142
142
|
slot(id: string): HfsSlot | undefined;
|
|
143
|
+
/** The vocabulary the root package of a file declares in the `starci` key of its manifest (the view of the root packages only), or null outside a package. */
|
|
144
|
+
readonly packageContract?: (file: string) => HfsPackageContract | null;
|
|
145
|
+
}
|
|
146
|
+
/** A type a root package declares: its name and the app-root relative file that declares it. */
|
|
147
|
+
export interface HfsPackageDeclaredType {
|
|
148
|
+
readonly name: string;
|
|
149
|
+
readonly file: string;
|
|
150
|
+
}
|
|
151
|
+
/** The error base and the outcome union a root package declares for itself, since it cannot import the app's `platform/errors` or `GraphQLResponse<T>`. */
|
|
152
|
+
export interface HfsPackageContract {
|
|
153
|
+
readonly errorBase?: HfsPackageDeclaredType;
|
|
154
|
+
readonly outcome?: HfsPackageDeclaredType;
|
|
143
155
|
}
|
package/dist/lib/hfs.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { HfsView } from "./hfs-view.js";
|
|
2
2
|
import type { Context } from "./rule.js";
|
|
3
|
-
export type { HfsAllowsVerdict, HfsApp, HfsClassification, HfsConnection, HfsParamName, HfsRuleParams, HfsSlot, HfsSpecDouble, HfsUnitRole, HfsView, } from "./hfs-view.js";
|
|
3
|
+
export type { HfsAllowsVerdict, HfsApp, HfsClassification, HfsConnection, HfsPackageContract, HfsPackageDeclaredType, HfsParamName, HfsRuleParams, HfsSlot, HfsSpecDouble, HfsUnitRole, HfsView, } from "./hfs-view.js";
|
|
4
4
|
/**
|
|
5
5
|
* The HFS view of the side whose `eslint.config.mjs` (in be/) calls this.
|
|
6
6
|
*
|
|
@@ -77,7 +77,7 @@ const dependenciesOf = (hfs) => {
|
|
|
77
77
|
throw new Error("third-party-import-owner needs the app-root package.json beside be/ to derive SDK ownership");
|
|
78
78
|
const declaration = JSON.parse(readFileSync(manifest, "utf8"));
|
|
79
79
|
const dependencies = new Map();
|
|
80
|
-
// The app's own workspace packages (packages
|
|
80
|
+
// The app's own workspace packages (packages/<name>: the agent SDK, a block library, a module package) are first-party source, not third-party libraries: whatever
|
|
81
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
82
|
const own = rootPackageNames(dirname(manifest));
|
|
83
83
|
for (const section of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
|
package/package.json
CHANGED
|
@@ -38,7 +38,7 @@ 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.18
|
|
42
42
|
group: starci
|
|
43
43
|
install: registry
|
|
44
44
|
side: fe
|
|
@@ -52,28 +52,28 @@ pins:
|
|
|
52
52
|
source: packages/next-i18n/package.json
|
|
53
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.'
|
|
54
54
|
'@starci/eslint-canon-be':
|
|
55
|
-
version: 3.
|
|
55
|
+
version: 3.15.1
|
|
56
56
|
group: starci
|
|
57
57
|
install: registry
|
|
58
58
|
side: be
|
|
59
59
|
source: packages/eslint-canon-be/package.json
|
|
60
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.'
|
|
61
61
|
'@starci/eslint-canon-fe':
|
|
62
|
-
version: 9.
|
|
62
|
+
version: 9.13.1
|
|
63
63
|
group: starci
|
|
64
64
|
install: registry
|
|
65
65
|
side: fe
|
|
66
66
|
source: packages/eslint-canon-fe/package.json
|
|
67
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.'
|
|
68
68
|
'@starci/eslint-grammar-core':
|
|
69
|
-
version: 0.21.
|
|
69
|
+
version: 0.21.18
|
|
70
70
|
group: starci
|
|
71
71
|
install: registry
|
|
72
72
|
side: fe
|
|
73
73
|
source: packages/eslint-grammar-core/package.json
|
|
74
74
|
why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
|
|
75
75
|
'@starci/eslint-grammar-offset-pop':
|
|
76
|
-
version: 0.21.
|
|
76
|
+
version: 0.21.18
|
|
77
77
|
group: starci
|
|
78
78
|
install: registry
|
|
79
79
|
side: fe
|
|
@@ -99,7 +99,7 @@ pins:
|
|
|
99
99
|
side: both
|
|
100
100
|
source: packages/prettier-config/package.json
|
|
101
101
|
'@starci/jest-preset':
|
|
102
|
-
version: 2.
|
|
102
|
+
version: 2.7.1
|
|
103
103
|
group: starci
|
|
104
104
|
install: registry
|
|
105
105
|
side: be
|
|
@@ -127,14 +127,14 @@ pins:
|
|
|
127
127
|
source: packages/nest-kit/package.json
|
|
128
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
129
|
'@starci/auth':
|
|
130
|
-
version: 0.
|
|
130
|
+
version: 0.3.0
|
|
131
131
|
group: starci
|
|
132
132
|
install: registry
|
|
133
133
|
side: both
|
|
134
134
|
source: packages/auth/package.json
|
|
135
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
136
|
'@starci/auth-oidc':
|
|
137
|
-
version: 0.1.
|
|
137
|
+
version: 0.1.2
|
|
138
138
|
group: starci
|
|
139
139
|
install: registry
|
|
140
140
|
side: both
|
|
@@ -155,7 +155,7 @@ pins:
|
|
|
155
155
|
source: packages/mail/package.json
|
|
156
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).'
|
|
157
157
|
'@starci/hfs':
|
|
158
|
-
version: 5.
|
|
158
|
+
version: 5.5.1
|
|
159
159
|
group: starci
|
|
160
160
|
install: registry
|
|
161
161
|
side: both
|
|
@@ -592,7 +592,7 @@ pins:
|
|
|
592
592
|
version: 3.1150.0
|
|
593
593
|
group: framework
|
|
594
594
|
side: be
|
|
595
|
-
why: 'the S3 transport inside @starci/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces), which depends on it at exactly this version and which no app file imports; 3.1150.0 is the release of 2026-10-12
|
|
595
|
+
why: 'the S3 transport inside @starci/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces), which depends on it at exactly this version and which no app file imports; 3.1150.0 is the release of 2026-10-12.'
|
|
596
596
|
'@aws-sdk/s3-request-presigner':
|
|
597
597
|
version: 3.1150.0
|
|
598
598
|
group: framework
|
|
@@ -602,7 +602,7 @@ pins:
|
|
|
602
602
|
version: 10.1.7
|
|
603
603
|
group: framework
|
|
604
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
|
|
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.'
|
|
606
606
|
'@apollo/server':
|
|
607
607
|
version: 5.5.1
|
|
608
608
|
group: framework
|
|
@@ -652,7 +652,7 @@ pins:
|
|
|
652
652
|
version: 6.29.0
|
|
653
653
|
group: framework
|
|
654
654
|
side: be
|
|
655
|
-
why: 'the Agent of platform/http (its one owner, R90): FetchHttpClient hands fetch a pool that trusts HttpOptions.trustedCa beside the bundled roots (a test world''s per-run fake CA); the 6 line is the undici the Node 22 runtime of the app images bundles, and its Agent also serves the fetch of Node 24; 6.29.0 is the release of 2026-09-25
|
|
655
|
+
why: 'the Agent of platform/http (its one owner, R90): FetchHttpClient hands fetch a pool that trusts HttpOptions.trustedCa beside the bundled roots (a test world''s per-run fake CA); the 6 line is the undici the Node 22 runtime of the app images bundles, and its Agent also serves the fetch of Node 24; 6.29.0 is the release of 2026-09-25.'
|
|
656
656
|
# --- lite identity (integrations/passport, ruling lite-self-hosted-postgres-passport-minio)
|
|
657
657
|
'@nestjs/passport':
|
|
658
658
|
version: 11.0.5
|
|
@@ -3299,7 +3299,7 @@ rules:
|
|
|
3299
3299
|
code: "HFS_DOCKER_BUILD_CONTEXT"
|
|
3300
3300
|
editions: [lite, full]
|
|
3301
3301
|
docs: [docs/application-stacks.md#r187]
|
|
3302
|
-
law: "Every app image is built from the app root: the header comment of an app's Dockerfile states `starci docker build <app>` for its own path,
|
|
3302
|
+
law: "Every app image is built from the app root: the header comment of an app's Dockerfile states `starci docker build <app>` for its own path, no COPY or ADD source leaves the build context (a `..` segment or an absolute path), and the image of a Next app whose front end reads be/contracts/ copies that folder only when the back end holds it (a back end that emits no contract has none, and a COPY of a missing folder fails the build)."
|
|
3303
3303
|
kinds: [check]
|
|
3304
3304
|
gates: [settle, land, ci]
|
|
3305
3305
|
failureCodes: ["HFS_DOCKER_BUILD_CONTEXT"]
|
|
@@ -5791,7 +5791,7 @@ rules:
|
|
|
5791
5791
|
ruling: "Lite storage is the MinIO already running on the Tay Son host, reached through the one S3 integration."
|
|
5792
5792
|
- id: R332
|
|
5793
5793
|
code: "LITE_DB_MIGRATION"
|
|
5794
|
-
law: "A lite app's schema lives only in db/: every schema change is one db/migrations/<ts14>_<kebab>.sql (archive db/migrations/archive/,
|
|
5794
|
+
law: "A lite app's schema lives only in db/: every schema change is one db/migrations/<ts14>_<kebab>.sql (archive db/migrations/archive/, the managed db/bootstrap.sql), every other SQL file under db/ is refused, and the tree holds no supabase/ folder and no SQL file outside db/ but the sql/ entries of its seed levels (R375)."
|
|
5795
5795
|
kinds: [check]
|
|
5796
5796
|
gates: [settle, land, ci]
|
|
5797
5797
|
failureCodes: ["LITE_DB_MIGRATION"]
|
|
@@ -6628,3 +6628,16 @@ rules:
|
|
|
6628
6628
|
- {path: contexts/project/stacks.md#project-stacks-11-a-customised-service-is-an-image-the-app-builds-the-same-in-every-environment, editions: [lite, full]}
|
|
6629
6629
|
proves:
|
|
6630
6630
|
- {path: packages/hfs/src/stacks-service-images.spec.mjs, editions: [lite, full]}
|
|
6631
|
+
- id: R375
|
|
6632
|
+
code: "HFS_SEEDS_SHAPE"
|
|
6633
|
+
law: "Seed data lives only in the seed levels of `.starcistacks/`, where `seeds/` is applied in every environment first and `<env>/seeds/` in the one environment the stack declaration names `<env>`; each level is a `seeds.yaml` manifest (schema starci/seeds@1) whose entries list every file of its `sql/`, `data/` and `files/` folders; a seed is never a migration (no statement that creates, alters, drops, truncates, grants, revokes or comments on an object), never custody, a data document validates against the schema its entry names, a level a production environment applies holds no test data but the one test account an environment declares (a test-account entry with its reason), and a document names a secret only as a reference to a sealed seeds-<name> member of its environment."
|
|
6634
|
+
kinds: [check]
|
|
6635
|
+
gates: [settle, land, ci]
|
|
6636
|
+
failureCodes: ["HFS_SEEDS_SHAPE", "HFS_SEED_MANIFEST", "HFS_SEED_DDL", "HFS_SEED_DATA_SCHEMA", "HFS_SEED_TEST_DATA", "HFS_SEED_SECRET_REF"]
|
|
6637
|
+
enforcers:
|
|
6638
|
+
- {kind: hfs, id: seeds-shape, at: scripts/hfs/rules/seeds.mjs}
|
|
6639
|
+
editions: [lite, full]
|
|
6640
|
+
docs:
|
|
6641
|
+
- {path: contexts/project/stacks.md#project-stacks-12-seed-data-lives-in-the-seed-levels-of-the-stack, editions: [lite, full]}
|
|
6642
|
+
proves:
|
|
6643
|
+
- {path: packages/hfs/src/hfs-seeds-shape.spec.mjs, editions: [lite, full]}
|
|
@@ -859,10 +859,10 @@ slots:
|
|
|
859
859
|
- id: app.packages
|
|
860
860
|
since: 3.17.0
|
|
861
861
|
profiles: [app]
|
|
862
|
-
editionWhy: Lite and full share the slot; a product
|
|
863
|
-
# A workspace package of the app ROOT (packages
|
|
862
|
+
editionWhy: Lite and full share the slot; every root workspace package of a product (its agent SDK, a block library, a module package, a reviewed plugin package) is one in both.
|
|
863
|
+
# A workspace package of the app ROOT (packages/<name>: the agent SDK, a block library, packages/module-<name>): first-party source that both sides import through its
|
|
864
864
|
# package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
|
|
865
|
-
path: "packages
|
|
865
|
+
path: "packages/<name>/"
|
|
866
866
|
presence: optional
|
|
867
867
|
tracked: tracked
|
|
868
868
|
tier: none
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// root-packages.mjs - the workspace packages of an app ROOT (packages
|
|
1
|
+
// root-packages.mjs - the workspace packages of an app ROOT (packages/<name>: the agent SDK, a block library, a module package, the managed packages/modules).
|
|
2
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
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
4
|
// a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder
|
|
@@ -140,7 +140,7 @@ function observeBlockProblems(observe) {
|
|
|
140
140
|
bad.push('observe.reporter must name the optional error reporter');
|
|
141
141
|
return bad;
|
|
142
142
|
}
|
|
143
|
-
const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'lexicon', 'observe']);
|
|
143
|
+
const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'modules', 'lexicon', 'observe']);
|
|
144
144
|
const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
|
|
145
145
|
function productDeclarationProblems(declaration, profiles) {
|
|
146
146
|
const bad = [];
|
|
@@ -150,6 +150,8 @@ function productDeclarationProblems(declaration, profiles) {
|
|
|
150
150
|
bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
|
|
151
151
|
if (declaration.browser !== undefined && declaration.browser !== true)
|
|
152
152
|
bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
|
|
153
|
+
if (declaration.modules !== undefined && declaration.modules !== 'data')
|
|
154
|
+
bad.push('modules is `"data"` when the app keeps its modules as data (seeds, no rendered registry package), and is left out otherwise');
|
|
153
155
|
if (declaration.kind !== APP_KIND)
|
|
154
156
|
bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
|
|
155
157
|
if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) {
|
|
@@ -177,6 +177,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
|
|
|
177
177
|
// tsconfig.json that type-checks it, both switched on by `browser: true`.
|
|
178
178
|
apps: Object.freeze([]),
|
|
179
179
|
optionalSlots: Object.freeze(declaration.browser === true ? ['app.browser', 'app.browser-config'] : []),
|
|
180
|
+
modules: declaration.modules === 'data' ? 'data' : 'packages',
|
|
180
181
|
connections: Object.freeze([]),
|
|
181
182
|
providers,
|
|
182
183
|
reads: Object.freeze([]),
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// their rules (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
|
|
3
3
|
// runtime/ bundle (scripts/hfs/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
|
|
4
4
|
// architecture machine and `starci app check` use, and never tests a path with a regular expression of its own.
|
|
5
|
+
import fs from 'node:fs';
|
|
5
6
|
import path from 'node:path';
|
|
6
7
|
import { allowsFile } from './allows.mjs';
|
|
7
8
|
import { openHfs } from './slots.mjs';
|
|
@@ -70,6 +71,36 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
|
|
|
70
71
|
* @returns {object} The frozen view.
|
|
71
72
|
*/
|
|
72
73
|
export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
|
|
74
|
+
const CONTRACT_KEYS = ['errorBase', 'outcome'];
|
|
75
|
+
/**
|
|
76
|
+
* The contract of the package at `packageDir` (app-root relative, `packages/<pkg>`), read from the `starci` key of its manifest. A
|
|
77
|
+
* declaration that is not `{ name, file }` with an identifier name and a file inside `src/` stops the lint, because a rule must not guess.
|
|
78
|
+
*
|
|
79
|
+
* @param {string} repoRoot - The absolute app root.
|
|
80
|
+
* @param {string} packageDir - The package folder, relative to the app root.
|
|
81
|
+
* @returns {object} The declared error base and outcome union, each with its file relative to the app root.
|
|
82
|
+
*/
|
|
83
|
+
export const readPackageContract = (repoRoot, packageDir) => {
|
|
84
|
+
const manifestPath = path.join(repoRoot, packageDir, 'package.json');
|
|
85
|
+
const manifest = (fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : null);
|
|
86
|
+
const declared = manifest?.starci;
|
|
87
|
+
if (declared === undefined)
|
|
88
|
+
return {};
|
|
89
|
+
if (typeof declared !== 'object' || declared === null)
|
|
90
|
+
throw new Error(`${packageDir}/package.json: "starci" is an object ({ errorBase, outcome })`);
|
|
91
|
+
const contract = {};
|
|
92
|
+
for (const key of CONTRACT_KEYS) {
|
|
93
|
+
const entry = declared[key];
|
|
94
|
+
if (entry === undefined)
|
|
95
|
+
continue;
|
|
96
|
+
const { name, file } = (typeof entry === 'object' && entry !== null ? entry : {});
|
|
97
|
+
if (typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name) || typeof file !== 'string' || !/^src\/(?:[\w.-]+\/)*[\w.-]+\.ts$/.test(file)) {
|
|
98
|
+
throw new Error(`${packageDir}/package.json: "starci.${key}" is { "name": "<Identifier>", "file": "src/<path>.ts" }`);
|
|
99
|
+
}
|
|
100
|
+
contract[key] = Object.freeze({ name, file: `${packageDir}/${file}` });
|
|
101
|
+
}
|
|
102
|
+
return Object.freeze(contract);
|
|
103
|
+
};
|
|
73
104
|
/**
|
|
74
105
|
* 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
106
|
* 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
|
|
@@ -103,6 +134,15 @@ function packagesView(opened, repoRoot, side) {
|
|
|
103
134
|
const relative = rel(file);
|
|
104
135
|
return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
|
|
105
136
|
};
|
|
137
|
+
const contracts = new Map();
|
|
138
|
+
const packageContract = (file) => {
|
|
139
|
+
const dir = packageOf(file);
|
|
140
|
+
if (dir === null)
|
|
141
|
+
return null;
|
|
142
|
+
if (!contracts.has(dir))
|
|
143
|
+
contracts.set(dir, readPackageContract(repoRoot, dir));
|
|
144
|
+
return contracts.get(dir);
|
|
145
|
+
};
|
|
106
146
|
return Object.freeze({
|
|
107
147
|
repoRoot,
|
|
108
148
|
profile: side,
|
|
@@ -121,6 +161,7 @@ function packagesView(opened, repoRoot, side) {
|
|
|
121
161
|
ownerOf: () => null,
|
|
122
162
|
allows: (file) => allowsFile(opened, rel(file)),
|
|
123
163
|
slot: (id) => opened.slot(id),
|
|
164
|
+
packageContract,
|
|
124
165
|
});
|
|
125
166
|
}
|
|
126
167
|
/**
|