@starci/eslint-canon-be 3.4.39 → 3.4.41

package/runtime/scripts/lib/language.mjs

@@ -15,7 +15,7 @@ export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìí
 export const hasSecondLanguage = (text) => typeof text === 'string' && SECOND_LANGUAGE_LETTER.test(text.normalize('NFC'));
 
 /** Every line of `text` with a Vietnamese letter: `[{ line, column }]`, both 1-based. */
-export function secondLanguageHits(text) {
+function secondLanguageHits(text) {
   const hits = [];
   String(text).split(/\r?\n/).forEach((raw, index) => {
     const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
@@ -24,6 +24,99 @@ export function secondLanguageHits(text) {
   return hits;
 }
 
+/** The named bindings of an import from the backend message catalog contract. */
+function messageCatalogBindings(ts, statement) {
+  if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== '@modules/platform/i18n') return null;
+  return statement.importClause?.namedBindings ?? null;
+}
+
+/** The local type names imported from the backend message catalog contract. */
+function messageBundleImports(ts, source) {
+  const named = new Set();
+  const namespaces = new Set();
+  for (const statement of source.statements) {
+    const bindings = messageCatalogBindings(ts, statement);
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    for (const entry of ts.isNamedImports(bindings) ? bindings.elements : []) {
+      if ((entry.propertyName ?? entry.name).text === 'MessageBundle') named.add(entry.name.text);
+    }
+  }
+  return { named, namespaces };
+}
+
+/** A declaration that introduces a same-named local type or namespace. */
+function declaresTypeName(ts, statement, name) {
+  if (statement.name?.text !== name) return false;
+  return [ts.isTypeAliasDeclaration, ts.isInterfaceDeclaration, ts.isClassDeclaration, ts.isEnumDeclaration, ts.isModuleDeclaration]
+    .some(predicate => predicate(statement));
+}
+
+/** A type reference bound to the imported MessageBundle contract, including import aliases. */
+function isMessageBundleType(ts, type, imports) {
+  if (!type || !ts.isTypeReferenceNode(type)) return false;
+  const name = type.typeName;
+  if (ts.isIdentifier(name)) return imports.named.has(name.text) && !shadowsImportedType(ts, type, name.text);
+  return ts.isQualifiedName(name) && ts.isIdentifier(name.left)
+    && imports.namespaces.has(name.left.text) && name.right.text === 'MessageBundle' && !shadowsImportedType(ts, type, name.left.text);
+}
+
+/** A local declaration or generic type parameter takes precedence over a same-named import. */
+function shadowsImportedType(ts, node, name) {
+  for (let scope = node.parent; scope; scope = scope.parent) {
+    if (scope.typeParameters?.some(parameter => parameter.name.text === name)) return true;
+    if (scope.statements?.some(statement => declaresTypeName(ts, statement, name))) return true;
+  }
+  return false;
+}
+
+/** The literal object supplied by a variable typed with the imported MessageBundle contract. */
+function messageCatalogObject(ts, node, imports) {
+  if (!ts.isVariableDeclaration(node) || !node.initializer) return null;
+  let value = node.initializer;
+  const type = ts.isSatisfiesExpression(value) ? value.type : node.type;
+  if (ts.isSatisfiesExpression(value)) value = value.expression;
+  return isMessageBundleType(ts, type, imports) && ts.isObjectLiteralExpression(value) ? value : null;
+}
+
+/** Literal string values in the Vietnamese locale of one message catalog. */
+function vietnameseValueRanges(ts, catalog, source) {
+  const ranges = [];
+  for (const locale of catalog.properties) {
+    if (!ts.isPropertyAssignment(locale) || locale.name.text !== 'vi' || !ts.isObjectLiteralExpression(locale.initializer)) continue;
+    for (const message of locale.initializer.properties) {
+      if (ts.isPropertyAssignment(message) && ts.isStringLiteralLike(message.initializer))
+        ranges.push({ start: message.initializer.getStart(source), end: message.initializer.end });
+    }
+  }
+  return ranges;
+}
+
+/** Literal Vietnamese message values of typed catalogs; keys, comments, English values and expressions remain source. */
+function messageBundleValueRanges(ts, source) {
+  const imports = messageBundleImports(ts, source);
+  const ranges = [];
+  const visit = (node) => {
+    const catalog = messageCatalogObject(ts, node, imports);
+    if (catalog) ranges.push(...vietnameseValueRanges(ts, catalog, source));
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return ranges;
+}
+
+/** Source-language hits, treating only literal vi values of typed backend MessageBundle objects as translated product data. */
+export function sourceLanguageHits(rel, text, ts) {
+  if (!hasSecondLanguage(text)) return [];
+  if (!ts || !/\.[cm]?tsx?$/.test(rel)) return secondLanguageHits(text);
+  const source = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
+  let sourceText = text;
+  for (const range of messageBundleValueRanges(ts, source).sort((left, right) => right.start - left.start)) {
+    sourceText = sourceText.slice(0, range.start) + sourceText.slice(range.start, range.end).replace(/[^\r\n]/g, ' ') + sourceText.slice(range.end);
+  }
+  return secondLanguageHits(sourceText);
+}
+
 /**
  * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
  * (scripts/checks/check-failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.

package/runtime/scripts/lib/package-at.mjs

@@ -0,0 +1,62 @@
+// scripts/lib/package-at.mjs — a package the runtime does not ship (playwright, esbuild, tailwindcss) comes from the
+// project that owns it: node resolution from that project's directory, walking up its node_modules.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+
+/** The package.json of `name` as resolved from `dir`, or null. */
+export const packageAt = (dir, name) => {
+  try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
+};
+
+/** This runtime's own `starci` bin (packages/cli is the only package that declares one). */
+const RUNTIME_STARCI_BIN = path.join(skillRoot, 'packages', 'cli', 'bin', 'starci.mjs');
+
+/** The `starci` bin of the @starci/cli that `dir` installs (a product runs its own pinned CLI), else this runtime's own. */
+function starciBin(dir) {
+  const packageFile = packageAt(dir, '@starci/cli');
+  if (packageFile) {
+    try {
+      const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+      const rel = typeof bin === 'string' ? bin : bin?.starci;
+      const file = rel ? path.join(path.dirname(packageFile), rel) : null;
+      if (file && fs.existsSync(file)) return file;
+    } catch { /* an unreadable install falls back to the runtime's own CLI */ }
+  }
+  return RUNTIME_STARCI_BIN;
+}
+
+/** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
+export function findPackage(dirs, names) {
+  for (const dir of dirs.filter(Boolean)) {
+    for (const name of names) {
+      const packageFile = packageAt(dir, name);
+      if (!packageFile) continue;
+      const require = createRequire(packageFile);
+      return { name, root: path.dirname(packageFile), packageFile, version: require(packageFile).version };
+    }
+  }
+  return null;
+}
+
+/** The CommonJS entry of a package found by findPackage. */
+export const requirePackage = (found) => createRequire(found.packageFile)(found.name);
+
+/** The TypeScript compiler resolvable from the first of `dirs` (an app root, then the caller's own), or null. */
+export const loadTypescript = (...dirs) => {
+  const located = findPackage(dirs, ['typescript']);
+  return located ? requirePackage(located) : null;
+};
+
+/**
+ * The app's command line and the app implementation behind it: `bin` the `starci` bin of the app's installed @starci/cli, else
+ * this runtime's packages/cli/bin/starci.mjs (starciBin); `dir` the @starci/hfs that answers
+ * `starci app` - the app's own install, else the one beside its @starci/cli, else this runtime's packages/hfs - whose runtime
+ * slice the gate's base lint (scripts/gates/gate.mjs) and the READ digest (scripts/gates/read-digest.mjs) load in-process.
+ */
+export function hfsEntry(root) {
+  const cli = packageAt(root, '@starci/cli');
+  const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
+  return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
+}

package/runtime/scripts/lib/same-text.mjs

@@ -0,0 +1,5 @@
+// same-text.mjs - text equality that ignores the line-ending form and a trailing blank tail (a git runner may trim stdout, a work tree may
+// carry CRLF): the one comparison the database rules use for a committed file against its base or against a regenerated one.
+
+/** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
+export const sameText = (a, b) => a !== null && b !== null && a.replaceAll('\r\n', '\n').trimEnd() === b.replaceAll('\r\n', '\n').trimEnd();

package/runtime/scripts/lib/ts-analysis.mjs

@@ -25,3 +25,13 @@ export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiterals
 
 /** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
 export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });
+
+/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
+export function lexicalChecker(ts, source) {
+  const options = { noLib: true, noResolve: true, allowJs: true };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
+  host.fileExists = () => false;
+  host.readFile = () => undefined;
+  return ts.createProgram([source.fileName], options, host).getTypeChecker();
+}

package/suppression.mjs

@@ -8,7 +8,7 @@
  *     `eslint-env`, and a `/* global x *\/` declaration;
  *   - TypeScript: `@ts-ignore`, `@ts-expect-error` and `@ts-nocheck`, wherever they sit in a comment;
  *   - coverage: `istanbul ignore`, `c8 ignore`, `v8 ignore`;
- *   - Sonar: `NOSONAR` and `sonar-disable`;
+ *   - Sonar: its no-sonar comment and `sonar-disable`;
  *   - Prettier: `prettier-ignore`.
  *
  * The factory also sets `noInlineConfig: true`, so ESLint itself ignores such a comment; this rule is what turns the

package/unit-spec.mjs

@@ -5,7 +5,9 @@
  * and takes every double from the one shared kit, `@starci/jest-preset`:
  *
  *   - `spec-builds-with-testing-module`: the spec calls `Test.createTestingModule(...)` from `@nestjs/testing`, awaits
- *     `.compile()` and reads the subject with `.get(...)` on the resulting `TestingModule`.
+ *     `.compile()` and reads the subject with `.get(...)` on the resulting `TestingModule`. A spec of a value role
+ *     (`ruleParams.be.valueRoles`) is exempt only while its sibling is a real boundary schema (an owner tier, zod values and types
+ *     only, `schema-file-values-only`): its subject is a declared value, parsed directly.
  *   - `spec-no-new-subject`: the subject (the class of the sibling `<name>.<role>.ts`) is never built with `new`.
  *   - `spec-module-definition-only-providers`: the module definition has a `providers` list and nothing else: no `imports` key
  *     and no `override*` call (`overrideProvider`, `overrideGuard`, `overrideModule`, `overrideFilter`, `overridePipe`,
@@ -28,9 +30,13 @@
 import { hfsOf } from "./lib/hfs.mjs"
 import { keyName, walk } from "./lib/ast.mjs"
 import { importOf, isImportedFrom } from "./lib/import-source.mjs"
-import { isPackageType, typeOrigins } from "./lib/types.mjs"
-import { baseOf, isServiceSpecFile, isUnitSpecFile, unitRoleOfSpec } from "./lib/unit-spec.mjs"
+import ts from "typescript"
+import { normalizePath } from "./lib/path.mjs"
+import { isPackageType, typeOrigins, typed } from "./lib/types.mjs"
+import { baseOf, isServiceSpecFile, isUnitSpecFile, isValueRoleSpec, unitRoleOfSpec } from "./lib/unit-spec.mjs"
 import { isRealSubjectValue, valueObjectsOfSibling } from "./lib/subject-values.mjs"
+import { ownerNameOf } from "./lib/ports.mjs"
+import { siblingIsValueSchema } from "./lib/schema-values.mjs"
 
 const TESTING_PACKAGE = "@nestjs/testing"
 
@@ -77,7 +83,12 @@ export const specBuildsWithTestingModule = {
         },
     },
     create(context) {
-        if (!isFormSpecFile(hfsOf(context), context.filename || context.getFilename())) return {}
+        const filename = context.filename || context.getFilename()
+        // a value role (a zod schema) declares a value Nest never constructs: its spec parses it and builds no module, but only when the
+        // sibling really is one (a boundary schema of an owner tier holding zod values and types, nothing else); any other file keeps the rule
+        const hfs = hfsOf(context)
+        if (!isFormSpecFile(hfs, filename)) return {}
+        if (isValueRoleSpec(hfs, filename) && siblingIsValueSchema(hfs, filename)) return {}
         // a value-object subject (undecorated, no constructor injection token) is built with `new`: Nest never constructs it
         const valueObjectSpec = valueObjectsOfSibling(context).length > 0
         let created = null
@@ -385,12 +396,36 @@ const COMPILED = new WeakMap()
 const tableOf = (specDoubles) => {
     let compiled = COMPILED.get(specDoubles)
     if (!compiled) {
-        compiled = { kit: specDoubles.kit, entries: specDoubles.doubles.map((entry) => ({ ...entry, pattern: new RegExp(entry.token) })), fallback: specDoubles.fallback }
+        compiled = { kit: specDoubles.kit, entries: specDoubles.doubles.map((entry) => ({ ...entry, pattern: new RegExp(entry.token), from: entry.from === undefined ? undefined : new RegExp(entry.from) })), fallback: specDoubles.fallback }
         COMPILED.set(specDoubles, compiled)
     }
     return compiled
 }
 
+/** The file and exported name a token identifier is declared in, after following every import and re-export, or null when it cannot be resolved. */
+const declarationOf = (context, token) => {
+    const { checker, toTs } = typed(context)
+    const symbol = checker.getSymbolAtLocation(toTs(token))
+    const target = symbol?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol
+    const declaration = target?.getDeclarations?.()?.[0]
+    return declaration === undefined ? null : { file: normalizePath(declaration.getSourceFile().fileName), name: target.getName() }
+}
+
+/**
+ * Whether a table entry applies to a provider token. The spelling picks the entry; when the entry names where its port is declared
+ * (`from`, a pattern over the declaring file), the declaration decides, never the import written in the spec: a token declared in
+ * another module that merely ends alike (`CORRELATION_IDS` of logging against `IDS` of ids) is a different port, a token the
+ * owner declares stays that port however it is re-exported or renamed (`IDS as SYSTEM_SOURCE`, a fixture re-export). A token
+ * that cannot be resolved, or is declared in the spec itself, is judged by its spelling alone.
+ */
+const entryApplies = (context, entry, spelled, token) => {
+    if (entry.from === undefined || token?.type !== "Identifier") return entry.pattern.test(spelled)
+    const declared = declarationOf(context, token)
+    if (declared === null || declared.file === normalizePath(context.filename || context.getFilename())) return entry.pattern.test(spelled)
+    if (!entry.from.test(declared.file)) return !declared.file.includes("/src/modules/") && entry.pattern.test(spelled)
+    return entry.pattern.test(spelled) || entry.pattern.test(screamingSnake(declared.name))
+}
+
 /** A const identifier's initializer, or null when its value cannot be followed. */
 const constantInitializer = (context, value) => {
     for (let scope = context.sourceCode.getScope(value); scope; scope = scope.upper) {
@@ -403,6 +438,31 @@ const constantInitializer = (context, value) => {
     return null
 }
 
+/** An imported token retains its declared identity through const aliases and assertion wrappers. */
+const originsOfToken = (context, token) => {
+    let value = peel(token)
+    const seen = new Set()
+    while (value?.type === "Identifier" && !seen.has(value)) {
+        seen.add(value)
+        const initial = peel(constantInitializer(context, value))
+        if (!initial || !["Identifier", "MemberExpression"].includes(initial.type)) break
+        value = initial
+    }
+    return typeOrigins(context, value)
+}
+
+/** Inbox is the platform port; a service or producer whose name contains Inbox remains an ordinary collaborator. */
+const providerDoubleEntry = (context, hfs, table, token, normalised) => {
+    const named = (name, from) => table.entries.find((entry) => entryApplies(context, entry, screamingSnake(name), from)) ?? table.fallback
+    const lexical = named(normalised, token)
+    const inbox = named("INBOX")
+    const origins = originsOfToken(context, token)
+    const platform = origins.filter((origin) => origin.module === null && hfs.tierOf(origin.file) === "platform")
+    if (platform.some((origin) => origin.name === "INBOX" && ownerNameOf(hfs, origin.file) === "inbox")) return inbox
+    if (lexical !== inbox || origins.length === 0) return lexical
+    return platform.map((origin) => named(origin.name)).find((entry) => entry !== inbox) ?? table.fallback
+}
+
 /** A value's form and the double it names: `{ form, name }`, or null when it is not a form the table knows. */
 const formOf = (context, node, depth = 0) => {
     const value = peel(node)
@@ -489,7 +549,7 @@ export const specInfraDoubleFromKit = {
                 const spelled = tokenName(provide?.value)
                 if (spelled === null) return
                 const normalised = screamingSnake(spelled)
-                const entry = table.entries.find((candidate) => candidate.pattern.test(normalised)) ?? table.fallback
+                const entry = providerDoubleEntry(context, hfs, table, provide.value, normalised)
                 const found = formOf(context, node.value)
                 const want = describe(entry)
                 const data = { token: spelled, want, kit: table.kit }

package/uploads.mjs

@@ -0,0 +1,112 @@
+/**
+ * The mechanically recognisable buffering surfaces of BE-TRANSPORT-1. Browser uploads use storage grants; the API
+ * exchanges metadata. An actual byte-stream route remains a separate transport case, so `StreamableFile` stays legal.
+ * This rule does not prove a storage policy's principal, key, expiry or byte bound; the integration's behavior specs do.
+ */
+import { keyName, staticText } from "./lib/ast.mjs"
+import { importOf, moduleReferences } from "./lib/import-source.mjs"
+import { resolveVariable } from "./lib/transactions.mjs"
+
+/** Libraries that implement API-side multipart uploads instead of a storage grant. */
+const UPLOAD_PACKAGES = [
+    "multer",
+    "express-fileupload",
+    "graphql-upload",
+    "graphql-upload-minimal",
+    "@fastify/multipart",
+    "fastify-multipart",
+    "busboy",
+    "formidable",
+    "multiparty",
+    "connect-multiparty",
+]
+
+/** Selected Nest exports consume multipart files; other exports of these packages remain usable. */
+const NEST_UPLOADS = {
+    "@nestjs/common": ["UploadedFile", "UploadedFiles"],
+    "@nestjs/platform-express": ["MulterModule", "FileInterceptor", "FilesInterceptor", "AnyFilesInterceptor", "FileFieldsInterceptor"],
+}
+
+/** The statement block in which this expression is evaluated. */
+const statementBlock = (expression) => {
+    let statement = expression
+    while (statement.parent && !["Program", "BlockStatement"].includes(statement.parent.type)) statement = statement.parent
+    return statement.parent
+}
+
+/**
+ * The namespace source at one read, following completed standalone writes in that statement block.
+ * Branches, destructuring assignments and closure execution require dataflow beyond this rule's supported alias shape.
+ */
+const namespaceSource = (context, expression, seen = new Set()) => {
+    if (!expression || seen.has(expression)) return null
+    seen.add(expression)
+    if (expression?.type === "Identifier") {
+        const found = importOf(context, expression)
+        if (found?.imported === "*") return found.source
+        const variable = resolveVariable(context.sourceCode, expression)
+        if (!variable) return null
+        const definition = variable.defs[0]
+        if (definition?.type !== "Variable" || definition.node.type !== "VariableDeclarator" || definition.node.id.type !== "Identifier") return null
+        const writes = variable.references.filter((reference) => reference.isWrite() && !reference.init
+            && reference.writeExpr?.range[1] <= expression.range[0])
+            .sort((left, right) => right.identifier.range[0] - left.identifier.range[0])
+        const write = writes[0]
+        if (!write) return namespaceSource(context, definition.node.init, seen)
+        const assignment = write.identifier.parent
+        if (assignment.type !== "AssignmentExpression" || assignment.operator !== "=" || assignment.left !== write.identifier
+            || assignment.parent.type !== "ExpressionStatement" || assignment.parent.parent !== statementBlock(expression)) return null
+        return namespaceSource(context, write.writeExpr, seen)
+    }
+    if (expression?.type === "AwaitExpression") return namespaceSource(context, expression.argument, seen)
+    const source = expression?.type === "ImportExpression" ? expression.source
+        : expression?.type === "CallExpression" && expression.callee.type === "Identifier" && expression.callee.name === "require" ? expression.arguments[0] : null
+    return staticText(source)
+}
+
+/** Multipart buffers are never the API's upload contract. */
+export const noBufferedUpload = {
+    meta: {
+        type: "problem",
+        docs: { description: "Browser file uploads use presigned storage grants, without Nest/Multer or GraphQL multipart buffering in the API." },
+        schema: [],
+        messages: {
+            buffered: "[BE_UPLOAD_BUFFERED] `{{name}}` accepts multipart files in the API. Return an authenticated, short-lived presigned PUT scoped to the principal and exact object key, signed for the exact content type and length, verify the stored object with a head call after the upload, and send the file directly to storage. An actual streaming REST route needs its own BE-TRANSPORT-1 evidence.",
+        },
+    },
+    create(context) {
+        const report = (node, name) => context.report({ node, messageId: "buffered", data: { name } })
+        const selected = (source, name) => typeof source === "string" && Object.entries(NEST_UPLOADS)
+            .some(([pkg, names]) => (source === pkg || source.startsWith(`${pkg}/`)) && names.includes(name))
+        return {
+            ...moduleReferences(({ source, value, names }) => {
+                if (UPLOAD_PACKAGES.some((pkg) => value === pkg || value.startsWith(`${pkg}/`))) {
+                    report(source, value)
+                    return
+                }
+                const forbidden = names.filter((name) => selected(value, name))
+                if (forbidden.length > 0) report(source, forbidden.join(", "))
+            }),
+            MemberExpression(node) {
+                const source = namespaceSource(context, node.object)
+                const name = node.computed ? staticText(node.property) : keyName(node.property)
+                if (selected(source, name)) report(node, name)
+            },
+            VariableDeclarator(node) {
+                if (node.id.type !== "ObjectPattern") return
+                const source = namespaceSource(context, node.init)
+                for (const property of node.id.properties) {
+                    if (property.type !== "Property") continue
+                    const name = property.computed ? staticText(property.key) : keyName(property.key)
+                    if (selected(source, name)) report(property, name)
+                }
+            },
+        }
+    },
+}
+
+/** The transport buffering rule's published name. */
+export const rules = { "no-buffered-upload": noBufferedUpload }
+
+/** Upload buffering is an error in every backend. */
+export const recommended = { "starci-be/no-buffered-upload": "error" }