@starci/eslint-canon-be 3.25.0 → 3.27.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +22 -0
- package/README.md +15 -1
- package/dist/comments.d.ts +2 -1
- package/dist/comments.js +27 -2
- package/dist/event-bus.js +10 -2
- package/dist/feature-thin.js +2 -2
- package/dist/health-ready.js +25 -9
- package/dist/jobs.d.ts +9 -3
- package/dist/jobs.js +315 -24
- package/dist/lib/config.d.ts +2 -1
- package/dist/lib/config.js +13 -3
- package/dist/lib/hfs-view.d.ts +4 -0
- package/dist/lib/nivoos-profile.d.ts +40 -0
- package/dist/lib/nivoos-profile.js +54 -0
- package/dist/lib/persistence.js +1 -1
- package/dist/naming.js +6 -3
- package/dist/realtime.js +68 -8
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.27.1 - 2026-11-18
|
|
4
|
+
|
|
5
|
+
- Added (`lib/nivoos-profile.ts`): the lint profile of a declared nivoos business package (slot `app.nivoos-package`, `lintProfile: nivoos`, PROJECT-BUSINESS-1): `no-non-ascii-source` allows Vietnamese letters inside string and template literals (comments, identifiers and emoji stay refused); `no-default-export` allows the default export of `src/<name>.package.ts`, which the SDK loads; `explicit-export-surface`, `require-public-member-jsdoc`, `job-shape` and `throw-domain-error` do not apply to the package source (nothing imports it, the SDK interface owns its members, `.step.ts` is the SDK file kind, an SDK node fails with a coded `Error`). Every other rule, `schema-bounded` included, still applies.
|
|
6
|
+
|
|
7
|
+
## 3.27.0 - 2026-11-14
|
|
8
|
+
|
|
9
|
+
- Changed: cut with `@starci/hfs` 6.13.0 (peer line); requires `@starci/hfs` `~6.13.0`. No rule changes.
|
|
10
|
+
|
|
11
|
+
## 3.26.0 - 2026-11-14
|
|
12
|
+
|
|
13
|
+
- Changed (R159, breaking): `job-run-key` is `job-effect-piece` (`BE_JOB_EFFECT_PIECE`). In a job step, and in a function that takes a `ClaimedJob` (a closure of it included), every call on an integration port is the `act` or the `confirm` read of an `Effects.once` call of `platform/effects`; a call made as the key argument, or outside the call object, is a finding. A function handed to a helper that `platform/effects` itself declares together with the `Effects` port (one that answers what its act answered) is an act too, and so is a `const` function whose every use hands it to the piece (`const act = ...` then `{ act }`); a use that only calls it adds no finding of its own. A member its port declares an outside READ (the port's interface extends `OutsideReads<"member" | ...>` of `platform/effects`, a client class merges an interface of its own name that extends it, or a class implements a contract that does; judged by that interface's origin, never by a name) needs no intent; an undeclared member is an act, and a read that decides an act does not excuse the act. Fixtures `integrations/mailer/mail-box.port.ts`, `own-reads.port.ts`. The `RunKey` of `platform/jobs` is no longer read. Spec `src/jobs.spec.ts`.
|
|
14
|
+
- Added (R403, `job-next-declared`): in a `defineJob` declaration `next` is an array literal of statically readable job names, each the name of a job a `defineJob` of the program declares (a computed or spread entry, a name no declaration carries, are findings). Spec `src/jobs.spec.ts`.
|
|
15
|
+
- Added (R404, `job-progress-shape`): a `defineJob` `progress.topic` is a function whose declared return type is `JobProgressTopic` of `platform/jobs`, and a function of `modules/domain` that takes a `ClaimedJob` never calls the `RealtimeHub` (it reports through `JobProgress`). Spec `src/jobs.spec.ts`.
|
|
16
|
+
- Changed (R152, `outbox-write-tx`): a direct `QueueOutbox.write` outside a typed producer is judged like a producer call: only a domain service writes it, with the manager of its own transaction. Spec `src/event-bus.spec.ts`.
|
|
17
|
+
- Changed (R185, R186, `realtime-read-only`, `realtime-topic-scope`): an SSE door may inject ONE stream read service (a class of the platform or domain tier whose public methods all answer an rxjs `Observable`) besides, or instead of, the `RealtimeHub`, and its call must pass the handler's principal (`serviceScope`); a second such service (`second`), a service that also writes, and a stream service in a gateway or a subscription door stay findings. `feature-thin` accepts the one-call door. Specs `src/realtime.spec.ts`, `src/feature-thin.spec.ts`.
|
|
18
|
+
- Fixed (R83, `no-repository-class`): `effects` is a persistence capability, so a platform effects piece may hold the `EntityManager` (`settleIn(tx)`). Spec `src/service-deps.spec.ts`.
|
|
19
|
+
- Changed: cut with `@starci/hfs` 6.12.0; requires `@starci/hfs` `~6.12.0`. Carries the 3.25.2 fix below.
|
|
20
|
+
|
|
21
|
+
## 3.25.2 - 2026-11-13
|
|
22
|
+
|
|
23
|
+
- Fixed (R262, `health-signals`, `ready-real`): `RangeError: Maximum call stack size exceeded` at the first file of an app that holds a constant used many times. `expandedNodes` re-expanded a local constant at every identifier that named it (a cost per reference, and a doubling per nested constant) and appended each expansion with `push(...expansion)`, which overflows the call stack once the list is large. Each constant is now expanded once per call under a visited set shared by the whole walk, nodes are appended one by one, and a self-referencing constant or a ring of constants ends at its second visit. Verdicts are unchanged. Spec `src/health-ready.spec.ts` (a tripling chain of constants, a ring, a self reference). 3.25.1 is taken by the open branch `pkg/claude-lint-split-s2`, so this patch is 3.25.2.
|
|
24
|
+
|
|
3
25
|
## 3.25.0 - 2026-11-13
|
|
4
26
|
|
|
5
27
|
- Changed (PROJECT-LINT-3, breaking for an app that relied on the fixed layout): `starciBePackagesConfig` knows no folder of a root package. It judges every script file of `packages/<pkg>/src/**` but the slots the project declares `lint: "fe"` in `ext/manifest.json` `packages` (the package view's `packageLint`); a back-end slot declared before a front-end slot it lies in stays back end. The fixed `src/workbench/**` and `src/public/**` ignores and the `src/workbench/contract/**` block are gone, so an undeclared package is back end whole. Spec `src/packages-config.spec.ts`.
|
package/README.md
CHANGED
|
@@ -31,6 +31,19 @@ longer holds is deleted from the plugin; every rule that ships is on.
|
|
|
31
31
|
|
|
32
32
|
Also exported: `rules`, `ruleOwners`, `lawOwners`, `ruleDeclarations`, `recommended`, `linterOptions`.
|
|
33
33
|
|
|
34
|
+
## A business package: the SDK authoring profile
|
|
35
|
+
|
|
36
|
+
A package authored with the nivoos SDK (agents, workflows, cells, steps, brain, accounts, seed) is declared in `hfs.json` `sides.nivoos.packages`; its folder is then the slot `app.nivoos-package`
|
|
37
|
+
(`lintProfile: nivoos`), and `starciBePackagesConfig` judges `packages/<name>/src/**` with the same canon less what an SDK package cannot satisfy. The profile is chosen by the slot and takes no
|
|
38
|
+
file comment; the same code in an undeclared package is judged by the whole canon (`src/lib/nivoos-profile.ts`, `src/nivoos-profile.spec.ts`):
|
|
39
|
+
|
|
40
|
+
- `no-non-ascii-source` accepts Vietnamese letters inside string and template literals (the business's copy) and refuses them in comments and identifiers; an emoji or ornament is refused everywhere;
|
|
41
|
+
- `no-default-export` accepts the default export of the entry `src/<name>.package.ts`, which the SDK loads;
|
|
42
|
+
- `explicit-export-surface`, `require-public-member-jsdoc`, `job-shape` and `throw-domain-error` are not applied, each with its reason in `NIVOOS_RELAXED` (nothing imports a package's source and the SDK's
|
|
43
|
+
interfaces type its members; a member is a field of the SDK interface; `.step.ts` is a workflow step, not a job step; an SDK node fails by a thrown coded `Error`).
|
|
44
|
+
|
|
45
|
+
[contexts/project/business-repo.md](../../contexts/project/business-repo.md) owns the page; the findings each relaxation held are those of the first package, `nivo-web`.
|
|
46
|
+
|
|
34
47
|
## What it actually catches
|
|
35
48
|
|
|
36
49
|
A sample, not the list:
|
|
@@ -63,7 +76,8 @@ A sample, not the list:
|
|
|
63
76
|
| **Entity base** | An `@Entity` class does not repeat the columns every table shares: a database-set `created_at` or `updated_at` (`@CreateDateColumn`, `@UpdateDateColumn`, or a `@Column` on those names with `insert: false`, `update: false` or a `default`) and, beside both, the generated uuid `id` are inherited from `UuidAbstractEntity` or `AbstractEntity` of `@modules/platform/database`; the finding names the base. A table whose timestamps the application sets, or that lacks one of them, extends nothing, and the base file `platform/database/abstract.entity.ts` is exempt (`entity-extends-base`, R342, BE-PERSISTENCE-3) |
|
|
64
77
|
| **Connections** | One database is one connection and one `Inject<Conn>EntityManager()` injector: `InjectEntityManager(`, `InjectDataSource(` and `getEntityManagerToken(` are called only in `platform/database/<conn>.decorators.ts`, the cli and the test world; an exported EntityManager injector is exactly the declared connection's; `TypeOrmModule.forRoot*` and `new DataSource(` live in the platform database capability and the cli; the connection name is written once, in its `<conn>.connection.ts`; a `<conn>.config.ts` reads only keys of its `envPrefix` (`one-connection-per-database`) |
|
|
65
78
|
| **Operations** | A versioned operation is declared once in the app's typed operation table (`query({ input, output, refusal })` / `mutation(...)` registered by `defineOperations`, declared by the platform capability `operations`): bounded input and output schemas come from an owner's `*.schema.ts` file, their inferred types are closed, and refusal codes form a closed union of string literals. A route takes `OperationRequest<Table>`, validates it with the canon `OperationValidationPolicy` constructed from that same table, and answers `Promise<OperationReply<Table>>` (`operation-contract-decidable`, `operation-table-schemas`, `operation-route-driven-by-table`) |
|
|
66
|
-
| **Webhooks and realtime** | A provider webhook door injects only the `WebhookSignatureService` and domain services, verifies first (awaited when async), and hands the POST delivery to exactly one domain intake that records the inbox receipt and outbox event; a domain method may combine proof and intake. The POST returns nothing or the own-feature exported literal `PROVIDER_ACK`. One optional GET challenge handler returns only its declared domain verifier's result. The door and HTTP module import or inject no `CommandBus`, `QueryBus` or feature command handler, and its resolved domain intake dispatches no command/query bus or feature handler; a reactor or job dispatches after commit (`webhook-shape`, `webhook-verify-first`, `feature-thin`). A realtime door is one gateway or
|
|
79
|
+
| **Webhooks and realtime** | A provider webhook door injects only the `WebhookSignatureService` and domain services, verifies first (awaited when async), and hands the POST delivery to exactly one domain intake that records the inbox receipt and outbox event; a domain method may combine proof and intake. The POST returns nothing or the own-feature exported literal `PROVIDER_ACK`. One optional GET challenge handler returns only its declared domain verifier's result. The door and HTTP module import or inject no `CommandBus`, `QueryBus` or feature command handler, and its resolved domain intake dispatches no command/query bus or feature handler; a reactor or job dispatches after commit (`webhook-shape`, `webhook-verify-first`, `feature-thin`). A realtime door is one gateway, subscription or SSE controller that injects the `RealtimeHub` (an SSE door may instead inject ONE stream read service whose public methods only answer an `Observable`, called with the principal) and subscribes to a topic built from its `@CurrentPrincipal()` (`realtime-shape`, `realtime-read-only`, `realtime-topic-scope`) |
|
|
80
|
+
| **Jobs** (R157-R160, R403, R404) | The job row is written only by `platform/jobs` through guarded writes that require the fencing token (`job-write-owner`, `job-fence-required`); a processor extends `FencedProcessor` and a step implements `JobStep` in their job folder (`job-shape`); in a step, and in any function that takes a `ClaimedJob`, every call on an integration port its port does not declare an outside read (`OutsideReads` of `platform/effects`) is the `act` or `confirm` of an `Effects.once` call (`job-effect-piece`); a `defineJob` `next` lists only declared jobs, as readable names (`job-next-declared`); a `progress.topic` returns the platform's principal-first `JobProgressTopic`, and a function that takes a `ClaimedJob` never calls the `RealtimeHub` (`job-progress-shape`); a job enqueues its next job through an outbox write of its own transaction (`outbox-write-tx`) |
|
|
67
81
|
| **Transport** | A door injects only `CommandBus` / `QueryBus` (and `RequestLocale` in REST) and dispatches exactly one message per handler, holding no branch, loop, EntityManager or call other than the bus, and pure `*.mapper.ts` functions and `unwrapOutcome` of `platform/primitives` (`transport-is-thin`); no response envelope, no `GraphQLJSON`, no `unknown` body, no `switch (input.operation)`; a REST door lives in `transport/http` and shows a public reason, a byte stream or a redirect; a capability never imports a feature (`transport-is-thin`, `no-response-envelope`, `no-graphql-json`, `door-lives-in-features`, `rest-door-needs-a-reason`, `no-capability-imports-features`) |
|
|
68
82
|
| **Feature thin** (R203 BE_FEATURE_THIN) | A feature-tier file of a thin role (`<name>.handler.ts`, `.resolver.ts`, `.controller.ts`, `.consumer.ts`, `.processor.ts`, `.step.ts`, `.saga.ts`, `.saga-step.ts`, `.compensation.ts`, `.webhook.ts`, `.gateway.ts`, `.subscription.ts`, `.cli.ts`, `.mapper.ts`, `.service.ts`) maps its parameters and makes exactly one delegating call into the modules - an injected member, a bus `execute` or a modules function in statement position - with no branch, loop, `try`, `throw` or computation; free calls are pure `*.mapper.ts` functions, the `Logger` port and a webhook's first verification call when followed by one separate intake (a combined domain verification and intake call counts as the delegation). A webhook POST may return its declared literal `PROVIDER_ACK`; its optional GET challenge has one domain verifier call and echoes only that result. Webhook doors and their HTTP modules reach no command/query bus or feature command handler; orchestration (step order, compensation, claim, fencing, retry) belongs to the platform (`feature-thin`) |
|
|
69
83
|
| **Infrastructure owners** | Each raw library (HTTP, cache, queue, scheduler, logger, date, config, events) is imported or reached as a global only inside the capability the manifest names for it (`ruleParams.be.infraOwners`); `@nestjs/config`, `dotenv` and `@nestjs/event-emitter` nowhere; the `HttpClient` port of `platform/http` (found by the receiver's type) is called only in an `integrations` owner, `platform/http` and the test world (`infra-import-owner`, `http-client-only-in-integrations`) |
|
package/dist/comments.d.ts
CHANGED
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
* - `require-enum-member-jsdoc` checks an adjacent non-empty description, never whether it states a
|
|
14
14
|
* consequence. That half is read by a person, and the rule says so rather than pretending.
|
|
15
15
|
* - `no-non-ascii-source` takes no exemption marker, so text a program depends on
|
|
16
|
-
* lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear
|
|
16
|
+
* lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear (and, in a declared
|
|
17
|
+
* nivoos package, the string and template literals that hold its business copy, lib/nivoos-profile.ts). Specs
|
|
17
18
|
* and fixtures get no exemption.
|
|
18
19
|
* - `no-restated-name-jsdoc` (law 7) holds the decidable slice of law 3 - a doc block whose only
|
|
19
20
|
* content is the declared name re-spelled in words teaches nothing beyond the import line, so it
|
package/dist/comments.js
CHANGED
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
* - `require-enum-member-jsdoc` checks an adjacent non-empty description, never whether it states a
|
|
14
14
|
* consequence. That half is read by a person, and the rule says so rather than pretending.
|
|
15
15
|
* - `no-non-ascii-source` takes no exemption marker, so text a program depends on
|
|
16
|
-
* lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear
|
|
16
|
+
* lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear (and, in a declared
|
|
17
|
+
* nivoos package, the string and template literals that hold its business copy, lib/nivoos-profile.ts). Specs
|
|
17
18
|
* and fixtures get no exemption.
|
|
18
19
|
* - `no-restated-name-jsdoc` (law 7) holds the decidable slice of law 3 - a doc block whose only
|
|
19
20
|
* content is the declared name re-spelled in words teaches nothing beyond the import line, so it
|
|
@@ -24,6 +25,7 @@
|
|
|
24
25
|
*/
|
|
25
26
|
import { nameOrValue } from "./lib/ast.js";
|
|
26
27
|
import { hfsOf } from "./lib/hfs.js";
|
|
28
|
+
import { nivoosAuthored } from "./lib/nivoos-profile.js";
|
|
27
29
|
import { normalizePath } from "./lib/path.js";
|
|
28
30
|
import { hasSecondLanguage } from "@starci/hfs/runtime/scripts/lib/language.mjs";
|
|
29
31
|
import { jsdocBefore, jsdocDescription } from "../runtime/scripts/lib/jsdoc.mjs";
|
|
@@ -80,6 +82,26 @@ const offenceIn = (line) => {
|
|
|
80
82
|
return "an ornamental symbol";
|
|
81
83
|
return null;
|
|
82
84
|
};
|
|
85
|
+
/**
|
|
86
|
+
* The source text with the Vietnamese letters inside string and template literals replaced by `a`, so a line of it offends only with what is
|
|
87
|
+
* outside a literal (a comment, an identifier) or with an emoji or an ornament anywhere.
|
|
88
|
+
*
|
|
89
|
+
* @param sourceCode - The linted file.
|
|
90
|
+
* @returns The text, line breaks kept.
|
|
91
|
+
*/
|
|
92
|
+
const withoutLiteralText = (sourceCode) => {
|
|
93
|
+
const text = sourceCode.text;
|
|
94
|
+
let out = "";
|
|
95
|
+
let at = 0;
|
|
96
|
+
for (const token of sourceCode.ast.tokens) {
|
|
97
|
+
if (token.type !== "String" && token.type !== "Template")
|
|
98
|
+
continue;
|
|
99
|
+
out += text.slice(at, token.range[0]);
|
|
100
|
+
out += Array.from(text.slice(token.range[0], token.range[1]).normalize("NFC"), (char) => (hasSecondLanguage(char) ? "a" : char)).join("");
|
|
101
|
+
at = token.range[1];
|
|
102
|
+
}
|
|
103
|
+
return out + text.slice(at);
|
|
104
|
+
};
|
|
83
105
|
/**
|
|
84
106
|
* Whether an exported declaration has a surface a caller documents: a data constant is already described by its name,
|
|
85
107
|
* and a kind outside DOCUMENTED_KINDS has no surface at all.
|
|
@@ -283,9 +305,12 @@ export const noNonAsciiSource = {
|
|
|
283
305
|
const slot = hfsOf(context).slotOf(context.filename);
|
|
284
306
|
if (CATALOG_SLOTS.has(slot) || FIXTURE_SLOTS.has(slot))
|
|
285
307
|
return {};
|
|
308
|
+
// A declared nivoos package carries its business copy (titles, labels, prompts, guidance) in string and template literals: Vietnamese is accepted there and
|
|
309
|
+
// nowhere else (a comment, an identifier), and an emoji or an ornament stays refused everywhere (lib/nivoos-profile.ts).
|
|
310
|
+
const copyInLiterals = nivoosAuthored(context);
|
|
286
311
|
return {
|
|
287
312
|
"Program:exit"(node) {
|
|
288
|
-
const lines = sourceCode.
|
|
313
|
+
const lines = (copyInLiterals ? withoutLiteralText(sourceCode) : sourceCode.text).split(/\r\n|[\r\n\u2028\u2029]/u);
|
|
289
314
|
for (const [index, line] of lines.entries()) {
|
|
290
315
|
const offence = offenceIn(line);
|
|
291
316
|
if (offence === null)
|
package/dist/event-bus.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The rules that hold the event-bus and queue patterns (catalog R152 `BE_OUTBOX_WRITE_TX`, R153 `BE_EVENT_CONSUMER_SHAPE`,
|
|
3
|
-
* R154 `BE_QUEUE_PRODUCER_SHAPE`).
|
|
3
|
+
* R154 `BE_QUEUE_PRODUCER_SHAPE`). A job starts, and enqueues its next job, only from an outbox row written in the transaction of the
|
|
4
|
+
* change that calls for it: every outbox write, a producer call and a direct `QueueOutbox.write` alike, is judged by `outbox-write-tx`.
|
|
4
5
|
*
|
|
5
6
|
* The one durable path of an event is: a domain service writes the outbox row in ITS transaction (`eventBus.publish(event, tx)`), the
|
|
6
7
|
* relay hands the row to Kafka, a consumer in `transport/message` receives it and dispatches one command. A queue job takes the same
|
|
@@ -68,12 +69,19 @@ const isTransactionManager = (context, argument) => {
|
|
|
68
69
|
return false;
|
|
69
70
|
return infraTypeOf(context, definition.name) === "EntityManager";
|
|
70
71
|
};
|
|
71
|
-
/**
|
|
72
|
+
/**
|
|
73
|
+
* The outbox-writing call a node is: `{ kind: "publish", argument }` or `{ kind: "producer", argument }`, or null. A `write` on the
|
|
74
|
+
* `QueueOutbox` port is an outbox write wherever it is called: a typed producer's own (tier `queues`) is judged by `queue-producer-shape`,
|
|
75
|
+
* any other, a job enqueuing its next job included, is judged here like a producer call.
|
|
76
|
+
*/
|
|
72
77
|
const outboxWriteOf = (context, hfs, node) => {
|
|
73
78
|
const callee = node.callee;
|
|
74
79
|
if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "publish" && isEventBusType(context, callee.object)) {
|
|
75
80
|
return { kind: "publish", argument: node.arguments[1], expected: 1 };
|
|
76
81
|
}
|
|
82
|
+
if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "write" && isQueueOutboxType(context, callee.object)) {
|
|
83
|
+
return hfs.tierOf(context.filename) === "queues" ? null : { kind: "producer", argument: node.arguments[0], expected: 0 };
|
|
84
|
+
}
|
|
77
85
|
const { checker, toTs } = typed(context);
|
|
78
86
|
const tsNode = toTs(node);
|
|
79
87
|
const declaration = tsNode ? checker.getResolvedSignature(tsNode)?.declaration : undefined;
|
package/dist/feature-thin.js
CHANGED
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
* the file-name suffix the closed role vocabulary defines - never a path regex. What a receiver is comes
|
|
16
16
|
* from its TYPE (`Logger` of `platform/logging`, `WebhookSignatureService` of `platform/http-security`) and
|
|
17
17
|
* from whether the member is injected (`injectedMembers`); what a free function is comes from the file its
|
|
18
|
-
* import resolves to. A job `step` records its fence through `JobClaims` (`advance
|
|
18
|
+
* import resolves to. A job `step` records its fence through `JobClaims` (`advance`), and a webhook proves its signature through the shared `verify`
|
|
19
19
|
* or a declared domain verifier as its first call: a separate gate call is free beside the one intake delegation.
|
|
20
20
|
* A combined domain proof and intake counts as the delegation. `.spec.ts` and `.d.ts` are never judged, and neither is a file whose tier is not
|
|
21
21
|
* `feature` or whose role is not a thin role. A clean thin file is never flagged: that is the bar.
|
|
@@ -57,7 +57,7 @@ const roleOf = (filename) => /\.([a-z][a-z0-9-]*)\.ts$/.exec(baseName(filename))
|
|
|
57
57
|
const isSignatureReceiver = (context, node) => isOwnedType(context, node, { name: "WebhookSignatureService", capability: "http-security", tier: "platform" });
|
|
58
58
|
/** The shape conversions a mapper may make on a value it received: a collection mapped item by item and a date written as text. They decide nothing and compute nothing. */
|
|
59
59
|
const MAPPER_SHAPE_METHODS = new Set(["map", "toISOString"]);
|
|
60
|
-
/** The `JobClaims` port of `platform/jobs` - the fence a job step records itself through (`advance
|
|
60
|
+
/** The `JobClaims` port of `platform/jobs` - the fence a job step records itself through (`advance`): bookkeeping the fenced-job pattern requires, free beside the step's one delegating call. */
|
|
61
61
|
const isClaimsReceiver = (context, node) => isOwnedType(context, node, { name: "JobClaims", capability: "jobs", tier: "platform" });
|
|
62
62
|
/** The `Logger` port of `platform/logging` - the one call that is always free. */
|
|
63
63
|
const isLoggerReceiver = isLoggerType;
|
package/dist/health-ready.js
CHANGED
|
@@ -62,16 +62,32 @@ const bindingsOf = (program) => {
|
|
|
62
62
|
bindings.set(node.id.name, node.init); });
|
|
63
63
|
return bindings;
|
|
64
64
|
};
|
|
65
|
-
/**
|
|
66
|
-
|
|
65
|
+
/**
|
|
66
|
+
* Expand local constants when proving a race: a timeout promise or duration may be held in a const.
|
|
67
|
+
* Each constant is expanded once per call (a visited set shared by the whole walk), so a constant referenced many times, constants that
|
|
68
|
+
* reference each other in a chain or a ring, and a constant that refers to itself cost one visit each, never one per reference.
|
|
69
|
+
* The nodes are appended one by one: a spread of a large expansion into `push` overflows the call stack.
|
|
70
|
+
*/
|
|
71
|
+
function expandedNodes(node, bindings) {
|
|
67
72
|
const nodes = [];
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
73
|
+
const seen = new Set();
|
|
74
|
+
const expanded = new Set();
|
|
75
|
+
const visit = (start) => {
|
|
76
|
+
walk(start, (child) => {
|
|
77
|
+
if (seen.has(child))
|
|
78
|
+
return;
|
|
79
|
+
seen.add(child);
|
|
80
|
+
nodes.push(child);
|
|
81
|
+
if (child.type !== "Identifier" || expanded.has(child.name))
|
|
82
|
+
return;
|
|
83
|
+
const init = bindings.get(child.name);
|
|
84
|
+
if (!init)
|
|
85
|
+
return;
|
|
86
|
+
expanded.add(child.name);
|
|
87
|
+
visit(init);
|
|
88
|
+
});
|
|
89
|
+
};
|
|
90
|
+
visit(node);
|
|
75
91
|
return nodes;
|
|
76
92
|
}
|
|
77
93
|
function sourcePath(source, filename, root) {
|
package/dist/jobs.d.ts
CHANGED
|
@@ -3,15 +3,21 @@ import type { Recommended, RuleModule } from "./lib/rule.js";
|
|
|
3
3
|
export declare const jobWriteOwner: RuleModule;
|
|
4
4
|
/** Calls on the `JobClaims` port, and what a guarded write is: required token, no cast to get around it, and `JobFencedOut` is not swallowed. */
|
|
5
5
|
export declare const jobFenceRequired: RuleModule;
|
|
6
|
-
/**
|
|
7
|
-
export declare const
|
|
6
|
+
/** An outside call of a job is made by the effects piece: its intent row before the act, its result after. */
|
|
7
|
+
export declare const jobEffectPiece: RuleModule;
|
|
8
|
+
/** A job's `next` names only jobs a `defineJob` declares. */
|
|
9
|
+
export declare const jobNextDeclared: RuleModule;
|
|
10
|
+
/** A job's progress is a view the frame publishes: its topic is built principal-first, and no domain method publishes it itself. */
|
|
11
|
+
export declare const jobProgressShape: RuleModule;
|
|
8
12
|
/** A processor extends the fenced base and is named after its job; a step implements `JobStep` in `steps/`. */
|
|
9
13
|
export declare const jobShape: RuleModule;
|
|
10
14
|
export declare const rules: {
|
|
11
15
|
"job-write-owner": RuleModule;
|
|
12
16
|
"job-fence-required": RuleModule;
|
|
13
|
-
"job-
|
|
17
|
+
"job-effect-piece": RuleModule;
|
|
14
18
|
"job-shape": RuleModule;
|
|
19
|
+
"job-next-declared": RuleModule;
|
|
20
|
+
"job-progress-shape": RuleModule;
|
|
15
21
|
};
|
|
16
22
|
/** The level these laws ask for: `error`, switched off nowhere. */
|
|
17
23
|
export declare const recommended: Recommended;
|
package/dist/jobs.js
CHANGED
|
@@ -1,25 +1,39 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The rules that hold the fenced-job pattern (catalog R157 `BE_JOB_WRITE_OUTSIDE_OWNER`, R158 `BE_JOB_FENCE_REQUIRED`,
|
|
3
|
-
* R159 `
|
|
3
|
+
* R159 `BE_JOB_EFFECT_PIECE`, R160 `BE_JOB_SHAPE`, R403 `BE_JOB_NEXT_DECLARED`, R404 `BE_JOB_PROGRESS_SHAPE`).
|
|
4
4
|
*
|
|
5
|
-
* A
|
|
6
|
-
* write to the row is guarded by `expectedFencingToken
|
|
7
|
-
* `platform/jobs` is the ONE owner of the row: it declares the entity, the claim
|
|
5
|
+
* A job is a step of a chain: a row whose `fencingToken` the claim bumps, declared once with `defineJob`. A worker that lost its claim (a
|
|
6
|
+
* zombie) holds a stale token, so every write to the row is guarded by `expectedFencingToken`, and every outside act goes through the
|
|
7
|
+
* effects piece, which commits an intent row before the act. `platform/jobs` is the ONE owner of the row: it declares the entity, the claim
|
|
8
|
+
* and the guarded writes, and nothing else writes it.
|
|
8
9
|
*
|
|
9
|
-
* Everything is found by TYPE ORIGIN (the `JobClaims`, `JobStep`, `
|
|
10
|
-
*
|
|
11
|
-
*
|
|
10
|
+
* Everything is found by TYPE ORIGIN (the `JobClaims`, `JobStep`, `ClaimedJob`, `JobProgressTopic`, `defineJob` and `FencedProcessor`
|
|
11
|
+
* declared by `platform/jobs`, the `Effects` port of `platform/effects`, the `RealtimeHub` of `platform/realtime`, the entity class
|
|
12
|
+
* declared by that owner, typeorm receivers and query builders) and by the slot view (`be.feature.jobs.steps`, `be.feature.jobs`,
|
|
13
|
+
* `be.queues`); the only names read are the contract's own members `once` (with its `act` and `confirm`), `next`, `progress`, `topic`,
|
|
14
|
+
* `jobId` and `expectedFencingToken`.
|
|
12
15
|
*/
|
|
13
16
|
import ts from "typescript";
|
|
14
|
-
import { walk } from "./lib/ast.js";
|
|
17
|
+
import { keyName, walk } from "./lib/ast.js";
|
|
15
18
|
import { writtenEntityOrigins } from "./lib/entity-writes.js";
|
|
16
19
|
import { hfsOf, inTestWorld } from "./lib/hfs.js";
|
|
17
20
|
import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.js";
|
|
18
|
-
import { typeOrigins, typed } from "./lib/types.js";
|
|
21
|
+
import { originsOfType, resolvedSymbol, typeOrigins, typed } from "./lib/types.js";
|
|
19
22
|
const isJobClaimsType = (context, node) => isOwnedType(context, node, { name: "JobClaims", capability: "jobs", tier: "platform" });
|
|
20
23
|
const isJobStepType = (context, node) => isOwnedType(context, node, { name: "JobStep", capability: "jobs", tier: "platform" });
|
|
21
24
|
const isFencedProcessorType = (context, node) => isOwnedType(context, node, { name: "FencedProcessor", capability: "jobs", tier: "platform" });
|
|
22
|
-
const
|
|
25
|
+
const isClaimedJobType = (context, node) => isOwnedType(context, node, { name: "ClaimedJob", capability: "jobs", tier: "platform" });
|
|
26
|
+
const isEffectsType = (context, node) => isOwnedType(context, node, { name: "Effects", capability: "effects", tier: "platform" });
|
|
27
|
+
const isRealtimeHubType = (context, node) => isOwnedType(context, node, { name: "RealtimeHub", capability: "realtime", tier: "platform" });
|
|
28
|
+
/** The contract's own members and types the rules below read. */
|
|
29
|
+
const ONCE = "once";
|
|
30
|
+
const ACT = "act";
|
|
31
|
+
const CONFIRM = "confirm";
|
|
32
|
+
const NEXT = "next";
|
|
33
|
+
const PROGRESS = "progress";
|
|
34
|
+
const TOPIC = "topic";
|
|
35
|
+
const DEFINE_JOB = "defineJob";
|
|
36
|
+
const PROGRESS_TOPIC = "JobProgressTopic";
|
|
23
37
|
/** True for a file of the owner itself, and for the test composition. */
|
|
24
38
|
const isOwnerOrTest = (hfs, file) => {
|
|
25
39
|
const tier = hfs.tierOf(file);
|
|
@@ -129,38 +143,311 @@ export const jobFenceRequired = {
|
|
|
129
143
|
};
|
|
130
144
|
},
|
|
131
145
|
};
|
|
132
|
-
/**
|
|
133
|
-
|
|
146
|
+
/** True for a function node that takes a `ClaimedJob`: the domain method a job's step calls. */
|
|
147
|
+
const takesClaimedJob = (context, fn) => fn.params.some((param) => {
|
|
148
|
+
const target = param.type === "TSParameterProperty" ? param.parameter : param;
|
|
149
|
+
const bound = target.type === "AssignmentPattern" ? target.left : target;
|
|
150
|
+
return isClaimedJobType(context, bound);
|
|
151
|
+
});
|
|
152
|
+
/** True when the node sits inside a function (or a closure of one) that takes a `ClaimedJob`. */
|
|
153
|
+
const insideJobFunction = (context, node) => {
|
|
154
|
+
for (let current = node.parent; current; current = current.parent) {
|
|
155
|
+
if ((current.type === "FunctionDeclaration" || current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") && takesClaimedJob(context, current))
|
|
156
|
+
return true;
|
|
157
|
+
}
|
|
158
|
+
return false;
|
|
159
|
+
};
|
|
160
|
+
/** True for `Effects.once(...)`: a call of `once` on the `Effects` port of `platform/effects`. */
|
|
161
|
+
const isEffectsOnce = (context, call) => call.callee.type === "MemberExpression"
|
|
162
|
+
&& !call.callee.computed
|
|
163
|
+
&& call.callee.property.type === "Identifier"
|
|
164
|
+
&& call.callee.property.name === ONCE
|
|
165
|
+
&& isEffectsType(context, call.callee.object);
|
|
166
|
+
/**
|
|
167
|
+
* True for a call of a function that `platform/effects` itself declares and that is handed the `Effects` port (a helper of the piece,
|
|
168
|
+
* such as one that answers what the act answered): the piece runs the functions passed to it inside its own `Effects.once`.
|
|
169
|
+
*/
|
|
170
|
+
const isEffectsHelperCall = (context, call) => {
|
|
171
|
+
if (!call.arguments.some((argument) => argument.type !== "SpreadElement" && isEffectsType(context, argument)))
|
|
172
|
+
return false;
|
|
173
|
+
const hfs = hfsOf(context);
|
|
174
|
+
const { checker, toTs } = typed(context);
|
|
175
|
+
const target = toTs(call.callee.type === "MemberExpression" ? call.callee.property : call.callee);
|
|
176
|
+
const symbol = resolvedSymbol(checker, target ? checker.getSymbolAtLocation(target) : undefined);
|
|
177
|
+
return (symbol?.declarations ?? []).some((declaration) => {
|
|
178
|
+
const file = String(declaration.getSourceFile().fileName).replace(/\\/g, "/");
|
|
179
|
+
return hfs.tierOf(file) === "platform" && ownerNameOf(hfs, file) === "effects";
|
|
180
|
+
});
|
|
181
|
+
};
|
|
182
|
+
/**
|
|
183
|
+
* True when the expression is handed to the effects piece as an act or a confirm read: the value of `act` or `confirm` in the call
|
|
184
|
+
* object of `Effects.once`, or a function argument of a helper of the piece.
|
|
185
|
+
*/
|
|
186
|
+
const isHandedToEffects = (context, expression) => {
|
|
187
|
+
const parent = expression.parent;
|
|
188
|
+
if (parent?.type === "CallExpression" && parent.arguments.includes(expression))
|
|
189
|
+
return isEffectsHelperCall(context, parent);
|
|
190
|
+
if (parent?.type !== "Property" || parent.value !== expression)
|
|
191
|
+
return false;
|
|
192
|
+
const key = keyName(parent.key);
|
|
193
|
+
if (key !== ACT && key !== CONFIRM)
|
|
194
|
+
return false;
|
|
195
|
+
const object = parent.parent;
|
|
196
|
+
const call = object?.parent;
|
|
197
|
+
return object?.type === "ObjectExpression" && call?.type === "CallExpression" && call.arguments.includes(object) && isEffectsOnce(context, call);
|
|
198
|
+
};
|
|
199
|
+
/**
|
|
200
|
+
* True when the function is an act or a confirm read the effects piece runs: handed to it directly, or bound to a `const` whose every
|
|
201
|
+
* use hands it to the piece (`const act = () => ...` then `{ act }`).
|
|
202
|
+
*/
|
|
203
|
+
const isEffectsAct = (context, fn) => {
|
|
204
|
+
if (isHandedToEffects(context, fn))
|
|
205
|
+
return true;
|
|
206
|
+
const declarator = fn.parent;
|
|
207
|
+
if (declarator?.type !== "VariableDeclarator" || declarator.init !== fn || declarator.id.type !== "Identifier")
|
|
208
|
+
return false;
|
|
209
|
+
if (declarator.parent.type !== "VariableDeclaration" || declarator.parent.kind !== "const")
|
|
210
|
+
return false;
|
|
211
|
+
const uses = context.sourceCode.getDeclaredVariables(declarator).flatMap((variable) => variable.references.filter((reference) => !reference.init));
|
|
212
|
+
// A use that only calls it (`return act()`, a path with no job) makes no outside call of a job by itself; the rule judges the uses that hand it on.
|
|
213
|
+
const handed = uses.filter((reference) => !(reference.identifier.parent.type === "CallExpression" && reference.identifier.parent.callee === reference.identifier));
|
|
214
|
+
return handed.length > 0 && handed.every((reference) => isHandedToEffects(context, reference.identifier));
|
|
215
|
+
};
|
|
216
|
+
/** True when the call is an act or a confirm read the effects piece runs: inside a function handed to `Effects.once` or to a helper of the piece. */
|
|
217
|
+
const insideEffectCall = (context, node) => {
|
|
218
|
+
for (let current = node.parent; current; current = current.parent) {
|
|
219
|
+
if ((current.type === "FunctionExpression" || current.type === "ArrowFunctionExpression") && isEffectsAct(context, current))
|
|
220
|
+
return true;
|
|
221
|
+
}
|
|
222
|
+
return false;
|
|
223
|
+
};
|
|
224
|
+
/** The marker a port declares its outside reads with: `OutsideReads<"member" | ...>` of `platform/effects`. */
|
|
225
|
+
const OUTSIDE_READS = "OutsideReads";
|
|
226
|
+
/** True for the phantom property of `OutsideReads`, judged by where it is declared: the interface `platform/effects` declares. */
|
|
227
|
+
const isOutsideReadsMarker = (hfs, property) => (property.declarations ?? []).some((declaration) => {
|
|
228
|
+
const holder = declaration.parent;
|
|
229
|
+
if (!ts.isInterfaceDeclaration(holder) || holder.name.text !== OUTSIDE_READS)
|
|
230
|
+
return false;
|
|
231
|
+
const file = String(declaration.getSourceFile().fileName).replace(/\\/g, "/");
|
|
232
|
+
return hfs.tierOf(file) === "platform" && ownerNameOf(hfs, file) === "effects";
|
|
233
|
+
});
|
|
234
|
+
/**
|
|
235
|
+
* The members a port declares as outside READS: the string literals of the `OutsideReads` its type extends (the port's interface, or an
|
|
236
|
+
* interface merged with a client class) or that the contract a class implements extends. A member the port does not declare is an act, so a forgotten declaration only makes the rule stricter.
|
|
237
|
+
*/
|
|
238
|
+
const declaredReads = (hfs, checker, type) => {
|
|
239
|
+
const reads = new Set();
|
|
240
|
+
const collect = (holder) => {
|
|
241
|
+
for (const property of checker.getPropertiesOfType(holder)) {
|
|
242
|
+
if (!isOutsideReadsMarker(hfs, property))
|
|
243
|
+
continue;
|
|
244
|
+
const members = checker.getTypeOfSymbol(property);
|
|
245
|
+
for (const part of members.isUnion() ? members.types : [members])
|
|
246
|
+
if (part.isStringLiteral())
|
|
247
|
+
reads.add(part.value);
|
|
248
|
+
}
|
|
249
|
+
};
|
|
250
|
+
collect(type);
|
|
251
|
+
for (const declaration of type.getSymbol()?.declarations ?? []) {
|
|
252
|
+
if (!ts.isClassDeclaration(declaration))
|
|
253
|
+
continue;
|
|
254
|
+
for (const clause of declaration.heritageClauses ?? [])
|
|
255
|
+
for (const implemented of clause.types)
|
|
256
|
+
collect(checker.getTypeAtLocation(implemented));
|
|
257
|
+
}
|
|
258
|
+
return reads;
|
|
259
|
+
};
|
|
260
|
+
/** True when the call is a member its port declares as an outside read (`OutsideReads`): a read has no intent to protect. */
|
|
261
|
+
const isDeclaredRead = (context, callee) => {
|
|
262
|
+
if (callee.property.type !== "Identifier")
|
|
263
|
+
return false;
|
|
264
|
+
const { checker, toTs } = typed(context);
|
|
265
|
+
const receiver = toTs(callee.object);
|
|
266
|
+
if (!receiver)
|
|
267
|
+
return false;
|
|
268
|
+
return declaredReads(hfsOf(context), checker, checker.getTypeAtLocation(receiver)).has(callee.property.name);
|
|
269
|
+
};
|
|
270
|
+
/** An outside call of a job is made by the effects piece: its intent row before the act, its result after. */
|
|
271
|
+
export const jobEffectPiece = {
|
|
134
272
|
meta: {
|
|
135
273
|
type: "problem",
|
|
136
|
-
docs: { description: "In a job step every call on an integration port
|
|
274
|
+
docs: { description: "In a job step, and in a function that takes a `ClaimedJob`, every call on an integration port that its port does not declare an outside read (`OutsideReads` of `platform/effects`) is the `act` or the `confirm` read of an `Effects.once` call of `platform/effects`." },
|
|
137
275
|
schema: [],
|
|
138
276
|
messages: {
|
|
139
|
-
|
|
140
|
-
forged: "This `RunKey` is built with a cast. Only `JobClaims.runKey(job, step)` makes one, so the key always carries the fencing token of the claim.",
|
|
277
|
+
outside: "`{{call}}` is an outside call of a job made without the effects piece. An act outside the database (a provider call, a mail, a paid model call, a write to an index) goes through `Effects.once(key, effect, { act, confirm?, ... })` of `platform/effects`: its intent row is committed before the act and its result after, so a crash between them is settled as the effect declares (`repeatable`, `confirm` or `person`) and never acted twice blind. A member that only reads the outside world has no intent to protect: its port declares it in `OutsideReads<\"member\">` of `platform/effects` (the port's interface extends it; a client class with no contract merges an interface of its own name that extends it); an undeclared member is an act.",
|
|
141
278
|
},
|
|
142
279
|
},
|
|
143
280
|
create(context) {
|
|
144
281
|
const hfs = hfsOf(context);
|
|
145
|
-
|
|
282
|
+
const file = context.filename;
|
|
283
|
+
const inStep = hfs.slotOf(file) === "be.feature.jobs.steps";
|
|
284
|
+
const inDomain = hfs.tierOf(file) === "domain";
|
|
285
|
+
if (!inStep && !inDomain)
|
|
146
286
|
return {};
|
|
147
287
|
return {
|
|
148
288
|
CallExpression(node) {
|
|
149
289
|
const callee = node.callee;
|
|
150
290
|
if (callee.type !== "MemberExpression" || callee.computed)
|
|
151
291
|
return;
|
|
292
|
+
if (!inStep && !insideJobFunction(context, node))
|
|
293
|
+
return;
|
|
152
294
|
const origins = typeOrigins(context, callee.object);
|
|
153
295
|
if (!origins.some((origin) => origin.module === null && hfs.tierOf(origin.file) === "integrations"))
|
|
154
296
|
return;
|
|
155
|
-
|
|
156
|
-
if (keyArguments.length === 0) {
|
|
157
|
-
context.report({ node, messageId: "missing", data: { call: context.sourceCode.getText(callee) } });
|
|
297
|
+
if (isDeclaredRead(context, callee) || insideEffectCall(context, node))
|
|
158
298
|
return;
|
|
299
|
+
context.report({ node, messageId: "outside", data: { call: context.sourceCode.getText(callee) } });
|
|
300
|
+
},
|
|
301
|
+
};
|
|
302
|
+
},
|
|
303
|
+
};
|
|
304
|
+
/** The names of the jobs the `defineJob` calls of the program declare, read once per program. */
|
|
305
|
+
const declaredJobNames = (context, hfs) => {
|
|
306
|
+
const { program, checker } = typed(context);
|
|
307
|
+
const known = declaredNames.get(program);
|
|
308
|
+
if (known)
|
|
309
|
+
return known;
|
|
310
|
+
const names = new Set();
|
|
311
|
+
const visit = (node) => {
|
|
312
|
+
if (ts.isCallExpression(node) && isDefineJobCall(hfs, checker, node)) {
|
|
313
|
+
const name = propertyValue(node.arguments[0], "name");
|
|
314
|
+
const type = name ? checker.getTypeAtLocation(name) : undefined;
|
|
315
|
+
if (type?.isStringLiteral())
|
|
316
|
+
names.add(type.value);
|
|
317
|
+
}
|
|
318
|
+
ts.forEachChild(node, visit);
|
|
319
|
+
};
|
|
320
|
+
for (const sourceFile of program.getSourceFiles()) {
|
|
321
|
+
if (!sourceFile.isDeclarationFile && hfs.slotOf(sourceFile.fileName) === "be.queues")
|
|
322
|
+
visit(sourceFile);
|
|
323
|
+
}
|
|
324
|
+
declaredNames.set(program, names);
|
|
325
|
+
return names;
|
|
326
|
+
};
|
|
327
|
+
/** The declared names per program: one scan serves every file linted in it. */
|
|
328
|
+
const declaredNames = new WeakMap();
|
|
329
|
+
/** The initializer of the property `name` in an object literal argument, or undefined. */
|
|
330
|
+
const propertyValue = (argument, name) => {
|
|
331
|
+
if (!argument || !ts.isObjectLiteralExpression(argument))
|
|
332
|
+
return undefined;
|
|
333
|
+
for (const property of argument.properties) {
|
|
334
|
+
if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === name)
|
|
335
|
+
return property.initializer;
|
|
336
|
+
}
|
|
337
|
+
return undefined;
|
|
338
|
+
};
|
|
339
|
+
/** True when a TypeScript call is `defineJob` of `platform/jobs`, judged by the declaration the callee resolves to. */
|
|
340
|
+
const isDefineJobCall = (hfs, checker, call) => {
|
|
341
|
+
const target = ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression;
|
|
342
|
+
let symbol = checker.getSymbolAtLocation(target);
|
|
343
|
+
if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0)
|
|
344
|
+
symbol = checker.getAliasedSymbol(symbol);
|
|
345
|
+
return symbol?.getName() === DEFINE_JOB && (symbol.declarations ?? []).some((declaration) => {
|
|
346
|
+
const owner = declaration.getSourceFile().fileName;
|
|
347
|
+
return hfs.tierOf(owner) === "platform" && ownerNameOf(hfs, owner) === "jobs";
|
|
348
|
+
});
|
|
349
|
+
};
|
|
350
|
+
/** The `defineJob` calls of an ESTree program, with the object literal they declare. */
|
|
351
|
+
const isDefineJobNode = (context, hfs, node) => {
|
|
352
|
+
const { checker, toTs } = typed(context);
|
|
353
|
+
const tsNode = toTs(node);
|
|
354
|
+
return Boolean(tsNode) && ts.isCallExpression(tsNode) && isDefineJobCall(hfs, checker, tsNode);
|
|
355
|
+
};
|
|
356
|
+
/** The value node of a property of an object literal, by key. */
|
|
357
|
+
const memberOf = (object, name) => object.properties.find((property) => property.type === "Property" && !property.computed && keyName(property.key) === name);
|
|
358
|
+
/** A job's `next` names only jobs a `defineJob` declares. */
|
|
359
|
+
export const jobNextDeclared = {
|
|
360
|
+
meta: {
|
|
361
|
+
type: "problem",
|
|
362
|
+
docs: { description: "In a `defineJob` declaration `next` is an array literal of statically readable job names, each the name of a job a `defineJob` of the program declares." },
|
|
363
|
+
schema: [],
|
|
364
|
+
messages: {
|
|
365
|
+
shape: "`next` of a job declaration is an array literal of job names. A computed, spread or variable list hides which jobs the job may enqueue, and the queue platform refuses an enqueue its `next` does not list; write the names out.",
|
|
366
|
+
literal: "This `next` entry is not a statically readable job name (a string literal or an enum member). Name the job the way its own `defineJob` does, so the chain can be read from the declarations.",
|
|
367
|
+
unknown: "`next` lists the job `{{name}}`, but no `defineJob` of the program declares a job of that name. A chain is the jobs the declarations name: declare the next job, or delete the entry.",
|
|
368
|
+
},
|
|
369
|
+
},
|
|
370
|
+
create(context) {
|
|
371
|
+
const hfs = hfsOf(context);
|
|
372
|
+
if (hfs.slotOf(context.filename) !== "be.queues")
|
|
373
|
+
return {};
|
|
374
|
+
const { checker, toTs } = typed(context);
|
|
375
|
+
return {
|
|
376
|
+
CallExpression(node) {
|
|
377
|
+
if (!isDefineJobNode(context, hfs, node))
|
|
378
|
+
return;
|
|
379
|
+
const [declaration] = node.arguments;
|
|
380
|
+
if (declaration?.type !== "ObjectExpression")
|
|
381
|
+
return;
|
|
382
|
+
const next = memberOf(declaration, NEXT);
|
|
383
|
+
if (!next)
|
|
384
|
+
return;
|
|
385
|
+
if (next.value.type !== "ArrayExpression") {
|
|
386
|
+
context.report({ node: next.value, messageId: "shape" });
|
|
387
|
+
return;
|
|
388
|
+
}
|
|
389
|
+
const declared = declaredJobNames(context, hfs);
|
|
390
|
+
for (const entry of next.value.elements) {
|
|
391
|
+
if (!entry || entry.type === "SpreadElement") {
|
|
392
|
+
context.report({ node: entry ?? next.value, messageId: "shape" });
|
|
393
|
+
continue;
|
|
394
|
+
}
|
|
395
|
+
const tsEntry = toTs(entry);
|
|
396
|
+
const type = tsEntry ? checker.getTypeAtLocation(tsEntry) : undefined;
|
|
397
|
+
if (!type?.isStringLiteral())
|
|
398
|
+
context.report({ node: entry, messageId: "literal" });
|
|
399
|
+
else if (!declared.has(type.value))
|
|
400
|
+
context.report({ node: entry, messageId: "unknown", data: { name: type.value } });
|
|
159
401
|
}
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
402
|
+
},
|
|
403
|
+
};
|
|
404
|
+
},
|
|
405
|
+
};
|
|
406
|
+
/** True when a type is a function type whose every return is `JobProgressTopic` of `platform/jobs`. */
|
|
407
|
+
const returnsProgressTopic = (checker, hfs, type) => {
|
|
408
|
+
const signatures = type.getCallSignatures();
|
|
409
|
+
return signatures.length > 0 && signatures.every((signature) => originsOfType(checker, checker.getReturnTypeOfSignature(signature)).some((origin) => origin.module === null && origin.name === PROGRESS_TOPIC && hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === "jobs"));
|
|
410
|
+
};
|
|
411
|
+
/** A job's progress is a view the frame publishes: its topic is built principal-first, and no domain method publishes it itself. */
|
|
412
|
+
export const jobProgressShape = {
|
|
413
|
+
meta: {
|
|
414
|
+
type: "problem",
|
|
415
|
+
docs: { description: "A `defineJob` `progress.topic` is a function whose declared return type is `JobProgressTopic` of `platform/jobs` (principal first), and a function that takes a `ClaimedJob` never calls the `RealtimeHub`: it reports through `JobProgress`." },
|
|
416
|
+
schema: [],
|
|
417
|
+
messages: {
|
|
418
|
+
topic: "The `progress.topic` of this job does not return a `JobProgressTopic` of `platform/jobs`. A progress topic is principal first, then the chain root, so a client can only read what its principal owns: build it with a function whose declared return type is `JobProgressTopic`, never an object literal or a string.",
|
|
419
|
+
hub: "`{{call}}` publishes to the realtime hub from a function that takes a `ClaimedJob`. The progress of a job is a view the jobs frame publishes after commit: report step progress through `JobProgress.report(job, done, total, labelKey)`, which stores it on the job row first.",
|
|
420
|
+
},
|
|
421
|
+
},
|
|
422
|
+
create(context) {
|
|
423
|
+
const hfs = hfsOf(context);
|
|
424
|
+
const file = context.filename;
|
|
425
|
+
const inQueues = hfs.slotOf(file) === "be.queues";
|
|
426
|
+
const inDomain = hfs.tierOf(file) === "domain";
|
|
427
|
+
if (!inQueues && !inDomain)
|
|
428
|
+
return {};
|
|
429
|
+
const { checker, toTs } = typed(context);
|
|
430
|
+
return {
|
|
431
|
+
CallExpression(node) {
|
|
432
|
+
if (inQueues && isDefineJobNode(context, hfs, node)) {
|
|
433
|
+
const [declaration] = node.arguments;
|
|
434
|
+
if (declaration?.type !== "ObjectExpression")
|
|
435
|
+
return;
|
|
436
|
+
const progress = memberOf(declaration, PROGRESS);
|
|
437
|
+
if (progress?.value.type !== "ObjectExpression")
|
|
438
|
+
return;
|
|
439
|
+
const topic = memberOf(progress.value, TOPIC);
|
|
440
|
+
const tsTopic = topic ? toTs(topic.value) : undefined;
|
|
441
|
+
if (!topic || !tsTopic || !returnsProgressTopic(checker, hfs, checker.getTypeAtLocation(tsTopic)))
|
|
442
|
+
context.report({ node: topic ?? progress.value, messageId: "topic" });
|
|
443
|
+
return;
|
|
163
444
|
}
|
|
445
|
+
const callee = node.callee;
|
|
446
|
+
if (!inDomain || callee.type !== "MemberExpression" || callee.computed)
|
|
447
|
+
return;
|
|
448
|
+
if (!isRealtimeHubType(context, callee.object) || !insideJobFunction(context, node))
|
|
449
|
+
return;
|
|
450
|
+
context.report({ node, messageId: "hub", data: { call: context.sourceCode.getText(callee) } });
|
|
164
451
|
},
|
|
165
452
|
};
|
|
166
453
|
},
|
|
@@ -219,13 +506,17 @@ export const jobShape = {
|
|
|
219
506
|
export const rules = {
|
|
220
507
|
"job-write-owner": jobWriteOwner,
|
|
221
508
|
"job-fence-required": jobFenceRequired,
|
|
222
|
-
"job-
|
|
509
|
+
"job-effect-piece": jobEffectPiece,
|
|
223
510
|
"job-shape": jobShape,
|
|
511
|
+
"job-next-declared": jobNextDeclared,
|
|
512
|
+
"job-progress-shape": jobProgressShape,
|
|
224
513
|
};
|
|
225
514
|
/** The level these laws ask for: `error`, switched off nowhere. */
|
|
226
515
|
export const recommended = {
|
|
227
516
|
"starci-be/job-write-owner": "error",
|
|
228
517
|
"starci-be/job-fence-required": "error",
|
|
229
|
-
"starci-be/job-
|
|
518
|
+
"starci-be/job-effect-piece": "error",
|
|
230
519
|
"starci-be/job-shape": "error",
|
|
520
|
+
"starci-be/job-next-declared": "error",
|
|
521
|
+
"starci-be/job-progress-shape": "error",
|
|
231
522
|
};
|
package/dist/lib/config.d.ts
CHANGED
|
@@ -47,7 +47,8 @@ export declare const PACKAGE_IGNORED: readonly string[];
|
|
|
47
47
|
* `packages/<pkg>/src/**`. Which files are the front end's is the project's declaration, never a folder name this canon knows: a slot of
|
|
48
48
|
* `ext/manifest.json` `packages` with `lint: "fe"` is left to the front-end canon, and the first slot that holds a file decides
|
|
49
49
|
* (`hfs.packageLint`, PROJECT-LINT-3), so a back-end slot declared before a front-end slot it lies in stays back end. A package the project
|
|
50
|
-
* does not declare is back end whole. It is the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`).
|
|
50
|
+
* does not declare is back end whole. It is the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`). A nivoos package the project
|
|
51
|
+
* declares (`hfs.packageLint.nivoos`) is judged by the SDK authoring profile, which keeps the rule set but the rules lib/nivoos-profile.ts relaxes, each with its reason.
|
|
51
52
|
*
|
|
52
53
|
* @param {object} input - The attachment options of `buildBeConfig`.
|
|
53
54
|
* @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package files.
|
package/dist/lib/config.js
CHANGED
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
import tsParser from "@typescript-eslint/parser";
|
|
20
20
|
import { OUTSIDE_THE_SCAN_FILES } from "../../runtime/scripts/lib/sonar-syntax-rules.mjs";
|
|
21
21
|
import { sonarWayRules, sonarWayTestRules } from "../../runtime/scripts/lib/sonar-way.mjs";
|
|
22
|
+
import { withoutRelaxed } from "./nivoos-profile.js";
|
|
22
23
|
/** A disable directive is a weakening of lint, and one that suppresses nothing is dead weight. */
|
|
23
24
|
export const linterOptions = Object.freeze({ noInlineConfig: true, reportUnusedDisableDirectives: "error" });
|
|
24
25
|
/** Every tracked source a back end holds; the factory lints them all. */
|
|
@@ -113,23 +114,32 @@ export const PACKAGE_IGNORED = Object.freeze(["**/dist/**", "**/coverage/**", "*
|
|
|
113
114
|
* `packages/<pkg>/src/**`. Which files are the front end's is the project's declaration, never a folder name this canon knows: a slot of
|
|
114
115
|
* `ext/manifest.json` `packages` with `lint: "fe"` is left to the front-end canon, and the first slot that holds a file decides
|
|
115
116
|
* (`hfs.packageLint`, PROJECT-LINT-3), so a back-end slot declared before a front-end slot it lies in stays back end. A package the project
|
|
116
|
-
* does not declare is back end whole. It is the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`).
|
|
117
|
+
* does not declare is back end whole. It is the very rule set of the be side, over the package view of the app root (`loadPackagesHfs`). A nivoos package the project
|
|
118
|
+
* declares (`hfs.packageLint.nivoos`) is judged by the SDK authoring profile, which keeps the rule set but the rules lib/nivoos-profile.ts relaxes, each with its reason.
|
|
117
119
|
*
|
|
118
120
|
* @param {object} input - The attachment options of `buildBeConfig`.
|
|
119
121
|
* @returns {Promise<Array<object>>} The flat config: one ignore block and the rule and Sonar way blocks over the package files.
|
|
120
122
|
*/
|
|
121
123
|
export const buildBePackagesConfig = async (input) => {
|
|
122
124
|
const [, ...blocks] = await buildBeConfig(input);
|
|
123
|
-
const lint = input.hfs?.packageLint ?? { frontEnd: [], fe: [], be: [] };
|
|
125
|
+
const lint = input.hfs?.packageLint ?? { frontEnd: [], fe: [], be: [], nivoos: [] };
|
|
126
|
+
const nivoos = lint.nivoos ?? [];
|
|
127
|
+
// The nivoos packages the project declares (slot app.nivoos-package, `lintProfile: nivoos`) are judged by the SDK authoring profile instead: the same blocks over their source with the
|
|
128
|
+
// recommendation less the rules the profile relaxes (lib/nivoos-profile.ts). Every other package file keeps the back end's canon, and the nivoos source is left out of it.
|
|
129
|
+
const profiled = nivoos.length === 0 ? [] : (await buildBeConfig({ ...input, recommended: withoutRelaxed(input.recommended ?? {}) })).slice(1);
|
|
124
130
|
return [
|
|
125
131
|
{ ignores: [...PACKAGE_IGNORED] },
|
|
126
132
|
...blocks.flatMap((block) => {
|
|
127
133
|
const tests = block.name === TEST_SCOPE_BLOCK;
|
|
128
134
|
return [
|
|
129
|
-
{ ...block, files: [...(tests ? PACKAGE_SPEC_FILES : PACKAGE_SOURCE_FILES)], ignores: [...(block.ignores ?? []), ...lint.frontEnd] },
|
|
135
|
+
{ ...block, files: [...(tests ? PACKAGE_SPEC_FILES : PACKAGE_SOURCE_FILES)], ignores: [...(block.ignores ?? []), ...lint.frontEnd, ...nivoos] },
|
|
130
136
|
// A back-end slot declared before a front-end slot that reaches it: its files, less the front-end slots declared before it.
|
|
131
137
|
...lint.be.map((scope) => ({ ...block, files: [[scope.files, tests ? SCRIPT_SPEC : SCRIPT]], ignores: [...(block.ignores ?? []), ...scope.ignores] })),
|
|
132
138
|
];
|
|
133
139
|
}),
|
|
140
|
+
...profiled.flatMap((block) => {
|
|
141
|
+
const tests = block.name === TEST_SCOPE_BLOCK;
|
|
142
|
+
return nivoos.map((glob) => ({ ...block, files: [[glob, tests ? SCRIPT_SPEC : SCRIPT]] }));
|
|
143
|
+
}),
|
|
134
144
|
];
|
|
135
145
|
};
|
package/dist/lib/hfs-view.d.ts
CHANGED
|
@@ -63,6 +63,8 @@ export interface HfsSlot {
|
|
|
63
63
|
readonly role?: string;
|
|
64
64
|
/** The side-relative path patterns of the only files that may import this file by deep path. */
|
|
65
65
|
readonly importedBy?: readonly string[];
|
|
66
|
+
/** The lint profile the slot hands the canon (`nivoos`: the SDK authoring profile of a declared nivoos package). */
|
|
67
|
+
readonly lintProfile?: string;
|
|
66
68
|
}
|
|
67
69
|
/** A unit-tested role (`ruleParams.be.unitRoles`). */
|
|
68
70
|
export interface HfsUnitRole {
|
|
@@ -184,6 +186,8 @@ export interface HfsPackageLint {
|
|
|
184
186
|
readonly frontEnd: readonly string[];
|
|
185
187
|
readonly fe: readonly HfsPackageLintScope[];
|
|
186
188
|
readonly be: readonly HfsPackageLintScope[];
|
|
189
|
+
/** The source globs (`packages/<name>/src/**`) of the nivoos packages the project declares, judged by the SDK authoring profile. */
|
|
190
|
+
readonly nivoos?: readonly string[];
|
|
187
191
|
}
|
|
188
192
|
/** A type a root package declares: its name and the app-root relative file that declares it. */
|
|
189
193
|
export interface HfsPackageDeclaredType {
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { HfsView } from "./hfs-view.js";
|
|
2
|
+
import type { Context } from "./rule.js";
|
|
3
|
+
/** The slot of a declared nivoos package folder. */
|
|
4
|
+
export declare const NIVOOS_SLOT = "app.nivoos-package";
|
|
5
|
+
/** The profile name the slot's `lintProfile` carries. */
|
|
6
|
+
export declare const NIVOOS_PROFILE = "nivoos";
|
|
7
|
+
/**
|
|
8
|
+
* Whether `filename` is source of a declared nivoos package: the slot owns it and hands it the SDK authoring profile.
|
|
9
|
+
*
|
|
10
|
+
* @param hfs - The HFS view of the root packages.
|
|
11
|
+
* @param filename - The linted file.
|
|
12
|
+
* @returns True when the profile applies.
|
|
13
|
+
*/
|
|
14
|
+
export declare const isNivoosAuthored: (hfs: HfsView, filename: string) => boolean;
|
|
15
|
+
/**
|
|
16
|
+
* The same question from inside a rule: is the file being linted source of a declared nivoos package.
|
|
17
|
+
*
|
|
18
|
+
* @param context - The rule context.
|
|
19
|
+
* @returns True when the profile applies.
|
|
20
|
+
*/
|
|
21
|
+
export declare const nivoosAuthored: (context: Context) => boolean;
|
|
22
|
+
/**
|
|
23
|
+
* The package entry the SDK loads by its default export: `packages/<name>/src/<name>.package.ts` (`export default { package, cells, workspaces } satisfies Package`).
|
|
24
|
+
*
|
|
25
|
+
* @param filename - The linted file.
|
|
26
|
+
* @returns True for an entry file.
|
|
27
|
+
*/
|
|
28
|
+
export declare const isNivoosEntry: (filename: string) => boolean;
|
|
29
|
+
/**
|
|
30
|
+
* The rules a nivoos package is not judged by, each with the reason. A rule is dropped for the slot's files only (the same rule stays on everywhere else), and the
|
|
31
|
+
* reason is the finding: what the real package showed and why the rule's own purpose does not hold for SDK code.
|
|
32
|
+
*/
|
|
33
|
+
export declare const NIVOOS_RELAXED: Readonly<Record<string, string>>;
|
|
34
|
+
/**
|
|
35
|
+
* The rule levels of a nivoos package: the recommendation less the relaxed rules.
|
|
36
|
+
*
|
|
37
|
+
* @param recommended - The canon levels of the root packages.
|
|
38
|
+
* @returns The same levels without the rules of `NIVOOS_RELAXED`.
|
|
39
|
+
*/
|
|
40
|
+
export declare const withoutRelaxed: <Level>(recommended: Readonly<Record<string, Level>>) => Record<string, Level>;
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The SDK authoring lint profile: what the canon judges differently in a nivoos package, a business package authored with the nivoos SDK (agents, workflows,
|
|
3
|
+
* cells, steps, brain, accounts, seed). The project declares the package in `hfs.json` `sides.nivoos.packages`; its folder is then the slot `app.nivoos-package`,
|
|
4
|
+
* and the slot's `lintProfile: nivoos` is what puts its source under this profile: the profile is applied by the slot, never by a disable in the file.
|
|
5
|
+
*
|
|
6
|
+
* The profile keeps the whole canon and relaxes exactly what an SDK package cannot satisfy, each for a reason the real findings of a package showed (the
|
|
7
|
+
* `nivo-web` package: 508 findings, of which these relaxations account for 412 and 96 are source to fix). Two rules narrow inside their own file
|
|
8
|
+
* (`no-non-ascii-source` for string literals, `no-default-export` for the package entry); the rest is a rule the profile does not enable, in `NIVOOS_RELAXED`.
|
|
9
|
+
*/
|
|
10
|
+
import { normalizePath } from "./path.js";
|
|
11
|
+
import { hfsOf } from "./hfs.js";
|
|
12
|
+
/** The slot of a declared nivoos package folder. */
|
|
13
|
+
export const NIVOOS_SLOT = "app.nivoos-package";
|
|
14
|
+
/** The profile name the slot's `lintProfile` carries. */
|
|
15
|
+
export const NIVOOS_PROFILE = "nivoos";
|
|
16
|
+
/**
|
|
17
|
+
* Whether `filename` is source of a declared nivoos package: the slot owns it and hands it the SDK authoring profile.
|
|
18
|
+
*
|
|
19
|
+
* @param hfs - The HFS view of the root packages.
|
|
20
|
+
* @param filename - The linted file.
|
|
21
|
+
* @returns True when the profile applies.
|
|
22
|
+
*/
|
|
23
|
+
export const isNivoosAuthored = (hfs, filename) => hfs.slotOf(filename) === NIVOOS_SLOT && hfs.slot(NIVOOS_SLOT)?.lintProfile === NIVOOS_PROFILE;
|
|
24
|
+
/**
|
|
25
|
+
* The same question from inside a rule: is the file being linted source of a declared nivoos package.
|
|
26
|
+
*
|
|
27
|
+
* @param context - The rule context.
|
|
28
|
+
* @returns True when the profile applies.
|
|
29
|
+
*/
|
|
30
|
+
export const nivoosAuthored = (context) => isNivoosAuthored(hfsOf(context), context.filename);
|
|
31
|
+
/**
|
|
32
|
+
* The package entry the SDK loads by its default export: `packages/<name>/src/<name>.package.ts` (`export default { package, cells, workspaces } satisfies Package`).
|
|
33
|
+
*
|
|
34
|
+
* @param filename - The linted file.
|
|
35
|
+
* @returns True for an entry file.
|
|
36
|
+
*/
|
|
37
|
+
export const isNivoosEntry = (filename) => /\/packages\/[^/]+\/src\/[^/]+\.package\.ts$/.test(`/${normalizePath(filename).replace(/^\//, "")}`);
|
|
38
|
+
/**
|
|
39
|
+
* The rules a nivoos package is not judged by, each with the reason. A rule is dropped for the slot's files only (the same rule stays on everywhere else), and the
|
|
40
|
+
* reason is the finding: what the real package showed and why the rule's own purpose does not hold for SDK code.
|
|
41
|
+
*/
|
|
42
|
+
export const NIVOOS_RELAXED = Object.freeze({
|
|
43
|
+
"starci-be/explicit-export-surface": "Its purpose is that importers read a file's declared types without inferring them and are not re-linted when it changes. Nothing imports a business package's source: the nivoos CLI loads the entry and writes the seed document, and the SDK's own interfaces (Node, NodeIf, NodeRun, Workspace, Package) type every member. The SDK idioms it refuses cannot be annotated at all: `export class X extends NodeRun(Cell)<typeof State>` (an extends clause with a call), an exported `z.strictObject(...)` schema the next line's `typeof` reads, `export default {...} satisfies Package`. 186 of 508 findings.",
|
|
44
|
+
"starci-be/require-public-member-jsdoc": "The public members of a cell, step, agent or workspace class are the fields of the SDK interface it implements (key, version, title, input, output, reads, mutation, run, when, yes, no, next, into, label): the SDK documents them, and the class JSDoc (`require-export-jsdoc`, kept) says what this node is for. A sentence on each restates the interface. 152 of 508 findings.",
|
|
45
|
+
"starci-be/job-shape": "The canon's `<step>.step.ts` is the jobs capability's file kind (`features/jobs/<job>/steps/`); the SDK's `.step.ts` is a workflow step (NodeRun, NodeIf) of the same suffix, and an SDK package has no jobs capability. 17 of 508 findings, all false positives of the shared suffix.",
|
|
46
|
+
"starci-be/throw-domain-error": "The failure contract of an SDK node is a thrown Error whose message starts with a snake_case code (`front_door_cannot_answer: ...`) that the platform records on the run; `DomainError` of @starci/common is not a dependency of an SDK package, which authors against the SDK alone. 10 of 508 findings.",
|
|
47
|
+
});
|
|
48
|
+
/**
|
|
49
|
+
* The rule levels of a nivoos package: the recommendation less the relaxed rules.
|
|
50
|
+
*
|
|
51
|
+
* @param recommended - The canon levels of the root packages.
|
|
52
|
+
* @returns The same levels without the rules of `NIVOOS_RELAXED`.
|
|
53
|
+
*/
|
|
54
|
+
export const withoutRelaxed = (recommended) => Object.fromEntries(Object.entries(recommended).filter(([name]) => !(name in NIVOOS_RELAXED)));
|
package/dist/lib/persistence.js
CHANGED
|
@@ -95,7 +95,7 @@ export const connectionFileOf = (hfs, file, role) => {
|
|
|
95
95
|
return connectionsOf(hfs).find((connection) => connection.name === name) ?? null;
|
|
96
96
|
};
|
|
97
97
|
/** The platform capabilities that own a `persistence/` and so may hold an `EntityManager` (a pattern capability is named by its folder). */
|
|
98
|
-
const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox", "realtime", "http-security"];
|
|
98
|
+
const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "effects", "saga", "outbox", "realtime", "http-security"];
|
|
99
99
|
/**
|
|
100
100
|
* Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a projection, a typed queue producer (it takes the transaction of its caller), a platform persistence capability.
|
|
101
101
|
*
|
package/dist/naming.js
CHANGED
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
* that. Those are read by a person, which is why the law states them with the scars attached.
|
|
31
31
|
*/
|
|
32
32
|
import { hfsOf, inTestWorld } from "./lib/hfs.js";
|
|
33
|
+
import { isNivoosEntry, nivoosAuthored } from "./lib/nivoos-profile.js";
|
|
33
34
|
import { normalizePath } from "./lib/path.js";
|
|
34
35
|
/** A schema generation baked into an identifier. */
|
|
35
36
|
const VERSIONED_NAME = /(?:^|[a-z])V[0-9]+(?:$|[A-Z_])|_V[0-9]+/;
|
|
@@ -198,8 +199,10 @@ export const noBareVerbExport = {
|
|
|
198
199
|
},
|
|
199
200
|
};
|
|
200
201
|
// -- no-default-export -------------------------------------------------------------------------------------------
|
|
201
|
-
/**
|
|
202
|
+
/** A file kind that may default-export: a Jest global setup, whose API is a default function. */
|
|
202
203
|
const isGlobalSetup = (context) => inTestWorld(hfsOf(context), context.filename) && /\/global-(?:setup|teardown)\.ts$/.test(normalizePath(context.filename));
|
|
204
|
+
/** The other file kind that may default-export: the entry of a declared nivoos package (`src/<name>.package.ts`), which the SDK loads by its default export (lib/nivoos-profile.ts). */
|
|
205
|
+
const isNivoosPackageEntry = (context) => nivoosAuthored(context) && isNivoosEntry(context.filename);
|
|
203
206
|
/** Named exports only: a default export has no name to grep, rename or import-check. */
|
|
204
207
|
export const noDefaultExport = {
|
|
205
208
|
meta: {
|
|
@@ -207,13 +210,13 @@ export const noDefaultExport = {
|
|
|
207
210
|
docs: { description: "TypeScript source uses named exports only; the Jest global setup is the one exception." },
|
|
208
211
|
schema: [],
|
|
209
212
|
messages: {
|
|
210
|
-
default: "A default export has no name of its own: every importer picks one, renames and greps stop working, and the file cannot be found by what it exports. Use a named export. (The only default
|
|
213
|
+
default: "A default export has no name of its own: every importer picks one, renames and greps stop working, and the file cannot be found by what it exports. Use a named export. (The only default exports are the Jest `global-setup.ts`/`global-teardown.ts` of the e2e world and the entry of a nivoos package, whose APIs require it.)",
|
|
211
214
|
},
|
|
212
215
|
},
|
|
213
216
|
create(context) {
|
|
214
217
|
if (!/\.[cm]?ts$/.test(normalizePath(context.filename)))
|
|
215
218
|
return {};
|
|
216
|
-
if (isGlobalSetup(context))
|
|
219
|
+
if (isGlobalSetup(context) || isNivoosPackageEntry(context))
|
|
217
220
|
return {};
|
|
218
221
|
const isDefault = (name) => name && ((name.type === "Identifier" && name.name === "default") || (name.type === "Literal" && name.value === "default"));
|
|
219
222
|
return {
|
package/dist/realtime.js
CHANGED
|
@@ -10,11 +10,14 @@
|
|
|
10
10
|
* `.subscription.ts` holds one `@Resolver` class whose operations are `@Subscription`, and an SSE `.controller.ts` holds one
|
|
11
11
|
* `@Controller` class whose one route is `@Sse`. Each is the door its file role names, and none carries a query, a mutation or a
|
|
12
12
|
* plain REST route.
|
|
13
|
-
* - `realtime-read-only` (R185): the only value injected into a realtime door is the `RealtimeHub` of `platform/realtime
|
|
14
|
-
*
|
|
13
|
+
* - `realtime-read-only` (R185): the only value injected into a realtime door is the `RealtimeHub` of `platform/realtime`, or, in an SSE
|
|
14
|
+
* door, ONE stream read service: a class of the platform or domain tier whose public methods all answer an rxjs `Observable`, so the
|
|
15
|
+
* read of "current state, then live" happens in that service and the door stays one call. No `EntityManager`, bus, queue, event bus
|
|
16
|
+
* or other domain service reaches it.
|
|
15
17
|
* - `realtime-topic-scope` (R186): the topic passed to `hub.subscribe` (or `hub.stream`, the SSE form) is built from the principal parameter of the handler
|
|
16
18
|
* (`@CurrentPrincipal()` of `domain/identity`, or `Principal` of `platform/cqrs` for a push-only stream), so a client
|
|
17
|
-
* can only listen to what the principal owns
|
|
19
|
+
* can only listen to what the principal owns; a call to a stream read service passes that principal, which builds the topic the same
|
|
20
|
+
* way. A `Last-Event-ID` header only picks where the replay resumes inside that topic.
|
|
18
21
|
*
|
|
19
22
|
* What a receiver is comes from its TYPE, what a decorator is from the import that binds it, and where a parameter comes
|
|
20
23
|
* from from the declaration its name resolves to. No rule here tests a path pattern or a variable name.
|
|
@@ -24,10 +27,39 @@ import { aliasTarget, callsOf, hasClassDecorator, injectedMembers, methodsDecora
|
|
|
24
27
|
import { hfsOf } from "./lib/hfs.js";
|
|
25
28
|
import { decoratorCallee } from "./lib/import-source.js";
|
|
26
29
|
import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.js";
|
|
30
|
+
import { originsOfType, typed } from "./lib/types.js";
|
|
31
|
+
import ts from "typescript";
|
|
27
32
|
/** The slot of realtime doors. */
|
|
28
33
|
const DOOR_SLOTS = new Set(["be.feature.realtime.graphql", "be.feature.realtime.websocket", "be.feature.realtime.sse"]);
|
|
29
34
|
/** The `RealtimeHub` port of `platform/realtime`. */
|
|
30
35
|
const isHubType = (context, node) => isOwnedType(context, node, { name: "RealtimeHub", capability: "realtime", tier: "platform" });
|
|
36
|
+
/** The slot of server-sent-event doors, the only door kind that may call a stream read service. */
|
|
37
|
+
const SSE_SLOT = "be.feature.realtime.sse";
|
|
38
|
+
/** The tiers a stream read service lives in: the platform capability that owns the stream, or the domain capability that does. */
|
|
39
|
+
const STREAM_SERVICE_TIERS = new Set(["platform", "domain"]);
|
|
40
|
+
/** The package and class of the stream a read service answers. */
|
|
41
|
+
const OBSERVABLE_PACKAGE = "rxjs";
|
|
42
|
+
const OBSERVABLE = "Observable";
|
|
43
|
+
/** True when a TypeScript member is declared private or protected: not part of a class's public surface. */
|
|
44
|
+
const isHidden = (symbol) => (symbol.declarations ?? []).some((declaration) => (ts.getCombinedModifierFlags(declaration) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected)) !== 0);
|
|
45
|
+
/**
|
|
46
|
+
* True when the node's type is a stream read service: declared in the repository by a platform or domain capability, with at least one
|
|
47
|
+
* public method and every public method answering an rxjs `Observable`. What the class IS comes from its type, never its name.
|
|
48
|
+
*/
|
|
49
|
+
const isStreamReadService = (context, hfs, node) => {
|
|
50
|
+
const { checker, toTs } = typed(context);
|
|
51
|
+
const tsNode = toTs(node);
|
|
52
|
+
if (!tsNode)
|
|
53
|
+
return false;
|
|
54
|
+
const type = ts.isTypeNode(tsNode) ? checker.getTypeFromTypeNode(tsNode) : checker.getTypeAtLocation(tsNode);
|
|
55
|
+
if (!originsOfType(checker, type).some((origin) => origin.module === null && STREAM_SERVICE_TIERS.has(hfs.tierOf(origin.file) ?? "")))
|
|
56
|
+
return false;
|
|
57
|
+
const methods = type.getProperties().filter((symbol) => (symbol.flags & ts.SymbolFlags.Method) !== 0 && !isHidden(symbol));
|
|
58
|
+
return methods.length > 0 && methods.every((method) => {
|
|
59
|
+
const signatures = checker.getTypeOfSymbolAtLocation(method, tsNode).getCallSignatures();
|
|
60
|
+
return signatures.length > 0 && signatures.every((signature) => originsOfType(checker, checker.getReturnTypeOfSignature(signature)).some((origin) => origin.module === OBSERVABLE_PACKAGE && origin.name === OBSERVABLE));
|
|
61
|
+
});
|
|
62
|
+
};
|
|
31
63
|
/** The plain HTTP route decorators of `@nestjs/common`: an SSE controller carries none of them, its one route is `@Sse`. */
|
|
32
64
|
const HTTP_ROUTES = ["Get", "Post", "Put", "Patch", "Delete", "All", "Options", "Head"];
|
|
33
65
|
/** The decorators that make a class a door of one kind of realtime file, by file role. */
|
|
@@ -121,21 +153,32 @@ const hasDecorator = (context, decorator, source, name) => hasClassDecorator(con
|
|
|
121
153
|
export const realtimeReadOnly = {
|
|
122
154
|
meta: {
|
|
123
155
|
type: "problem",
|
|
124
|
-
docs: { description: "
|
|
156
|
+
docs: { description: "A realtime door injects the `RealtimeHub` of `platform/realtime` and, in an SSE door, at most one stream read service (public methods that only answer an `Observable`): no `EntityManager`, bus, queue, event bus or other domain service." },
|
|
125
157
|
schema: [],
|
|
126
158
|
messages: {
|
|
127
|
-
injects: "`{{what}}` is injected into a realtime door. A realtime door reads and pushes only: it injects the `RealtimeHub` of `platform/realtime` and nothing that can write (an `EntityManager`, a `CommandBus`, an event bus, a queue,
|
|
159
|
+
injects: "`{{what}}` is injected into a realtime door. A realtime door reads and pushes only: it injects the `RealtimeHub` of `platform/realtime`, or in an SSE door one stream read service whose public methods only answer an `Observable`, and nothing that can write (an `EntityManager`, a `CommandBus`, an event bus, a queue, another domain service). The push is fed by a reactor that calls the hub; a write belongs in an api feature.",
|
|
160
|
+
second: "`{{what}}` is a second stream read service in this realtime door. A door makes ONE call: the read of the current state, the membership check and the topic live in one service, which this door asks.",
|
|
128
161
|
},
|
|
129
162
|
},
|
|
130
163
|
create(context) {
|
|
131
164
|
const hfs = hfsOf(context);
|
|
132
|
-
|
|
165
|
+
const slot = hfs.slotOf(context.filename) ?? "";
|
|
166
|
+
if (!DOOR_SLOTS.has(slot) || roleOf(context.filename) === null)
|
|
133
167
|
return {};
|
|
134
168
|
return {
|
|
135
169
|
ClassDeclaration(node) {
|
|
170
|
+
let services = 0;
|
|
136
171
|
for (const { node: member, annotation } of injectedMembers(context, node)) {
|
|
137
|
-
|
|
138
|
-
|
|
172
|
+
const what = context.sourceCode.getText(member);
|
|
173
|
+
if (annotation && isHubType(context, annotation))
|
|
174
|
+
continue;
|
|
175
|
+
if (slot === SSE_SLOT && annotation && isStreamReadService(context, hfs, annotation)) {
|
|
176
|
+
services += 1;
|
|
177
|
+
if (services > 1)
|
|
178
|
+
context.report({ node: member, messageId: "second", data: { what } });
|
|
179
|
+
continue;
|
|
180
|
+
}
|
|
181
|
+
context.report({ node: member, messageId: "injects", data: { what } });
|
|
139
182
|
}
|
|
140
183
|
},
|
|
141
184
|
};
|
|
@@ -183,6 +226,22 @@ const checkMethodTopics = (context, hfs, method, push) => {
|
|
|
183
226
|
if (!scoped)
|
|
184
227
|
context.report({ node: call, messageId: "scope" });
|
|
185
228
|
}
|
|
229
|
+
if (hfs.slotOf(context.filename) !== SSE_SLOT)
|
|
230
|
+
return;
|
|
231
|
+
for (const { call, receiver } of callsOf(method)) {
|
|
232
|
+
if (receiver === null || isHubType(context, receiver) || !isStreamReadService(context, hfs, receiver))
|
|
233
|
+
continue;
|
|
234
|
+
const passed = call.arguments.some((argument) => {
|
|
235
|
+
let scoped = false;
|
|
236
|
+
walk(argument, (child) => {
|
|
237
|
+
if (child.type === "Identifier" && resolvesTo(context, child, principals))
|
|
238
|
+
scoped = true;
|
|
239
|
+
});
|
|
240
|
+
return scoped;
|
|
241
|
+
});
|
|
242
|
+
if (!passed)
|
|
243
|
+
context.report({ node: call, messageId: "serviceScope" });
|
|
244
|
+
}
|
|
186
245
|
};
|
|
187
246
|
/** The topic a client subscribes to is built from the principal the handler receives. */
|
|
188
247
|
export const realtimeTopicScope = {
|
|
@@ -191,6 +250,7 @@ export const realtimeTopicScope = {
|
|
|
191
250
|
docs: { description: "The topic passed to `RealtimeHub.subscribe` is built from the handler's `@CurrentPrincipal()` parameter or the push-only stream's platform `Principal` parameter." },
|
|
192
251
|
schema: [],
|
|
193
252
|
messages: {
|
|
253
|
+
serviceScope: "The call to the stream read service does not pass the principal. A realtime handler takes `@CurrentPrincipal() principal` and hands it to the service (`this.stream.open(principal, ...)`), which builds the principal-first topic and checks membership before it reads anything; a call that takes only a client selector is a leak.",
|
|
194
254
|
scope: "The topic of this `subscribe` is not built from the principal. A realtime handler takes `@CurrentPrincipal() principal`, or a push-only stream takes the platform `Principal`, and subscribes to a topic made from `principal.id` (plus any verified id), so one client cannot listen to another's channel. A topic taken only from client input is a leak.",
|
|
195
255
|
},
|
|
196
256
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@starci/eslint-canon-be",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.27.1",
|
|
4
4
|
"description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
"node": ">=22.13.0"
|
|
41
41
|
},
|
|
42
42
|
"peerDependencies": {
|
|
43
|
-
"@starci/hfs": "~6.
|
|
43
|
+
"@starci/hfs": "~6.13.0",
|
|
44
44
|
"eslint": ">=9",
|
|
45
45
|
"typescript": ">=5.9"
|
|
46
46
|
},
|
|
@@ -74,6 +74,6 @@
|
|
|
74
74
|
"typescript": "^6.0.3"
|
|
75
75
|
},
|
|
76
76
|
"types": "./dist/index.d.ts",
|
|
77
|
-
"gitHead": "
|
|
78
|
-
"starciSource": "
|
|
77
|
+
"gitHead": "49d93772597ef22ea73bece30b6258a1c94384cc",
|
|
78
|
+
"starciSource": "edc86f0ddfffc6deb46654e3b5ed116d79173f9f98df54867d2ae7c1f530187f"
|
|
79
79
|
}
|