Files
msd-core/eslint-rules/require-registered-exit.cjs
Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
2026-10-06 01:47:40 +02:00

203 lines
8.9 KiB
JavaScript

'use strict';
const path = require('node:path');
/**
* require-registered-exit
*
* Issue #3910 (epic #3889 Phase 6): "the raw terminator is banned by
* construction." A raw `process.exit(...)` call bypasses the registered
* exit-contract machinery in src/cli-exit.cts (ExitError/runMain for a CLI
* path, terminateNow for a hook) — the whole point of ADR-3889 is that
* EVERY process termination is projected through one of those two seams, so
* a bare `process.exit()` re-opens exactly the "nothing fails with success"
* defect class the epic exists to close.
*
* Flags: any `CallExpression` whose callee is a `MemberExpression` with
* `object.name === 'process'` and `property.name === 'exit'` — i.e.
* `process.exit(...)`.
*
* Does NOT flag `process.exitCode = N` — that assignment is the CORRECT
* drain-then-exit pattern `runMain` itself uses, and conflating the two is
* what inflated this epic's original raw-`process.exit()` census 2x (a
* `MemberExpression` assignment target is never a `CallExpression`, so this
* rule's `CallExpression`-only selector already excludes it structurally;
* see the negative-control tests in tests/eslint-rules.test.cjs).
*
* ── Allowlist (exactly two sites, repo-wide) ────────────────────────────────
*
* 1. The body of `terminateNow` in src/cli-exit.cts — the single sanctioned
* terminator (ADR-3889 §3: write-then-terminate, the only place exit code
* 2 — the hook-protocol deny — may be produced). Detected STRUCTURALLY
* below (any process.exit() call lexically nested inside a function
* declaration/expression named `terminateNow`, AND the file's basename is
* `cli-exit.cts`), not by a path+line number, which rots the instant the
* function grows or moves. The basename constraint is required in
* addition to the name check: without it, any function named
* `terminateNow` anywhere in the repo would silently inherit the
* allowlist, widening the rule's trust boundary to a name that can be
* typo'd or copy-pasted into an unrelated module.
*
* 2. msd-core/bin/msd-tools.cjs's `ensureRuntimeBuild` bootstrap-failure path
* (see its own inline `// eslint-disable-next-line local/require-registered-exit`
* comment). That call runs BEFORE `./lib/cli-exit.cjs` is even required —
* the registered-exit seam does not exist yet at that point in the
* process's lifetime, so there is nothing to route through. An inline
* disable directive WITH a reason comment at that one call site was
* chosen over a hardcoded path in this rule for the same reason
* terminateNow's allowlisting is structural rather than path-based: a
* path-keyed allowlist here would silently stop protecting the file the
* moment its bootstrap code moved, while an inline directive travels with
* the call site and fails loudly (an unused-disable lint error) if the
* surrounding code changes such that it is no longer needed.
*
* ── Computed member access — `process['exit']()` / `process[x]()` ─────────
*
* A `MemberExpression` callee on `process` is followed whether or not it is
* computed. For a computed property the property name is resolved via
* `resolveComputedPropertyName` below:
*
* - A string `Literal` property (`process['exit'](0)`) resolves directly.
* - An `Identifier` property (`process[exit](0)`) resolves ONLY when it is
* statically determinable: the identifier must bind to exactly one
* variable declaration in scope, that declaration's initializer must be
* a string `Literal`, and the variable must have at most one write
* reference (its own initializer — i.e. never reassigned). This closes
* `const exit = 'exit'; process[exit](1);`.
*
* A genuinely dynamic computed property (a runtime value, a function call, a
* reassigned binding, or an identifier with no resolvable single-literal
* definition) resolves to `null` and is deliberately NOT flagged — the rule
* never guesses at a property name it cannot prove.
*
* ── Known limits (documented, deliberately out of scope) ────────────────────
*
* Even with the computed-property resolution above, the rule does NOT do
* general binding/flow analysis, so it still cannot catch:
*
* - `const e = process.exit; e(1);` — aliasing the function reference to a
* local binding before calling it; by the time the alias is called, the
* callee is a plain Identifier, not a MemberExpression on `process`.
* - `process.exit.call(null, 1)` / `process.exit.apply(null, [1])` —
* invoking `process.exit` indirectly via Function.prototype.call/apply;
* the outer CallExpression's callee is `process.exit.call`, not
* `process.exit` itself.
*
* Catching these would require a materially different and more expensive
* class of analysis (tracking that a local variable or a `.call`/`.apply`
* receiver resolves back to `process.exit`). Out of scope for this issue.
* See the pinning tests in tests/eslint-rules.test.cjs ("KNOWN LIMIT (pinned,
* not endorsed)") that assert these are NOT flagged today — if a future
* change starts catching one of them, those tests will fail loudly instead
* of the change silently altering the rule's reach.
*/
/**
* True if `node` (a CallExpression) is lexically nested inside a function
* declaration or function expression named `name`, walking up the ESLint
* `.parent` chain. Used to allowlist the terminateNow body structurally —
* see the module doc comment above.
*/
function isInsideFunctionNamed(node, name) {
let current = node.parent;
while (current) {
if (
(current.type === 'FunctionDeclaration' || current.type === 'FunctionExpression') &&
current.id &&
current.id.type === 'Identifier' &&
current.id.name === name
) {
return true;
}
current = current.parent;
}
return false;
}
/**
* Resolves the property name of a computed `MemberExpression` property node
* to a string, or returns `null` when it cannot be statically determined.
* See the module doc comment ("Computed member access") for the resolution
* rules. `callNode` is used to anchor scope lookup for an Identifier
* property.
*/
function resolveComputedPropertyName(propertyNode, callNode, context) {
if (propertyNode.type === 'Literal' && typeof propertyNode.value === 'string') {
return propertyNode.value;
}
if (propertyNode.type === 'Identifier') {
const scope =
context.sourceCode && typeof context.sourceCode.getScope === 'function'
? context.sourceCode.getScope(callNode)
: context.getScope();
let cur = scope;
while (cur) {
const variable = cur.variables.find((v) => v.name === propertyNode.name);
if (variable) {
if (variable.defs.length !== 1) return null;
const def = variable.defs[0];
if (
def.type !== 'Variable' ||
!def.node.init ||
def.node.init.type !== 'Literal' ||
typeof def.node.init.value !== 'string'
) {
return null;
}
const writeRefs = variable.references.filter((r) => r.isWrite());
if (writeRefs.length > 1) return null;
return def.node.init.value;
}
cur = cur.upper;
}
return null;
}
return null;
}
/** @type {import('eslint').Rule.RuleModule} */
const rule = {
meta: {
type: 'problem',
docs: {
description:
'Disallow raw process.exit() outside terminateNow — route CLI paths through runMain/ExitError, hooks through terminateNow, and drain-only exits through process.exitCode',
category: 'Best Practices',
},
schema: [],
messages: {
rawProcessExit:
'Raw process.exit() is banned outside terminateNow (ADR-3889). Use runMain/ExitError '
+ '(src/cli-exit.cts) for a CLI entrypoint, terminateNow (src/cli-exit.cts) for a hook that '
+ 'must write-then-terminate immediately, or set process.exitCode and let the process drain '
+ 'naturally when nothing needs an immediate hard exit.',
},
},
create(context) {
return {
CallExpression(node) {
const callee = node.callee;
if (callee.type !== 'MemberExpression') return;
if (callee.object.type !== 'Identifier' || callee.object.name !== 'process') return;
let propertyName;
if (!callee.computed) {
if (callee.property.type !== 'Identifier') return;
propertyName = callee.property.name;
} else {
propertyName = resolveComputedPropertyName(callee.property, node, context);
if (propertyName === null) return;
}
if (propertyName !== 'exit') return;
const filename = context.filename ?? context.getFilename();
if (path.basename(filename) === 'cli-exit.cts' && isInsideFunctionNamed(node, 'terminateNow')) return;
context.report({ node, messageId: 'rawProcessExit' });
},
};
},
};
module.exports = rule;