Skip to content

Commit e89a54a

Browse files
mdjermanovicnzakas
mdjermanovic
and
nzakas
authored
feat: change behavior of inactive flags (#19386)
* feat: change behavior of inactive flags Fixes #19337 * generate flag inactivity reason message * add comment Co-authored-by: Nicholas C. Zakas <[email protected]> --------- Co-authored-by: Nicholas C. Zakas <[email protected]>
1 parent fa25c7a commit e89a54a

File tree

8 files changed

+272
-34
lines changed

8 files changed

+272
-34
lines changed

‎docs/src/_data/flags.js

+29-3
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,42 @@
55

66
"use strict";
77

8+
//-----------------------------------------------------------------------------
9+
// Helpers
10+
//-----------------------------------------------------------------------------
11+
12+
/**
13+
* Determines whether the flag is used for test purposes only.
14+
* @param {string} name The flag name to check.
15+
* @returns {boolean} `true` if the flag is used for test purposes only.
16+
*/
17+
function isTestOnlyFlag(name) {
18+
return name.startsWith("test_only");
19+
}
20+
821
//-----------------------------------------------------------------------------
922
// Exports
1023
//-----------------------------------------------------------------------------
1124

1225
module.exports = function() {
1326

14-
const { activeFlags, inactiveFlags } = require("../../../lib/shared/flags");
27+
const { activeFlags, inactiveFlags, getInactivityReasonMessage } = require("../../../lib/shared/flags");
1528

1629
return {
17-
active: Object.fromEntries([...activeFlags]),
18-
inactive: Object.fromEntries([...inactiveFlags])
30+
active: Object.fromEntries(
31+
[...activeFlags]
32+
.filter(([name]) => !isTestOnlyFlag(name))
33+
),
34+
inactive: Object.fromEntries(
35+
[...inactiveFlags]
36+
.filter(([name]) => !isTestOnlyFlag(name))
37+
.map(([name, inactiveFlagData]) => [
38+
name,
39+
{
40+
...inactiveFlagData,
41+
inactivityReason: getInactivityReasonMessage(inactiveFlagData)
42+
}
43+
])
44+
)
1945
};
2046
};

‎docs/src/pages/flags.md

+13-4
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,17 @@ ESLint ships experimental and future breaking changes behind feature flags to le
2020
The prefix of a flag indicates its status:
2121

2222
* `unstable_` indicates that the feature is experimental and the implementation may change before the feature is stabilized. This is a "use at your own risk" feature.
23-
* `v##_` indicates that the feature is stabilized and will be available in the next major release. For example, `v10_some_feature` indicates that this is a breaking change that will be formally released in ESLint v10.0.0. These flags are removed each major release.
23+
* `v##_` indicates that the feature is stabilized and will be available in the next major release. For example, `v10_some_feature` indicates that this is a breaking change that will be formally released in ESLint v10.0.0. These flags are removed each major release, and further use of them throws an error.
2424

25-
A feature may move from unstable to stable without a major release if it is a non-breaking change.
25+
A feature may move from unstable to being enabled by default without a major release if it is a non-breaking change.
26+
27+
The following policies apply to `unstable_` flags.
28+
29+
* When the feature is stabilized
30+
* If enabling the feature by default would be a breaking change, a new `v##_` flag is added as active, and the `unstable_` flag becomes inactive. Further use of the `unstable_` flag automatically enables the `v##_` flag but emits a warning.
31+
* Otherwise, the feature is enabled by default, and the `unstable_` flag becomes inactive. Further use of the `unstable_` flag emits a warning.
32+
* If the feature is abandoned, the `unstable_` flag becomes inactive. Further use of it throws an error.
33+
* All inactive `unstable_` flags are removed each major release, and further use of them throws an error.
2634

2735
## Active Flags
2836

@@ -51,11 +59,12 @@ The following flags were once used but are no longer active.
5159
<tr>
5260
<th>Flag</th>
5361
<th>Description</th>
62+
<th>Inactivity Reason</th>
5463
</tr>
5564
</thead>
5665
<tbody>
57-
{%- for name, desc in flags.inactive -%}
58-
<tr><td><code>{{name}}</code></td><td>{{desc}}</td></tr>
66+
{%- for name, data in flags.inactive -%}
67+
<tr><td><code>{{name}}</code></td><td>{{data.description}}</td><td>{{data.inactivityReason}}</td></tr>
5968
{%- endfor -%}
6069
</tbody>
6170
</table>

‎lib/eslint/eslint.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -470,7 +470,7 @@ class ESLint {
470470
defaultConfigs
471471
};
472472

473-
this.#configLoader = processedOptions.flags.includes("unstable_config_lookup_from_file")
473+
this.#configLoader = linter.hasFlag("unstable_config_lookup_from_file")
474474
? new ConfigLoader(configLoaderOptions)
475475
: new LegacyConfigLoader(configLoaderOptions);
476476

‎lib/linter/linter.js

+24-3
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ const { assertIsRuleSeverity } = require("../config/flat-config-schema");
4343
const { normalizeSeverityToString, normalizeSeverityToNumber } = require("../shared/severity");
4444
const { deepMergeArrays } = require("../shared/deep-merge-arrays");
4545
const jslang = require("../languages/js");
46-
const { activeFlags, inactiveFlags } = require("../shared/flags");
46+
const { activeFlags, inactiveFlags, getInactivityReasonMessage } = require("../shared/flags");
4747
const debug = require("debug")("eslint:linter");
4848
const MAX_AUTOFIX_PASSES = 10;
4949
const DEFAULT_PARSER_NAME = "espree";
@@ -1326,19 +1326,40 @@ class Linter {
13261326
*/
13271327
constructor({ cwd, configType = "flat", flags = [] } = {}) {
13281328

1329+
const processedFlags = [];
1330+
13291331
flags.forEach(flag => {
13301332
if (inactiveFlags.has(flag)) {
1331-
throw new Error(`The flag '${flag}' is inactive: ${inactiveFlags.get(flag)}`);
1333+
const inactiveFlagData = inactiveFlags.get(flag);
1334+
const inactivityReason = getInactivityReasonMessage(inactiveFlagData);
1335+
1336+
if (typeof inactiveFlagData.replacedBy === "undefined") {
1337+
throw new Error(`The flag '${flag}' is inactive: ${inactivityReason}`);
1338+
}
1339+
1340+
// if there's a replacement, enable it instead of original
1341+
if (typeof inactiveFlagData.replacedBy === "string") {
1342+
processedFlags.push(inactiveFlagData.replacedBy);
1343+
}
1344+
1345+
globalThis.process?.emitWarning?.(
1346+
`The flag '${flag}' is inactive: ${inactivityReason}`,
1347+
`ESLintInactiveFlag_${flag}`
1348+
);
1349+
1350+
return;
13321351
}
13331352

13341353
if (!activeFlags.has(flag)) {
13351354
throw new Error(`Unknown flag '${flag}'.`);
13361355
}
1356+
1357+
processedFlags.push(flag);
13371358
});
13381359

13391360
internalSlotsMap.set(this, {
13401361
cwd: normalizeCwd(cwd),
1341-
flags,
1362+
flags: processedFlags,
13421363
lastConfigArray: null,
13431364
lastSourceCode: null,
13441365
lastSuppressedMessages: [],

‎lib/shared/flags.js

+43-5
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,23 @@
44

55
"use strict";
66

7+
//------------------------------------------------------------------------------
8+
// Typedefs
9+
//------------------------------------------------------------------------------
10+
11+
/**
12+
* @typedef {Object} InactiveFlagData
13+
* @property {string} description Flag description
14+
* @property {string | null} [replacedBy] Can be either:
15+
* - An active flag (string) that enables the same feature.
16+
* - `null` if the feature is now enabled by default.
17+
* - Omitted if the feature has been abandoned.
18+
*/
19+
20+
//-----------------------------------------------------------------------------
21+
// Exports
22+
//-----------------------------------------------------------------------------
23+
724
/**
825
* The set of flags that change ESLint behavior with a description.
926
* @type {Map<string, string>}
@@ -14,15 +31,36 @@ const activeFlags = new Map([
1431
]);
1532

1633
/**
17-
* The set of flags that used to be active but no longer have an effect.
18-
* @type {Map<string, string>}
34+
* The set of flags that used to be active.
35+
* @type {Map<string, InactiveFlagData>}
1936
*/
2037
const inactiveFlags = new Map([
21-
["test_only_old", "Used only for testing."],
22-
["unstable_ts_config", "This flag is no longer required to enable TypeScript configuration files."]
38+
["test_only_replaced", { description: "Used only for testing flags that have been replaced by other flags.", replacedBy: "test_only" }],
39+
["test_only_enabled_by_default", { description: "Used only for testing flags whose features have been enabled by default.", replacedBy: null }],
40+
["test_only_abandoned", { description: "Used only for testing flags whose features have been abandoned." }],
41+
["unstable_ts_config", { description: "Enable TypeScript configuration files.", replacedBy: null }]
2342
]);
2443

44+
/**
45+
* Creates a message that describes the reason the flag is inactive.
46+
* @param {InactiveFlagData} inactiveFlagData Data for the inactive flag.
47+
* @returns {string} Message describing the reason the flag is inactive.
48+
*/
49+
function getInactivityReasonMessage({ replacedBy }) {
50+
if (typeof replacedBy === "undefined") {
51+
return "This feature has been abandoned.";
52+
}
53+
54+
if (typeof replacedBy === "string") {
55+
return `This flag has been renamed '${replacedBy}' to reflect its stabilization. Please use '${replacedBy}' instead.`;
56+
}
57+
58+
// null
59+
return "This feature is now enabled by default.";
60+
}
61+
2562
module.exports = {
2663
activeFlags,
27-
inactiveFlags
64+
inactiveFlags,
65+
getInactivityReasonMessage
2866
};

‎tests/lib/cli.js

+46-3
Original file line numberDiff line numberDiff line change
@@ -1907,14 +1907,21 @@ describe("cli", () => {
19071907

19081908
describe("--flag option", () => {
19091909

1910-
it("should throw an error when an inactive flag is used", async () => {
1910+
let processStub;
1911+
1912+
beforeEach(() => {
1913+
sinon.restore();
1914+
processStub = sinon.stub(process, "emitWarning").withArgs(sinon.match.any, sinon.match(/^ESLintInactiveFlag_/u)).returns();
1915+
});
1916+
1917+
it("should throw an error when an inactive flag whose feature has been abandoned is used", async () => {
19111918
const configPath = getFixturePath("eslint.config.js");
19121919
const filePath = getFixturePath("passing.js");
1913-
const input = `--flag test_only_old --config ${configPath} ${filePath}`;
1920+
const input = `--flag test_only_abandoned --config ${configPath} ${filePath}`;
19141921

19151922
await stdAssert.rejects(async () => {
19161923
await cli.execute(input, null, true);
1917-
}, /The flag 'test_only_old' is inactive: Used only for testing\./u);
1924+
}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned\./u);
19181925
});
19191926

19201927
it("should error out when an unknown flag is used", async () => {
@@ -1927,6 +1934,42 @@ describe("cli", () => {
19271934
}, /Unknown flag 'test_only_oldx'\./u);
19281935
});
19291936

1937+
it("should emit a warning and not error out when an inactive flag that has been replaced by another flag is used", async () => {
1938+
const configPath = getFixturePath("eslint.config.js");
1939+
const filePath = getFixturePath("passing.js");
1940+
const input = `--flag test_only_replaced --config ${configPath} ${filePath}`;
1941+
const exitCode = await cli.execute(input, null, true);
1942+
1943+
assert.strictEqual(processStub.callCount, 1, "calls `process.emitWarning()` for flags once");
1944+
assert.deepStrictEqual(
1945+
processStub.getCall(0).args,
1946+
[
1947+
"The flag 'test_only_replaced' is inactive: This flag has been renamed 'test_only' to reflect its stabilization. Please use 'test_only' instead.",
1948+
"ESLintInactiveFlag_test_only_replaced"
1949+
]
1950+
);
1951+
sinon.assert.notCalled(log.error);
1952+
assert.strictEqual(exitCode, 0);
1953+
});
1954+
1955+
it("should emit a warning and not error out when an inactive flag whose feature is enabled by default is used", async () => {
1956+
const configPath = getFixturePath("eslint.config.js");
1957+
const filePath = getFixturePath("passing.js");
1958+
const input = `--flag test_only_enabled_by_default --config ${configPath} ${filePath}`;
1959+
const exitCode = await cli.execute(input, null, true);
1960+
1961+
assert.strictEqual(processStub.callCount, 1, "calls `process.emitWarning()` for flags once");
1962+
assert.deepStrictEqual(
1963+
processStub.getCall(0).args,
1964+
[
1965+
"The flag 'test_only_enabled_by_default' is inactive: This feature is now enabled by default.",
1966+
"ESLintInactiveFlag_test_only_enabled_by_default"
1967+
]
1968+
);
1969+
sinon.assert.notCalled(log.error);
1970+
assert.strictEqual(exitCode, 0);
1971+
});
1972+
19301973
it("should not error when a valid flag is used", async () => {
19311974
const configPath = getFixturePath("eslint.config.js");
19321975
const filePath = getFixturePath("passing.js");

‎tests/lib/eslint/eslint.js

+63-12
Original file line numberDiff line numberDiff line change
@@ -335,33 +335,67 @@ describe("ESLint", () => {
335335

336336
processStub.restore();
337337
});
338-
339-
it("should throw an error if the flag 'unstable_ts_config' is used", () => {
340-
assert.throws(
341-
() => new ESLint({
342-
flags: [...flags, "unstable_ts_config"]
343-
}),
344-
{ message: "The flag 'unstable_ts_config' is inactive: This flag is no longer required to enable TypeScript configuration files." }
345-
);
346-
});
347338
});
348339

349340
describe("hasFlag", () => {
350341

351342
/** @type {InstanceType<ESLint>} */
352343
let eslint;
353344

345+
let processStub;
346+
347+
beforeEach(() => {
348+
sinon.restore();
349+
processStub = sinon.stub(process, "emitWarning").withArgs(sinon.match.any, sinon.match(/^ESLintInactiveFlag_/u)).returns();
350+
});
351+
354352
it("should return true if the flag is present and active", () => {
355353
eslint = new ESLint({ cwd: getFixturePath(), flags: ["test_only"] });
356354

357355
assert.strictEqual(eslint.hasFlag("test_only"), true);
358356
});
359357

360-
it("should throw an error if the flag is inactive", () => {
358+
it("should return true for the replacement flag if an inactive flag that has been replaced is used", () => {
359+
eslint = new ESLint({ cwd: getFixturePath(), flags: ["test_only_replaced"] });
360+
361+
assert.strictEqual(eslint.hasFlag("test_only"), true);
362+
assert.strictEqual(processStub.callCount, 1, "calls `process.emitWarning()` for flags once");
363+
assert.deepStrictEqual(
364+
processStub.getCall(0).args,
365+
[
366+
"The flag 'test_only_replaced' is inactive: This flag has been renamed 'test_only' to reflect its stabilization. Please use 'test_only' instead.",
367+
"ESLintInactiveFlag_test_only_replaced"
368+
]
369+
);
370+
});
371+
372+
it("should return false if an inactive flag whose feature is enabled by default is used", () => {
373+
eslint = new ESLint({ cwd: getFixturePath(), flags: ["test_only_enabled_by_default"] });
374+
375+
assert.strictEqual(eslint.hasFlag("test_only_enabled_by_default"), false);
376+
assert.strictEqual(processStub.callCount, 1, "calls `process.emitWarning()` for flags once");
377+
assert.deepStrictEqual(
378+
processStub.getCall(0).args,
379+
[
380+
"The flag 'test_only_enabled_by_default' is inactive: This feature is now enabled by default.",
381+
"ESLintInactiveFlag_test_only_enabled_by_default"
382+
]
383+
);
384+
});
385+
386+
it("should throw an error if an inactive flag whose feature has been abandoned is used", () => {
387+
388+
assert.throws(() => {
389+
eslint = new ESLint({ cwd: getFixturePath(), flags: ["test_only_abandoned"] });
390+
}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned/u);
391+
392+
});
393+
394+
it("should throw an error if the flag is unknown", () => {
361395

362396
assert.throws(() => {
363-
eslint = new ESLint({ cwd: getFixturePath(), flags: ["test_only_old"] });
364-
}, /The flag 'test_only_old' is inactive/u);
397+
eslint = new ESLint({ cwd: getFixturePath(), flags: ["foo_bar"] });
398+
}, /Unknown flag 'foo_bar'/u);
365399

366400
});
367401

@@ -370,6 +404,23 @@ describe("ESLint", () => {
370404

371405
assert.strictEqual(eslint.hasFlag("x_feature"), false);
372406
});
407+
408+
// TODO: Remove in ESLint v10 when the flag is removed
409+
it("should not throw an error if the flag 'unstable_ts_config' is used", () => {
410+
eslint = new ESLint({
411+
flags: [...flags, "unstable_ts_config"]
412+
});
413+
414+
assert.strictEqual(eslint.hasFlag("unstable_ts_config"), false);
415+
assert.strictEqual(processStub.callCount, 1, "calls `process.emitWarning()` for flags once");
416+
assert.deepStrictEqual(
417+
processStub.getCall(0).args,
418+
[
419+
"The flag 'unstable_ts_config' is inactive: This feature is now enabled by default.",
420+
"ESLintInactiveFlag_unstable_ts_config"
421+
]
422+
);
423+
});
373424
});
374425

375426
describe("lintText()", () => {

0 commit comments

Comments
 (0)