@starci/eslint-canon-be 3.0.10 → 3.2.0

package/runtime/scripts/lib/sops-envelope.mjs

@@ -25,7 +25,12 @@ export function testSecretPaths(name, { repo, stack = 'dev' } = {}) {
 export const setCommand = (name = '<name>', stack = 'dev') => `node scripts/stack-secret.mjs set ${stack}/secrets/test/${name}`;
 
 /** sops' format for a plaintext path, as the repository's stack-secret.mjs formatFor decides it. */
-export const sopsFormatFor = (file) => (file.endsWith('.env') ? 'dotenv' : /\.json$/.test(file) ? 'json' : /\.(ya?ml|kubeconfig)$/.test(file) ? 'yaml' : 'binary');
+export const sopsFormatFor = (file) => {
+  if (file.endsWith('.env')) return 'dotenv';
+  if (file.endsWith('.json')) return 'json';
+  if (/\.(ya?ml|kubeconfig)$/.test(file)) return 'yaml';
+  return 'binary';
+};
 
 /** Every leaf outside the `sops` block is an ENC[...] value (or null); the block itself carries a mac. */
 const allEncrypted = (node) => {
@@ -48,7 +53,7 @@ export function isSopsEnvelope(text) {
   if (!src.trim()) return false;
   try { return sopsTree(JSON.parse(src)); } catch { /* not JSON */ }
   const lines = src.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#/.test(l));
-  if (lines.length && lines.every((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l))) {
+  if (lines.length && lines.every((l) => /^[A-Za-z_]\w*=/.test(l))) {
     const pairs = lines.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]);
     const meta = pairs.filter(([k]) => k.startsWith('sops_'));
     const vals = pairs.filter(([k]) => !k.startsWith('sops_'));
@@ -58,55 +63,97 @@ export function isSopsEnvelope(text) {
 }
 
 /** Admit one flat age envelope for the native selected-identity invocation; this is shape admission, never cryptographic proof. */
-export function selectedAgeEnvelope(text, format, recipient) {
-  const refuse = reason => ({ ok: false, reason });
-  if (!['binary', 'json', 'yaml', 'dotenv'].includes(format)) return refuse('unsupported-format');
-  let meta;
+const refusal = (reason) => ({ ok: false, reason });
+
+function dotenvMetadataValue(meta, age, key, value) {
+  if (key === 'age__list_0__map_recipient') age.recipient = value;
+  else if (key === 'age__list_0__map_enc') age.enc = value;
+  else if (key === 'mac_only_encrypted') {
+    if (value !== 'false') return 'partial-mac';
+    meta[key] = false;
+  } else if (key.includes('__')) return 'unsupported-key-group';
+  else meta[key] = value;
+  return null;
+}
+
+function readDotenvMetadata(text) {
+  const pairs = new Map();
+  for (const line of String(text).split('\n')) {
+    if (!line || line.startsWith('#')) continue;
+    if (line.includes('\r')) return { refusal: 'unsupported-dotenv' };
+    const at = line.indexOf('=');
+    if (at < 1) return { refusal: 'unsupported-dotenv' };
+    const name = line.slice(0, at);
+    if (pairs.has(name)) return { refusal: 'duplicate-key' };
+    pairs.set(name, line.slice(at + 1).replaceAll(String.raw`\n`, '\n'));
+  }
+  const meta = {};
+  const age = {};
+  for (const [name, value] of pairs) {
+    if (!name.startsWith('sops_')) continue;
+    const reason = dotenvMetadataValue(meta, age, name.slice('sops_'.length), value);
+    if (reason) return { refusal: reason };
+  }
+  meta.age = [age];
+  return { meta };
+}
+
+function readStructuredMetadata(text, format) {
+  const doc = parseYaml(String(text));
+  if (format !== 'yaml') JSON.parse(String(text));
+  if (format === 'binary' && (!doc || Object.keys(doc).length !== 2 || !Object.hasOwn(doc, 'data') || !Object.hasOwn(doc, 'sops') || typeof doc.data !== 'string'))
+    return { refusal: 'unsupported-binary-shape' };
+  return { meta: doc?.sops };
+}
+
+function readAgeMetadata(text, format) {
   try {
-    if (format === 'dotenv') {
-      const pairs = new Map();
-      for (const line of String(text).split('\n')) {
-        if (!line || line.startsWith('#')) continue;
-        if (line.includes('\r')) return refuse('unsupported-dotenv');
-        const at = line.indexOf('=');
-        if (at < 1) return refuse('unsupported-dotenv');
-        const name = line.slice(0, at);
-        if (pairs.has(name)) return refuse('duplicate-key');
-        pairs.set(name, line.slice(at + 1).replaceAll('\\n', '\n'));
-      }
-      meta = {};
-      const age = {};
-      for (const [name, value] of pairs) {
-        if (!name.startsWith('sops_')) continue;
-        const key = name.slice('sops_'.length);
-        if (key === 'age__list_0__map_recipient') age.recipient = value;
-        else if (key === 'age__list_0__map_enc') age.enc = value;
-        else if (key === 'mac_only_encrypted') {
-          if (value !== 'false') return refuse('partial-mac');
-          meta[key] = false;
-        } else if (key.includes('__')) return refuse('unsupported-key-group');
-        else meta[key] = value;
-      }
-      meta.age = [age];
-    } else {
-      const doc = parseYaml(String(text));
-      if (format !== 'yaml') JSON.parse(String(text));
-      if (format === 'binary' && (!doc || Object.keys(doc).length !== 2 || !Object.hasOwn(doc, 'data') || !Object.hasOwn(doc, 'sops') || typeof doc.data !== 'string')) return refuse('unsupported-binary-shape');
-      meta = doc?.sops;
-    }
-  } catch { return refuse('invalid-envelope'); }
-  if (!meta || typeof meta !== 'object' || Array.isArray(meta) || !isSopsEnvelope(text)) return refuse('invalid-envelope');
-  if (Object.hasOwn(meta, 'key_groups') || Object.hasOwn(meta, 'shamir_threshold')) return refuse('unsupported-key-group');
+    return format === 'dotenv' ? readDotenvMetadata(text) : readStructuredMetadata(text, format);
+  } catch { return { refusal: 'invalid-envelope' }; }
+}
+
+function hasNonAgeProvider(meta, providers) {
+  for (const name of providers) {
+    if (Object.hasOwn(meta, name) && (!Array.isArray(meta[name]) || meta[name].length)) return true;
+  }
+  return false;
+}
+
+function isAgeEntry(entry) {
+  return !!entry && typeof entry === 'object' && !Array.isArray(entry)
+    && !Object.keys(entry).some(name => !['recipient', 'enc'].includes(name));
+}
+
+function hasValidAgePayload(entry) {
+  return typeof entry.enc === 'string' && entry.enc.startsWith('-----BEGIN AGE ENCRYPTED FILE-----\n')
+    && entry.enc.includes('\n-----END AGE ENCRYPTED FILE-----');
+}
+
+function hasValidEnvelopeVersion(meta) {
+  return typeof meta.version === 'string' && /^\d+\.\d+\.\d+$/.test(meta.version)
+    && typeof meta.lastmodified === 'string' && Number.isFinite(Date.parse(meta.lastmodified));
+}
+
+function validateAgeMetadata(meta, text, recipient) {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta) || !isSopsEnvelope(text)) return refusal('invalid-envelope');
+  if (Object.hasOwn(meta, 'key_groups') || Object.hasOwn(meta, 'shamir_threshold')) return refusal('unsupported-key-group');
   const providers = ['kms', 'gcp_kms', 'hckms', 'azure_kv', 'hc_vault', 'pgp'];
-  for (const name of providers) if (Object.hasOwn(meta, name) && (!Array.isArray(meta[name]) || meta[name].length)) return refuse('non-age-provider');
+  if (hasNonAgeProvider(meta, providers)) return refusal('non-age-provider');
   const fields = new Set([...providers, 'age', 'lastmodified', 'mac', 'version', 'unencrypted_suffix', 'encrypted_suffix', 'unencrypted_regex', 'encrypted_regex', 'unencrypted_comment_regex', 'encrypted_comment_regex', 'mac_only_encrypted']);
-  if (Object.keys(meta).some(name => !fields.has(name))) return refuse('unknown-metadata');
-  if (Object.hasOwn(meta, 'mac_only_encrypted') && meta.mac_only_encrypted !== false) return refuse('partial-mac');
-  if (!Array.isArray(meta.age) || meta.age.length !== 1) return refuse('unsupported-age-set');
+  if (Object.keys(meta).some(name => !fields.has(name))) return refusal('unknown-metadata');
+  if (Object.hasOwn(meta, 'mac_only_encrypted') && meta.mac_only_encrypted !== false) return refusal('partial-mac');
+  if (!Array.isArray(meta.age) || meta.age.length !== 1) return refusal('unsupported-age-set');
   const entry = meta.age[0];
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some(name => !['recipient', 'enc'].includes(name))) return refuse('invalid-age-entry');
-  if (typeof entry.recipient !== 'string' || entry.recipient !== recipient) return refuse('recipient-mismatch');
-  if (typeof entry.enc !== 'string' || !entry.enc.startsWith('-----BEGIN AGE ENCRYPTED FILE-----\n') || !entry.enc.includes('\n-----END AGE ENCRYPTED FILE-----')) return refuse('invalid-age-entry');
-  if (typeof meta.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(meta.version) || typeof meta.lastmodified !== 'string' || !Number.isFinite(Date.parse(meta.lastmodified))) return refuse('invalid-envelope');
+  if (!isAgeEntry(entry)) return refusal('invalid-age-entry');
+  if (typeof entry.recipient !== 'string' || entry.recipient !== recipient) return refusal('recipient-mismatch');
+  if (!hasValidAgePayload(entry)) return refusal('invalid-age-entry');
+  if (!hasValidEnvelopeVersion(meta)) return refusal('invalid-envelope');
   return { ok: true };
 }
+
+export function selectedAgeEnvelope(text, format, recipient) {
+  if (!['binary', 'json', 'yaml', 'dotenv'].includes(format)) return refusal('unsupported-format');
+  const parsed = readAgeMetadata(text, format);
+  if (parsed.refusal) return refusal(parsed.refusal);
+  return validateAgeMetadata(parsed.meta, text, recipient);
+}

package/runtime/scripts/lib/stack-services.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { words } from './dockerfile.mjs';
+import { asList } from './list.mjs';
 
 /**
  * The services of a repository's own stack definition, read from `.starcistacks/application-stacks.yaml` and the compose
@@ -74,8 +75,6 @@ const imagePathOf = image => {
 /** True when the image reference carries a tag or digest (an external image, not a placeholder of the repository's own build). */
 const isTagged = image => image.includes('@') || image.slice(image.lastIndexOf('/') + 1).includes(':');
 
-const asList = value => (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]);
-
 /** A compose `environment` (map or `KEY=VALUE` list) as a plain object; a `*_FILE` variable becomes the plain variable with the test value. */
 const environmentOf = value => {
   const entries = Array.isArray(value)

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

@@ -2,6 +2,15 @@
 // literal text, a node's 1-based position, a named property's initializer text. `ts` is the caller's
 // already-resolved compiler (see package-at.mjs loadTypescript); nothing here resolves a package.
 
+/** Whether the single-bit `flag` (a ts.NodeFlags member) is set in `flags`: the bit read as arithmetic, no bitwise operator in the condition. */
+export const hasFlag = (flags, flag) => Math.floor(flags / flag) % 2 === 1;
+
+/** Whether any bit of `mask` (a ts flag or an OR of flags) is set in `flags` (absent flags read as none): an explicit comparison of the masked value. */
+export const hasAnyFlag = (flags, mask) => ((flags ?? 0) & mask) !== 0;
+
+/** Whether the variable `declaration` belongs to a `const` list: the TypeScript node-flag test, an explicit comparison of the masked flags. */
+export const isConstVariable = (ts, declaration) => (ts.getCombinedNodeFlags(declaration.parent) & ts.NodeFlags.Const) !== 0;
+
 /** The text of an identifier or a string-literal-like `node`, or null (property names, literal specifiers). */
 export const nameText = (ts, node) => (node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null);
 

package/runtime/scripts/lib/walk.mjs

@@ -20,7 +20,12 @@ export function walkFiles(dir, {filter = () => true, sorted = false, exclude = (
     if (depth > maxDepth) return;
     let entries;
     try { entries = fs.readdirSync(current, {withFileTypes: true}); }
-    catch (error) { if (ignoreReadErrors) return; throw error; }
+    catch (error) {
+      if (ignoreReadErrors) {
+        return;
+      }
+      throw error;
+    }
     if (sorted) entries = entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
       const full = path.join(current, entry.name);

package/runtime/scripts/lib/yaml-cached.mjs

@@ -0,0 +1,14 @@
+// yaml-cached.mjs - parse a YAML text once per distinct text in a process.
+//
+// The HFS slot manifest and rule catalog are large documents that one process asks for again at every check, every render and every fixture. Their
+// bytes do not change between those asks, so the parse (the dominant cost of a load) is keyed by the text itself; each caller gets its own copy of the
+// parsed document, so nothing a caller does to it reaches the next one. A changed file is a different text and parses again.
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const parsed = new Map();
+
+/** The parsed document of `text`: parsed on the first ask for this text, a structured copy afterwards. Throws what parseYaml throws, every time. */
+export function parseYamlCached(text) {
+  if (!parsed.has(text)) parsed.set(text, parseYaml(text));
+  return structuredClone(parsed.get(text));
+}

package/schema-authority.mjs

@@ -224,7 +224,7 @@ export const noRuntimeSchema = {
 const isEntityDecorator = (checker, decorator) => {
     const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression
     let symbol = checker.getSymbolAtLocation(callee)
-    if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+    if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol)
     return symbol?.name === "Entity" && (symbol.declarations ?? []).some((declaration) => packageOfFile(declaration.getSourceFile().fileName) === "typeorm")
 }
 

package/service-deps.mjs

@@ -59,7 +59,7 @@ const isClassToken = (context, annotation) => {
     if (!tsNode) return false
     const type = checker.getTypeFromTypeNode(tsNode)
     const symbol = type.getSymbol()
-    if (!symbol || !(symbol.flags & ts.SymbolFlags.Class)) return false
+    if (!symbol || (symbol.flags & ts.SymbolFlags.Class) === 0) return false
     const declaration = symbol.declarations?.find((entry) => ts.isClassDeclaration(entry) || ts.isClassExpression(entry))
     return Boolean(declaration)
 }

package/sonar-parity.mjs

@@ -0,0 +1,19 @@
+/**
+ * The law that keeps the code clear of the smells SonarCloud measures (R235 `SCAN_SMELL`).
+ *
+ * Each rule is the syntax-tree form of one Sonar rule, shared with the front-end canon (scripts/lib/sonar-syntax-rules.mjs,
+ * bundled under `runtime/`): `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).
+ * The three Sonar rules that need the type checker, S1874 (a deprecated API), S6551 (an object turned into text) and S7503 (an `async`
+ * function that never awaits and returns no promise), are the typescript-eslint rules `no-deprecated`, `no-base-to-string` and
+ * `require-await` the factory turns on.
+ */
+import { SONAR_SYNTAX_RULES } from "./runtime/scripts/lib/sonar-syntax-rules.mjs"
+
+const NAMES = ["no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import", "prefer-export-from"]
+
+/** The rules this law contributes to the plugin. */
+export const rules = Object.fromEntries(NAMES.map((name) => [name, SONAR_SYNTAX_RULES[name]]))
+
+/** Starts at error: a repository's fix lane clears the debt before the rule ships. */
+export const recommended = Object.fromEntries(NAMES.map((name) => [`starci-be/${name}`, "error"]))

package/suppression.mjs

@@ -9,8 +9,7 @@
  *   - 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`;
- *   - Prettier: `prettier-ignore`;
- *   - the `vn-ok` language marker.
+ *   - Prettier: `prettier-ignore`.
  *
  * The factory also sets `noInlineConfig: true`, so ESLint itself ignores such a comment; this rule is what turns the
  * ignored comment into a failure a person reads, instead of a silent no-op that looks like an exemption. There is no
@@ -24,7 +23,6 @@ const TS_DIRECTIVE = /@ts-(?:ignore|expect-error|nocheck)\b/
 const COVERAGE_IGNORE = /(?:^|[\s*/])(?:istanbul|c8|v8)\s+ignore\b/
 const SONAR = /\bNOSONAR\b|\bsonar-(?:disable|enable)\b/i
 const PRETTIER_IGNORE = /(?:^|[\s*/])prettier-ignore\b/
-const LANGUAGE_MARKER = /\bvn-ok\b/
 
 /** The finding a comment is, or null when it is ordinary prose. `/* global x *\/` is a block-comment form only. */
 const kindOf = (comment) => {
@@ -35,7 +33,6 @@ const kindOf = (comment) => {
     if (COVERAGE_IGNORE.test(text)) return "coverage"
     if (SONAR.test(text)) return "sonar"
     if (PRETTIER_IGNORE.test(text)) return "prettier"
-    if (LANGUAGE_MARKER.test(text)) return "vn-ok"
     return null
 }
 
@@ -43,7 +40,7 @@ const kindOf = (comment) => {
 export const noInlineSuppression = {
     meta: {
         type: "problem",
-        docs: { description: "No eslint, TypeScript, coverage, Sonar or Prettier suppression comment, and no vn-ok marker." },
+        docs: { description: "No eslint, TypeScript, coverage, Sonar or Prettier suppression comment." },
         schema: [],
         messages: {
             eslint: "An `eslint-disable`/`eslint-enable`, `eslint-env`, `/* global */` or rule-configuration comment. HFS does not switch a rule off or declare a global in place: fix the code, or propose a change to the rule in the canon.",
@@ -51,7 +48,6 @@ export const noInlineSuppression = {
             coverage: "An `istanbul`/`c8`/`v8 ignore` comment hides code from coverage. Write the test that covers it, or delete the code that nothing reaches.",
             sonar: "A `NOSONAR` or `sonar-disable` comment hides a finding from Sonar. Fix the finding.",
             prettier: "A `prettier-ignore` comment exempts code from the formatter. Let the formatter write it.",
-            "vn-ok": "A `vn-ok` marker exempts a line from the language rule. HFS keeps no exemption marker: write the text in English, or move the data to a locale or data file.",
         },
     },
     create(context) {

package/test-world.mjs

@@ -145,8 +145,7 @@ const plainKey = (property) => {
 
 /**
  * The world an integration spec (`{ modules }`, with real peer apps beside them as `apps` when its client calls another app of
- * ours) or an e2e spec (`{ apps }`, never `modules`) asks for; every such spec asks for one; the retired name `useE2eWorld`
- * exists nowhere.
+ * ours) or an e2e spec (`{ apps }`, never `modules`) asks for; every such spec asks for one.
  */
 export const testWorldShape = {
     meta: {
@@ -158,21 +157,14 @@ export const testWorldShape = {
             apps: "An e2e spec boots applications: call `useTestWorld({ apps: {...} })`, not `modules`.",
             literal: "The options of `useTestWorld(...)` must be one object literal with plain keys: a variable, a spread or a computed key hides whether the spec asks for `modules` or `apps`.",
             missing: "This spec never calls `useTestWorld(...)`: integration and e2e specs run inside the one test world.",
-            retired: "`useE2eWorld` is the retired name of `useTestWorld`; there is one name, no alias.",
         },
     },
     create(context) {
         const slot = hfsOf(context).slotOf(context.filename || context.getFilename())
         const wants = slot === "be.tests.integration" ? "modules" : slot === "be.tests.e2e" ? "apps" : null
-        const retired = {
-            Identifier(node) {
-                if (node.name === "useE2eWorld") context.report({ node, messageId: "retired" })
-            },
-        }
-        if (!wants) return retired
+        if (!wants) return {}
         let seen = false
         return {
-            ...retired,
             CallExpression(node) {
                 if (node.callee.type !== "Identifier" || node.callee.name !== "useTestWorld") return
                 seen = true