@starci/eslint-canon-be 3.4.41 → 3.4.43
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 +4 -1
- package/idempotency.mjs +115 -28
- package/package.json +1 -1
- package/runtime/knowledge/hfs/canon-pins.yaml +5 -5
- package/runtime/knowledge/hfs/rules.yaml +106 -6
- package/runtime/knowledge/hfs/slots.yaml +8 -6
- package/runtime/scripts/hfs/architecture/typescript.mjs +1 -1
- package/runtime/scripts/hfs/declaration-slots.mjs +6 -4
- package/runtime/scripts/hfs/rule-params-shape.mjs +5 -3
- package/runtime/scripts/hfs/slot-side-problems.mjs +2 -2
- package/runtime/scripts/hfs/slots.mjs +1 -1
- package/runtime/scripts/lib/secret-patterns.mjs +58 -9
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 3.4.43 - 2026-10-26
|
|
4
|
+
- Changed: `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`) accepts a delivery whose one write transaction hands its work to a typed helper: the sole `.transaction(...)` runs on typeorm's `EntityManager` or on a port the `platform/database` owner declares, its arrow callback returns `this.<method>(..., tx, ...)` of the same class (resolved by the checker), and that async helper claims first with the never-reassigned manager parameter and returns on `false`. The database port also runs the inline claim callback. A helper that never claims, claims after other work or under a condition, claims with another manager, a lookalike runner, a callback that hands work to another object or detaches it, and an ignored claim answer stay refused; every form refused before stays refused.
|
|
5
|
+
|
|
6
|
+
## 3.4.42 - 2026-10-26
|
|
4
7
|
- Changed: `operation-table-schemas` and `operation-contract-decidable` leave alone a stub table a spec keeps to itself, but judge one a spec exports (`export const`, `export { }`, `export default`); `rest-route-declared` never counts a table made in a spec as the app's declared table. The same stub table in a production file stays refused.
|
|
5
8
|
- Changed: R95 requires named zod input/output schema exports for every `defineOperations` entry (`operation-table-schemas`) and a canon `OperationValidationPolicy` constructed with the same table on the route body (`operation-route-driven-by-table`). Schema provenance and route binding are proved in both editions, including strict empty inputs, aliases, mismatched tables and local imitations.
|
|
6
9
|
|
package/idempotency.mjs
CHANGED
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* - `inbox-dedupe-required` judges every DELIVERY method of a service. Doors (consumers, `SignedWebhook` controllers) are
|
|
10
10
|
* thin (R88): they map the delivery and dispatch one message, so the claim lives in the `*.service.ts` the handler calls,
|
|
11
11
|
* inside its transaction. A delivery method is a public method of a `<name>.service.ts` whose FIRST parameter has an
|
|
12
|
-
* `eventId` property, read by the parameter's TYPE. Its first awaited work is the Inbox claim, directly or
|
|
13
|
-
*
|
|
12
|
+
* `eventId` property, read by the parameter's TYPE. Its first awaited work is the Inbox claim, directly or as the
|
|
13
|
+
* first work of the one write transaction it runs, with that transaction's manager, and the method must return
|
|
14
14
|
* early when the claim answers `false`. A lookalike `Inbox` declared by another owner, a renamed receiver and a
|
|
15
15
|
* property injection are all judged by the receiver's type, so only the real port satisfies the rule; a keyword or a
|
|
16
16
|
* class name never does.
|
|
@@ -20,15 +20,27 @@
|
|
|
20
20
|
* if ((await this.inbox.claim(source, id)) === false) { return }
|
|
21
21
|
* const fresh = await this.inbox.claim(source, id)
|
|
22
22
|
* if (!fresh) return
|
|
23
|
-
* A transaction delivery returns or awaits one transaction as its sole statement
|
|
24
|
-
*
|
|
25
|
-
*
|
|
23
|
+
* A transaction delivery returns or awaits one `.transaction(...)` as its sole statement, on a receiver typed as typeorm's
|
|
24
|
+
* `EntityManager` or as a port the `platform/database` owner declares; the callback's one parameter is typed `EntityManager`.
|
|
25
|
+
* Either the actual selected inline async callback claims with that manager in its first statement, then returns on false,
|
|
26
|
+
* or an arrow callback hands its whole work to one `this.<method>(..., tx, ...)` of the same class, resolved by the checker:
|
|
27
|
+
* that async helper receives the manager in a never-reassigned `EntityManager` parameter, prepares only `const` arguments,
|
|
28
|
+
* and its first await is the claim with that parameter at its top level, followed by the return on false:
|
|
29
|
+
* return this.manager.transaction((tx) => this.recordInTransaction(delivery, tx))
|
|
30
|
+
* async recordInTransaction(delivery: Delivery, manager: EntityManager) {
|
|
31
|
+
* const key = keyOf(delivery)
|
|
32
|
+
* if (!(await this.inbox.claim(source, key, manager))) return this.readRepeat(delivery, manager)
|
|
33
|
+
* return this.write(delivery, manager)
|
|
34
|
+
* }
|
|
35
|
+
* No outer work runs after a duplicate. A lookalike runner (a `transaction` method on a type no package or database owner
|
|
36
|
+
* declares), a callback that hands work to another object and a helper reached through a further call are refused.
|
|
37
|
+
* Synchronous effects before a claim, getters and helpers called past the first one stay review questions.
|
|
26
38
|
*/
|
|
27
39
|
import { hfsOf } from "./lib/hfs.mjs"
|
|
28
40
|
import { walk } from "./lib/ast.mjs"
|
|
29
41
|
import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
|
|
30
42
|
import { resolveVariable } from "./lib/transactions.mjs"
|
|
31
|
-
import { isPackageType, typed } from "./lib/types.mjs"
|
|
43
|
+
import { isPackageType, typeOrigins, typed } from "./lib/types.mjs"
|
|
32
44
|
import { mutationIdempotent } from "./lib/client-idempotency.mjs"
|
|
33
45
|
|
|
34
46
|
/** The `Inbox` port of `platform/inbox`. */
|
|
@@ -87,8 +99,15 @@ const hasPriorEffect = (expression, call) => {
|
|
|
87
99
|
return found
|
|
88
100
|
}
|
|
89
101
|
|
|
90
|
-
/**
|
|
91
|
-
const
|
|
102
|
+
/** A transaction port the `platform/database` owner declares: a receiver typed by that owner, never by its name. */
|
|
103
|
+
const isDatabasePort = (context, node) => {
|
|
104
|
+
const hfs = hfsOf(context)
|
|
105
|
+
return typeOrigins(context, node).some((origin) =>
|
|
106
|
+
origin.module === null && hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === "database")
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** The callback a sole, returned or awaited `.transaction(...)` runs on an EntityManager or the database port, and its manager parameter. */
|
|
110
|
+
const soleTransactionCallback = (context, body) => {
|
|
92
111
|
if (body.body.length !== 1) return null
|
|
93
112
|
const outer = body.body[0]
|
|
94
113
|
const expression = outer.type === "ReturnStatement" ? outer.argument
|
|
@@ -96,32 +115,100 @@ const transactionClaim = (context, body) => {
|
|
|
96
115
|
const call = expression?.type === "AwaitExpression" ? expression.argument : expression
|
|
97
116
|
const callee = call?.callee
|
|
98
117
|
if (call?.type !== "CallExpression" || callee.type !== "MemberExpression" || callee.computed
|
|
99
|
-
|| callee.property.type !== "Identifier" || callee.property.name !== "transaction"
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
118
|
+
|| callee.property.type !== "Identifier" || callee.property.name !== "transaction" || hasPriorEffect(call, call)) return null
|
|
119
|
+
let callback = null
|
|
120
|
+
if (isPackageType(context, callee.object, "EntityManager", "typeorm")) {
|
|
121
|
+
// TypeORM runs arg0 when it is a function, otherwise arg1. Never accept a later, ignored callback.
|
|
122
|
+
const isolation = call.arguments[0]
|
|
123
|
+
callback = call.arguments.length === 1 ? isolation
|
|
124
|
+
: call.arguments.length === 2 && isolation.type === "Literal"
|
|
125
|
+
&& ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"].includes(isolation.value)
|
|
126
|
+
? call.arguments[1] : null
|
|
127
|
+
} else if (isDatabasePort(context, callee.object) && call.arguments.length === 1) callback = call.arguments[0]
|
|
128
|
+
if (!callback || !["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type) || callback.params.length !== 1) return null
|
|
109
129
|
const manager = callback.params[0]
|
|
110
130
|
if (manager.type !== "Identifier" || !isPackageType(context, manager, "EntityManager", "typeorm")) return null
|
|
111
|
-
|
|
131
|
+
return { callback, manager }
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** True when `argument` is the identifier bound to the parameter `param`; with `unwritten`, that parameter is also never reassigned. */
|
|
135
|
+
const isParameter = (context, argument, param, { unwritten = false } = {}) => {
|
|
136
|
+
const binding = resolveVariable(context.sourceCode, param)
|
|
137
|
+
const argumentBinding = argument?.type === "Identifier" ? resolveVariable(context.sourceCode, argument) : null
|
|
138
|
+
return !!binding && binding.defs[0]?.name === param && argumentBinding === binding
|
|
139
|
+
&& !(unwritten && binding.references.some((reference) => reference.isWrite()))
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** The statement of a block that holds its first await as the claim it tests, stores or awaits; null when that await sits deeper. */
|
|
143
|
+
const claimStatement = (block) => {
|
|
144
|
+
const awaited = firstAwait(block)
|
|
112
145
|
const parent = awaited?.parent
|
|
113
146
|
const statement = parent?.type === "VariableDeclarator" && parent.init === awaited
|
|
114
147
|
&& parent.parent.declarations.length === 1 ? parent.parent
|
|
115
148
|
: ["UnaryExpression", "BinaryExpression"].includes(parent?.type) ? parent.parent
|
|
116
149
|
: parent?.type === "ExpressionStatement" ? parent : null
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
if (!
|
|
123
|
-
|
|
124
|
-
return
|
|
150
|
+
return statement?.parent === block ? { awaited, statement } : null
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** The claim that opens the inline async callback with its own manager, as its first statement. */
|
|
154
|
+
const inlineClaim = (context, { callback, manager }) => {
|
|
155
|
+
if (!callback.async || callback.body.type !== "BlockStatement") return null
|
|
156
|
+
const found = claimStatement(callback.body)
|
|
157
|
+
if (!found || found.statement !== callback.body.body[0]) return null
|
|
158
|
+
const claim = found.awaited.argument
|
|
159
|
+
if (claim?.type !== "CallExpression" || !isParameter(context, claim.arguments[2], manager) || hasPriorEffect(found.statement, claim)) return null
|
|
160
|
+
return found.awaited
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** The `this.<method>(...)` call an arrow callback hands its whole work to: its expression body, or its sole returned or awaited statement. */
|
|
164
|
+
const handedCall = (callback) => {
|
|
165
|
+
if (callback.type !== "ArrowFunctionExpression") return null
|
|
166
|
+
let expression = callback.body
|
|
167
|
+
if (expression.type === "BlockStatement") {
|
|
168
|
+
const [sole] = expression.body
|
|
169
|
+
if (expression.body.length !== 1) return null
|
|
170
|
+
expression = sole.type === "ReturnStatement" ? sole.argument
|
|
171
|
+
: sole.type === "ExpressionStatement" && sole.expression.type === "AwaitExpression" ? sole.expression : null
|
|
172
|
+
}
|
|
173
|
+
const call = expression?.type === "AwaitExpression" ? expression.argument : expression
|
|
174
|
+
const callee = call?.callee
|
|
175
|
+
return call?.type === "CallExpression" && callee.type === "MemberExpression" && !callee.computed
|
|
176
|
+
&& callee.object.type === "ThisExpression" && callee.property.type === "Identifier" ? call : null
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* The claim of a typed helper the callback delegates to: a method of the delivery's own class, resolved by the checker, that receives
|
|
181
|
+
* the callback's manager, awaits nothing before the claim, claims with that parameter at its top level and runs no statement but `const`
|
|
182
|
+
* argument preparation before it.
|
|
183
|
+
*/
|
|
184
|
+
const delegatedClaim = (context, delivery, { callback, manager }) => {
|
|
185
|
+
const call = handedCall(callback)
|
|
186
|
+
if (!call || hasPriorEffect(call, call)) return null
|
|
187
|
+
const position = call.arguments.findIndex((argument) => argument.type === "Identifier" && argument.name === manager.name)
|
|
188
|
+
if (position < 0 || !isParameter(context, call.arguments[position], manager)) return null
|
|
189
|
+
const { checker, toTs } = typed(context)
|
|
190
|
+
const declarations = checker.getSymbolAtLocation(toTs(call.callee.property))?.getDeclarations?.() ?? []
|
|
191
|
+
const helper = declarations.length === 1
|
|
192
|
+
? delivery.parent.body.find((member) => member.type === "MethodDefinition" && toTs(member) === declarations[0]) : undefined
|
|
193
|
+
if (!helper || helper === delivery || helper.kind !== "method" || helper.static || !helper.value.async || !helper.value.body) return null
|
|
194
|
+
const param = helper.value.params[position]
|
|
195
|
+
if (param?.type !== "Identifier" || !isPackageType(context, param, "EntityManager", "typeorm")) return null
|
|
196
|
+
const body = helper.value.body
|
|
197
|
+
const found = claimStatement(body)
|
|
198
|
+
if (!found) return null
|
|
199
|
+
const before = body.body.slice(0, body.body.indexOf(found.statement))
|
|
200
|
+
if (before.some((statement) => statement.type !== "VariableDeclaration" || statement.kind !== "const")) return null
|
|
201
|
+
const claim = found.awaited.argument
|
|
202
|
+
if (claim?.type !== "CallExpression" || !isParameter(context, claim.arguments[2], param, { unwritten: true })
|
|
203
|
+
|| hasPriorEffect(found.statement, claim)) return null
|
|
204
|
+
return found.awaited
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** The first awaited claim of a delivery that runs as one transaction: inline in its callback, or in the typed helper that callback delegates to. */
|
|
208
|
+
const transactionClaim = (context, delivery) => {
|
|
209
|
+
const transaction = soleTransactionCallback(context, delivery.value.body)
|
|
210
|
+
if (!transaction) return null
|
|
211
|
+
return inlineClaim(context, transaction) ?? delegatedClaim(context, delivery, transaction)
|
|
125
212
|
}
|
|
126
213
|
/** Whether a parameter's type has an `eventId` property: the shape of a delivery. */
|
|
127
214
|
const isDeliveryParam = (context, param) => {
|
|
@@ -157,7 +244,7 @@ export const inboxDedupeRequired = {
|
|
|
157
244
|
if (node.accessibility === "private" || node.accessibility === "protected") return
|
|
158
245
|
const first = node.value.params[0]
|
|
159
246
|
if (!first || !isDeliveryParam(context, first)) return
|
|
160
|
-
const awaited = transactionClaim(context, node
|
|
247
|
+
const awaited = transactionClaim(context, node) ?? firstAwait(node.value.body)
|
|
161
248
|
const call = awaited?.argument
|
|
162
249
|
const claims = call?.type === "CallExpression"
|
|
163
250
|
&& call.callee.type === "MemberExpression"
|
package/package.json
CHANGED
|
@@ -23,21 +23,21 @@ pins:
|
|
|
23
23
|
source: packages/heroicons/package.json
|
|
24
24
|
why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
|
|
25
25
|
'@starci/grammar':
|
|
26
|
-
version: 0.12.
|
|
26
|
+
version: 0.12.1
|
|
27
27
|
group: starci
|
|
28
28
|
install: registry
|
|
29
29
|
side: fe
|
|
30
30
|
source: packages/grammar/package.json
|
|
31
31
|
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.'
|
|
32
32
|
'@starci/eslint-canon-be':
|
|
33
|
-
version: 3.4.
|
|
33
|
+
version: 3.4.43
|
|
34
34
|
group: starci
|
|
35
35
|
install: registry
|
|
36
36
|
side: be
|
|
37
37
|
source: packages/eslint/be/package.json
|
|
38
38
|
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.'
|
|
39
39
|
'@starci/eslint-canon-fe':
|
|
40
|
-
version: 8.4.
|
|
40
|
+
version: 8.4.42
|
|
41
41
|
group: starci
|
|
42
42
|
install: registry
|
|
43
43
|
side: fe
|
|
@@ -77,14 +77,14 @@ pins:
|
|
|
77
77
|
source: packages/test-world/package.json
|
|
78
78
|
why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
|
|
79
79
|
'@starci/cli':
|
|
80
|
-
version: 1.7.
|
|
80
|
+
version: 1.7.34
|
|
81
81
|
group: starci
|
|
82
82
|
install: registry
|
|
83
83
|
side: both
|
|
84
84
|
source: packages/cli/package.json
|
|
85
85
|
why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
|
|
86
86
|
'@starci/hfs':
|
|
87
|
-
version: 4.7.
|
|
87
|
+
version: 4.7.34
|
|
88
88
|
group: starci
|
|
89
89
|
install: registry
|
|
90
90
|
side: both
|
|
@@ -167,7 +167,7 @@ rules:
|
|
|
167
167
|
code: "HFS_STACKS_SHAPE"
|
|
168
168
|
editions: [lite, full]
|
|
169
169
|
docs: [docs/legacy-tree-rule-coverage.md#r10]
|
|
170
|
-
law: "`.starcistacks` has the edition-aware standard shape and the host Sonar owner; Swarm stacks have digest-pinned images, healthchecks, rollout, rollback and restart policies, versioned external secrets, ingress-only published ports and declared schedulers for replicated jobs. Recurring work is app-owned; host crontab installation is forbidden. Lite declares Supabase as managed backing and runs no duplicate backing-service component."
|
|
170
|
+
law: "`.starcistacks` has the edition-aware standard shape and the host Sonar owner. STACK-DEV keeps every dependency in Docker Linux containers in development (local Supabase through its CLI); application processes follow their declared development profile. Production runs the app and dependencies on Docker Swarm except hosted Supabase, the only admitted managed backing provider (owner:dev-docker-prod-swarm). Swarm stacks have digest-pinned images, healthchecks, rollout, rollback and restart policies, versioned external secrets, ingress-only published ports and declared schedulers for replicated jobs. Recurring work is app-owned; host crontab installation is forbidden. Lite declares Supabase as managed backing and runs no duplicate backing-service component."
|
|
171
171
|
kinds: [check, codemod]
|
|
172
172
|
gates: [settle, land, ci]
|
|
173
173
|
failureCodes: ["HFS_STACKS_SHAPE"]
|
|
@@ -3599,7 +3599,7 @@ rules:
|
|
|
3599
3599
|
docs: [docs/lite-edition.md#edition-validation]
|
|
3600
3600
|
templateNa: "The hfs.json edition declaration is generated programmatically by packages/hfs/scaffold/app.mjs; no managed declaration template exists. Forbidden paths are rejected rather than scaffolded."
|
|
3601
3601
|
code: "HFS_EDITION_INVALID"
|
|
3602
|
-
law: "hfs.json names an edition the manifest knows (full, or lite; absent means full). Lite is a minimal production (case-10): the same monorepo, code structure, slots, patterns and back-end unit specs, one stateless instance type that scales horizontally, managed Supabase for Postgres, Auth and Storage, and one minimal instance of each backing service a declared capability needs (hfs.json sides.be.backing: Redis for the queue, with AOF persistence;
|
|
3602
|
+
law: "hfs.json names an edition the manifest knows (full, or lite; absent means full). Lite is a minimal production (case-10): the same monorepo, code structure, slots, patterns and back-end unit specs, one stateless instance type that scales horizontally, managed Supabase for Postgres, Auth and Storage, and one minimal instance of each backing service a declared capability needs (hfs.json sides.be.backing: Redis for the queue, with AOF persistence); vector search uses Supabase pgvector (owner:lite-vector-is-pgvector, which excludes Qdrant from lite); a backing service is declared or absent, never on by default. The queue is BullMQ on Redis in both editions, fed by the Postgres outbox; pg_cron ticks enqueue through that outbox; the event bus keeps its lite adapter (pgmq-backed topics or in-process delivery) because full's event bus is Kafka, not Redis; cache and locks are Postgres unless Redis is declared; the api and sidecars run on docker-swarm on a VPS. The realtime pattern serves SSE (the default for one-way push), the same socket.io gateway or the restricted GraphQL subscription inside the be api process (scales horizontally and stateless: the memory hub is for a single replica or tests only, and replicas > 1 use the Redis hub and the sharded @socket.io/redis-adapter when Redis is declared, else the Postgres hub and @socket.io/postgres-adapter; both shared socket adapters force websocket-only connections with no sticky sessions; R212 case-9, which amends the realtime clauses of case-2, case-3 and case-5; the GraphQL subscription door is R212 case-7 and owner:lite-graphql-subscription-door), and both editions share knowledge/hfs/fe-stack.yaml. Lite requires application-stacks.yaml and permits environment metadata, runbooks, infra/swarm and encrypted-secret custody, while refusing infra/compose, infra/k8s, infra/terraform and components duplicating Supabase backing services (runtime/{config,env}, seeds and the sealed secrets of its environments are allowed). Contract specs and `test:contract` are allowed (owner 2026-10-14); it has no e2e spec, `test:e2e`, `test:stack` or `test:browser` script, e2e workflow, browser journey, Work catalog, shell, features, resources, UAT or br records, test container, toxiproxy, browser-runner or Kafka dependency, client library of an undeclared backing service (HFS_BACKING_UNDECLARED), declared backing service without a consumer (HFS_BACKING_UNUSED), or supabase/functions. Its .starciwork is optional and admits only .gitignore, workspace.yaml and brand/**; workspace.yaml is optional and carries project identity and repo roles for the Work tools."
|
|
3603
3603
|
kinds: [check]
|
|
3604
3604
|
gates: [settle, land, ci]
|
|
3605
3605
|
failureCodes: ["HFS_EDITION_INVALID", "HFS_EDITION_FORBIDDEN_PRESENT", "HFS_STARCIWORK_LITE_FORBIDDEN", "HFS_BACKING_UNDECLARED", "HFS_BACKING_UNUSED"]
|
|
@@ -3643,7 +3643,7 @@ rules:
|
|
|
3643
3643
|
date: "2026-10-24"
|
|
3644
3644
|
source: owner
|
|
3645
3645
|
quote: "GraphQL subscriptions are allowed in lite too, as a restricted door; SSE stays the default for one-way push and WebSocket the choice for two-way. (alpha.31 realtime canon brief, owner decisions 2026-10-24, relayed by the lead)"
|
|
3646
|
-
ruling: "The GraphQL subscription is the third restricted door of the realtime pattern in both editions (slot be.feature.realtime.graphql and its dto slot, no longer full-only; graphql-ws and graphql-subscriptions are owned by platform/realtime in lite as in full). SSE stays the default for one-way push, the socket.io gateway is the door for two-way messages, and the GraphQL subscription is used only when the client already uses GraphQL and needs the typed schema payload, with a snapshot refetch on reconnect because graphql-ws has no replay. Every door rule stays: a door reads and pushes only, topics are built from the principal, a door is never public and no token travels in the URL. The memory hub is non-scale (tests and one replica); the hub is Redis when Redis is declared (lite or full) and Postgres LISTEN/NOTIFY when lite declares no Redis. The lite Redis gate and the R212 clause that refused Redis are retired by case-10 (final owner ruling 2026-10-24: lite is a minimal production
|
|
3646
|
+
ruling: "The GraphQL subscription is the third restricted door of the realtime pattern in both editions (slot be.feature.realtime.graphql and its dto slot, no longer full-only; graphql-ws and graphql-subscriptions are owned by platform/realtime in lite as in full). SSE stays the default for one-way push, the socket.io gateway is the door for two-way messages, and the GraphQL subscription is used only when the client already uses GraphQL and needs the typed schema payload, with a snapshot refetch on reconnect because graphql-ws has no replay. Every door rule stays: a door reads and pushes only, topics are built from the principal, a door is never public and no token travels in the URL. The memory hub is non-scale (tests and one replica); the hub is Redis when Redis is declared (lite or full) and Postgres LISTEN/NOTIFY when lite declares no Redis. The lite Redis gate and the R212 clause that refused Redis are retired by case-10 (final owner ruling 2026-10-24: lite is a minimal production with declared Redis; owner:lite-vector-is-pgvector narrows its vector store to Supabase pgvector). This amends the clause of case-5 that kept the subscription door full-only."
|
|
3647
3647
|
- id: case-8
|
|
3648
3648
|
date: "2026-10-24"
|
|
3649
3649
|
source: owner
|
|
@@ -3658,7 +3658,7 @@ rules:
|
|
|
3658
3658
|
date: "2026-10-24"
|
|
3659
3659
|
source: owner
|
|
3660
3660
|
quote: "Lite still has Redis, Qdrant and the like!!! That is, it deploys a minimal production. Lite is one instance that scales horizontally and is stateless! Full's infrastructure is more complex. Lite cannot go up to full!!! Lite is lite, full is full. The queue is Redis!!! (translated from Vietnamese; the owner approved the ruling table with \"ok, fix all of it, that is right\")"
|
|
3661
|
-
ruling: "This case replaces the clauses of case-1, case-2 and case-3 that ban backing services in lite and the clause of case-7 that keeps Redis out of the realtime hub of lite (no BullMQ or Redis, one instance with no Redis adapter, the full architecture minus self-hosted infrastructure, the queue on pgmq). Lite is a minimal production: one instance type (one api, an optional worker) that is stateless and scales horizontally, managed Supabase for Postgres, Auth and Storage, and one minimal instance of each backing service a declared capability needs, deployed compactly on docker-swarm; full is several services each with its own database plus Redis, Kafka/CDC, its own IdP, object storage and observability on a multi-node stack. A backing service is declared or absent: hfs.json sides.be.backing names
|
|
3661
|
+
ruling: "This case replaces the clauses of case-1, case-2 and case-3 that ban backing services in lite and the clause of case-7 that keeps Redis out of the realtime hub of lite (no BullMQ or Redis, one instance with no Redis adapter, the full architecture minus self-hosted infrastructure, the queue on pgmq). Lite is a minimal production: one instance type (one api, an optional worker) that is stateless and scales horizontally, managed Supabase for Postgres, Auth and Storage, and one minimal instance of each backing service a declared capability needs, deployed compactly on docker-swarm; full is several services each with its own database plus Redis, Kafka/CDC, its own IdP, object storage and observability on a multi-node stack. A backing service is declared or absent: hfs.json sides.be.backing names redis in lite (redis or qdrant in full), nothing is on by default; owner:lite-vector-is-pgvector narrows the lite vector store to Supabase pgvector and refuses Qdrant even when declared, the lite stack renders only declared services (STACKS_LITE_SELFHOSTED_DB), a client library of an undeclared service is refused (HFS_BACKING_UNDECLARED) and a declared service without a consumer is refused (HFS_BACKING_UNUSED). The queue is BullMQ on Redis in both editions behind the same platform/queue ports (outbox in Postgres, relay to BullMQ, processors, retry with exponential backoff, failed jobs kept as the dead letter); pgmq is not a queue transport, a declared queue or fenced-job pattern requires Redis, and a pg_cron tick enqueues through the queue outbox. The lite Redis runs with AOF persistence (appendonly yes) on a named volume because queue jobs must not be lost (STACKS_LITE_REDIS_PERSISTENCE); cache, rate limit and realtime pub/sub may share that instance, which keeps maxmemory-policy noeviction so no queue job is evicted. Durable data and the outbox stay in Postgres. MongoDB stays out of lite. Editions are fixed at scaffold (case-6)."
|
|
3662
3662
|
proves: [packages/hfs/src/hfs-edition-invalid.spec.mjs, packages/hfs/src/hfs-edition-forbidden-present.spec.mjs, packages/hfs/src/hfs-starciwork-lite-forbidden.spec.mjs, packages/hfs/src/hfs-backing-declared.spec.mjs]
|
|
3663
3663
|
exemplifiedBy:
|
|
3664
3664
|
- {path: packages/hfs/src/hfs-edition-invalid.spec.mjs, editions: [lite, full]}
|
|
@@ -4773,14 +4773,14 @@ rules:
|
|
|
4773
4773
|
- {path: packages/hfs/src/hfs-stacks-full-fixtures.spec.mjs, edition: full}
|
|
4774
4774
|
- id: R276
|
|
4775
4775
|
code: "STACKS_LITE_SELFHOSTED_DB"
|
|
4776
|
-
law: "Lite keeps PostgreSQL on managed Supabase and runs no PostgreSQL or
|
|
4776
|
+
law: "Lite keeps PostgreSQL and vector search on managed Supabase pgvector and runs no PostgreSQL, MongoDB or Qdrant backing image, even when declared (owner:lite-vector-is-pgvector). A Redis image runs only when hfs.json sides.be.backing declares redis (ruling:R212/case-10), as one minimal instance; a declared Redis runs as exactly one stack service, with AOF persistence (`appendonly yes`, `appendfsync everysec` or `always`, never `no`) on a writable named volume so queue jobs survive a restart and with no maxmemory-policy but noeviction so none is evicted. A queue job Redis loses inside the at most one second `everysec` leaves unwritten is not lost work: every job is born from a Postgres outbox row, and the relay marks that row sent only after Redis confirms the job is in its append-only file (WAITAOF) and still holds it, so a job Redis did not persist leaves its row waiting and the relay adds it again (examples/lite-app queue-relay.service.spec.ts and bullmq-queue-transport.client.spec.ts). A sidecar keeps its own SQLite on a named persistent volume declared by its component and mounted in the rendered model, and never uses the app's declared Redis, which serves the back-end app services only; a sidecar requiring another database, that Redis included, is refused. Full retains its declared backing topology."
|
|
4777
4777
|
kinds: [check]
|
|
4778
4778
|
gates: ["settle","land","ci"]
|
|
4779
4779
|
failureCodes: ["STACKS_LITE_SELFHOSTED_DB", "STACKS_SIDECAR_VOLUME_UNDECLARED", "STACKS_SIDECAR_DB_UNSUPPORTED", "STACKS_LITE_REDIS_PERSISTENCE"]
|
|
4780
4780
|
enforcers:
|
|
4781
4781
|
- {kind: hfs, id: stacks-lite-backing, at: scripts/hfs/rules/stacks-lite-backing.mjs}
|
|
4782
4782
|
editions: ["lite"]
|
|
4783
|
-
editionWhy: "ruling:R276 records owner ruling 4, amended by ruling:R212/case-10: lite keeps Postgres on managed Supabase, runs a Redis
|
|
4783
|
+
editionWhy: "ruling:R276 records owner ruling 4, amended by ruling:R212/case-10: lite keeps Postgres on managed Supabase, uses Supabase pgvector for vectors, refuses Qdrant even when declared (owner:lite-vector-is-pgvector), runs a Redis instance only when declared, runs a declared Redis as one service persisted with AOF fsynced at least every second on a named volume and never evicting (the outbox relay re-adds a job Redis did not persist), and permits database-dependent sidecars only with SQLite on declared persistent volumes, never on the app's Redis; full keeps its declared backing topology."
|
|
4784
4784
|
docs:
|
|
4785
4785
|
- "docs/application-stacks.md#r276"
|
|
4786
4786
|
proves: [packages/hfs/src/hfs-stacks-lite-backing.spec.mjs]
|
|
@@ -5448,3 +5448,103 @@ rules:
|
|
|
5448
5448
|
witness:
|
|
5449
5449
|
- {path: packages/eslint/be/uploads.spec.mjs, editions: [lite, full], codes: [BE_UPLOAD_BUFFERED]}
|
|
5450
5450
|
templateNa: "A storage grant is declared per integration; the canon scaffolds none, and the presigned-upload examples of both editions are the reference."
|
|
5451
|
+
- id: R313
|
|
5452
|
+
code: "FE_APP_SHELL_FRAME"
|
|
5453
|
+
law: "FE-APP-SHELL-1 requires WorkspaceShell viewport=fixed to own the application frame, including persistent header and navigation; hand-built header/nav frames are refused."
|
|
5454
|
+
kinds: [lint, design]
|
|
5455
|
+
gates: [pre-commit, settle, land, ci]
|
|
5456
|
+
failureCodes: ["FE_APP_SHELL_FRAME"]
|
|
5457
|
+
enforcers:
|
|
5458
|
+
- {kind: eslint-fe, id: app-shell-frame}
|
|
5459
|
+
editions: [lite, full]
|
|
5460
|
+
docs:
|
|
5461
|
+
- {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
|
|
5462
|
+
proves:
|
|
5463
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
|
|
5464
|
+
exemplifiedBy:
|
|
5465
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
|
|
5466
|
+
- {path: examples/full-app/fe/apps/app/src/features/layouts/ShopLayout/component.tsx, edition: full}
|
|
5467
|
+
- {path: examples/lite-app/fe/apps/web/src/features/layouts/WorkspaceLayout/component.tsx, edition: lite}
|
|
5468
|
+
witness:
|
|
5469
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
|
|
5470
|
+
templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
|
|
5471
|
+
- id: R314
|
|
5472
|
+
code: "FE_NAVBAR_CONTROL_SIZE"
|
|
5473
|
+
law: "FE-APP-SHELL-2 requires every navbar control to declare size=control so Grammar owns the common control height."
|
|
5474
|
+
kinds: [lint, design]
|
|
5475
|
+
gates: [pre-commit, settle, land, ci]
|
|
5476
|
+
failureCodes: ["FE_NAVBAR_CONTROL_SIZE"]
|
|
5477
|
+
enforcers:
|
|
5478
|
+
- {kind: eslint-fe, id: navbar-control-size}
|
|
5479
|
+
editions: [lite, full]
|
|
5480
|
+
docs:
|
|
5481
|
+
- {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
|
|
5482
|
+
proves:
|
|
5483
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
|
|
5484
|
+
exemplifiedBy:
|
|
5485
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
|
|
5486
|
+
- {path: examples/full-app/fe/packages/ecommerce-ui/src/branches/WorkspaceNavbar/component.tsx, edition: full}
|
|
5487
|
+
- {path: examples/lite-app/fe/apps/web/src/components/branches/Navbar/component.tsx, edition: lite}
|
|
5488
|
+
witness:
|
|
5489
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
|
|
5490
|
+
templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
|
|
5491
|
+
- id: R315
|
|
5492
|
+
code: "FE_NAVBAR_CLUSTER"
|
|
5493
|
+
law: "FE-APP-SHELL-3 requires the statically composed navbar right cluster to contain a tertiary language IconButton opening DropdownMenu, a theme Switch, a notification IconButton opening Popover and an account AvatarButton opening DropdownMenu, in that order."
|
|
5494
|
+
kinds: [lint, design]
|
|
5495
|
+
gates: [pre-commit, settle, land, ci]
|
|
5496
|
+
failureCodes: ["FE_NAVBAR_CLUSTER"]
|
|
5497
|
+
enforcers:
|
|
5498
|
+
- {kind: eslint-fe, id: navbar-cluster}
|
|
5499
|
+
editions: [lite, full]
|
|
5500
|
+
docs:
|
|
5501
|
+
- {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
|
|
5502
|
+
proves:
|
|
5503
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
|
|
5504
|
+
exemplifiedBy:
|
|
5505
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
|
|
5506
|
+
- {path: examples/full-app/fe/packages/ecommerce-ui/src/branches/WorkspaceNavbar/component.tsx, edition: full}
|
|
5507
|
+
- {path: examples/lite-app/fe/apps/web/src/components/branches/Navbar/component.tsx, edition: lite}
|
|
5508
|
+
witness:
|
|
5509
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
|
|
5510
|
+
templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
|
|
5511
|
+
- id: R316
|
|
5512
|
+
code: "FE_APP_SHELL_BOTTOM_TABS"
|
|
5513
|
+
law: "FE-APP-SHELL-4 keeps navigation in the Sidebar drawer and refuses a bottom tab bar in the application shell."
|
|
5514
|
+
kinds: [lint, design]
|
|
5515
|
+
gates: [pre-commit, settle, land, ci]
|
|
5516
|
+
failureCodes: ["FE_APP_SHELL_BOTTOM_TABS"]
|
|
5517
|
+
enforcers:
|
|
5518
|
+
- {kind: eslint-fe, id: no-shell-bottom-tabs}
|
|
5519
|
+
editions: [lite, full]
|
|
5520
|
+
docs:
|
|
5521
|
+
- {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
|
|
5522
|
+
proves:
|
|
5523
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
|
|
5524
|
+
exemplifiedBy:
|
|
5525
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
|
|
5526
|
+
- {path: examples/full-app/fe/apps/app/src/features/layouts/ShopLayout/component.tsx, edition: full}
|
|
5527
|
+
- {path: examples/lite-app/fe/apps/web/src/features/layouts/WorkspaceLayout/component.tsx, edition: lite}
|
|
5528
|
+
witness:
|
|
5529
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
|
|
5530
|
+
templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
|
|
5531
|
+
- id: R317
|
|
5532
|
+
code: "FE_NAVBAR_CREATE"
|
|
5533
|
+
law: "FE-APP-SHELL-5 places create actions on their pages and refuses them in the navbar."
|
|
5534
|
+
kinds: [lint, design]
|
|
5535
|
+
gates: [pre-commit, settle, land, ci]
|
|
5536
|
+
failureCodes: ["FE_NAVBAR_CREATE"]
|
|
5537
|
+
enforcers:
|
|
5538
|
+
- {kind: eslint-fe, id: no-navbar-create}
|
|
5539
|
+
editions: [lite, full]
|
|
5540
|
+
docs:
|
|
5541
|
+
- {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
|
|
5542
|
+
proves:
|
|
5543
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
|
|
5544
|
+
exemplifiedBy:
|
|
5545
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
|
|
5546
|
+
- {path: examples/full-app/fe/packages/ecommerce-ui/src/branches/WorkspaceNavbar/component.tsx, edition: full}
|
|
5547
|
+
- {path: examples/lite-app/fe/apps/web/src/components/branches/Navbar/component.tsx, edition: lite}
|
|
5548
|
+
witness:
|
|
5549
|
+
- {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
|
|
5550
|
+
templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
|
|
@@ -251,8 +251,8 @@ ruleParams:
|
|
|
251
251
|
socket.io: [platform/realtime]
|
|
252
252
|
graphql-subscriptions: [platform/realtime]
|
|
253
253
|
graphql-ws: [platform/realtime]
|
|
254
|
-
"@socket.io/postgres-adapter": [platform/realtime] # the stateless socket.io adapter of a scaled lite back end
|
|
255
|
-
"@socket.io/redis-adapter": [platform/realtime] # the sharded socket.io adapter of a scaled
|
|
254
|
+
"@socket.io/postgres-adapter": [platform/realtime] # the stateless socket.io adapter of a scaled lite back end without Redis
|
|
255
|
+
"@socket.io/redis-adapter": [platform/realtime] # the sharded socket.io adapter of a scaled back end on the declared Redis
|
|
256
256
|
pg: [platform/realtime] # the LISTEN connection of the Postgres hub; every other query goes through TypeORM
|
|
257
257
|
# R87 BE_CQRS_SHAPE no-event-bus: the in-process event vocabulary the rule refuses. `imports` maps a module
|
|
258
258
|
# specifier to the member names that are an in-process event; `[]` flags the package itself (its emitter packages
|
|
@@ -371,11 +371,11 @@ ruleParams:
|
|
|
371
371
|
# ruling:R212/case-10 (R212 HFS_BACKING_UNDECLARED / HFS_BACKING_UNUSED, R276 STACKS_LITE_SELFHOSTED_DB): THE backing services a back
|
|
372
372
|
# end may declare in hfs.json sides.be.backing. `clients` are the libraries that consume the service: one of them as a dependency
|
|
373
373
|
# is its consumer, and under lite none of them may be a dependency while the service is undeclared. `patterns` are the declared
|
|
374
|
-
# patterns that need the service. `images` are the image repositories (the last path segment) a
|
|
375
|
-
#
|
|
374
|
+
# patterns that need the service. `images` are the image repositories (the last path segment) a stack runs it from.
|
|
375
|
+
# `editions` limits admission: owner:lite-vector-is-pgvector keeps vector search on Supabase pgvector in lite.
|
|
376
376
|
backing:
|
|
377
377
|
redis: {clients: [bullmq, "@nestjs/bullmq", bull, "@nestjs/bull", ioredis, redis, "@keyv/redis", cache-manager-redis-yet, cache-manager-ioredis-yet, "@socket.io/redis-adapter"], patterns: [queue, fenced-job], images: [redis, redis-stack, redis-stack-server]}
|
|
378
|
-
qdrant: {clients: ["@qdrant/js-client-rest", "@qdrant/qdrant-js"], patterns: [], images: [qdrant]}
|
|
378
|
+
qdrant: {clients: ["@qdrant/js-client-rest", "@qdrant/qdrant-js"], patterns: [], images: [qdrant], editions: [full]}
|
|
379
379
|
# Edition lite (ruleParams(manifest, 'be', 'lite') merges these keys over the base; a map merges one level deep): the schema
|
|
380
380
|
# authority is the Supabase migration tree (supabase/migrations/*.sql, forward-only), so a lite back end holds no TypeORM
|
|
381
381
|
# migration or entity under be/ (R34/R35 read schemaAuthority; be.persistence's lite overlay allows neither). The unit roles,
|
|
@@ -389,6 +389,8 @@ ruleParams:
|
|
|
389
389
|
schemaAuthority: supabase
|
|
390
390
|
infraOwners:
|
|
391
391
|
kafkajs: []
|
|
392
|
+
"@qdrant/js-client-rest": []
|
|
393
|
+
"@qdrant/qdrant-js": []
|
|
392
394
|
|
|
393
395
|
slots:
|
|
394
396
|
|
|
@@ -764,7 +766,7 @@ slots:
|
|
|
764
766
|
- id: app.starcistacks
|
|
765
767
|
since: 3.1.0
|
|
766
768
|
profiles: [app]
|
|
767
|
-
editionWhy: "owner:lite-production-swarm: lite requires declared docker-swarm production with Supabase backing;
|
|
769
|
+
editionWhy: "owner:lite-production-swarm: lite requires declared docker-swarm production with Supabase backing; owner:dev-docker-prod-swarm keeps dependencies in Docker Linux containers in dev and the app and dependencies on Swarm in prod except hosted Supabase."
|
|
768
770
|
exemplifiedBy:
|
|
769
771
|
- {path: packages/hfs/templates/app/skeleton/.starcistacks/, edition: full}
|
|
770
772
|
- {path: packages/hfs/templates/app/skeleton-lite/.starcistacks/, edition: lite}
|
|
@@ -311,7 +311,7 @@ const packageIndexSource = workspace => {
|
|
|
311
311
|
};
|
|
312
312
|
|
|
313
313
|
/** The source entry a workspace import resolves to without a build: its export targets mapped back to source, `src/index.ts` for the package root. */
|
|
314
|
-
function workspaceSourceEntry(ts, workspace, specifier) {
|
|
314
|
+
export function workspaceSourceEntry(ts, workspace, specifier) {
|
|
315
315
|
if (!workspace.workspace || !workspace.name || !sameOrUnder(specifier, workspace.name)) return null;
|
|
316
316
|
const isRoot = specifier === workspace.name;
|
|
317
317
|
const candidates = isRoot && !workspace.exports ? manifestEntryTargets(workspace.manifest) : exportCandidates(workspace, specifier);
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// (a slot with `appKind`) and by declared pattern (a slot with `pattern: <name>` is enabled by `sides.<side>.patterns: [<name>]`, one
|
|
3
3
|
// mechanism for pattern slots). A cross-cutting pattern can instead be owned by the side's canonical proof scenario catalog.
|
|
4
4
|
// slots.mjs asks this file to judge a side's lists and to say whether a slot is enabled for a repository.
|
|
5
|
+
import { judgedInEdition } from './edition-slots.mjs';
|
|
5
6
|
|
|
6
7
|
/** The problems of a side's `optionalSlots` and `patterns` against the manifest. */
|
|
7
8
|
export function optionalSlotProblems(manifest, side, s) {
|
|
@@ -24,11 +25,12 @@ export function optionalSlotProblems(manifest, side, s) {
|
|
|
24
25
|
return bad;
|
|
25
26
|
}
|
|
26
27
|
|
|
27
|
-
/** The problems of a side's `backing` list: every name is
|
|
28
|
-
export function backingProblems(manifest, side, s) {
|
|
29
|
-
const services = Object.
|
|
28
|
+
/** The problems of a side's `backing` list: every name is admitted by ruleParams.be.backing in this edition. */
|
|
29
|
+
export function backingProblems(manifest, side, s, edition = 'full') {
|
|
30
|
+
const services = Object.entries(manifest.ruleParams?.be?.backing ?? {})
|
|
31
|
+
.filter(([, entry]) => judgedInEdition(entry, edition)).map(([name]) => name);
|
|
30
32
|
return (s.backing ?? []).filter((name) => !services.includes(name))
|
|
31
|
-
.map((name) => `sides.${side}.backing names ${name}, which is not
|
|
33
|
+
.map((name) => `sides.${side}.backing names ${name}, which is not admitted in edition ${edition} by ruleParams.be.backing (${services.join(', ')})`);
|
|
32
34
|
}
|
|
33
35
|
|
|
34
36
|
/** The problems of the shape of a side's `patterns` list (a unique list of pattern names). */
|
|
@@ -6,13 +6,15 @@ import { paramNamesOk } from './param-names.mjs';
|
|
|
6
6
|
import { kindParamProblems, scenarioProblem } from './declaration-slots.mjs';
|
|
7
7
|
import { NAME, namedMapValid, PACKAGE_NAME, roleListProblems, SCHEMA_AUTHORITIES, unitRolesProblems } from './manifest-shape.mjs';
|
|
8
8
|
import { byCodeUnit, nonemptyUniqueList } from '../lib/list.mjs';
|
|
9
|
+
import { ruleEditionProblems } from './edition-slots.mjs';
|
|
9
10
|
|
|
10
11
|
const PROFILES = ['be', 'fe'];
|
|
11
12
|
const BE_OWN = ['infraOwners', 'eventBus', 'specDoubles', 'paramNames', 'suffixes', 'bannedSuffixes', 'contractShape', 'unitRoles', 'logicRoles', 'valueRoles', 'thinRoles', 'patternScenarios', 'kindPatterns', 'addKinds', 'backing'];
|
|
12
|
-
const backingEntryOk = (entry) => isPlainObject(entry) && Object.keys(entry).
|
|
13
|
+
const backingEntryOk = (entry) => isPlainObject(entry) && Object.keys(entry).every((key) => ['clients', 'images', 'patterns', 'editions'].includes(key))
|
|
13
14
|
&& nonemptyUniqueList(entry.clients, (name) => PACKAGE_NAME.test(String(name)))
|
|
14
15
|
&& Array.isArray(entry.patterns) && entry.patterns.every((name) => NAME.test(String(name))) && new Set(entry.patterns).size === entry.patterns.length
|
|
15
|
-
&& nonemptyUniqueList(entry.images, (name) => PACKAGE_NAME.test(String(name)))
|
|
16
|
+
&& nonemptyUniqueList(entry.images, (name) => PACKAGE_NAME.test(String(name)))
|
|
17
|
+
&& ruleEditionProblems(entry, 'backing service').length === 0;
|
|
16
18
|
const FORM_NAMES = new Set(['call', 'new', 'curried', 'object', 'primitive', 'array']);
|
|
17
19
|
const blockOk = (v) => isPlainObject(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
|
|
18
20
|
const fileLinesOk = (v) => isPlainObject(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
|
|
@@ -51,7 +53,7 @@ function beSpecificProblems(be, manifest) {
|
|
|
51
53
|
const eventBus = be.eventBus;
|
|
52
54
|
if (!isPlainObject(eventBus) || Object.keys(eventBus).sort(byCodeUnit).join() !== 'classes,imports' || !memberMap(eventBus.imports, true) || !memberMap(eventBus.classes, false)) bad.push('ruleParams.be.eventBus must be {imports: {<module>: [unique PascalCase members]}, classes: {<module>: [non-empty unique PascalCase classes]}}');
|
|
53
55
|
if (!paramNamesOk(be.paramNames)) bad.push('ruleParams.be.paramNames must be a non-empty list of unique {type | typeSuffix, names, nameSuffix?} entries');
|
|
54
|
-
if (!namedMapValid(be.backing, backingEntryOk)) bad.push('ruleParams.be.backing must map a backing service name to {clients: [unique package names], patterns: [unique pattern names], images: [unique image repositories]}');
|
|
56
|
+
if (!namedMapValid(be.backing, backingEntryOk)) bad.push('ruleParams.be.backing must map a backing service name to {clients: [unique package names], patterns: [unique pattern names], images: [unique image repositories], editions?: [unique known editions]}');
|
|
55
57
|
if (!roleList(be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
|
|
56
58
|
if (!roleList(be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
|
|
57
59
|
else if (roleList(be.suffixes) && be.suffixes.some((x) => be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
|
|
@@ -19,9 +19,9 @@ function requiredAppKindProblems(manifest, side, declaration) {
|
|
|
19
19
|
}
|
|
20
20
|
|
|
21
21
|
/** Problems for one side declaration, preserving the manifest's checks and their order. */
|
|
22
|
-
export function sideProblems(manifest, side, declaration) {
|
|
22
|
+
export function sideProblems(manifest, side, declaration, edition = 'full') {
|
|
23
23
|
const bad = sideAppKindProblems(manifest, side, declaration.apps);
|
|
24
|
-
bad.push(...optionalSlotProblems(manifest, side, declaration), ...backingProblems(manifest, side, declaration));
|
|
24
|
+
bad.push(...optionalSlotProblems(manifest, side, declaration), ...backingProblems(manifest, side, declaration, edition));
|
|
25
25
|
for (const read of declaration.reads ?? []) if (!manifest.sides[side].reads.includes(read)) bad.push(`sides.${side}.reads names ${read}; ${side} may read only ${manifest.sides[side].reads.join(', ') || 'nothing of the other side'}`);
|
|
26
26
|
bad.push(...requiredAppKindProblems(manifest, side, declaration));
|
|
27
27
|
return bad;
|
|
@@ -140,7 +140,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
|
|
|
140
140
|
if (declaration.kind === RUNTIME_KIND) return runtimeDeclaration(manifest, declaration, file, side);
|
|
141
141
|
const { edition, known, valid } = declarationEdition(manifest, declaration);
|
|
142
142
|
if (!valid) fail('HFS_EDITION_INVALID', `hfs.json edition is ${JSON.stringify(declaration.edition)}; the editions this manifest knows are ${known.join(', ')} (absent means full)`, { file, edition: declaration.edition });
|
|
143
|
-
const bad = PROFILES.flatMap((name) => sideProblems(manifest, name, declaration.sides[name]));
|
|
143
|
+
const bad = PROFILES.flatMap((name) => sideProblems(manifest, name, declaration.sides[name], edition));
|
|
144
144
|
if (bad.length) declarationInvalid(bad, file);
|
|
145
145
|
if (side !== null && !PROFILES.includes(side)) fail('HFS_DECLARATION_INVALID', `${side} is not a side of an app (be, fe)`, { file, side });
|
|
146
146
|
// A provider declared on any connection enables the provider slots of every profile (a fe side declares none): each view carries the union.
|
|
@@ -56,6 +56,45 @@ const ASSIGNED_UNQUOTED = new RegExp(
|
|
|
56
56
|
SECRET_NAME + String.raw`(?!['"\`]|env\()([A-Za-z0-9_+=-]{12,})(?![A-Za-z0-9_+=.(\[-])`,
|
|
57
57
|
);
|
|
58
58
|
|
|
59
|
+
const SQL_ROLE_HEAD = /^\s*(?:CREATE|ALTER)\s+(?:ROLE|USER)\b/i;
|
|
60
|
+
const SQL_STATEMENT = /[^;\r\n]+/g;
|
|
61
|
+
const SQL_PASSWORD_WORD = /\bPASSWORD\s+/gi;
|
|
62
|
+
const PSQL_PASSWORD_REFERENCE = /:(?:'[A-Za-z_]\w*'|"[A-Za-z_]\w*")/y;
|
|
63
|
+
const SQL_PASSWORD_QUOTED = /'([^'\r\n]{12,})'/y;
|
|
64
|
+
const ASSIGNED_PLACEHOLDER = /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i;
|
|
65
|
+
const SQL_PASSWORD_RULE = { name: 'assigned-secret' };
|
|
66
|
+
|
|
67
|
+
/** Read only password tokens in role statements; sticky value readers never retry at later character positions. */
|
|
68
|
+
function sqlPasswordParts(file, text) {
|
|
69
|
+
const references = [], literals = [];
|
|
70
|
+
if (!/\.(?:sql|sh)(?:\.tpl)?$/i.test(file ?? '')) return { references, literals };
|
|
71
|
+
for (const statement of text.matchAll(SQL_STATEMENT)) {
|
|
72
|
+
if (!SQL_ROLE_HEAD.test(statement[0])) continue;
|
|
73
|
+
for (const keyword of statement[0].matchAll(SQL_PASSWORD_WORD)) {
|
|
74
|
+
const start = statement.index + keyword.index + keyword[0].length;
|
|
75
|
+
PSQL_PASSWORD_REFERENCE.lastIndex = start;
|
|
76
|
+
SQL_PASSWORD_QUOTED.lastIndex = start;
|
|
77
|
+
const reference = PSQL_PASSWORD_REFERENCE.exec(text);
|
|
78
|
+
const literal = SQL_PASSWORD_QUOTED.exec(text);
|
|
79
|
+
if (reference) references.push([start, start + reference[0].length]);
|
|
80
|
+
if (literal) literals.push(literal[1]);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
return { references, literals };
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Psql variable references retain their positions while the assignment heuristic sees no literal value there. */
|
|
87
|
+
function maskedReferences(text, references) {
|
|
88
|
+
const parts = [];
|
|
89
|
+
let cursor = 0;
|
|
90
|
+
for (const [start, end] of references) {
|
|
91
|
+
parts.push(text.slice(cursor, start), ' '.repeat(end - start));
|
|
92
|
+
cursor = end;
|
|
93
|
+
}
|
|
94
|
+
parts.push(text.slice(cursor));
|
|
95
|
+
return parts.join('');
|
|
96
|
+
}
|
|
97
|
+
|
|
59
98
|
const NAME_WORD = (word, tail) => new RegExp(`^${NAME_REST}${SEGMENT_BEFORE}(?:${word})${tail}`);
|
|
60
99
|
const SECRET_NAME_TEST = NAME_WORD(SECRET_WORD, String.raw`(?:[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$)`);
|
|
61
100
|
const BENIGN_TAIL_TEST = NAME_WORD(BENIGN_WORD, '$');
|
|
@@ -84,27 +123,37 @@ export const SECRET_PATTERNS = [
|
|
|
84
123
|
// A spec file's keyword-assigned values are test inputs (a spec's sign-in
|
|
85
124
|
// form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
|
|
86
125
|
// A SCREAMING_SNAKE quoted value in source is a public code (an enum member whose value is an upper-case code), not a credential.
|
|
87
|
-
{ name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder:
|
|
126
|
+
{ name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: ASSIGNED_PLACEHOLDER,
|
|
88
127
|
skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
|
|
89
128
|
// An unquoted value in TypeScript or JavaScript source is an identifier or a type (`token: InjectionToken`,
|
|
90
129
|
// `MODULE_OPTIONS_TOKEN: DATABASE_OPTIONS_TOKEN`), never a literal; the unquoted form is the dotenv, compose and toml shape.
|
|
91
|
-
{ name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder:
|
|
130
|
+
{ name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: ASSIGNED_PLACEHOLDER,
|
|
92
131
|
skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$|\.[cm]?[jt]sx?$/ },
|
|
93
132
|
];
|
|
94
133
|
|
|
95
134
|
|
|
96
|
-
/**
|
|
97
|
-
|
|
98
|
-
const
|
|
135
|
+
/** Matched pattern metadata stays private; callers receive pattern names, never credential values. */
|
|
136
|
+
function matchingSecretPatterns(file, text) {
|
|
137
|
+
const matches = [];
|
|
138
|
+
const sql = sqlPasswordParts(file, text);
|
|
139
|
+
const assignments = maskedReferences(text, sql.references);
|
|
99
140
|
for (const rule of SECRET_PATTERNS) {
|
|
100
141
|
if (rule.skipFile?.test(file ?? '')) continue;
|
|
101
|
-
const hit = rule.re.exec(text);
|
|
102
|
-
if (hit && rule.
|
|
103
|
-
if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
|
|
142
|
+
const hit = rule.re.exec(rule.name === 'assigned-secret' ? assignments : text);
|
|
143
|
+
if (hit && !rule.placeholder?.test(hit[1] ?? '')) matches.push({ rule, value: hit[1] ?? '' });
|
|
104
144
|
}
|
|
105
|
-
|
|
145
|
+
for (const value of sql.literals) if (!ASSIGNED_PLACEHOLDER.test(value)) matches.push({ rule: SQL_PASSWORD_RULE, value });
|
|
146
|
+
return matches;
|
|
106
147
|
}
|
|
107
148
|
|
|
149
|
+
/** The strict secret-shape judgement used by Work custody, including uppercase keyword-assigned credentials. */
|
|
150
|
+
export const secretPatternHits = (file, text) => matchingSecretPatterns(file, text).map(({ rule }) => rule.name);
|
|
151
|
+
|
|
152
|
+
/** The source judgement also admits public SCREAMING_SNAKE codes; every provider shape remains refused. */
|
|
153
|
+
export const secretHits = (file, text) => matchingSecretPatterns(file, text)
|
|
154
|
+
.filter(({ rule, value }) => !(rule.sourceCode?.test(value) && /\.[cm]?[jt]sx?$/.test(file ?? '')))
|
|
155
|
+
.map(({ rule }) => rule.name);
|
|
156
|
+
|
|
108
157
|
const BADGE_BEGIN = '<!-- >>> starci app sync (managed block; do not edit) >>> -->';
|
|
109
158
|
const BADGE_END = '<!-- <<< starci app sync <<< -->';
|
|
110
159
|
|