@dloizides/frontend-devtools 2.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,20 @@ All notable changes to `@dloizides/frontend-devtools` are documented here.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.4.0] - 2026-11-03
9
+
10
+ UI-COMPOSE-1 "Extract shared UI from the start; compose small single-purpose parts", D-COMPOSE-2 "Single responsibility, few props, compose with slots".
11
+
12
+ ### Added
13
+ - `max-component-props` rule (default cap 12, `frozen` names may only shrink) and the opt-in `composeConfig` pack.
14
+
15
+ ## [2.3.0] - 2026-10-28
16
+
17
+ OBS-1 "Every app ships metrics, production-grade logs and alerts with working links", D-OBS-15 "Front-end budgets, warn only".
18
+
19
+ ### Added
20
+ - `./lighthouse` subpath: `budgetAssertions` (LCP < 2500 ms, TBT < 200 ms, CLS < 0.1, script transfer < 300 KB, all `warn`), `mobileSettings` (Lighthouse's mid-range phone profile) and `withBudgets(config)`, which merges both into an app's `lighthouserc.js`; keys the app sets win.
21
+
8
22
  ## [2.2.0] - 2026-10-23
9
23
 
10
24
  FOCUS-1 "Every screen names its initial focus", D-FOCUS-2 "Lint rule and ledger".
package/README.md CHANGED
@@ -155,3 +155,12 @@ import { initI18n } from '@dloizides/i18n';
155
155
  ## License
156
156
 
157
157
  MIT © dloizides
158
+
159
+ ## Lighthouse budgets (`/lighthouse`)
160
+
161
+ D-OBS-15 front-end budgets, warn only, on a mid-range phone. In an app's `lighthouserc.js`:
162
+
163
+ ```js
164
+ const { withBudgets } = require('@dloizides/frontend-devtools/lighthouse');
165
+ module.exports = withBudgets({ ci: { collect: { url: ['http://localhost:8099/'] }, assert: { assertions: {} } } });
166
+ ```
@@ -98,5 +98,8 @@ declare const recommendedConfig: FlatConfig;
98
98
  declare const FOCUS_RULE_NAMES: readonly string[];
99
99
  /** FOCUS-1: a game menu or dialog names the control focused on open. Opt-in, not part of recommendedConfig. */
100
100
  declare const focusConfig: FlatConfig;
101
+ declare const COMPOSE_RULE_NAMES: readonly string[];
102
+ /** UI-COMPOSE-1: a component stays small and composes with slots. Opt-in; pass `frozen` for existing over-limit ones. */
103
+ declare const composeConfig: FlatConfig;
101
104
 
102
- export { API_RULE_NAMES, COMMENT_RULE_NAMES, type CustomRule, FOCUS_RULE_NAMES, type FlatConfig, type FlatConfigPlugin, GAME_RULE_NAMES, HOUSE_PATTERN_RULE_NAMES, REUSE_RULE_NAMES, ROW_ACTION_RULE_NAMES, type SingleRulePlugin, apiConfig, commentsConfig, focusConfig, gameConfig, legacyPlugins, patternPacksConfig, plugin, recommendedConfig, reuseConfig, rowActionsConfig, ruleNames, rules };
105
+ export { API_RULE_NAMES, COMMENT_RULE_NAMES, COMPOSE_RULE_NAMES, type CustomRule, FOCUS_RULE_NAMES, type FlatConfig, type FlatConfigPlugin, GAME_RULE_NAMES, HOUSE_PATTERN_RULE_NAMES, REUSE_RULE_NAMES, ROW_ACTION_RULE_NAMES, type SingleRulePlugin, apiConfig, commentsConfig, composeConfig, focusConfig, gameConfig, legacyPlugins, patternPacksConfig, plugin, recommendedConfig, reuseConfig, rowActionsConfig, ruleNames, rules };
@@ -98,5 +98,8 @@ declare const recommendedConfig: FlatConfig;
98
98
  declare const FOCUS_RULE_NAMES: readonly string[];
99
99
  /** FOCUS-1: a game menu or dialog names the control focused on open. Opt-in, not part of recommendedConfig. */
100
100
  declare const focusConfig: FlatConfig;
101
+ declare const COMPOSE_RULE_NAMES: readonly string[];
102
+ /** UI-COMPOSE-1: a component stays small and composes with slots. Opt-in; pass `frozen` for existing over-limit ones. */
103
+ declare const composeConfig: FlatConfig;
101
104
 
102
- export { API_RULE_NAMES, COMMENT_RULE_NAMES, type CustomRule, FOCUS_RULE_NAMES, type FlatConfig, type FlatConfigPlugin, GAME_RULE_NAMES, HOUSE_PATTERN_RULE_NAMES, REUSE_RULE_NAMES, ROW_ACTION_RULE_NAMES, type SingleRulePlugin, apiConfig, commentsConfig, focusConfig, gameConfig, legacyPlugins, patternPacksConfig, plugin, recommendedConfig, reuseConfig, rowActionsConfig, ruleNames, rules };
105
+ export { API_RULE_NAMES, COMMENT_RULE_NAMES, COMPOSE_RULE_NAMES, type CustomRule, FOCUS_RULE_NAMES, type FlatConfig, type FlatConfigPlugin, GAME_RULE_NAMES, HOUSE_PATTERN_RULE_NAMES, REUSE_RULE_NAMES, ROW_ACTION_RULE_NAMES, type SingleRulePlugin, apiConfig, commentsConfig, composeConfig, focusConfig, gameConfig, legacyPlugins, patternPacksConfig, plugin, recommendedConfig, reuseConfig, rowActionsConfig, ruleNames, rules };
@@ -1455,6 +1455,151 @@ var noCommentsRule = {
1455
1455
  }
1456
1456
  };
1457
1457
  var no_comments_default = { rules: { "no-comments": noCommentsRule } };
1458
+
1459
+ // src/rules/max-component-props.js
1460
+ var DEFAULT_MAX2 = 12;
1461
+ var PROPS_NAME = /Props$/;
1462
+ var COMPONENT_NAME = /^[A-Z]/;
1463
+ var COMPONENT_WRAPPERS = /* @__PURE__ */ new Set(["forwardRef", "memo"]);
1464
+ var MEMBER_TYPES = /* @__PURE__ */ new Set(["TSPropertySignature", "TSMethodSignature"]);
1465
+ var FUNCTION_TYPES = /* @__PURE__ */ new Set(["ArrowFunctionExpression", "FunctionExpression"]);
1466
+ function memberNames(members) {
1467
+ const names = /* @__PURE__ */ new Set();
1468
+ for (const member of members) {
1469
+ if (!MEMBER_TYPES.has(member.type)) continue;
1470
+ const name = member.key?.name ?? member.key?.value;
1471
+ if (name !== void 0) names.add(String(name));
1472
+ }
1473
+ return names;
1474
+ }
1475
+ function mergeInto(target, source) {
1476
+ for (const name of source) target.add(name);
1477
+ return target;
1478
+ }
1479
+ function namesOfReference(name, declarations, seen) {
1480
+ const declaration = declarations.get(name);
1481
+ if (!declaration || seen.has(name)) return /* @__PURE__ */ new Set();
1482
+ seen.add(name);
1483
+ return namesOfDeclaration(declaration, declarations, seen);
1484
+ }
1485
+ function namesOfType(type, declarations, seen) {
1486
+ if (type.type === "TSTypeLiteral") return memberNames(type.members);
1487
+ if (type.type === "TSIntersectionType") {
1488
+ return type.types.reduce(
1489
+ (all, part) => mergeInto(all, namesOfType(part, declarations, seen)),
1490
+ /* @__PURE__ */ new Set()
1491
+ );
1492
+ }
1493
+ if (type.type === "TSUnionType") {
1494
+ return type.types.reduce((largest, part) => {
1495
+ const names = namesOfType(part, declarations, new Set(seen));
1496
+ return names.size > largest.size ? names : largest;
1497
+ }, /* @__PURE__ */ new Set());
1498
+ }
1499
+ if (type.type === "TSTypeReference" && type.typeName.type === "Identifier") {
1500
+ return namesOfReference(type.typeName.name, declarations, seen);
1501
+ }
1502
+ return /* @__PURE__ */ new Set();
1503
+ }
1504
+ function namesOfDeclaration(declaration, declarations, seen) {
1505
+ if (declaration.type === "TSTypeAliasDeclaration") {
1506
+ return namesOfType(declaration.typeAnnotation, declarations, seen);
1507
+ }
1508
+ const names = memberNames(declaration.body.body);
1509
+ for (const parent of declaration.extends ?? []) {
1510
+ if (parent.expression.type === "Identifier") {
1511
+ mergeInto(names, namesOfReference(parent.expression.name, declarations, seen));
1512
+ }
1513
+ }
1514
+ return names;
1515
+ }
1516
+ function collectDeclarations(program) {
1517
+ const declarations = /* @__PURE__ */ new Map();
1518
+ for (const statement of program.body) {
1519
+ const node = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
1520
+ if (node?.type === "TSInterfaceDeclaration" || node?.type === "TSTypeAliasDeclaration") {
1521
+ declarations.set(node.id.name, node);
1522
+ }
1523
+ }
1524
+ return declarations;
1525
+ }
1526
+ function wrappedFunction(init) {
1527
+ if (!init) return void 0;
1528
+ if (FUNCTION_TYPES.has(init.type)) return init;
1529
+ if (init.type !== "CallExpression") return void 0;
1530
+ const callee = init.callee.type === "MemberExpression" ? init.callee.property : init.callee;
1531
+ return COMPONENT_WRAPPERS.has(callee.name) ? wrappedFunction(init.arguments[0]) : void 0;
1532
+ }
1533
+ function propsAnnotation(fn) {
1534
+ return fn?.params[0]?.typeAnnotation?.typeAnnotation;
1535
+ }
1536
+ var rule5 = {
1537
+ meta: {
1538
+ type: "problem",
1539
+ docs: {
1540
+ description: "UI-COMPOSE-1: a component declares at most the capped number of props; split it or compose with slots. Frozen names may only shrink."
1541
+ },
1542
+ schema: [
1543
+ {
1544
+ type: "object",
1545
+ properties: {
1546
+ max: { type: "integer", minimum: 0 },
1547
+ frozen: { type: "object", additionalProperties: { type: "integer", minimum: 0 } }
1548
+ },
1549
+ additionalProperties: false
1550
+ }
1551
+ ],
1552
+ messages: {
1553
+ tooMany: "{{name}} declares {{count}} props; the cap is {{max}}. Split it or compose with slots (UI-COMPOSE-1).",
1554
+ frozenGrew: "{{name}} is frozen at {{max}} props and now declares {{count}}. A frozen component may only shrink (UI-COMPOSE-1)."
1555
+ }
1556
+ },
1557
+ create(context) {
1558
+ const options = context.options[0] ?? {};
1559
+ const max = options.max ?? DEFAULT_MAX2;
1560
+ const frozen = options.frozen ?? {};
1561
+ let declarations = /* @__PURE__ */ new Map();
1562
+ const reported = /* @__PURE__ */ new Set();
1563
+ function check(node, name, names) {
1564
+ if (reported.has(name)) return;
1565
+ reported.add(name);
1566
+ const allowed = frozen[name] ?? max;
1567
+ if (names.size <= allowed) return;
1568
+ const messageId = frozen[name] === void 0 ? "tooMany" : "frozenGrew";
1569
+ context.report({ node, messageId, data: { name, count: names.size, max: allowed } });
1570
+ }
1571
+ function checkDeclaration(declaration) {
1572
+ const name = declaration.id.name;
1573
+ check(declaration, name, namesOfDeclaration(declaration, declarations, /* @__PURE__ */ new Set([name])));
1574
+ }
1575
+ function checkComponent(id, fn) {
1576
+ if (!id || !COMPONENT_NAME.test(id.name)) return;
1577
+ const annotation = propsAnnotation(fn);
1578
+ if (annotation?.type === "TSTypeLiteral") {
1579
+ check(annotation, id.name, memberNames(annotation.members));
1580
+ return;
1581
+ }
1582
+ if (annotation?.type !== "TSTypeReference" || annotation.typeName.type !== "Identifier") return;
1583
+ const declaration = declarations.get(annotation.typeName.name);
1584
+ if (declaration) checkDeclaration(declaration);
1585
+ }
1586
+ return {
1587
+ Program(program) {
1588
+ declarations = collectDeclarations(program);
1589
+ for (const [name, declaration] of declarations) {
1590
+ if (PROPS_NAME.test(name)) checkDeclaration(declaration);
1591
+ }
1592
+ },
1593
+ FunctionDeclaration(node) {
1594
+ checkComponent(node.id, node);
1595
+ },
1596
+ VariableDeclarator(node) {
1597
+ if (node.id.type === "Identifier") checkComponent(node.id, wrappedFunction(node.init));
1598
+ }
1599
+ };
1600
+ }
1601
+ };
1602
+ var max_component_props_default = { rules: { "max-component-props": rule5 } };
1458
1603
  function isPureReExportFile(programNode) {
1459
1604
  const { body } = programNode;
1460
1605
  if (body.length === 0) return false;
@@ -2469,7 +2614,7 @@ function isQueryKeyProperty(node) {
2469
2614
  if (node.key.type === "Identifier") return node.key.name === QUERY_KEY;
2470
2615
  return node.key.type === "Literal" && node.key.value === QUERY_KEY;
2471
2616
  }
2472
- var rule5 = {
2617
+ var rule6 = {
2473
2618
  meta: {
2474
2619
  type: "suggestion",
2475
2620
  docs: {
@@ -2500,7 +2645,7 @@ var rule5 = {
2500
2645
  };
2501
2646
  }
2502
2647
  };
2503
- var query_key_factory_default = { rules: { "query-key-factory": rule5 } };
2648
+ var query_key_factory_default = { rules: { "query-key-factory": rule6 } };
2504
2649
 
2505
2650
  // src/rules/require-stable-hook-args.js
2506
2651
  var STABLE_INIT_CALLS = /* @__PURE__ */ new Set([
@@ -3175,6 +3320,7 @@ var ruleModules = [
3175
3320
  game_menu_focusable_default,
3176
3321
  i18n_interpolation_default,
3177
3322
  i18n_param_names_default,
3323
+ max_component_props_default,
3178
3324
  no_barrel_companion_file_default,
3179
3325
  no_comments_default,
3180
3326
  no_duplicate_nav_prefix_default,
@@ -3195,11 +3341,11 @@ var ruleModules = [
3195
3341
  function mergeRules(modules) {
3196
3342
  const merged = {};
3197
3343
  for (const mod of modules) {
3198
- for (const [name, rule6] of Object.entries(mod.rules)) {
3344
+ for (const [name, rule7] of Object.entries(mod.rules)) {
3199
3345
  if (merged[name] !== void 0) {
3200
3346
  throw new Error(`Duplicate ESLint rule name: "${name}"`);
3201
3347
  }
3202
- merged[name] = rule6;
3348
+ merged[name] = rule7;
3203
3349
  }
3204
3350
  }
3205
3351
  return merged;
@@ -3215,15 +3361,15 @@ var ruleNames = Object.keys(plugin.rules).sort();
3215
3361
  var legacyPlugins = buildLegacyPlugins();
3216
3362
  function buildLegacyPlugins() {
3217
3363
  const out = {};
3218
- for (const [name, rule6] of Object.entries(rules)) {
3219
- out[name] = oneRulePlugin(name, rule6);
3364
+ for (const [name, rule7] of Object.entries(rules)) {
3365
+ out[name] = oneRulePlugin(name, rule7);
3220
3366
  }
3221
3367
  return out;
3222
3368
  }
3223
- function oneRulePlugin(name, rule6) {
3369
+ function oneRulePlugin(name, rule7) {
3224
3370
  return {
3225
3371
  meta: { name, version: "1.0.0" },
3226
- rules: { [name]: rule6 }
3372
+ rules: { [name]: rule7 }
3227
3373
  };
3228
3374
  }
3229
3375
  var OFF_LEVELS = ["off", 0];
@@ -3322,9 +3468,17 @@ var focusConfig = {
3322
3468
  "@dloizides/explicit-initial-focus": "error"
3323
3469
  }
3324
3470
  };
3471
+ var COMPOSE_RULE_NAMES = ["max-component-props"];
3472
+ var composeConfig = {
3473
+ plugins: commentsConfig.plugins,
3474
+ rules: {
3475
+ "@dloizides/max-component-props": "error"
3476
+ }
3477
+ };
3325
3478
 
3326
3479
  exports.API_RULE_NAMES = API_RULE_NAMES;
3327
3480
  exports.COMMENT_RULE_NAMES = COMMENT_RULE_NAMES;
3481
+ exports.COMPOSE_RULE_NAMES = COMPOSE_RULE_NAMES;
3328
3482
  exports.FOCUS_RULE_NAMES = FOCUS_RULE_NAMES;
3329
3483
  exports.GAME_RULE_NAMES = GAME_RULE_NAMES;
3330
3484
  exports.HOUSE_PATTERN_RULE_NAMES = HOUSE_PATTERN_RULE_NAMES;
@@ -3332,6 +3486,7 @@ exports.REUSE_RULE_NAMES = REUSE_RULE_NAMES;
3332
3486
  exports.ROW_ACTION_RULE_NAMES = ROW_ACTION_RULE_NAMES;
3333
3487
  exports.apiConfig = apiConfig;
3334
3488
  exports.commentsConfig = commentsConfig;
3489
+ exports.composeConfig = composeConfig;
3335
3490
  exports.focusConfig = focusConfig;
3336
3491
  exports.gameConfig = gameConfig;
3337
3492
  exports.legacyPlugins = legacyPlugins;