@fjall/eslint-plugin 12.2.0 → 12.4.0

package/index.js

@@ -29,6 +29,8 @@ import noRawDbTransaction from "./no-raw-db-transaction.js";
 import noRawExitCode from "./no-raw-exit-code.js";
 import noReplacementStringExpansion from "./no-replacement-string-expansion.js";
 import noSilentResultDiscard from "./no-silent-result-discard.js";
+import noOptionalWarningEmission from "./no-optional-warning-emission.js";
+import noUnguardedChmodInTests from "./no-unguarded-chmod-in-tests.js";
 
 export default {
   rules: {
@@ -64,6 +66,8 @@ export default {
     "no-raw-db-transaction": noRawDbTransaction,
     "no-raw-exit-code": noRawExitCode,
     "no-replacement-string-expansion": noReplacementStringExpansion,
-    "no-silent-result-discard": noSilentResultDiscard
+    "no-silent-result-discard": noSilentResultDiscard,
+    "no-optional-warning-emission": noOptionalWarningEmission,
+    "no-unguarded-chmod-in-tests": noUnguardedChmodInTests
   }
 };

package/mask-error-message-at-boundary.js

@@ -57,6 +57,22 @@
  *     masking opportunity. Catching at the ctor closes the gap before
  *     the value crosses the Result boundary.
  *
+ * Internally-masking sinks (callers pass RAW):
+ *   - `emitWarning(...)` (@fjall/util/diagnostics) — the spine strips
+ *     control sequences THEN masks inside the emitter, and hands
+ *     masksInternally sinks the pre-mask spelling. Pre-masking at the call
+ *     site would not leak but WOULD defeat the single-mask contract, so a
+ *     raw error leaf reaching `emitWarning(...)` is exempt here.
+ *
+ * Spine-consumer exemption (useDiagnostics / subscribeWarnings):
+ *   WarningEvent payloads delivered to subscribeWarnings listeners and the
+ *   useDiagnostics hook are post-mask BY CONTRACT — the subscription taps
+ *   after the mask (util/src/diagnostics). Consumers writing
+ *   `event.message` into set*-named state sinks therefore need no call-site
+ *   mask. The rule does not flag them (a WarningEvent binding is not an
+ *   error-shaped leaf), but that is convention, not naming accident: treat
+ *   spine payloads as post-mask, and do not re-mask them.
+ *
  * Complements `require-masked-log-payload`, which targets credential-prone
  * keys in 3rd-arg logger payload OBJECTS. This rule targets leaf access
  * shapes regardless of payload structure (template literals, direct
@@ -179,6 +195,10 @@ const MASKING_HELPER_CALLEES = new Set([
   "maskAndTruncate",
   "maskAndBound"
 ]);
+// Sinks that mask INSIDE the sink (util/src/diagnostics emitWarning:
+// strip-then-mask). Callers pass raw — a call-site mask would defeat the
+// spine's single-mask contract, so reaching one of these exempts the leaf.
+const INTERNALLY_MASKING_SINK_CALLEES = new Set(["emitWarning"]);
 
 /** @type {import('eslint').Rule.RuleModule} */
 export default {
@@ -565,6 +585,12 @@ function findEnclosingSink(leaf, context, visited, leafShape) {
       if (calleeName !== null && MASKING_HELPER_CALLEES.has(calleeName)) {
         return { kind: "exempt" };
       }
+      if (
+        calleeName !== null &&
+        INTERNALLY_MASKING_SINK_CALLEES.has(calleeName)
+      ) {
+        return { kind: "exempt" };
+      }
       if (calleeName !== null && INTERNAL_PASSTHROUGH_CALLEES.has(calleeName)) {
         return candidateSink ?? { kind: "exempt" };
       }

package/no-optional-warning-emission.js

@@ -0,0 +1,519 @@
+/**
+ * ESLint Rule: no-optional-warning-emission
+ *
+ * A warning-typed progress event emitted through an optional callback link
+ * (`callbacks.onProgress?.({ type: "warning", … })`) vanishes without trace
+ * when no caller wired the link — the emit-only-dead-warnings shape the
+ * diagnostics spine exists to close. Severity=warning diagnostics must reach
+ * a bound sink even when no surface registered a callback: absence of a
+ * consumer means the spine's default sink, never silence.
+ *
+ * Sanctioned fixes (named in the report message):
+ *   - `emitWarning(message, { scope })` (@fjall/util/diagnostics) wherever
+ *     the CLI owns the terminal end of the lane — the always-spine route;
+ *   - `emitStepWarnings(callbacks, step)` / `emitWarningEvent(callbacks,
+ *     message, opts)` (deploy-core orchestration/contextHelpers) at the
+ *     external-consumer boundary — present→callback, absent→spine.
+ *
+ * Flagged shape: a callback invocation that can silently short-circuit (the
+ * call itself is `?.()`, or any member link in its callee chain is optional)
+ * whose callee names an `on[A-Z]`-shaped callback and whose arguments carry
+ * an object literal with `type: "warning"` (TS `as`/`satisfies` wrappers
+ * unwrapped, spread-extended literals included).
+ *
+ * Deliberately kept wiring sites are declared in the rule-option allowlist
+ * (`allow`), seeded from SANCTIONED_WARNING_EMISSION_SITES below — enumerated
+ * config data, reviewable in one place, in preference to inline disables.
+ * Each entry names a file (path-suffix match on a path boundary) and
+ * optionally narrows by:
+ *   - `enclosingFunction` — the nearest NAMED enclosing function; property-
+ *     assigned and variable-assigned arrows count as named, anonymous
+ *     wrappers (returned arrows, IIFEs) are skipped upward;
+ *   - `withinCallee` — the site sits inside an ARGUMENT of a call or `new`
+ *     of this name (callee identifier, or member property for method calls);
+ *   - `messageProperty` — the event literal's `message` value is a read of
+ *     this property (or a bare identifier of this name).
+ * All fields given on an entry must match for the entry to sanction a site.
+ *
+ * Known limitations (deliberate, matching the plugin's untyped design):
+ * - Literal-keyed only: an event object built in a binding and passed
+ *   through, or a `type` held in a variable, passes unexamined.
+ * - Message-only `onWarning?.(msg)` lanes are out of scope: the
+ *   ProgressCallbacks.onWarning(message, proceed) consent flow must never be
+ *   flattened onto the fire-and-forget spine, and without type information
+ *   the rule cannot tell the two onWarning arities apart.
+ * - Non-callback-named emitters (`emit?.({ type: "warning" })`) pass — the
+ *   spine's own sink plumbing legitimately holds that shape.
+ *
+ * Escape hatch: prefer an `allow` entry so the sanctioned set stays
+ * enumerable; `// eslint-disable-next-line fjall/no-optional-warning-emission
+ * -- <why>` remains available for genuinely local one-offs.
+ */
+
+const CALLBACK_RE = /^on[A-Z]/;
+
+/**
+ * The sanctioned optional-warning wiring sites (diagnostics-spine design,
+ * Component 8). Imported by cli/eslint.config.js and the root
+ * eslint.config.mjs as the shared `allow` seed — single source, so the two
+ * configs cannot drift.
+ */
+export const SANCTIONED_WARNING_EMISSION_SITES = [
+  // Attribution-degrade warning: emits into the caller-supplied onProgress
+  // by contract (the caller decided the surface before invoking).
+  {
+    file: "cli/src/services/deployment/deploymentApiHelpers.ts",
+    enclosingFunction: "warnUnattributedOperation"
+  },
+  // §5.5 gateUntrackedDeploy onWarning wiring — feeds the tracked-deploy
+  // policy gate, whose warn-and-proceed arm renders on the caller's surface.
+  {
+    file: "cli/src/services/deployment/applicationDeployment.ts",
+    withinCallee: "gateUntrackedDeploy"
+  },
+  // §5.6 accept-and-mark upgrade notice off the 201 — a single non-blocking
+  // per-deploy notice on the deploy surface's own warning arm.
+  {
+    file: "cli/src/services/deployment/applicationDeployment.ts",
+    enclosingFunction: "deployApplication",
+    messageProperty: "upgradeNotice"
+  },
+  // The spine helpers' own internals: their present→callback arm IS the
+  // external-boundary fallback contract the rule points everyone else at.
+  {
+    file: "deploy-core/src/orchestration/contextHelpers.ts",
+    enclosingFunction: "emitWarningEvent"
+  },
+  {
+    file: "deploy-core/src/orchestration/contextHelpers.ts",
+    enclosingFunction: "emitStepWarnings"
+  },
+  {
+    file: "cli/src/services/deployment/callbackShared.ts",
+    enclosingFunction: "createOnLogHandler"
+  },
+
+  // Direct-producer lane — live-rendered via the surface builders' wired
+  // onProgress; migrates in the direct-producer-migration follow-on.
+  {
+    file: "cli/src/services/deployment/applicationDeployment.ts",
+    enclosingFunction: "warnBestEffort"
+  },
+  {
+    file: "cli/src/services/deployment/applicationDeployment.ts",
+    enclosingFunction: "deployApplication"
+  },
+  // DeploymentTracker onWarning wiring arrow.
+  {
+    file: "cli/src/services/deployment/applicationDeployment.ts",
+    enclosingFunction: "onWarning"
+  },
+  {
+    file: "cli/src/services/deployment/applicationDestruction.ts",
+    enclosingFunction: "destroyApplication"
+  },
+  {
+    file: "cli/src/services/deployment/applicationDestruction.ts",
+    enclosingFunction: "onWarning"
+  },
+  {
+    file: "cli/src/services/deployment/applicationDestruction.ts",
+    enclosingFunction: "trackAndReturnFailure"
+  },
+  {
+    file: "cli/src/services/deployment/applicationRestart.ts",
+    enclosingFunction: "warnBestEffort"
+  },
+  {
+    file: "cli/src/services/deployment/applicationRestart.ts",
+    enclosingFunction: "onWarning"
+  },
+  // Quarantine/retained-bucket cleanup signals on both adapter copies.
+  {
+    file: "cli/src/services/deployment/baseCallbackBuilder.ts",
+    enclosingFunction: "onStackCleanupProgress"
+  },
+  {
+    file: "cli/src/services/deployment/InteractiveCallbackAdapter.ts",
+    enclosingFunction: "onStackCleanupProgress"
+  },
+  {
+    file: "cli/src/services/deployment/orgCallbackMapper.ts",
+    enclosingFunction: "onCascadeLedger"
+  },
+
+  // Import lane — importOperation wires onProgress on every production
+  // path; deliberately callback-based, revisited in the
+  // direct-producer-migration follow-on.
+  {
+    file: "cli/src/services/import/ImportService.ts",
+    enclosingFunction: "importResource"
+  },
+  {
+    file: "cli/src/services/import/importAdoptionHelpers.ts",
+    enclosingFunction: "generateAndWriteCode"
+  },
+  {
+    file: "cli/src/services/monitoring/DiscoveryService.ts",
+    enclosingFunction: "readS3BucketDetail"
+  },
+  {
+    file: "cli/src/services/monitoring/DiscoveryService.ts",
+    enclosingFunction: "discoverVpcs"
+  },
+
+  // Pre-existing stock, wiring unverified — catalogued as fresh census
+  // input for the follow-on census (ADR); audited then migrated in the
+  // direct-producer-migration follow-on.
+  {
+    file: "cli/src/commands/provisioning/restore.ts",
+    enclosingFunction: "onWarning"
+  },
+  {
+    file: "cli/src/operations/resources/secretsOperations.ts",
+    enclosingFunction: "applyDeclaration"
+  },
+  {
+    file: "cli/src/services/application/ApplicationDetectionHelpers.ts",
+    enclosingFunction: "reportValidationNotRun"
+  },
+  {
+    file: "cli/src/services/application/ApplicationDetectionHelpers.ts",
+    enclosingFunction: "validateSecrets"
+  },
+  {
+    file: "cli/src/services/auth/OidcBootstrapService.ts",
+    enclosingFunction: "establishOidcTrust"
+  },
+  {
+    file: "cli/src/services/aws-account/AwsAccountService.ts",
+    enclosingFunction: "buildProviderAccountsFromConfig"
+  },
+  {
+    file: "cli/src/services/aws/awsExecution.ts",
+    enclosingFunction: "executeWithAwsCredentials"
+  },
+  {
+    file: "cli/src/services/domain-dns/CliDomainDeployProvider.ts",
+    enclosingFunction: "deployDomain"
+  },
+  {
+    file: "cli/src/services/domain-dns/delegationService.ts",
+    enclosingFunction: "deployPhase"
+  },
+  {
+    file: "cli/src/services/organisation/OrganisationDeployService.ts",
+    enclosingFunction: "onWarn"
+  },
+  {
+    file: "cli/src/services/organisation/OrganisationDestroyService.ts",
+    enclosingFunction: "onWarning"
+  },
+  {
+    file: "cli/src/services/organisation/OrganisationDestroyService.ts",
+    enclosingFunction: "destroy"
+  },
+  {
+    file: "cli/src/services/organisation/OrganisationSetupService.ts",
+    enclosingFunction: "onWarning"
+  },
+  {
+    file: "cli/src/services/organisation/OrganisationSetupService.ts",
+    enclosingFunction: "runOrganisationSetup"
+  },
+  {
+    file: "cli/src/services/organisation/OrganisationStandaloneHelpers.ts",
+    enclosingFunction: "registerStandaloneAccount"
+  },
+
+  // Dormant reporter-warning twin: ProgressReporter.warning has no live
+  // production instantiation post-tap; kept until the reporter-lane-reroute
+  // follow-on (a diagnostics import into the types module would be wrong
+  // layering).
+  {
+    file: "deploy-core/src/types/ProgressEvent.ts",
+    enclosingFunction: "warning"
+  }
+];
+
+/**
+ * Strip TS type-level wrappers so `"warning" as const` and
+ * `{ … } satisfies ProgressEvent` cannot evade the literal check.
+ */
+function unwrapTypeExpressions(node) {
+  let current = node;
+  while (
+    current.type === "TSAsExpression" ||
+    current.type === "TSSatisfiesExpression" ||
+    current.type === "TSNonNullExpression" ||
+    current.type === "TSTypeAssertion"
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+/**
+ * True when the invocation can short-circuit silently: the call itself is
+ * `?.()`, or an optional member link sits in ITS chain (`callbacks?.on…(…)`).
+ * A parenthesised chain in callee position (`(a?.b)()`) ends the chain — an
+ * absent link there throws rather than skips, so it is not this defect.
+ */
+function invocationCanSilentlySkip(node) {
+  if (node.optional) return true;
+  let current = node.callee;
+  while (current.type === "MemberExpression") {
+    if (current.optional) return true;
+    current = current.object;
+  }
+  return false;
+}
+
+/** Terminal callee name: bare identifier, or member property. */
+function terminalCalleeName(callee) {
+  let current = callee;
+  if (current.type === "ChainExpression") current = current.expression;
+  if (current.type === "Identifier") return current.name;
+  if (
+    current.type === "MemberExpression" &&
+    !current.computed &&
+    current.property.type === "Identifier"
+  ) {
+    return current.property.name;
+  }
+  return null;
+}
+
+/** Non-computed property whose key spells `name`. */
+function isPropertyNamed(property, name) {
+  if (property.type !== "Property" || property.computed) return false;
+  if (property.key.type === "Identifier") return property.key.name === name;
+  if (property.key.type === "Literal") return property.key.value === name;
+  return false;
+}
+
+/**
+ * First argument object literal carrying `type: "warning"`, else null.
+ */
+function findWarningEventLiteral(node) {
+  for (const rawArgument of node.arguments) {
+    const argument = unwrapTypeExpressions(rawArgument);
+    if (argument.type !== "ObjectExpression") continue;
+    for (const property of argument.properties) {
+      if (!isPropertyNamed(property, "type")) continue;
+      const value = unwrapTypeExpressions(property.value);
+      if (value.type === "Literal" && value.value === "warning") {
+        return argument;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Name of a function node, when one is derivable: own id, variable binding,
+ * object-property key, class-method key, or assignment target.
+ */
+function functionName(fn) {
+  if (
+    (fn.type === "FunctionDeclaration" || fn.type === "FunctionExpression") &&
+    fn.id
+  ) {
+    return fn.id.name;
+  }
+  const parent = fn.parent;
+  if (!parent) return null;
+  if (
+    parent.type === "VariableDeclarator" &&
+    parent.init === fn &&
+    parent.id.type === "Identifier"
+  ) {
+    return parent.id.name;
+  }
+  if (parent.type === "Property" && parent.value === fn && !parent.computed) {
+    if (parent.key.type === "Identifier") return parent.key.name;
+    if (parent.key.type === "Literal" && typeof parent.key.value === "string") {
+      return parent.key.value;
+    }
+  }
+  if (
+    parent.type === "MethodDefinition" &&
+    parent.value === fn &&
+    !parent.computed &&
+    parent.key.type === "Identifier"
+  ) {
+    return parent.key.name;
+  }
+  if (parent.type === "AssignmentExpression" && parent.right === fn) {
+    if (parent.left.type === "Identifier") return parent.left.name;
+    if (
+      parent.left.type === "MemberExpression" &&
+      !parent.left.computed &&
+      parent.left.property.type === "Identifier"
+    ) {
+      return parent.left.property.name;
+    }
+  }
+  return null;
+}
+
+/**
+ * Nearest NAMED enclosing function: anonymous wrappers are skipped upward so
+ * a returned arrow attributes to the factory that returns it, while a
+ * property-assigned arrow (`onWarning: (m) => …`) attributes to its key.
+ */
+function nearestNamedEnclosingFunction(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === "FunctionDeclaration" ||
+      current.type === "FunctionExpression" ||
+      current.type === "ArrowFunctionExpression"
+    ) {
+      const name = functionName(current);
+      if (name !== null) return name;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+/**
+ * True when `node` sits inside an ARGUMENT of a call/new whose callee spells
+ * `calleeName`. Walks the full ancestor chain — the wiring arrow between the
+ * emission and the sanctioning call is expected.
+ */
+function isWithinCalleeArgument(node, calleeName) {
+  let previous = node;
+  let current = node.parent;
+  while (current) {
+    if (
+      (current.type === "CallExpression" || current.type === "NewExpression") &&
+      previous !== current.callee &&
+      terminalCalleeName(current.callee) === calleeName
+    ) {
+      return true;
+    }
+    previous = current;
+    current = current.parent;
+  }
+  return false;
+}
+
+/**
+ * True when the event literal's `message` value reads `propertyName` — a
+ * non-computed member access (`startOutcome.upgradeNotice`) or a bare
+ * identifier of that name.
+ */
+function messageReadsProperty(eventLiteral, propertyName) {
+  for (const property of eventLiteral.properties) {
+    if (!isPropertyNamed(property, "message")) continue;
+    const value = unwrapTypeExpressions(property.value);
+    if (value.type === "Identifier") return value.name === propertyName;
+    if (
+      value.type === "MemberExpression" &&
+      !value.computed &&
+      value.property.type === "Identifier"
+    ) {
+      return value.property.name === propertyName;
+    }
+  }
+  return false;
+}
+
+/** Path-suffix match on a path boundary (or exact match). */
+function fileMatches(filename, entryFile) {
+  const normalised = filename.replace(/\\/g, "/");
+  return normalised === entryFile || normalised.endsWith(`/${entryFile}`);
+}
+
+function siteIsSanctioned(allow, filename, node, eventLiteral) {
+  for (const entry of allow) {
+    if (!fileMatches(filename, entry.file)) continue;
+    if (
+      entry.enclosingFunction !== undefined &&
+      nearestNamedEnclosingFunction(node) !== entry.enclosingFunction
+    ) {
+      continue;
+    }
+    if (
+      entry.withinCallee !== undefined &&
+      !isWithinCalleeArgument(node, entry.withinCallee)
+    ) {
+      continue;
+    }
+    if (
+      entry.messageProperty !== undefined &&
+      !messageReadsProperty(eventLiteral, entry.messageProperty)
+    ) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow warning-typed events on optional callback links — an absent link silently swallows the warning; route it via the diagnostics spine",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      optionalWarningEmission:
+        "Warning-typed event rides an optional callback link (`{{callee}}`) — when the link is absent the warning vanishes silently. Emit via emitWarning(message, { scope }) (@fjall/util/diagnostics) where the CLI owns the lane, or emitStepWarnings/emitWarningEvent (deploy-core contextHelpers) at the external-consumer boundary. Deliberately kept wiring sites belong in this rule's `allow` option, not behind inline disables."
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          allow: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                file: { type: "string" },
+                enclosingFunction: { type: "string" },
+                withinCallee: { type: "string" },
+                messageProperty: { type: "string" }
+              },
+              required: ["file"],
+              additionalProperties: false
+            }
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+
+  create(context) {
+    const allow = context.options[0]?.allow ?? [];
+
+    return {
+      CallExpression(node) {
+        if (!invocationCanSilentlySkip(node)) return;
+
+        const calleeName = terminalCalleeName(node.callee);
+        if (calleeName === null || !CALLBACK_RE.test(calleeName)) return;
+
+        const eventLiteral = findWarningEventLiteral(node);
+        if (eventLiteral === null) return;
+
+        if (siteIsSanctioned(allow, context.filename, node, eventLiteral)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "optionalWarningEmission",
+          data: { callee: calleeName }
+        });
+      }
+    };
+  }
+};

package/no-unguarded-chmod-in-tests.js

@@ -0,0 +1,143 @@
+/**
+ * ESLint Rule: no-unguarded-chmod-in-tests
+ *
+ * Hosted CI (Buildkite agents) executes the test suite as ROOT, and root
+ * ignores file modes entirely: a fixture chmod-ed to 0o000 still reads
+ * fine, a 0o444 file still writes. A permission-failure lane simulated via
+ * chmod therefore inverts under root — the code under test succeeds where
+ * the test expects failure, and the lane either fails in CI only or
+ * silently stops testing anything.
+ *
+ * Decision rule (the report message teaches the same thing):
+ *   - PREFER injecting the failure at the first-party fs seam — a
+ *     passthrough vi.mock of the fs module (importOriginal spread) with a
+ *     per-test armed rejection such as
+ *     `vi.mocked(readFile).mockRejectedValueOnce(eacces)` — deterministic
+ *     in every environment, including root CI.
+ *   - chmod + `it.skipIf(process.getuid?.() === 0)` is sanctioned ONLY
+ *     where the failure must arise inside third-party code that cannot be
+ *     seam-mocked (e.g. a glob library walking a mode-000 directory) — and
+ *     it means the lane is untested in CI.
+ *
+ * Flagged shape: any call to a chmod-family function (chmod / chmodSync /
+ * fchmod / fchmodSync / lchmod / lchmodSync — bare import or member call
+ * such as `fs.chmodSync` / `fs.promises.chmod`) inside a test file
+ * (*.test.* / *.spec.*, or any file under a __tests__/ directory) whose
+ * file carries no root guard.
+ *
+ * Guard heuristic — deliberately coarse and FILE-scoped: any reference to
+ * `process.getuid` anywhere in the file counts as the guard. That matches
+ * both established house shapes — the inline
+ * `it.skipIf(process.getuid?.() === 0)` idiom and the named-constant form
+ * (`const runningAsRoot = typeof process.getuid === "function" &&
+ * process.getuid() === 0`, then `it.skipIf(runningAsRoot)`) — without
+ * per-call data-flow tracking, which would buy little: the defect class is
+ * a whole file written without root awareness, not a guarded file with one
+ * stray call. Four further coarse edges, all deliberate: a member call
+ * named `chmod` on a non-fs object is still flagged (in test files that
+ * name is near-certainly the fs API; rename the member for a genuine
+ * collision); the rule does not check that the guard's uid comparison
+ * is against 0 (a file that reads process.getuid at all has engaged with
+ * the root question); a guard imported from a shared helper is NOT
+ * recognised — inline the `process.getuid` reference in the file that
+ * chmods, which keeps the guard visible next to the hazard it excuses;
+ * and shell-mediated chmod (`execSync("chmod 000 …")`) is out of static
+ * reach — string sniffing would catch only literals while variable-carried
+ * commands escape, so that residue is left to the post-push CI-green check
+ * rather than to a porous lint arm that would imply coverage it lacks.
+ */
+
+const CHMOD_FAMILY = new Set([
+  "chmod",
+  "chmodSync",
+  "fchmod",
+  "fchmodSync",
+  "lchmod",
+  "lchmodSync"
+]);
+
+/** Test files only: *.test.* / *.spec.* basenames, or __tests__/ paths. */
+function isTestFile(filename) {
+  const normalised = filename.replace(/\\/g, "/");
+  return (
+    /\.(test|spec)\.[cm]?[jt]sx?$/.test(normalised) ||
+    normalised.includes("/__tests__/")
+  );
+}
+
+/** Terminal callee name: bare identifier, or non-computed member property. */
+function terminalCalleeName(callee) {
+  let current = callee;
+  if (current.type === "ChainExpression") current = current.expression;
+  if (current.type === "Identifier") return current.name;
+  if (
+    current.type === "MemberExpression" &&
+    !current.computed &&
+    current.property.type === "Identifier"
+  ) {
+    return current.property.name;
+  }
+  return null;
+}
+
+/** Non-computed `process.getuid` access (plain or optional-chained). */
+function isProcessGetuidReference(node) {
+  return (
+    !node.computed &&
+    node.object.type === "Identifier" &&
+    node.object.name === "process" &&
+    node.property.type === "Identifier" &&
+    node.property.name === "getuid"
+  );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow chmod-family calls in test files with no process.getuid root guard — root CI ignores file modes, so chmod-simulated permission failures invert there",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      unguardedChmod:
+        "`{{name}}` simulates a permission failure that root ignores — hosted CI runs tests as root, where a mode-000 file still reads fine, so this lane inverts in CI. Prefer injecting the failure at the first-party fs seam (passthrough vi.mock of the fs module, then vi.mocked(fn).mockRejectedValueOnce with a realistic EACCES error): deterministic in every environment, including root CI. chmod plus it.skipIf(process.getuid?.() === 0) is sanctioned ONLY where the failure must arise inside third-party code that cannot be seam-mocked — accepting that the lane goes untested in CI."
+    },
+    schema: []
+  },
+
+  create(context) {
+    if (!isTestFile(context.filename)) return {};
+
+    // The guard may appear before or after the chmod call (it is
+    // file-scoped), so collect calls and decide at Program:exit.
+    const chmodCalls = [];
+    let hasRootGuard = false;
+
+    return {
+      MemberExpression(node) {
+        if (isProcessGetuidReference(node)) hasRootGuard = true;
+      },
+
+      CallExpression(node) {
+        const name = terminalCalleeName(node.callee);
+        if (name !== null && CHMOD_FAMILY.has(name)) {
+          chmodCalls.push({ node, name });
+        }
+      },
+
+      "Program:exit"() {
+        if (hasRootGuard) return;
+        for (const { node, name } of chmodCalls) {
+          context.report({
+            node,
+            messageId: "unguardedChmod",
+            data: { name }
+          });
+        }
+      }
+    };
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/eslint-plugin",
-  "version": "12.2.0",
+  "version": "12.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",