@starci/eslint-canon-be 3.15.4 → 3.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +9 -0
- package/README.md +1 -1
- package/dist/boundary-schema.js +9 -3
- package/package.json +1 -1
- package/runtime/knowledge/hfs/canon-pins.yaml +6 -6
- package/runtime/knowledge/hfs/rules.yaml +7 -6
- package/runtime/knowledge/hfs/slots.yaml +2 -2
- package/runtime/scripts/hfs/declaration-shape.mjs +10 -1
- package/runtime/scripts/hfs/rules/database-constants.mjs +2 -0
- package/runtime/scripts/hfs/rules/database-migrations.mjs +44 -11
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.16.0 - 2026-11-04
|
|
4
|
+
|
|
5
|
+
- Changed: `schema-place` (R304) lets any file of a root workspace package (tier `package`: `packages/<name>/`, slots `app.packages` and `app.module-registry`) import `zod`, since its node, block and vocabulary contracts are zod schemas; a door or `dto/` folder there still answers to `class-validator`, a `<name>.schema.ts` there still never shares a file with `class-validator` or a GraphQL type, and `schema-bounded` holds unchanged (ruling package-zod-contracts). Spec: `src/packages-config.spec.ts`.
|
|
6
|
+
- Changed: the runtime copies carry the landed-migration db rules, the module shape of `be.integrations.passport` in the package slot manifest and the canon pins of `@starci/hfs` 5.8.0.
|
|
7
|
+
|
|
8
|
+
## 3.15.5 - 2026-11-04
|
|
9
|
+
|
|
10
|
+
- Changed: the runtime copy of the canon pins names `@starci/hfs` 5.7.1 and the release-7a versions.
|
|
11
|
+
|
|
3
12
|
## 3.15.4 - 2026-11-04
|
|
4
13
|
|
|
5
14
|
- Changed: the runtime copies carry the R343, R251, R272 and R376 laws of `@starci/hfs` 5.7.0 and the release-6 canon pins.
|
package/README.md
CHANGED
|
@@ -54,7 +54,7 @@ A sample, not the list:
|
|
|
54
54
|
| **Log safety** | A call on the `Logger` port (found by the receiver's type) passes no `Secret` or `Pii` value and no value named like a credential or a personal identifier (`no-secret-in-log`); a constructed error (its type derives from `Error`) carries no `Secret` value and no text value named like a credential (`no-secret-in-error`) |
|
|
55
55
|
| **Async and types** | An `async` function awaits; handlers and public methods declare a return type; no `Function` type, no `eval`; an inline object type takes a name; no `const enum`. Casts, `x!` and `any` are refused in every file, specs included, by the typescript-eslint rules the factory turns on (`async-needs-await`, `explicit-handler-return-type`, `no-function-or-eval`, `no-inline-param-type`, `no-inline-object-type`, `no-const-enum`) |
|
|
56
56
|
| **Migrations and input** | A migration's `down()` reverses its `up()`; every property of an input class has the `class-validator` decorators its type calls for (string `@MaxLength`, enum `@IsEnum`, array `@ArrayMaxSize`, nested `@ValidateNested()` and `@Type`); reads page by cursor, never by `skip`, `offset` or `OFFSET`; a door opened for `PublicReason.AuthHandshake` or `PublicReason.SignedWebhook` carries `RateTier.Strict` of `platform/http-security` on the method or its class (`migration-down-reversible`, `input-bounded`, `no-offset-pagination`, `auth-door-strict-rate-tier`) |
|
|
57
|
-
| **Boundary schema** (R304, R305) | `zod` reads only boundary data that never reaches a DTO (a provider response, model output, a queue or outbox payload read back): it is imported only from a `<name>.schema.ts` of a domain, platform or integrations owner, never in a feature, a transport door or a `dto/` folder, and a schema file imports no `class-validator`, `class-transformer` or `@nestjs/graphql` (`schema-place`) and holds only zod values and types (`schema-file-values-only`; its spec is exempt from the testing module of R281 only while this holds); every string, array, set, record and map of a schema has an upper bound and `z.any()`, `z.unknown()` and `z.json()` do not exist (`schema-bounded`) |
|
|
57
|
+
| **Boundary schema** (R304, R305) | `zod` reads only boundary data that never reaches a DTO (a provider response, model output, a queue or outbox payload read back): it is imported only from a `<name>.schema.ts` of a domain, platform or integrations owner, or from any file of a root workspace package (tier `package`: `packages/<name>/`, whose node, block and vocabulary contracts are zod schemas), never in a feature, a transport door or a `dto/` folder, and a schema file imports no `class-validator`, `class-transformer` or `@nestjs/graphql` (`schema-place`) and holds only zod values and types (`schema-file-values-only`; its spec is exempt from the testing module of R281 only while this holds); every string, array, set, record and map of a schema has an upper bound and `z.any()`, `z.unknown()` and `z.json()` do not exist (`schema-bounded`) |
|
|
58
58
|
| **Spec quality** | A spec does not read repository source with `fs` (`spec-no-source-read`); the borrowed `consistent-type-assertions` (`never`) and `no-non-null-assertion` leave no `as` and no `x!` in a spec, and `no-ambient-clock` and `no-direct-env-read` cover specs, so no `Date.now()`, argless `new Date()` or `process.env`. A unit spec is `<name>.service.spec.ts`: it builds its subject with `Test.createTestingModule({ providers })` from `@nestjs/testing`, `.compile()` and `moduleRef.get(...)` (`spec-builds-with-testing-module`), never `new` on the service (`spec-no-new-subject`), no `imports` key and no `override*` (`spec-module-definition-only-providers`), no `jest.mock`/`doMock`/`unstable_mockModule`/`requireMock` of an own module or a library (`spec-no-module-mock`), no cast-laundering helper in a spec or fixture: a return-only generic, an `unknown` handed back as another type, `JSON.parse(JSON.stringify(x))`, `Object.assign(new X(), y)` returned as another type (`no-return-only-generic`); a provider `{ provide: TOKEN, useValue: X }` takes X from the matching `@starci/jest-preset` double, the token table being `ruleParams.be.specDoubles` of the slot manifest (`spec-infra-double-from-kit`); a unit spec asserts exact values, never `expect.any(String)`, `expect.any(Number)` or `expect.any(Date)` (`expect` being the jest global or the `@jest/globals` import): ids come from `fakeIds()` and dates from `FakeClock` (`spec-exact-values`); the EntityManager double is the kit's `mockEntityManager()`/`fakeTransaction()`, never ad hoc (`spec-typed-entity-manager`); test data goes through builders, see the **Test data builders** row |
|
|
59
59
|
| **Test data builders** (R98 to R101) | Builders live only in `src/tests/fixtures/builders/<area>.builder.ts`: a module of the test tree that exports a function creating persisted rows through an EntityManager, DataSource or QueryRunner is a builder wherever it sits (`persisting-builder-in-builders-slot`, R98); a spec never runs a raw INSERT/UPDATE/DELETE or a direct write (`save`, `insert`, `upsert`, `update`, `delete`, `remove`) on a typeorm receiver and never builds the same `@Entity` class as an object literal twice (`spec-no-raw-insert`, `spec-no-repeated-row-literal`, R99); a builder never asserts and has deterministic defaults (`builder-arranges-only`, R101); nothing under `src/tests` disables or drops a constraint (`tests-keep-constraints`, R100) |
|
|
60
60
|
| **CQRS** | A message extends `Command<R>` / `Query<R>` from `@nestjs/cqrs`, carries one `readonly params: ExecuteParams<X>` (no entity reachable from `X`), a handler extends `ICQRSHandler` and overrides `process`; a handler is thin: it injects only `*Service` classes and the Logger, and `process` is one `return this.<service>.<method>(...)` with no branch, loop, EntityManager or second call (`handler-is-thin`); no `*.use-case.ts`, no forwarder service, no `EventBus`, `@nestjs/event-emitter`, `EventEmitter` or RxJS `Subject` constructed or extended, and no class that stores callbacks other code registers (`handler-overrides-process`, `message-carries-params-only`, `message-typed-result`, `execute-params-shape`, `no-use-case`, `no-event-bus`) |
|
package/dist/boundary-schema.js
CHANGED
|
@@ -7,8 +7,10 @@
|
|
|
7
7
|
* argument, structured model output, a queue or outbox payload. The two territories are kept disjoint by lint, never by memory.
|
|
8
8
|
*
|
|
9
9
|
* - `schema-place` (R304) holds the territory. `zod` is imported only from a `<name>.schema.ts` file (or its spec) that sits
|
|
10
|
-
* in a `domain`, `platform` or `integrations` owner
|
|
11
|
-
*
|
|
10
|
+
* in a `domain`, `platform` or `integrations` owner, or from any file of a root workspace package (tier `package`, slots
|
|
11
|
+
* `app.packages` and `app.module-registry`), whose node, block and vocabulary contracts are zod schemas; never in a feature
|
|
12
|
+
* (a transport door answers to `class-validator`), never in a `dto/` folder, and a schema file does not also carry
|
|
13
|
+
* `class-validator` or a GraphQL type.
|
|
12
14
|
* - `schema-bounded` (R305) holds the cost. Every string, array, set, map and record a schema builds has an upper bound
|
|
13
15
|
* (`.max(n)`, `.length(n)`, `.size(n)`, or for a record and a map a `.refine`/`.check` on its entry count), and `z.any()`,
|
|
14
16
|
* `z.unknown()` and `z.json()` are refused: an unbounded array whose elements all fail validation allocates an issue each
|
|
@@ -22,6 +24,8 @@ const ZOD = /^zod(?:\/|$)/;
|
|
|
22
24
|
/** The imports of the other validation layer, which never share a file with a schema. */
|
|
23
25
|
const MIXED = new Set(["class-validator", "class-transformer", "@nestjs/graphql"]);
|
|
24
26
|
const SCHEMA_FILE = /\.schema(?:\.spec)?\.ts$/;
|
|
27
|
+
/** The tier of a root workspace package: a contract library whose node, block and vocabulary contracts are zod schemas. */
|
|
28
|
+
const PACKAGE_TIER = "package";
|
|
25
29
|
/** Constructors that build a string-valued schema and owe a `.max(n)` or `.length(n)`. */
|
|
26
30
|
const STRINGY = new Set(["string", "email", "url", "httpUrl", "hostname", "base64", "base64url", "jwt", "emoji", "hex", "iso.datetime", "iso.date", "iso.time", "iso.duration"]);
|
|
27
31
|
/** The ISO namespace constructs strings; `z.date()` instead constructs a Date-valued schema. */
|
|
@@ -167,7 +171,7 @@ const referencesZod = (node) => referenceNodes(node).filter((source) => source.t
|
|
|
167
171
|
export const schemaPlace = {
|
|
168
172
|
meta: {
|
|
169
173
|
type: "problem",
|
|
170
|
-
docs: { description: "`zod` is imported only from a `*.schema.ts` file of a domain, platform or integrations owner, never in a transport door or beside a DTO decorator." },
|
|
174
|
+
docs: { description: "`zod` is imported only from a `*.schema.ts` file of a domain, platform or integrations owner or from a root workspace package, never in a transport door or beside a DTO decorator." },
|
|
171
175
|
schema: [],
|
|
172
176
|
messages: {
|
|
173
177
|
door: "`zod` is imported in a transport door or a `dto/` folder. A door's input is validated by `class-validator` (R42); read untrusted data that is not a DTO through a `<name>.schema.ts` of the owner instead.",
|
|
@@ -192,6 +196,8 @@ export const schemaPlace = {
|
|
|
192
196
|
context.report({ node: first, messageId: "door" });
|
|
193
197
|
else if (tier === "feature")
|
|
194
198
|
context.report({ node: first, messageId: "tier", data: { tier } });
|
|
199
|
+
else if (tier === PACKAGE_TIER)
|
|
200
|
+
return;
|
|
195
201
|
else if (!isSchemaFile)
|
|
196
202
|
context.report({ node: first, messageId: "file" });
|
|
197
203
|
else if (!SCHEMA_TIERS.has(tier))
|
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.23
|
|
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.16.0
|
|
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.13.
|
|
62
|
+
version: 9.13.6
|
|
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.23
|
|
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.23
|
|
77
77
|
group: starci
|
|
78
78
|
install: registry
|
|
79
79
|
side: fe
|
|
@@ -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.8.0
|
|
159
159
|
group: starci
|
|
160
160
|
install: registry
|
|
161
161
|
side: both
|
|
@@ -2857,7 +2857,7 @@ rules:
|
|
|
2857
2857
|
code: "HFS_SERVICE_PLACEMENT"
|
|
2858
2858
|
editions: [lite, full]
|
|
2859
2859
|
docs: [docs/microservices.md#r163]
|
|
2860
|
-
law: "A back-end service lives only at `be/apps/<service>/`: a folder with a `Dockerfile` of its own, or with a `package.json` other than the app root's and those of the
|
|
2860
|
+
law: "A back-end service lives only at `be/apps/<service>/`: a folder with a `Dockerfile` of its own, or with a `package.json` other than the app root's and those of the workspace packages (`fe/apps/<app>`, `fe/packages/<pkg>`, a root `packages/<name>`), outside `be/apps/<service>/` (and outside a front end's `fe/apps/<app>/Dockerfile`) is a second service root and a finding; a service is a Nest app of the one repository that shares the `be/src` libraries and the one package.json, and its image is built from its own Dockerfile."
|
|
2861
2861
|
kinds: [check]
|
|
2862
2862
|
gates: [land, ci]
|
|
2863
2863
|
failureCodes: ["HFS_SERVICE_PLACEMENT"]
|
|
@@ -4185,7 +4185,7 @@ rules:
|
|
|
4185
4185
|
editions: [lite, full]
|
|
4186
4186
|
docs:
|
|
4187
4187
|
- {path: docs/application-stacks.md#r250-deploy-scan, editions: [lite, full]}
|
|
4188
|
-
law: "In lite and full apps, scheduled work belongs to the back-end queue scheduler, a platform/jobs tick (R335) that enqueues through the queue outbox or a declared replicated-job. Deployment files, scripts, workflows, compose files and Dockerfiles install no host crontab, cron.d entry, systemd timer, @reboot job or at job; a workflow does not schedule app work. Docker compose up, down and pull run only against an explicitly dev environment. Deploy shell scripts delegate to docker, starci or the app CLI, and contain no node -e, psql, inline SQL or downloaded shell logic."
|
|
4188
|
+
law: "In lite and full apps, scheduled work belongs to the back-end queue scheduler, a platform/jobs tick (R335) that enqueues through the queue outbox or a declared replicated-job. Deployment files, scripts, workflows, compose files and Dockerfiles install no host crontab, cron.d entry, systemd timer, @reboot job or at job; a workflow does not schedule app work (the managed nightly cache verify, `cache-verify.yml`, is the one scheduled workflow). Docker compose up, down and pull run only against an explicitly dev environment. Deploy shell scripts delegate to docker, starci or the app CLI, and contain no node -e, psql, inline SQL or downloaded shell logic."
|
|
4189
4189
|
kinds: [check]
|
|
4190
4190
|
gates: [settle, land, ci]
|
|
4191
4191
|
failureCodes: ["HFS_HOST_CRON", "HFS_DEPLOY_NO_LOGIC", "HFS_DEPLOY_COMPOSE_ON_VPS", "HFS_DEPLOY_SCHEDULER"]
|
|
@@ -4340,13 +4340,14 @@ rules:
|
|
|
4340
4340
|
editionWhy: "owner:lite-backing-services makes the db service lite's database; database configuration, extension, migration and seed requirements apply to that backing."
|
|
4341
4341
|
docs: [docs/microservices.md#r259]
|
|
4342
4342
|
templateNa: "Extension use, contract migrations, vault operations and seed literals are product-authored db content, rather than a scaffolded SQL surface."
|
|
4343
|
-
law: "DB_CONFIG_EXT: extensions belong to the database allowlist, vault writes and migration role passwords are refused, and seed data holds no real email or phone. Destructive DDL belongs only to *_contract_* migrations whose targets are no longer referenced by back-end SQL or entities, and a contract migration that is new since the previous release tag (the newest v* tag HEAD contains) never destroys an object that the back-end sources of that tag still reference: the deploy applies it right after the accept, while that release is the rollback target, so the code change goes in one release and its contract migration in the next. Seeds contain no real email or phone literals."
|
|
4343
|
+
law: "DB_CONFIG_EXT: extensions belong to the database allowlist, vault writes and migration role passwords are refused, and seed data holds no real email or phone. Destructive DDL belongs only to *_contract_* migrations whose targets are no longer referenced by back-end SQL or entities, and a contract migration that is new since the previous release tag (the newest v* tag HEAD contains) never destroys an object that the back-end sources of that tag still reference: the deploy applies it right after the accept, while that release is the rollback target, so the code change goes in one release and its contract migration in the next. A migration already on the base unchanged is immutable (R213), so its destructive and dynamic DDL is reported as a known item, not a blocker; an owner ruling in hfs.json `db.destructiveRulings` (the exact migration, the exact objects, a reason and the date) accepts those objects outside a contract migration only while the same proof finds them unreferenced, else DB_DESTRUCTIVE_RULING_UNPROVEN. Seeds contain no real email or phone literals."
|
|
4344
4344
|
kinds: [check]
|
|
4345
4345
|
gates: [settle, land, ci]
|
|
4346
|
-
failureCodes: ["DB_EXTENSION_ALLOWED", "DB_MIGRATION_DESTRUCTIVE", "HFS_SEED_PII", "DB_VAULT_WRITE"]
|
|
4346
|
+
failureCodes: ["DB_EXTENSION_ALLOWED", "DB_MIGRATION_DESTRUCTIVE", "DB_DESTRUCTIVE_RULING_UNPROVEN", "HFS_SEED_PII", "DB_VAULT_WRITE"]
|
|
4347
4347
|
enforcers:
|
|
4348
4348
|
- {kind: hfs, id: db-config-ext, at: scripts/hfs/rules/database-config.mjs}
|
|
4349
4349
|
- {kind: hfs, id: db-migration-destructive, at: scripts/hfs/rules/database-migrations.mjs}
|
|
4350
|
+
- {kind: hfs, id: db-migration-landed, at: scripts/hfs/rules/database-landed.mjs}
|
|
4350
4351
|
proves:
|
|
4351
4352
|
- {path: packages/hfs/src/hfs-database-config.spec.mjs, editions: [lite], codes: [DB_EXTENSION_ALLOWED, DB_MIGRATION_DESTRUCTIVE, HFS_SEED_PII, DB_VAULT_WRITE]}
|
|
4352
4353
|
exemplifiedBy:
|
|
@@ -5270,7 +5271,7 @@ rules:
|
|
|
5270
5271
|
- {path: packages/hfs/src/bypass-detector.spec.mjs, editions: [lite, full], codes: [HFS_BYPASS_MARKER]}
|
|
5271
5272
|
- id: R304
|
|
5272
5273
|
code: "BE_SCHEMA_PLACE"
|
|
5273
|
-
law: "The back end validates by zone. A transport door (GraphQL `@InputType`, REST request class) is validated by `class-validator` (R42); untrusted data that never reaches a DTO (a provider's HTTP response, structured model output, a queue or outbox payload read back, a tool argument) is read through a `zod` schema. `zod` is imported only from a `<name>.schema.ts` file (or its spec) of a `modules/domain`, `modules/platform` or `modules/integrations` owner, never in a feature, a transport door or a `dto/` folder, and a schema file imports neither `class-validator`, `class-transformer` nor `@nestjs/graphql`, imports zod and declares only zod schema values and their types (no class, provider, function or other logic). The spec of a schema file parses the schema directly and builds no testing module only while its sibling is such a file. The reader that calls the schema maps a failed parse to its owner's error family. No schema is shared between the front end and the back end: the shared contract is the emitted `schema.graphql` and `openapi.json`."
|
|
5274
|
+
law: "The back end validates by zone. A transport door (GraphQL `@InputType`, REST request class) is validated by `class-validator` (R42); untrusted data that never reaches a DTO (a provider's HTTP response, structured model output, a queue or outbox payload read back, a tool argument) is read through a `zod` schema. `zod` is imported only from a `<name>.schema.ts` file (or its spec) of a `modules/domain`, `modules/platform` or `modules/integrations` owner, or from any file of a root workspace package (tier `package`, `packages/<name>/`), whose node, block and vocabulary contracts are zod schemas, never in a feature, a transport door or a `dto/` folder, and a schema file imports neither `class-validator`, `class-transformer` nor `@nestjs/graphql`, imports zod and declares only zod schema values and their types (no class, provider, function or other logic). The spec of a schema file parses the schema directly and builds no testing module only while its sibling is such a file. The reader that calls the schema maps a failed parse to its owner's error family. No schema of a module is shared between the front end and the back end: the shared contract is the emitted `schema.graphql` and `openapi.json`."
|
|
5274
5275
|
kinds: [lint, design]
|
|
5275
5276
|
gates: [pre-commit, settle, land, ci]
|
|
5276
5277
|
failureCodes: ["BE_SCHEMA_PLACE"]
|
|
@@ -6623,7 +6624,7 @@ rules:
|
|
|
6623
6624
|
- {path: packages/hfs/src/stack-local.spec.mjs, editions: [lite, full]}
|
|
6624
6625
|
- id: R374
|
|
6625
6626
|
code: "STACKS_CODE_BIND_MOUNT"
|
|
6626
|
-
law: "A service the app customises runs from an image built out of `.starcistacks/images/<name>/` (a Dockerfile whose every FROM is digest-pinned and whose final stage is the harness's image for that service, the fork or its runtime layer, when the harness owns one), the same image in every environment; no stack or compose file bind-mounts code, plugins or scripts into a service container (data volumes, secrets, least grants and read-only plain config data files stay allowed)."
|
|
6627
|
+
law: "A service the app customises runs from an image built out of `.starcistacks/images/<name>/` (a Dockerfile whose every FROM is digest-pinned and whose final stage is the harness's image for that service, the fork or its runtime layer, when the harness owns one), the same image in every environment (the folder build, or a project-owned reference `<project>` or `<project>-<name>` as the managed images workflow publishes it); no stack or compose file bind-mounts code, plugins or scripts into a service container (data volumes, secrets, least grants and read-only plain config data files stay allowed)."
|
|
6627
6628
|
kinds: [check]
|
|
6628
6629
|
gates: [settle, land, ci]
|
|
6629
6630
|
failureCodes: ["STACKS_CODE_BIND_MOUNT", "STACKS_IMAGE_BASE_UNPINNED", "STACKS_IMAGE_BASE_NOT_FORK", "STACKS_IMAGE_ENV_DIVERGES"]
|
|
@@ -2044,8 +2044,8 @@ slots:
|
|
|
2044
2044
|
tracked: tracked
|
|
2045
2045
|
tier: integrations
|
|
2046
2046
|
owner: true
|
|
2047
|
-
requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.
|
|
2048
|
-
allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.
|
|
2047
|
+
requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.module-definition.ts, passport.module.ts] # Secrets, no defaults (R44); options and named injectors (R83); the kit and the module over @starci/auth
|
|
2048
|
+
allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.module-definition.ts, passport.module.ts, errors/]
|
|
2049
2049
|
logic: [passport.kit.ts] # the verifier mapping over the package: measured at 100 per file
|
|
2050
2050
|
tests: unit-beside
|
|
2051
2051
|
rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_AUTH_JWT_OWN_JWKS, BE_AUTH_REFRESH_COOKIE]
|
|
@@ -5,6 +5,13 @@ import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs
|
|
|
5
5
|
import { byCodeUnit } from '../lib/list.mjs';
|
|
6
6
|
/** Shape problems of the optional hfs.json `db` block of a lite app: the environment variable naming its database, its image, forced RLS and its application role. */
|
|
7
7
|
const isStringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim());
|
|
8
|
+
/** One owner ruling on a migration's destructive DDL: the exact file, the exact objects, the reason and the date the owner ruled it. */
|
|
9
|
+
const isDestructiveRuling = (ruling) => isPlainObject(ruling)
|
|
10
|
+
&& typeof ruling.migration === 'string' && /^db\/migrations\/\d{14}_[a-z0-9_-]+\.sql$/.test(ruling.migration)
|
|
11
|
+
&& isStringList(ruling.objects) && ruling.objects.length > 0
|
|
12
|
+
&& typeof ruling.reason === 'string' && ruling.reason.trim() !== ''
|
|
13
|
+
&& typeof ruling.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(ruling.date)
|
|
14
|
+
&& Object.keys(ruling).every((key) => ['migration', 'objects', 'reason', 'date'].includes(key));
|
|
8
15
|
function dbBlockProblems(block) {
|
|
9
16
|
if (block === undefined)
|
|
10
17
|
return [];
|
|
@@ -12,7 +19,7 @@ function dbBlockProblems(block) {
|
|
|
12
19
|
return ['db must be an object'];
|
|
13
20
|
const bad = [];
|
|
14
21
|
for (const key of Object.keys(block))
|
|
15
|
-
if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole'].includes(key))
|
|
22
|
+
if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole', 'destructiveRulings'].includes(key))
|
|
16
23
|
bad.push(`db has unknown key ${key}`);
|
|
17
24
|
if (block.urlEnv !== undefined && (typeof block.urlEnv !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(block.urlEnv)))
|
|
18
25
|
bad.push('db.urlEnv must name an UPPER_CASE environment variable');
|
|
@@ -24,6 +31,8 @@ function dbBlockProblems(block) {
|
|
|
24
31
|
bad.push('db.appRole must name a role');
|
|
25
32
|
if (block.forceRlsExemptions !== undefined && !Array.isArray(block.forceRlsExemptions))
|
|
26
33
|
bad.push('db.forceRlsExemptions must be a list of { table, reason }');
|
|
34
|
+
if (block.destructiveRulings !== undefined && !(Array.isArray(block.destructiveRulings) && block.destructiveRulings.every(isDestructiveRuling)))
|
|
35
|
+
bad.push('db.destructiveRulings must be a list of { migration, objects, reason, date } naming one db/migrations file, the objects it destroys, why and the date the owner ruled it (YYYY-MM-DD)');
|
|
27
36
|
return bad;
|
|
28
37
|
}
|
|
29
38
|
function appShapeProblems(apps, at, side, names) {
|
|
@@ -11,6 +11,8 @@ export const DB_ARCHIVE_MUTATED = 'DB_ARCHIVE_MUTATED';
|
|
|
11
11
|
export const DB_PGMQ_DECLARED = 'DB_PGMQ_DECLARED';
|
|
12
12
|
export const DB_EXTENSION_ALLOWED = 'DB_EXTENSION_ALLOWED';
|
|
13
13
|
export const DB_MIGRATION_DESTRUCTIVE = 'DB_MIGRATION_DESTRUCTIVE';
|
|
14
|
+
/** An owner ruling (hfs.json db.destructiveRulings) whose destroyed object is still referenced, or that names an object or migration it cannot prove. */
|
|
15
|
+
export const DB_DESTRUCTIVE_RULING_UNPROVEN = 'DB_DESTRUCTIVE_RULING_UNPROVEN';
|
|
14
16
|
export const HFS_SEED_PII = 'HFS_SEED_PII';
|
|
15
17
|
export const DB_VAULT_WRITE = 'DB_VAULT_WRITE';
|
|
16
18
|
|
|
@@ -7,8 +7,8 @@ import { tag } from '../../api/git/tag.mjs';
|
|
|
7
7
|
import { withoutGitLocalEnv } from '../../lib/git.mjs';
|
|
8
8
|
import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
|
|
9
9
|
import { sameText } from '../../lib/same-text.mjs';
|
|
10
|
-
import { found, readText } from './read.mjs';
|
|
11
|
-
import { DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
|
|
10
|
+
import { found, readJson, readText } from './read.mjs';
|
|
11
|
+
import { DB_DESTRUCTIVE_RULING_UNPROVEN, DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
|
|
12
12
|
import path from 'node:path';
|
|
13
13
|
import { fileURLToPath } from 'node:url';
|
|
14
14
|
import { loadTypescript } from '../../lib/package-at.mjs';
|
|
@@ -579,18 +579,42 @@ function migrationDestructiveObjects(text) {
|
|
|
579
579
|
return destructiveObjects(statement).filter((object) => !alterOfNewColumn(object, added));
|
|
580
580
|
});
|
|
581
581
|
}
|
|
582
|
-
|
|
583
|
-
|
|
582
|
+
const CONTRACT_MIGRATION = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/;
|
|
583
|
+
/**
|
|
584
|
+
* The owner rulings of hfs.json `db.destructiveRulings`, by migration file: the exact objects each may destroy outside a contract migration,
|
|
585
|
+
* held only while the same proof a contract migration gets finds them unreferenced. The declaration shape judges reason and date.
|
|
586
|
+
*/
|
|
587
|
+
function destructiveRulings(repoRoot) {
|
|
588
|
+
const listed = readJson(repoRoot, 'hfs.json')?.db?.destructiveRulings;
|
|
589
|
+
const rulings = new Map();
|
|
590
|
+
for (const ruling of Array.isArray(listed) ? listed : []) {
|
|
591
|
+
if (typeof ruling?.migration === 'string' && Array.isArray(ruling.objects))
|
|
592
|
+
rulings.set(ruling.migration, new Set(ruling.objects.filter((name) => typeof name === 'string')));
|
|
593
|
+
}
|
|
594
|
+
return rulings;
|
|
595
|
+
}
|
|
596
|
+
/** A ruled object is accepted while no be/src source references it; a reference makes the ruling unproven. */
|
|
597
|
+
function ruledObjectFinding(file, object, references) {
|
|
598
|
+
const reference = references.find(({ scopes }) => referencesObject(scopes, object));
|
|
599
|
+
return reference ? found(DB_DESTRUCTIVE_RULING_UNPROVEN, file, `${file}:${object.line} destroys ${object.name} under hfs.json db.destructiveRulings, but ${reference.file} still references it; the ruling holds only while its targets are unreferenced`, { line: object.line, object: object.name, reference: reference.file }) : null;
|
|
600
|
+
}
|
|
601
|
+
function destructiveFileFindings(file, text, references, ruled = new Set()) {
|
|
602
|
+
const contract = CONTRACT_MIGRATION.test(file);
|
|
584
603
|
const seen = new Set();
|
|
585
604
|
const objects = migrationDestructiveObjects(text);
|
|
586
|
-
|
|
605
|
+
const findings = objects.flatMap((object) => {
|
|
587
606
|
const key = `${object.line}:${object.kind}:${object.name}`;
|
|
588
607
|
if (seen.has(key))
|
|
589
608
|
return [];
|
|
590
609
|
seen.add(key);
|
|
591
|
-
const finding = destructiveObjectFinding(file, object, contract, references);
|
|
610
|
+
const finding = !contract && ruled.has(object.name) ? ruledObjectFinding(file, object, references) : destructiveObjectFinding(file, object, contract, references);
|
|
592
611
|
return finding ? [finding] : [];
|
|
593
612
|
});
|
|
613
|
+
for (const name of ruled) {
|
|
614
|
+
if (!objects.some((object) => object.name === name))
|
|
615
|
+
findings.push(found(DB_DESTRUCTIVE_RULING_UNPROVEN, file, `hfs.json db.destructiveRulings names ${name} for ${file}, which the migration does not destroy; a ruling names exactly the objects its migration destroys`, { object: name }));
|
|
616
|
+
}
|
|
617
|
+
return findings;
|
|
594
618
|
}
|
|
595
619
|
const BE_SQL_SOURCE = /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/;
|
|
596
620
|
/** The tag glob of a release (release.tagPrefix defaults to v). */
|
|
@@ -605,7 +629,8 @@ const RELEASE_TAG_GLOB = 'v*';
|
|
|
605
629
|
* DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
|
|
606
630
|
*/
|
|
607
631
|
export async function contractReleaseFindings({ repoRoot, migrations, git }) {
|
|
608
|
-
const
|
|
632
|
+
const rulings = destructiveRulings(repoRoot);
|
|
633
|
+
const contracts = migrations.filter((file) => CONTRACT_MIGRATION.test(file) || rulings.has(file));
|
|
609
634
|
if (!contracts.length)
|
|
610
635
|
return [];
|
|
611
636
|
const previous = await runGit(git, repoRoot, ['previous-release', RELEASE_TAG_GLOB]);
|
|
@@ -631,9 +656,11 @@ export async function contractReleaseFindings({ repoRoot, migrations, git }) {
|
|
|
631
656
|
const text = readText(repoRoot, file);
|
|
632
657
|
if (text === null)
|
|
633
658
|
return [];
|
|
634
|
-
|
|
659
|
+
// a ruled migration is judged here for its ruled objects only: its other objects are refused at HEAD already
|
|
660
|
+
const ruled = CONTRACT_MIGRATION.test(file) ? undefined : rulings.get(file);
|
|
661
|
+
return migrationDestructiveObjects(text).filter((object) => ruled === undefined || ruled.has(object.name)).flatMap((object) => {
|
|
635
662
|
const reference = references.find(({ scopes }) => referencesObject(scopes, object));
|
|
636
|
-
return reference ? [found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
|
|
663
|
+
return reference ? [found(ruled === undefined ? DB_MIGRATION_DESTRUCTIVE : DB_DESTRUCTIVE_RULING_UNPROVEN, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
|
|
637
664
|
});
|
|
638
665
|
});
|
|
639
666
|
}
|
|
@@ -644,8 +671,14 @@ export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
|
|
|
644
671
|
if (sources.length && !ts)
|
|
645
672
|
return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'destructive migration checks require the TypeScript parser to read be/src references')];
|
|
646
673
|
const references = ts ? sources.map((file) => ({ file, scopes: sourceNameScopes(ts, readText(repoRoot, file) ?? '', file) })) : [];
|
|
647
|
-
|
|
674
|
+
const rulings = destructiveRulings(repoRoot);
|
|
675
|
+
const findings = migrations.flatMap((file) => {
|
|
648
676
|
const text = readText(repoRoot, file);
|
|
649
|
-
return text === null ? [] : destructiveFileFindings(file, text, references);
|
|
677
|
+
return text === null ? [] : destructiveFileFindings(file, text, references, rulings.get(file));
|
|
650
678
|
});
|
|
679
|
+
for (const migration of rulings.keys()) {
|
|
680
|
+
if (!migrations.includes(migration))
|
|
681
|
+
findings.push(found(DB_DESTRUCTIVE_RULING_UNPROVEN, 'hfs.json', `hfs.json db.destructiveRulings names ${migration}, which is no active migration; a ruling names the exact file it covers`, { migration }));
|
|
682
|
+
}
|
|
683
|
+
return findings;
|
|
651
684
|
}
|