@starci/eslint-canon-be 3.0.9 → 3.1.0

package/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
-## Unreleased
+## 3.1.0 - 2026-10-08
+
+- New: the `sonar-parity` law (R235 `SCAN_SMELL`): `no-await-in-loop` (S9382), `prefer-code-point` (S7758), `prefer-string-raw` (S7780), `no-nested-conditional` (S3358), `no-void-operator` (S3735), `no-unused-import` (S1128) and `prefer-export-from` (S7763), each the syntax-tree form of the Sonar rule SonarCloud flagged in the example apps, shared with the front-end canon through the bundled `runtime/scripts/lib/sonar-syntax-rules.mjs`. The factory also turns on the typescript-eslint rules `no-deprecated` (S1874), `no-base-to-string` (S6551) and `require-await` (S7503).
 
 - New: `feature-thin` (R203 `BE_FEATURE_THIN`, law `feature-thin`): a feature-tier file of a role of `ruleParams.be.thinRoles` (handler, resolver, controller, consumer, processor, step, saga, saga-step, compensation, webhook, gateway, subscription, cli, mapper, the saga orchestrator service) maps its parameters and makes ONE delegating call into modules/, with no branch, loop, ternary, try, throw or computation. The slot manifest copy gains `coverage` on every tracked be slot and `ruleParams.be.logicRoles` and `thinRoles`.
 - Changed: `unit-test-colocated` also allows `<name>.<role>.spec.ts` beside a logic role (policy, client, guard, mapper, ...) inside a slot whose coverage is required; the spec stays required only for the roles of `ruleParams.be.unitRoles`, and the texts say so.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -41,10 +41,11 @@ A sample, not the list:
 | **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration, no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
 | **Config and secrets** | `process.env` (any form), `@nestjs/config`, `dotenv` only in the file of `platform/config` that declares `EnvSource` (and the test world, slot `be.tests.world`, for `process.env`); a function exported by a `<capability>.config.ts` is called only from `apps/<app>/src/main.ts` and `<app>.options.ts`, its own config file or spec, the test world and a provider contract spec (`config-parsed-in-main`); no default of any kind for a value typed `Secret` or `Url`; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `config-parsed-in-main`, `no-secret-default`, `secret-compare-timing-safe`) |
 | **Ambient ids** (R142) | `randomUUID` of Node's crypto (named, namespace or global), the `v1`, `v4`, `v6` and `v7` generators of `uuid`, `nanoid` and `ulid` are used only inside `platform/ids`, specs included: code asks the injected `Ids` port and a spec provides `fakeIds()`; the generators are found by the module they are imported from, never by a local name (`no-ambient-id`) |
+| **Sonar parity** (R235) | The smells SonarCloud measures that a lint rule can decide: no `await` inside a loop (`no-await-in-loop`, S9382; `for (;;)` and `while (true)` are spared), no `charCodeAt`/`fromCharCode` (`prefer-code-point`), no string that only escapes backslashes (`prefer-string-raw`), no nested conditional (`no-nested-conditional`), `void` only on a call (`no-void-operator`), no unused import (`no-unused-import`), `export ... from` for an import that is only handed on (`prefer-export-from`); the factory also turns on typescript-eslint `no-deprecated`, `no-base-to-string` and `require-await`. The files `*.spec.ts` and `*.e2e-spec.ts` are outside the scan, so outside these rules |
 | **Cookies** (R141) | A cookie a door writes through the response of Express or Fastify (`cookie`, `setCookie`) states `httpOnly: true`, `secure: true` and `sameSite` `lax` or `strict` in options typed with those literals, and `Set-Cookie` is never written as a header; the call is recognised by where its signature is declared (`response-cookie-attributes`). A secret-derived value is compared with `timingSafeEqual`: a `Secret` of `platform/config` and the `.digest()` of a `Hash` or `Hmac` of Node's crypto are recognised by type (`secret-compare-timing-safe`) |
 | **Default deny** | Typed bodies and arguments, no `GraphQLJSON` tunnel, no `switch (operation)`, `@Public` carries a `PublicReason` member of `domain/identity`, and no `@UseGuards` (the global `APP_GUARD` chain decides) (`no-untyped-body`, `public-needs-reason`, `no-auth-use-guards`) |
 | **Module shape** | No `@Global()`; `isGlobal: true` only in an app's `app.module.ts`; no import of another owner's module; typed `ConfigurableModuleBuilder`; `static register` is the only factory; a capability's representative module extends the `ConfigurableModuleClass` of its own module definition and every sub-module or feature module is plain (`capability-module-shape`); one module per file; no `new` of a provider; no module-level `let` (`no-global-decorator`, `is-global-only-in-app`, `no-cross-owner-module-import`, `static-module-register`) |
-| **Suppression** | No `eslint-disable`, `eslint-env`, `/* global */`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `istanbul`, `c8` or `v8 ignore`, `NOSONAR`, `sonar-disable`, `prettier-ignore` or `vn-ok` comment, anywhere (`no-inline-suppression`) |
+| **Suppression** | No `eslint-disable`, `eslint-env`, `/* global */`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `istanbul`, `c8` or `v8 ignore`, `NOSONAR`, `sonar-disable`, or `prettier-ignore` comment, anywhere (`no-inline-suppression`) |
 | **Size** | A source file, a spec included, over the manifest's line budget is not new and does not grow past its size at the parent commit; the rule takes no option (`file-size-growth`) |
 | **Query safety** | `.query(...)` takes only a `SqlText` built with the `sql` tag in a persistence `<name>.sql.ts`, and no query builder exists (`sql-text-only`, `no-query-builder`); the tag's only substitution is a `SqlIdent` and a `.query` string is never built by template or `+` (`no-interpolated-sql`); `find`, `findBy` and `findAndCount` on an `EntityManager` state `take` and no `EntityManager` read runs per loop element (`query-needs-limit`, `no-query-in-loop`) |
 | **Resilience** | An outbound HTTP call states a timeout or signal; `JSON.parse` of outside text sits in a `try`; a loop that catches and waits goes through `platform/retry` - the wait is `setTimeout`, `node:timers/promises` or a function outside `platform/retry` whose body waits, whatever it is called (`http-needs-timeout`, `json-parse-needs-guard`, `no-hand-rolled-retry`) |

package/builders.mjs

@@ -72,7 +72,7 @@ const isEntityClass = (checker, declaration) => {
         const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression
         const symbol = checker.getSymbolAtLocation(callee)
         if (!symbol) return false
-        const target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol
+        const target = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol
         return (target.getDeclarations?.() ?? []).some((found) => moduleOf(found, String(found.getSourceFile().fileName).replace(/\\/g, "/")) === "typeorm")
     })
 }

package/comments.mjs

@@ -10,9 +10,9 @@
  *     constructor and an index signature are not surface, overload signatures of one name share one doc, and a property
  *     set to a literal or a named constant is a data constant (COMMENT-1's reason). Product source only: the test tiers
  *     (`e2e`, `fixtures` of the slot manifest) document their spec-read shapes at the type.
- *   - `require-enum-member-jsdoc` can check that a doc EXISTS and never that it states a
+ *   - `require-enum-member-jsdoc` checks an adjacent non-empty description, never whether it states a
  *     consequence. That half is read by a person, and the rule says so rather than pretending.
- *   - `no-non-ascii-source` takes no exemption marker: HFS removed `vn-ok`, so text a program depends on
+ *   - `no-non-ascii-source` takes no exemption marker, so text a program depends on
  *     lives in a message catalog (slot be.domain.messages, of any module tier, or be.feature.messages), the only place Vietnamese may appear. Specs
  *     and fixtures get no exemption.
  *   - `no-restated-name-jsdoc` (law 7) holds the decidable slice of law 3 - a doc block whose only
@@ -26,6 +26,7 @@
 import { hfsOf } from "./lib/hfs.mjs"
 import { normalizePath } from "./lib/path.mjs"
 import { hasSecondLanguage } from "./runtime/scripts/lib/language.mjs"
+import { jsdocBefore, jsdocDescription } from "./runtime/scripts/lib/jsdoc.mjs"
 
 /** The slots of the per-owner message catalogs: the only source files that may hold Vietnamese. */
 const CATALOG_SLOTS = new Set(["be.domain.messages", "be.feature.messages"])
@@ -91,20 +92,15 @@ const offenceIn = (line) => {
  */
 const hasDocumentedSurface = (declaration) => {
   if (declaration.type === "VariableDeclaration") {
-    // only a const bound to a function has a surface; a data constant is already described
-    const first = declaration.declarations[0]
-    const init = first && first.init
-    return Boolean(init)
-      && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
+    // a later declarator can expose a function even when the first binding is plain data
+    return declaration.declarations.some(({ init }) => Boolean(init)
+      && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression"))
   }
   return DOCUMENTED_KINDS.has(declaration.type)
 }
 
-/** Whether a JSDoc block sits immediately before a node. */
-const hasJsdocBefore = (sourceCode, node) =>
-  sourceCode
-    .getCommentsBefore(node)
-    .some((comment) => comment.type === "Block" && comment.value.startsWith("*"))
+/** Whether the adjacent JSDoc has a declaration description rather than only tags or a file header. */
+const hasJsdocBefore = (sourceCode, node) => jsdocBefore(sourceCode, node) !== null
 
 /** The declared name, for the message. */
 const nameOf = (declaration) => {
@@ -123,7 +119,7 @@ export const requireExportJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "`{{name}}` is exported with no doc block. This is surface other files depend on, and a name plus a signature says what it TAKES - never what it is for, or when to reach for it rather than the thing beside it.",
+        "`{{name}}` is exported without an adjacent JSDoc description. This is surface other files depend on, and a name plus a signature says what it TAKES - never what it is for, or when to reach for it rather than the thing beside it.",
     },
   },
   create(context) {
@@ -214,7 +210,7 @@ export const requirePublicMemberJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "`{{owner}}.{{name}}` is public surface with no doc block. A caller reaches the member, not the type's doc: say what it is for, what calling or reading it causes, or what it holds.",
+        "`{{owner}}.{{name}}` is public surface without an adjacent JSDoc description. A caller reaches the member, not the type's doc: say what it is for, what calling or reading it causes, or what it holds.",
     },
   },
   create(context) {
@@ -253,7 +249,7 @@ export const requireEnumMemberJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "Enum member `{{name}}` has no doc. State what CHOOSING it causes, not what it is called - a member is picked at a call site far from the switch that gives it meaning. (A rule can only see that a doc exists; whether it states a consequence is read by a person.)",
+        "Enum member `{{name}}` has no adjacent JSDoc description. State what CHOOSING it causes, not what it is called - a member is picked at a call site far from the switch that gives it meaning. (A rule can only see that a doc exists; whether it states a consequence is read by a person.)",
     },
   },
   create(context) {
@@ -334,7 +330,7 @@ const RESTATEMENT_FILLER = new Set(["a", "an", "the", "is", "of", "for", "to", "
 
 /** The content words a doc comment contributes once filler is stripped out. */
 const docContentWords = (comment) =>
-  (comment.value.match(/[A-Za-z]+/g) || [])
+  (jsdocDescription(comment).match(/[A-Za-z]+/g) || [])
     .map((word) => word.toLowerCase())
     .filter((word) => !RESTATEMENT_FILLER.has(word))
 
@@ -350,11 +346,6 @@ const isPureRestatement = (comment, declaredName) => {
   return true
 }
 
-/** The doc block immediately before a node, or null. */
-const jsdocBefore = (sourceCode, node) =>
-  sourceCode.getCommentsBefore(node).find((comment) => comment.type === "Block" && comment.value.startsWith("*"))
-    || null
-
 /** A doc block that only re-spells the declared name is COMMENT-3's violation wearing COMMENT-1's shape. */
 export const noRestatedNameJsdoc = {
   meta: {

package/config-owner.mjs

@@ -213,7 +213,7 @@ export const configParsedInMain = {
 /** The brand classes of `platform/config` a default must never be given to. */
 const BRANDS = new Set(["Secret", "Url"])
 const SECRET_READERS = new Set(["secret", "url", "host"])
-const DEFAULT_LITERAL = /^(?:|localhost|127\.0\.0\.1|0\.0\.0\.0|https?:\/\/.*)$/i
+const DEFAULT_LITERAL = /^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|https?:\/\/.*)?$/i
 
 /** No secret or URL value has a default of any kind: a missing value stops the boot. */
 export const noSecretDefault = {

package/idempotency.mjs

@@ -9,8 +9,8 @@
  *   - `inbox-dedupe-required` judges every DELIVERY method of a service. Doors (consumers, `SignedWebhook` controllers) are
  *     thin (R88): they map the delivery and dispatch one message, so the claim lives in the `*.service.ts` the handler calls,
  *     inside its transaction. A delivery method is a public method of a `<name>.service.ts` whose FIRST parameter has an
- *     `eventId` property, read by the parameter's TYPE. The FIRST awaited expression of such a method must be
- *     `claim(source, eventId)` on a receiver whose type is the `Inbox` port of `platform/inbox`, and the method must return
+ *     `eventId` property, read by the parameter's TYPE. Its first awaited work is the Inbox claim, directly or inside
+ *     the callback of its own EntityManager transaction, with that callback's manager, and the method must return
  *     early when the claim answers `false`. A lookalike `Inbox` declared by another owner, a renamed receiver and a
  *     property injection are all judged by the receiver's type, so only the real port satisfies the rule; a keyword or a
  *     class name never does.
@@ -20,12 +20,15 @@
  *   if ((await this.inbox.claim(source, id)) === false) { return }
  *   const fresh = await this.inbox.claim(source, id)
  *   if (!fresh) return
- * Whether the handler has side effects BEFORE its first await stays a review question (the call graph is not read).
+ * A transaction delivery returns or awaits one transaction as its sole statement. The actual selected inline callback
+ * claims with its own manager in its first statement, then returns on false; no outer work runs after a duplicate.
+ * Direct-claim synchronous effects, getters and called helpers stay review questions (the call graph is not read).
  */
 import { hfsOf } from "./lib/hfs.mjs"
 import { walk } from "./lib/ast.mjs"
 import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
-import { typed } from "./lib/types.mjs"
+import { resolveVariable } from "./lib/transactions.mjs"
+import { isPackageType, typed } from "./lib/types.mjs"
 
 /** The `Inbox` port of `platform/inbox`. */
 const isInboxType = (context, node) => isOwnedType(context, node, { name: "Inbox", capability: "inbox", tier: "platform" })
@@ -73,6 +76,52 @@ const firstAwait = (body) => {
     return first
 }
 
+/** True when an expression evaluates a call, construction or write before the designated call completes. */
+const hasPriorEffect = (expression, call) => {
+    let found = false
+    walk(expression, (node) => {
+        if (["CallExpression", "NewExpression", "AssignmentExpression", "UpdateExpression"].includes(node.type)
+            && node !== call && node.range[1] < call.range[1]) found = true
+    }, { intoFunctions: false })
+    return found
+}
+
+/** The first awaited claim in the actual callback of a sole, returned or awaited EntityManager transaction. */
+const transactionClaim = (context, body) => {
+    if (body.body.length !== 1) return null
+    const outer = body.body[0]
+    const expression = outer.type === "ReturnStatement" ? outer.argument
+        : outer.type === "ExpressionStatement" && outer.expression.type === "AwaitExpression" ? outer.expression : null
+    const call = expression?.type === "AwaitExpression" ? expression.argument : expression
+    const callee = call?.callee
+    if (call?.type !== "CallExpression" || callee.type !== "MemberExpression" || callee.computed
+        || callee.property.type !== "Identifier" || callee.property.name !== "transaction"
+        || !isPackageType(context, callee.object, "EntityManager", "typeorm") || hasPriorEffect(call, call)) return null
+    // TypeORM runs arg0 when it is a function, otherwise arg1. Never accept a later, ignored callback.
+    const isolation = call.arguments[0]
+    const callback = call.arguments.length === 1 ? isolation
+        : call.arguments.length === 2 && isolation.type === "Literal"
+            && ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"].includes(isolation.value)
+            ? call.arguments[1] : null
+    if (!callback || !["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type)
+        || !callback.async || callback.body.type !== "BlockStatement" || callback.params.length !== 1) return null
+    const manager = callback.params[0]
+    if (manager.type !== "Identifier" || !isPackageType(context, manager, "EntityManager", "typeorm")) return null
+    const awaited = firstAwait(callback.body)
+    const parent = awaited?.parent
+    const statement = parent?.type === "VariableDeclarator" && parent.init === awaited
+        && parent.parent.declarations.length === 1 ? parent.parent
+        : ["UnaryExpression", "BinaryExpression"].includes(parent?.type) ? parent.parent
+            : parent?.type === "ExpressionStatement" ? parent : null
+    if (statement !== callback.body.body[0] || statement?.parent !== callback.body) return null
+    const claim = awaited.argument
+    const argument = claim?.type === "CallExpression" ? claim.arguments[2] : null
+    const managerBinding = resolveVariable(context.sourceCode, manager)
+    const argumentBinding = argument?.type === "Identifier" ? resolveVariable(context.sourceCode, argument) : null
+    if (!managerBinding || managerBinding.defs[0]?.name !== manager || !argumentBinding
+        || argumentBinding !== managerBinding || hasPriorEffect(statement, claim)) return null
+    return awaited
+}
 /** Whether a parameter's type has an `eventId` property: the shape of a delivery. */
 const isDeliveryParam = (context, param) => {
     const target = param.type === "TSParameterProperty" ? param.parameter : param.type === "AssignmentPattern" ? param.left : param
@@ -107,7 +156,7 @@ export const inboxDedupeRequired = {
                 if (node.accessibility === "private" || node.accessibility === "protected") return
                 const first = node.value.params[0]
                 if (!first || !isDeliveryParam(context, first)) return
-                const awaited = firstAwait(node.value.body)
+                const awaited = transactionClaim(context, node.value.body) ?? firstAwait(node.value.body)
                 const call = awaited?.argument
                 const claims = call?.type === "CallExpression"
                     && call.callee.type === "MemberExpression"

package/index.mjs

@@ -65,6 +65,7 @@ import { recommended as webhooksRecommended, rules as webhooksRules } from "./we
 import { recommended as realtimeRecommended, rules as realtimeRules } from "./realtime.mjs"
 import { recommended as featureThinRecommended, rules as featureThinRules } from "./feature-thin.mjs"
 import { recommended as projectGraphRecommended, rules as projectGraphRules } from "./project-graph.mjs"
+import { recommended as sonarParityRecommended, rules as sonarParityRules } from "./sonar-parity.mjs"
 
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
 const CONTRIBUTIONS = [
@@ -115,6 +116,7 @@ const CONTRIBUTIONS = [
     { law: "webhooks", rules: webhooksRules, recommended: webhooksRecommended },
     { law: "realtime", rules: realtimeRules, recommended: realtimeRecommended },
     { law: "feature-thin", rules: featureThinRules, recommended: featureThinRecommended },
+    { law: "sonar-parity", rules: sonarParityRules, recommended: sonarParityRecommended },
 ]
 
 /** Every gathered law. */

package/lib/config.mjs

@@ -32,7 +32,7 @@ export const IGNORED = Object.freeze(["dist/**", "coverage/**", "**/node_modules
  */
 const ROOT_SCRIPTS = Object.freeze(["*.js", "*.mjs", "*.cjs"])
 
-/** The typescript-eslint rules the canon borrows (BE-CONVENTION 1.17, R72/R73), all `error`. */
+/** The typescript-eslint rules the canon borrows (BE-CONVENTION 1.17, R72/R73; Sonar S1874, S6551 and S7503 through R235), all `error`. */
 export const BORROWED = Object.freeze({
     "@typescript-eslint/consistent-type-assertions": ["error", { assertionStyle: "never" }],
     "@typescript-eslint/no-explicit-any": "error",
@@ -41,6 +41,9 @@ export const BORROWED = Object.freeze({
     "@typescript-eslint/no-misused-promises": "error",
     "@typescript-eslint/switch-exhaustiveness-check": "error",
     "@typescript-eslint/array-type": ["error", { default: "generic", readonly: "generic" }],
+    "@typescript-eslint/no-deprecated": "error",
+    "@typescript-eslint/no-base-to-string": "error",
+    "@typescript-eslint/require-await": "error",
     "no-console": "error",
 })
 

package/lib/doors.mjs

@@ -55,7 +55,9 @@ export const aliasTarget = (context, identifier) => {
     const { checker, toTs } = typed(context)
     const tsNode = toTs(identifier)
     const symbol = tsNode && checker.getSymbolAtLocation(tsNode)
-    return symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol
+    if (!symbol) return symbol
+    const isAlias = (symbol.flags & ts.SymbolFlags.Alias) !== 0
+    return isAlias ? checker.getAliasedSymbol(symbol) : symbol
 }
 
 /** The methods of a class (instance, non-constructor) that carry one of the decorators `names` of `source`. */

package/module-shape.mjs

@@ -4,8 +4,7 @@
  * Globality is a composition decision, not a property of a module: a capability is registered once per app, in the app's
  * `app.module.ts`, as `X.register({ isGlobal: true, ...options })`, and never listed in another module's `imports`.
  *
- *   - `no-global-decorator` refuses `@Global()` anywhere, specs included. (It replaces `global-module-allowlist`: the
- *     manifest no longer carries a list of modules that may be global.)
+ *   - `no-global-decorator` refuses `@Global()` anywhere, specs included.
  *   - `is-global-only-in-app` refuses `isGlobal: true` (and a dynamic module literal `global: true`) outside
  *     `apps/<app>/src/app.module.ts`.
  *   - `no-cross-owner-module-import` refuses a `@Module({ imports })` entry whose module class is declared by another

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "3.0.9",
+  "version": "3.1.0",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "private": false,
   "exports": {
     ".": "./index.mjs"
   },
   "main": "./index.mjs",
   "files": [
+    "LICENSE",
     "*.mjs",
     "lib/*.mjs",
     "runtime/**",

package/resilience.mjs

@@ -185,7 +185,7 @@ const waitsThrough = (context, checker, call, depth, seen) => {
   const hfs = hfsOf(context)
   const target = ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression
   let symbol = checker.getSymbolAtLocation(target)
-  if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+  if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol)
   for (const declaration of symbol?.declarations ?? []) {
     if (seen.has(declaration)) continue
     seen.add(declaration)

package/runtime/config.example.yaml

@@ -0,0 +1,187 @@
+# config.example.yaml — seed for the per-project owner config.
+# The installer copies this file to the gitignored `config.yaml` next to it;
+# owners edit that copy. Everything below is read at runtime — no key here is
+# decorative. Kernel route precedence: explicit `--agent` flag >
+# `kernel` below > the tier chain (modules/models/tiers.yaml).
+language: vi
+model: null
+effort: medium
+# Explicit current owner adoption is required; shipped defaults grant no trust or purge authority.
+# launchTrust: {profile: automatic, approvedBy: owner, approvalRef: '<current approval>', roots: ['<exact absolute repository root>']}
+# profile: declined preserves an explicit decision; provider-side declines also remain authoritative.
+launchTrust: null
+# retention: {workflowPurge: {approvedBy: owner, approvalRef: '<current approval>', repos: ['<exact absolute ledger-owner repo>']}}
+retention: null
+# kernel — the long-lived [Kernel] seat. It takes the `high` tier of modules/models/tiers.yaml (an ordered chain of
+# members; the picker takes the first member with tokens after your bias and the balance step; docs/config-format.md).
+# {agent?, model?, effort?}: agent and/or model PIN the seat — the bias `only`, keeping the tier's model of that agent
+# (an explicit `--agent` flag is the same bias and wins). effort: the seat's effort; null takes the tier member's effort.
+kernel: {effort: high}
+# parallel — the one knob for how wide the workers run. `gear` indexes the agent
+# table in modules/models/runtimes.yaml allocation.slicing.size: a long (`l`)
+# operation asks for the `l.agents[gear]` agents, an extra-long (`xl`) one for
+# `xl.agents[gear]`; `s` and `m` operations are always one agent. Declared gears
+# are allocation.slicing.gears — an undeclared value fails closed. Absent means
+# the first declared gear. A gear raises only what `starci kernel estimate` requests; it
+# never raises a pool's maxParallel, maxParallelOps or budgets.maxOps below.
+parallel: {gear: 1}
+# supervisor — the optional chat digest cadence. pollIntervalMs controls
+# scripts/supervisor/poll.mjs when run continuously (its floor is the config
+# validation of engine/config.mjs); null uses scripts/machine/home.mjs
+# DEFAULTS, and --interval-ms overrides this key.
+# The reconciler engine owns host runtime cadence and restores seats after reboot.
+# repos: managed product ledger-owner repositories for the reconciler and Supervisor tools,
+# relative to the source root (the directory holding this skill) or absolute.
+# --repo on the poll command line can add another. stallMinutes (optional,
+# integer >= 5) marks a running workflow STALLED in scripts/supervisor/stall.mjs;
+# the Workflow controller turns actionable findings into Decision Items. The [Supervisor]
+# kernel (docs/supervisor.md) also takes, optional, defaults in home.mjs DEFAULTS:
+#   kernel: {agent, model, effort}   its agent pin (default: the kernel pin below)
+#   workers: {base, max}             the adaptive [Worker] cap, 0 to 10 (0 = the Supervisor runs no fix worker)
+#   landGate: {mode: shared}         shared lets running lanes commit directly; exclusive = gate only. A land
+#                                    fast-forwards LOCAL main only: the remote main moves with a release (starci release cut)
+supervisor:
+  # mode: chat (default) - the owner's desktop chat session is the Supervisor: it owns channel 'main'
+  #   and reads Decision Items; nothing starts a [Supervisor] kernel. kernel - the optional [Supervisor]
+  #   Orca kernel (scripts/supervisor/start-supervisor.mjs), kept alive by the reconciler Host controller.
+  #   See docs/supervisor.md.
+  # mode: chat
+  pollIntervalMs: null
+  repos: []
+  # frozenMinutes: <n>   # Host seat check: a busy frame unchanged this long is frozen, not busy
+  # landGate: {mode: shared|exclusive}
+# delegation — while the owner is away, a named delegate (e.g. the supervisor chat) may
+# answer owner asks until the given time; excluded classes stay owner-only. null = none.
+#   delegation: {asks: supervisor, until: 2026-09-23T09:00:00+07:00,
+#     excludes: [credentials, oauth-consent, payments, legal, payment-provider]}
+delegation: null
+# budgets — the owner's ceiling, surfaced by every plan before `ok`. Null = unbounded.
+budgets:
+  maxOps: null       # max concurrent dispatched ops one workflow may hold open;
+                     # route/dispatch refuse `max-ops` at min(this, maxParallelOps)
+# allocation — the owner's default grant for a pool whose capacity is an explicit grant (Devin).
+#   grants: '<pool>=<slots>@<role>+<role>' — the default grant every workflow gets. Once a grants list is
+#     declared it is the whole set: a pool whose registry.yaml capacityAuthority is explicit-workflow-quota
+#     (Devin) routes only for the roles and up to the running slots a grant names ([] closes it).
+allocation:
+  grants: [devin-agent=10@implement+verify+write]
+# models — optional overrides of the shipped model tiers (modules/models/tiers.yaml owns the defaults). Every key is optional:
+#   tiers:   {<tier>: [{agent, model, effort?}, ...]}  replaces or adds one tier's ordered member chain
+#   seats:   {<seat>: <tier>}                          remaps a seat (supervisor, kernel, worker, planner, validator, kernelManager)
+#   balance: {maxStreak, maxSharePercent}              a head member picked maxStreak times in a row, or holding more than
+#                                                      maxSharePercent of the tier's running seats, yields to the next member
+#   usage:   {reservePercent, biasPercent}             a member at reservePercent of its tokens is skipped; an owner bias
+#                                                      naming it keeps it usable up to biasPercent; never above it
+models: {}
+# connectors — the owner's public ask channel (docs/connectors.md). Everything is off by default.
+# One local gateway (scripts/connectors/ask-gateway.mjs) fronts every serve-ask form; a Cloudflare
+# tunnel (scripts/connectors/tunnel.mjs) publishes the gateway; when serve-ask binds a form, the
+# kernel's ask path sends the owner one Telegram message (scripts/connectors/telegram.mjs) with the
+# question, its options and the public link. Telegram carries owner asks only.
+# SECRETS NEVER GO IN THIS FILE: tokenEnv/botTokenEnv NAME an environment variable holding the token
+# (or <NAME>_FILE pointing at a custody file); a value that is not an UPPER_SNAKE env var name is refused.
+#   Host credentials use the canonical runtime root secret.env; docs/host-secrets.md owns setup.
+#     Supplied environment values win, including blank values. Missing local file adds no values.
+#   repos: ledger-owner repository roots whose asks go public, relative to the source root (the
+#     directory holding this skill) or absolute. [] = the source root plus every .workspaces project owner.
+#   gateway.port: the one fixed local port the tunnel points at (outside the 6969..7069 form band).
+#   cloudflare.mode: off | quick | named.
+#     quick — `cloudflared tunnel --url`, a random https://*.trycloudflare.com host, no account, no auth,
+#       a new host on every restart. Good for decisions only.
+#     named — a fixed `hostname`, authenticated one of two ways: `tunnel` (UUID) + `credentialsFile`
+#       (the JSON `cloudflared tunnel create` wrote; the manager writes its own ingress config mapping
+#       hostname -> the gateway and never reads ~/.cloudflared/config.yml), or a remotely managed tunnel
+#       token in `tokenEnv` (its public hostname is routed to http://127.0.0.1:<gateway.port> in the
+#       Cloudflare dashboard).
+#   cloudflare.access: whether a Cloudflare Access application guards `hostname` (informational; false
+#     prints a warning). Recommended for anything beyond yes/no decisions.
+#   telegram.enabled / chatId: the owner's chat with the bot (BotFather token in botTokenEnv). Send the
+#     bot /start, then `starci connect telegram discover-chat` prints the chat id.
+#   telegram.exposeCredentialAsks: false keeps a credential/secret ask off the public link — the message
+#     says to answer it on this machine and carries only the localhost link, and the gateway refuses it.
+connectors:
+  repos: []
+  gateway: {port: 7070}
+  cloudflare: {mode: off, tunnel: null, credentialsFile: null, tokenEnv: CLOUDFLARE_TUNNEL_TOKEN, hostname: null, access: false}
+  telegram:
+    enabled: false
+    botTokenEnv: TELEGRAM_BOT_TOKEN
+    chatId: null
+    exposeCredentialAsks: false
+# asks — owner asks that carry a recommended option (question.recommended, or exactly one option
+# marked "(recommended)" or its Vietnamese equivalents). autoAcceptRecommended: true answers such an
+# ask with its recommendation instead of serving the form: the ledger records ask-answered with
+# answeredBy auto-recommended, the kernel is woken, and Telegram gets one plain message naming the
+# pick. A later owner answer supersedes it. excludes lists the ask classes that always reach the owner:
+#   credential — any ask with secret fields, or of kind credential, account, access or consent;
+#   handover — every handover.review ask (always excluded, even when removed from this list);
+#   draw-review — the opt-out for drawings (interface.draw, scripts/work/draw-review.mjs): unlisted, a
+#     drawing the owner did not ask to review is accepted without the owner (its accept option is the
+#     recommendation); a drawing the owner asked for (a prior owner redraw of the record, the owner
+#     opened its form, or question.ownerRequested) always reaches the owner;
+#   or any ask kind: information, authority, business-decision, irreversible-confirmation, ...
+asks:
+  autoAcceptRecommended: false
+  excludes: [credential, irreversible-confirmation, handover]
+# uat — the machine-wide UAT ceiling. At most maxConcurrent UAT runs (a browser session, a player, the
+# app it drives) execute at once on this host, across every workflow; the rest wait queued for a slot
+# (scripts/uat/uat-slots.mjs, lock files under <runtime>/uat-slots). A slot whose holder died is
+# reclaimed. STARCI_UAT_MAX_CONCURRENT overrides it for one process tree.
+uat:
+  maxConcurrent: 10
+# orca — the owner's Orca app settings the runtime must know (engine/orca-config.mjs orcaSettings). maxWorkerDepth MUST equal
+# the worker depth set in the Orca app: the deepest worker Orca starts under the owner's chat (chat 0, Kernel or
+# Supervisor 1, op or [Worker] 2, draw critic 3). Orca exposes no read of it, so the runtime trusts this value and refuses
+# a deeper launch before worker-start (worker-depth-exceeded). `start --check` with STARCI_ORCA_LIVE=1 measures Orca's
+# real limit and turns red when the two differ.
+orca:
+  maxWorkerDepth: 4
+# debugLoop — the debug watcher. Workflow DEBUG is a /loop of the chat that started the workflow (the /starci skill sets it up in
+# Claude Code and Codex; no seat, no background agent, nothing in the runtime schedules it). Each tick runs the read-only
+# `starci debug digest`. interval is the loop cadence (<n>s | <n>m | <n>h, default `10m` = `debugLoop.interval`); worktreeLimit is the
+# per-repository core-watch alert threshold (default `40` = `debugLoop.worktreeLimit`). Both keys are optional (engine/config.mjs DEBUG_LOOP_DEFAULTS).
+debugLoop:
+  interval: 10m
+  worktreeLimit: 40
+# reconciler — the host's one reconciler engine (scripts/reconciler/engine.mjs; contract
+# modules/reconciler/reconciler.yaml). Each controller runs off | shadow (reads, records what it would do as
+# reconciler.would rows, runs nothing) | active (acts; the old loop yields that duty via scripts/reconciler/owns.mjs).
+# profile — the operational default of every controller, so a host is never left all-shadow by accident:
+#   operational  job, host, workflow, resource active (they settle jobs, start services and seats, wake stalled
+#                workflows, throttle); gc, workers, learning shadow. The `start` skill applies and checks it.
+#   observe      every controller shadow (read-only; a debugging or audit host).
+#   (absent)     only the explicit controllers.<name>.mode entries count; an unnamed controller is off.
+# controllers.<name>.mode overrides the profile for that one controller (e.g. gc: {mode: active}).
+# Rollback of a controller: set its mode to off (the old loops take the duty back within
+# allocation.reconciler.heartbeatStaleMs). Numbers: modules/models/runtimes.yaml allocation.reconciler.
+reconciler:
+  enabled: true
+  profile: operational
+  controllers: {}
+# specs.unit / specs.e2e in workflows (the `specs` map near the top; owner 2026-09-28 "speed up development;
+# test later when asked"; scripts/route/spec-deferral.mjs). Each op brief's policy.specsToggle says what it does:
+#   unit: false - backend.implement, interface.implement and code.refactor run no jest/vitest/test:ci/coverage
+#     and demand no changed-line coverage (Sonar still runs: bugs, smells, security gate);
+#     test.author legs are never dispatched; review/handover gates do not count unit tests or coverage.
+#   e2e: false - e2e.verify legs and e2e test authoring are never dispatched; uat.verify is not e2e.
+#   A leg that is not dispatched settles `deferred: specs.<class>=false` with no attempt spent and the workflow
+#   proceeds past it; starci kernel status lists testsDeferred and `starci kernel run-deferred-tests --workflow <id> [--kind unit|e2e]`
+#   runs them later. Read on every wake: flipping a switch needs no restart.
+# roots — where this host keeps the archive, the lane worktrees and its temporary files, when the owner moves them off the defaults.
+# All keys are optional absolute directories; env STARCI_ARCHIVE_ROOT / STARCI_LANES_ROOT / STARCI_TEMP_ROOT win over them, and an
+# absent key means <starciLocalRoot>/archive (<runtime root>/.runtime/archive), the per-user profile lanes directory, kept out of the checkout (scripts/machine/home.mjs lanesRoot),
+# and the OS temp directory (engine/temp-root.mjs tempRoot; the processes the runtime starts get it as TEMP/TMP/TMPDIR). No host location lives in
+# a tracked file: set the real directories only in the gitignored config.yaml copy, e.g.
+#   roots: {archive: <absolute directory>, lanes: <absolute directory>, temp: <absolute directory>}
+# sonar — the SonarCloud organization the release's Sonar proof of the example apps analyses in (scripts/supervisor/release-sonarcloud.mjs). It is configuration, not a secret,
+# so it lives here and not in secret.env; the project keys are <organization>_starci-example-<app>. The environment variable SONAR_ORGANIZATION wins over it (CI reads the
+# repository variable of the same name). Empty until the owner sets it in the gitignored config.yaml copy, e.g.
+#   sonar: {organization: <the organization key shown on sonarcloud.io>}
+sonar: {organization: null}
+# resources — the host capacity floors the dispatch gate enforces, over the shipped numbers of modules/models/runtimes.yaml allocation.resources
+# (scripts/machine/host-resources.mjs; docs/config-format.md "Host resource floors"). Every key is optional (a number above 0, or null):
+#   minFreeDiskGb  free GB a drive holding the temp root or the repository must keep
+#   minFreeDiskPct the same floor as a percentage of the drive's size; with minFreeDiskGb the larger requirement applies
+#   minFreeRamPct  free-RAM percentage below which no new heavy op starts
+# set them only in the gitignored config.yaml copy, e.g.
+#   resources: {minFreeDiskGb: 5, minFreeDiskPct: 1, minFreeRamPct: 10}

package/runtime/engine/by-code-unit.mjs

@@ -0,0 +1,12 @@
+// by-code-unit.mjs - the comparator of a bare `Array.prototype.sort()`, owned beside the engine files that digest and canonicalize (scripts/lib/list.mjs re-exports it).
+
+/**
+ * The comparator of a bare `Array.prototype.sort()`: values compared as strings by UTF-16 code unit. Pass it to `sort` and
+ * `toSorted` so the order is stated, and stays byte-identical to the default order that digests and canonical output depend on.
+ */
+export const byCodeUnit = (a, b) => {
+  const left = String(a);
+  const right = String(b);
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+};