@starci/eslint-canon-fe 8.4.43 → 9.0.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.
Files changed (53) hide show
  1. package/CHANGELOG.md +14 -1
  2. package/README.md +36 -84
  3. package/brand-values.mjs +1 -1
  4. package/docs/hooks-folder.md +5 -3
  5. package/docs/native-controls.md +1 -5
  6. package/docs/next-conventions.md +8 -8
  7. package/docs/size-and-state-budget.md +22 -0
  8. package/docs/surface-rules.md +11 -9
  9. package/drawing.mjs +4 -66
  10. package/hooks-folder.mjs +5 -3
  11. package/index.mjs +7 -25
  12. package/landmark.mjs +0 -3
  13. package/lib/class-text.mjs +29 -0
  14. package/lib/config.mjs +4 -6
  15. package/lib/drawing-scope.mjs +15 -0
  16. package/lib/typed-class-values.mjs +10 -1
  17. package/lib/why.mjs +10 -40
  18. package/next-conventions.mjs +33 -16
  19. package/package.json +4 -3
  20. package/runtime/knowledge/grammars/index.yaml +102 -0
  21. package/runtime/knowledge/hfs/canon-pins.yaml +22 -8
  22. package/runtime/knowledge/hfs/fe-stack.yaml +7 -0
  23. package/runtime/knowledge/hfs/slots.yaml +3 -3
  24. package/runtime/modules/kernel/removed-vocabulary.yaml +29 -0
  25. package/runtime/scripts/hfs/architecture/config.mjs +8 -8
  26. package/runtime/scripts/hfs/declaration-shape.mjs +8 -2
  27. package/runtime/scripts/hfs/rule-catalog.mjs +2 -2
  28. package/runtime/scripts/hfs/slots.mjs +1 -0
  29. package/runtime/scripts/hfs/view.mjs +1 -0
  30. package/runtime/scripts/lib/grammar-lint.mjs +48 -0
  31. package/size-and-state-budget.mjs +116 -4
  32. package/surface-rules.mjs +159 -26
  33. package/tokens.mjs +5 -217
  34. package/app-shell.mjs +0 -161
  35. package/docs/app-shell.md +0 -50
  36. package/docs/grammar-boundary.md +0 -57
  37. package/docs/status-colors.md +0 -32
  38. package/grammar-boundary.mjs +0 -203
  39. package/icon.mjs +0 -310
  40. package/lib/app-shell-cluster.mjs +0 -66
  41. package/lib/app-shell-create.mjs +0 -33
  42. package/lib/app-shell-owner-source.mjs +0 -124
  43. package/lib/app-shell-owner.mjs +0 -65
  44. package/lib/app-shell-scope.mjs +0 -79
  45. package/lib/app-shell-visible.mjs +0 -92
  46. package/lib/app-shell.mjs +0 -148
  47. package/lib/status-tones.generated.mjs +0 -9
  48. package/menu-entries.mjs +0 -133
  49. package/runtime/modules/goal/source-phrases.yaml +0 -95
  50. package/runtime/scripts/lib/source-phrases.mjs +0 -34
  51. package/status-colors.mjs +0 -137
  52. package/typography.mjs +0 -78
  53. package/vendor-boundary.mjs +0 -26
@@ -5,6 +5,7 @@ import { readJsonFile as readJson } from '../../lib/json.mjs';
5
5
  import { isInside } from '../../lib/walk.mjs';
6
6
  import { openHfs } from '../slots.mjs';
7
7
  import { byCodeUnit } from '../../lib/list.mjs';
8
+ import { grammarContractFor } from '../../lib/grammar-lint.mjs';
8
9
 
9
10
 
10
11
  /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -270,19 +271,18 @@ function derivedOwners(root, resolver) {
270
271
 
271
272
  const DECLARED_HANDLER_DECORATORS = ['CommandHandler', 'QueryHandler'];
272
273
 
273
- const GRAMMAR_PACKAGE = '@starci/grammar';
274
-
275
274
  /**
276
- * The Grammar contract of a frontend repository, derived rather than declared: every app's globals.css is a style
277
- * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
275
+ * The selected family's component contract with derived consumers: every app's globals.css is a style
276
+ * source, every app and every workspace package that depends on its package is a consumer. null when no app has
278
277
  * a globals.css to judge (the contract is then reported unavailable, never passed).
279
278
  */
280
- function derivedGrammar(root, packageRoot, workspaces, apps = []) {
279
+ function derivedGrammar(root, packageRoot, workspaces, apps, family) {
281
280
  const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
282
281
  if (!styleSources.length) return null;
282
+ const contract = grammarContractFor(family);
283
283
  // Every fe app and package is an npm workspace that declares what it imports (HFS_MONO_WORKSPACE_DEP): each workspace that
284
284
  // declares the Grammar package is a consumer, and so is the app root's manifest when it does.
285
- const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
285
+ const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, contract.package)));
286
286
  const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
287
287
  const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
288
288
  for (const workspace of workspaces) {
@@ -292,7 +292,7 @@ function derivedGrammar(root, packageRoot, workspaces, apps = []) {
292
292
  if (declaresGrammar(pkg)) consumerManifests.push(manifest);
293
293
  }
294
294
  if (!consumerManifests.length) return null;
295
- return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react', '@xyflow/react'] };
295
+ return { ...contract, styleSources, consumerManifests };
296
296
  }
297
297
 
298
298
  /**
@@ -328,7 +328,7 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
328
328
  hooks: inferred.hooks,
329
329
  modules: inferred.modules,
330
330
  transport: inferred.transport,
331
- grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
331
+ grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps, opened.repo.grammar) : null,
332
332
  };
333
333
  if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
334
334
  return {
@@ -73,11 +73,17 @@ function extraPackageProblems(side, entries) {
73
73
  return [];
74
74
  }
75
75
 
76
+ function grammarProblems(side, grammar) {
77
+ if (grammar === undefined) return [];
78
+ if (side !== 'fe') return ['grammar belongs to the fe side'];
79
+ return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
80
+ }
81
+
76
82
  function declarationSideProblems(side, value, names) {
77
83
  const bad = [];
78
84
  const at = `sides.${side}`;
79
85
  if (!isPlainObject(value)) return [`${at} must be an object`];
80
- for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
86
+ for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
81
87
  bad.push(...appShapeProblems(value.apps, at, side, names));
82
88
  if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
83
89
  if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
@@ -85,7 +91,7 @@ function declarationSideProblems(side, value, names) {
85
91
  bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
86
92
  if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
87
93
  if (value.connections !== undefined) bad.push(...connectionProblems(side, value));
88
- bad.push(...extraPackageProblems(side, value.extraPackages));
94
+ bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar));
89
95
  return bad;
90
96
  }
91
97
 
@@ -12,7 +12,7 @@ import { fail } from './slot-errors.mjs';
12
12
 
13
13
  const HFS_RULES_FILE = 'knowledge/hfs/rules.yaml';
14
14
  const RULE_GATES = Object.freeze(['pre-commit', 'pre-push', 'settle', 'land', 'ci', 'sonar', 'runtime']);
15
- const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
15
+ const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'eslint-grammar-starci', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
16
16
  const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
17
17
  const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
18
18
  const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -346,7 +346,7 @@ export function loadRuleCatalog({ root = skillRoot, file = path.join(root, HFS_R
346
346
  /** The catalogued why code of a lint finding's rule id (`starci-be/<id>`, `starci-fe/<id>`), or undefined. */
347
347
  lintCode: (ruleId) => {
348
348
  const [plugin, id] = String(ruleId ?? '').split('/');
349
- const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || null;
349
+ const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || (plugin === 'starci-grammar' && 'eslint-grammar-starci') || null;
350
350
  return kind ? list.find((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id))?.code : undefined;
351
351
  },
352
352
  /** The rules one enforcer judges, e.g. forEnforcer('eslint-be', 'error-home'). */
@@ -120,6 +120,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
120
120
  connections: Object.freeze((s.connections ?? []).map(connectionView)),
121
121
  providers,
122
122
  reads: Object.freeze([...(s.reads ?? [])]),
123
+ ...(s.grammar === undefined ? {} : { grammar: s.grammar }),
123
124
  ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map(entry => Object.freeze({ ...entry }))) }),
124
125
  manifestVersion: manifest.version,
125
126
  });
@@ -33,6 +33,7 @@ function hfsView(opened, repoRoot) {
33
33
  profile: opened.repo.profile,
34
34
  side: opened.repo.side ?? null,
35
35
  edition: opened.repo.edition ?? 'full',
36
+ ...(opened.repo.grammar === undefined ? {} : { grammar: opened.repo.grammar }),
36
37
  apps: opened.repo.apps,
37
38
  connections: opened.repo.connections,
38
39
  patterns: Object.freeze([...(opened.repo.patterns ?? [])]),
@@ -0,0 +1,48 @@
1
+ // Grammar-family lint selection reads the family catalog; an absent selection never chooses a family.
2
+ import fs from 'node:fs';
3
+ import { parseYamlCached } from './yaml-cached.mjs';
4
+
5
+ const CATALOG_FILE = new URL('../../knowledge/grammars/index.yaml', import.meta.url);
6
+
7
+ function selectedFamily(family) {
8
+ if (typeof family !== 'string' || !family.trim()) throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
9
+ const catalog = parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
10
+ const matches = (catalog.families ?? []).filter(entry => entry.id === family);
11
+ if (matches.length !== 1) throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
12
+ return { catalog, selected: matches[0] };
13
+ }
14
+
15
+ /** The explicitly selected authored family entry; callers share the catalog lookup rather than inferring a family. */
16
+ export function grammarFamilyFor(family) {
17
+ return Object.freeze(selectedFamily(family).selected);
18
+ }
19
+
20
+ /** The declared family's lint contract, including an explicit null package when that family has no rules. */
21
+ export function grammarLintFor(family) {
22
+ const { selected } = selectedFamily(family);
23
+ if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
24
+ throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
25
+ }
26
+ const lint = selected.lint;
27
+ if (lint.package === null) return Object.freeze({ family, package: null });
28
+ if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
29
+ || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
30
+ || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
31
+ throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
32
+ }
33
+ return Object.freeze({ family, package: lint.package, factory: lint.factory, prefix: lint.prefix });
34
+ }
35
+
36
+ /** The selected family's shared component/export contract, resolved through its catalog reference. */
37
+ export function grammarContractFor(family) {
38
+ const { catalog, selected } = selectedFamily(family);
39
+ const owners = (catalog.families ?? []).filter(entry => entry.id === selected.contractRef);
40
+ const contract = owners.length === 1 ? owners[0].componentContract : null;
41
+ if (!contract || typeof contract.package !== 'string' || !contract.package
42
+ || typeof contract.entry !== 'string' || !contract.entry.startsWith(`${contract.package}/`)
43
+ || typeof contract.styleEntry !== 'string' || !contract.styleEntry.startsWith(`${contract.package}/`)
44
+ || !Array.isArray(contract.peers) || !contract.peers.every(peer => typeof peer === 'string' && peer.trim())) {
45
+ throw new Error(`Grammar family ${family} has no valid component contract in knowledge/grammars/index.yaml`);
46
+ }
47
+ return Object.freeze({ ...contract, peers: Object.freeze([...contract.peers]) });
48
+ }
@@ -16,12 +16,16 @@
16
16
  * beside the data hook's own, and two mechanisms per resource means double requests and a spinner
17
17
  * that never settles. Each resource refreshes by exactly one mechanism (a SWR `refreshInterval`, or a
18
18
  * socket), so the loop in a component is always the wrong one.
19
+ *
20
+ * LIVE TIME. A recurring timer that reads the wall clock to refresh a time label is a second clock beside Grammar's shared
21
+ * ticker; product code passes the target instant to `RelativeTime` instead.
19
22
  */
20
23
 
21
- import { functionOf, isFn } from "./lib/bindings.mjs"
24
+ import { walk } from "./lib/ast.mjs"
25
+ import { functionOf, isFn, unwrap, variableOf } from "./lib/bindings.mjs"
22
26
  import { hfsOf } from "./lib/hfs.mjs"
23
27
  import { isPromiseValued } from "./lib/types.mjs"
24
- import { baseName, fileOf, roleOfFile, slotOfFile } from "./lib/scope.mjs"
28
+ import { baseName, fileOf, isProductSource, roleOfFile, slotOfFile } from "./lib/scope.mjs"
25
29
 
26
30
  /**
27
31
  * The budget the slot of the linted file states (`budget` in knowledge/hfs/slots.yaml), or an empty one when no slot owns the file
@@ -206,8 +210,7 @@ const readsData = (context, fn, seen = new Set()) => {
206
210
  *
207
211
  * A timer is polling when what it runs READS DATA (see `readsData`, decided by the type of each call, not by a name): a
208
212
  * `setInterval`, or a `setTimeout` whose callback schedules the enclosing function again. A timer that only ticks time or state
209
- * is not a data-refresh mechanism. Grammar's live-time ownership is independently enforced by `no-app-relative-clock` in
210
- * `grammar-boundary.mjs`.
213
+ * is not a data-refresh mechanism. Grammar's live-time ownership is independently enforced by `no-app-relative-clock` below.
211
214
  */
212
215
  export const noHandRolledPolling = {
213
216
  meta: {
@@ -253,11 +256,120 @@ export const noHandRolledPolling = {
253
256
  },
254
257
  }
255
258
 
259
+ /** The static property name of an access or destructured property. */
260
+ const propertyName = (node) => {
261
+ const key = node.property ?? node.key
262
+ if (!node.computed && key?.type === "Identifier") return key.name
263
+ return key?.type === "Literal" && typeof key.value === "string" ? key.value : null
264
+ }
265
+
266
+ /** The platform member a local destructured binding selects. */
267
+ const destructuredPath = (context, declarator, local, seen) => {
268
+ if (declarator.id.type !== "ObjectPattern") return null
269
+ const property = declarator.id.properties.find((entry) => entry.type === "Property" && entry.value.type === "Identifier" && entry.value.name === local)
270
+ const name = property && propertyName(property)
271
+ const object = platformPath(context, declarator.init, seen)
272
+ return object && name ? [...object, name] : null
273
+ }
274
+
275
+ /** A platform path, following local aliases and destructuring while refusing shadowed globals. */
276
+ const platformPath = (context, node, seen = new Set()) => {
277
+ const inner = unwrap(node)
278
+ if (!inner || seen.has(inner)) return null
279
+ seen.add(inner)
280
+ if (inner.type === "MemberExpression") {
281
+ const object = platformPath(context, inner.object, seen)
282
+ const name = propertyName(inner)
283
+ return object && name ? [...object, name] : null
284
+ }
285
+ if (inner.type !== "Identifier") return null
286
+ const variable = variableOf(context, inner)
287
+ if (!variable || variable.defs.length === 0) return [inner.name]
288
+ for (const definition of variable.defs) {
289
+ if (definition.type !== "Variable" || !definition.node.init) continue
290
+ const declarator = definition.node
291
+ if (declarator.id.type === "Identifier") return platformPath(context, declarator.init, seen)
292
+ return destructuredPath(context, declarator, inner.name, seen)
293
+ }
294
+ return null
295
+ }
296
+
297
+ /** A platform API spelling with the optional global-object prefix removed. */
298
+ const platformName = (context, node) => {
299
+ const parts = platformPath(context, node)
300
+ if (!parts) return null
301
+ if (["window", "globalThis", "self"].includes(parts[0])) parts.shift()
302
+ return parts.join(".")
303
+ }
304
+
305
+ /** A wall-clock read: Date.now(), Date(), zero-argument new Date(), or performance.now(). */
306
+ const readsClock = (context, root, seen = new Set()) => {
307
+ if (!root || seen.has(root)) return false
308
+ seen.add(root)
309
+ let found = false
310
+ walk(context.sourceCode, root, (node) => {
311
+ if (found) return false
312
+ if (node.type === "NewExpression" && node.arguments.length === 0 && platformName(context, node.callee) === "Date") found = true
313
+ if (node.type !== "CallExpression") return undefined
314
+ if (["Date", "Date.now", "performance.now"].includes(platformName(context, node.callee))) found = true
315
+ const helper = functionOf(context, node.callee)
316
+ if (helper && readsClock(context, helper.body, seen)) found = true
317
+ return undefined
318
+ })
319
+ return found
320
+ }
321
+
322
+ /** Whether a timer callback runs its enclosing function again, directly or through a same-file helper. */
323
+ const callsFunction = (context, root, target, seen = new Set()) => {
324
+ if (!root || seen.has(root)) return false
325
+ if (root === target) return true
326
+ seen.add(root)
327
+ let found = false
328
+ walk(context.sourceCode, root.body ?? root, (node) => {
329
+ if (found) return false
330
+ if (node.type !== "CallExpression") return undefined
331
+ const called = functionOf(context, node.callee)
332
+ if (called === target || called && callsFunction(context, called, target, seen)) found = true
333
+ return undefined
334
+ })
335
+ return found
336
+ }
337
+
338
+ /** Grammar owns the shared clock for live time labels; product components and hooks only pass instants. */
339
+ export const noAppRelativeClock = {
340
+ meta: {
341
+ type: "problem",
342
+ docs: { description: "Live relative time and countdowns use Grammar's shared clock rather than a product-owned ticker." },
343
+ schema: [],
344
+ messages: {
345
+ clock: "This recurring timer reads the clock. Render RelativeTime with dateTime, locale and mode; digital countdowns support format=\"digital\", expiredLabel and a serializable template containing {time}. Grammar owns its single shared ticker and server-safe first render. Product components and hooks pass the target instant and never start another clock for time labels.",
346
+ },
347
+ },
348
+ create(context) {
349
+ if (!isProductSource(context)) return {}
350
+ return {
351
+ CallExpression(node) {
352
+ const timer = platformName(context, node.callee)
353
+ if (timer !== "setInterval" && timer !== "setTimeout") return
354
+ const callback = functionOf(context, node.arguments[0])
355
+ if (!callback) return
356
+ let owner = node.parent
357
+ while (owner && !isFn(owner)) owner = owner.parent
358
+ const repeats = timer === "setInterval" || owner && callsFunction(context, callback, owner)
359
+ if (repeats && (readsClock(context, callback.body) || timer === "setTimeout" && readsClock(context, owner.body))) {
360
+ context.report({ node, messageId: "clock" })
361
+ }
362
+ },
363
+ }
364
+ },
365
+ }
366
+
256
367
  /** The rules this law contributes to the plugin. */
257
368
  export const rules = {
258
369
  "component-line-budget": componentLineBudget,
259
370
  "unit-hook-budget": unitHookBudget,
260
371
  "no-hand-rolled-polling": noHandRolledPolling,
372
+ "no-app-relative-clock": noAppRelativeClock,
261
373
  }
262
374
 
263
375
  /** Every rule is an error: the budget is the same for every app, and there is no baseline. */
package/surface-rules.mjs CHANGED
@@ -6,8 +6,9 @@ import { reactHookOf } from "./lib/react.mjs"
6
6
 
7
7
  const GRAMMAR_ENTRY = /^@starci\/grammar(?:\/(?:common|core|heritage|offset-pop))?$/
8
8
  const SURFACES = new Set([
9
- "SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard", "Rail", "Sidebar",
9
+ "SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard", "Sidebar",
10
10
  "Dialog", "Drawer", "AlertDialog", "Popover",
11
+ "WorkspaceShell", "TopBar", "NavigationFeatureNav",
11
12
  ])
12
13
  const FIELDS = new Set([
13
14
  "Input", "TextField", "Textarea", "TextArea", "SearchField", "NumberField", "DateField", "TimeField",
@@ -83,16 +84,49 @@ function* surfaceAncestors(context, node) {
83
84
  const isSurface = (context, node, descendant) => {
84
85
  const name = grammarName(context, node.name)
85
86
  if (name?.length !== 1) return false
86
- if (SURFACES.has(name[0])) return true
87
- if (name[0] !== "ChatWorkspace") return false
88
- for (let current = descendant; current && current !== node.parent; current = current.parent) {
89
- if (current.type === "JSXAttribute" && current.parent === node && current.name.name === "rail") return true
87
+ if (name[0] === "SurfaceAccordionCard") {
88
+ let frame = "painted"
89
+ for (const entry of node.attributes) {
90
+ const value = entry.type === "JSXSpreadAttribute" ? frameEffect(context, entry.argument, frame)
91
+ : entry.name.name === "frame" ? unpaintedFrame(context, attributeValue(entry)) ? "unpainted" : "painted" : "absent"
92
+ if (value !== "absent") frame = value
93
+ }
94
+ return frame !== "unpainted"
90
95
  }
91
- return false
96
+ if (name[0] === "WorkspaceShell") {
97
+ for (let current = descendant; current && current !== node.parent; current = current.parent) {
98
+ if (current.type === "JSXAttribute" && current.parent === node && current.name.name === "header") return true
99
+ }
100
+ return false
101
+ }
102
+ return SURFACES.has(name[0])
103
+ }
104
+ const classTokens = (text) => text.split(/\s+/).map((token) => {
105
+ let depth = 0
106
+ let start = 0
107
+ for (let index = 0; index < token.length; index++) {
108
+ if (token[index] === "[") depth++
109
+ else if (token[index] === "]") depth--
110
+ else if (token[index] === ":" && depth === 0) start = index + 1
111
+ }
112
+ return token.slice(start).replace(/^!|!$/g, "")
113
+ })
114
+ /** Paint and typography belong to Grammar even when the app uses a token rather than a raw colour. */
115
+ const paintProperty = (name) => {
116
+ const property = String(name).replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`).replace(/^-(?:webkit|moz|ms)-/, "")
117
+ if (/^text-(?:align|overflow|wrap)(?:-|$)/.test(property)) return false
118
+ return /^(?:background|border|outline|font|text|fill|stroke|mask|color|accent-color|caret-color)(?:-|$)/.test(property)
119
+ || /^(?:opacity|box-shadow|filter|backdrop-filter|mix-blend-mode|appearance|letter-spacing|line-height|clip-path)$/.test(property)
120
+ }
121
+
122
+ const rawSurface = (token) => {
123
+ const arbitrary = /^\[([^:]+):/.exec(token)
124
+ if (arbitrary) return paintProperty(arbitrary[1])
125
+ if (/^text-(?:left|right|center|justify|start|end|wrap|nowrap|balance|pretty|ellipsis|clip)$/.test(token)) return false
126
+ return /^-?(?:bg|from|via|to|shadow|inset-shadow|text-shadow|ring|inset-ring|outline|border|divide|rounded|text|font|leading|tracking|fill|stroke|mask|accent|caret|decoration|opacity|mix-blend|bg-blend|blur|brightness|contrast|drop-shadow|grayscale|hue-rotate|invert|saturate|sepia|backdrop|filter|appearance)(?:-|$)/.test(token)
127
+ || /^(?:underline|overline|line-through|no-underline|italic|not-italic|antialiased|subpixel-antialiased)$/.test(token)
92
128
  }
93
- const classTokens = (text) => text.split(/\s+/).map((token) => token.split(":").at(-1).replace(/^!|!$/g, ""))
94
- const rawSurface = (token) => /^bg-surface(?:-[a-z0-9-]+)?(?:\/[^\s]+)?$/.test(token)
95
- const horizontalPadding = (token) => /^(?:px|ps|pe)-.+$/.test(token)
129
+ const horizontalPadding = (token) => /^(?:p|px|ps|pe|pl|pr)-.+$/.test(token) || /^\[padding-inline(?:-start|-end)?:.+\]$/.test(token)
96
130
 
97
131
  /** Computed keys select their evaluated static name, rather than the identifier's spelling. */
98
132
  const propertyName = (context, property) => {
@@ -138,9 +172,70 @@ const propStrings = (context, entry, name, mode = "classes") => {
138
172
  return entry.name.name === name ? authoredStrings(context, attributeValue(entry), new Set(), mode) : []
139
173
  }
140
174
 
175
+ /** Only a fully known unpainted frame removes the accordion's bounded surface context. */
176
+ const unpaintedFrame = (context, input, seen = new Set()) => {
177
+ const node = unwrap(input)
178
+ if (!node || seen.has(node)) return false
179
+ seen.add(node)
180
+ const text = stringOf(node)
181
+ if (text !== null) return text === "unpainted"
182
+ if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].every((branch) => unpaintedFrame(context, branch, new Set(seen)))
183
+ const values = node.type === "Identifier" ? bindingValues(context, node)
184
+ : node.type === "MemberExpression" ? propertyValues(context, node.object, node.computed ? stringOf(node.property) : node.property.name) : []
185
+ return values.length > 0 && values.every((value) => unpaintedFrame(context, value, new Set(seen)))
186
+ }
187
+
188
+ /** A spread overrides preceding frame props; an unresolved spread may install a bounded frame. */
189
+ const frameEffect = (context, input, prior, seen = new Set()) => {
190
+ const node = unwrap(input)
191
+ if (!node || seen.has(node)) return "painted"
192
+ seen.add(node)
193
+ if (node.type === "ObjectExpression") {
194
+ let effect = prior
195
+ for (const property of node.properties) {
196
+ const key = property.type === "Property" ? propertyName(context, property) : null
197
+ const value = property.type === "SpreadElement" ? frameEffect(context, property.argument, effect, new Set(seen))
198
+ : key === "frame" ? unpaintedFrame(context, property.value) ? "unpainted" : "painted" : key === null ? "painted" : "absent"
199
+ if (value !== "absent") effect = value
200
+ }
201
+ return effect
202
+ }
203
+ const values = node.type === "Identifier" ? bindingValues(context, node)
204
+ : node.type === "MemberExpression" ? propertyValues(context, node.object, node.computed ? stringOf(node.property) : node.property.name)
205
+ : node.type === "ConditionalExpression" ? [node.consequent, node.alternate] : []
206
+ const effects = values.map((value) => frameEffect(context, value, prior, new Set(seen)))
207
+ return effects.length > 0 && effects.every((effect) => effect === effects[0]) ? effects[0] : "painted"
208
+ }
209
+
210
+ /** Resolve authored style objects without treating unrelated object siblings or conditions as CSS. */
211
+ const stylePaint = (context, input, seen = new Set()) => {
212
+ const node = unwrap(input?.type === "JSXExpressionContainer" ? input.expression : input)
213
+ if (!node || seen.has(node)) return []
214
+ seen.add(node)
215
+ if (node.type === "Identifier") {
216
+ const values = bindingValues(context, node)
217
+ return values.length ? values.flatMap((value) => stylePaint(context, value, seen))
218
+ : typedClassStrings(context, node, "style-keys").filter((entry) => paintProperty(entry.text)).map((entry) => entry.node)
219
+ }
220
+ if (node.type === "MemberExpression") {
221
+ const member = node.computed ? stringOf(node.property) : node.property.name
222
+ const values = propertyValues(context, node.object, member)
223
+ return values.length ? values.flatMap((value) => stylePaint(context, value, seen))
224
+ : typedClassStrings(context, node, "style-keys").filter((entry) => paintProperty(entry.text)).map((entry) => entry.node)
225
+ }
226
+ if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].flatMap((branch) => stylePaint(context, branch, seen))
227
+ if (node.type === "LogicalExpression") return (node.operator === "&&" ? [node.right] : [node.left, node.right]).flatMap((branch) => stylePaint(context, branch, seen))
228
+ if (node.type !== "ObjectExpression") return []
229
+ return node.properties.flatMap((property) => {
230
+ if (property.type === "SpreadElement") return stylePaint(context, property.argument, seen)
231
+ return paintProperty(propertyName(context, property)) ? [property] : []
232
+ })
233
+ }
234
+
141
235
  /** An explicit section caption excludes the row's own content subtree. */
142
236
  const inSectionCaption = (context, node) => {
143
237
  for (const ancestor of surfaceAncestors(context, node.parent)) {
238
+ if (isSurface(context, ancestor, node)) return false
144
239
  const owner = grammarName(context, ancestor.name)
145
240
  if (owner?.[0] !== "ListBox") continue
146
241
  if (owner[1] === "Item") return false
@@ -149,35 +244,72 @@ const inSectionCaption = (context, node) => {
149
244
  return false
150
245
  }
151
246
 
152
- /** ANATOMY-2: Grammar provides the secondary default; apps cannot force primary or paint a raw surface. */
247
+ /** ANATOMY-2: field variants belong to Grammar's context, including across app component boundaries. */
153
248
  export const nestedControlVariant = {
154
249
  meta: {
155
250
  type: "problem",
156
- docs: { description: "ANATOMY-2: nested fields use Grammar's secondary default and surfaces belong to Grammar." },
251
+ docs: { description: "ANATOMY-2: Grammar context supplies field variants; nested Tabs cannot force primary." },
157
252
  schema: [],
158
253
  messages: {
159
- primary: "FE_NESTED_VARIANT: a field inside a Grammar surface cannot force variant=\"primary\". Omit variant so Grammar supplies secondary through its nesting context.",
160
- surface: "FE_NESTED_VARIANT: bg-surface paints a surface in app CSS. Compose SurfaceCard, Rail, Sidebar or another Grammar surface instead.",
254
+ variant: "FE_NESTED_VARIANT: app fields cannot set a static variant. Omit variant so Grammar's surface context supplies the appropriate default.",
255
+ tabs: "FE_NESTED_VARIANT: Tabs inside a Grammar surface cannot force variant=\"primary\". Omit variant so Grammar supplies secondary.",
161
256
  },
162
257
  },
258
+ create(context) {
259
+ return {
260
+ JSXOpeningElement(node) {
261
+ const name = grammarName(context, node.name)
262
+ if (name?.length !== 1) return
263
+ if (FIELDS.has(name[0])) {
264
+ const variant = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").length > 0)
265
+ if (variant) context.report({ node: variant, messageId: "variant" })
266
+ } else if (name[0] === "Tabs") {
267
+ const primary = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "primary"))
268
+ if (primary && [...surfaceAncestors(context, node.parent)].some((ancestor) => isSurface(context, ancestor, node))) context.report({ node: primary, messageId: "tabs" })
269
+ }
270
+ },
271
+ }
272
+ },
273
+ }
274
+
275
+ /** App classes carry layout; Grammar owns surface paint. */
276
+ export const noAppSurfacePaint = {
277
+ meta: {
278
+ type: "problem",
279
+ docs: { description: "App composition CSS is layout-only; Grammar paints surfaces." },
280
+ schema: [],
281
+ messages: { surface: "FE_GRAMMAR_LAYOUT_ONLY: app CSS paints or styles Grammar content. Keep composition CSS layout-only and use Grammar's published surfaces, typography and tone props." },
282
+ },
163
283
  create(context) {
164
284
  const reported = new Set()
165
- const checkClasses = (value) => {
166
- for (const entry of authoredStrings(context, value)) {
285
+ const checkClassEntries = (entries) => {
286
+ for (const entry of entries) {
167
287
  if (!classTokens(entry.text).some(rawSurface) || reported.has(entry.node)) continue
168
288
  reported.add(entry.node)
169
289
  context.report({ node: entry.node, messageId: "surface" })
170
290
  }
171
291
  }
292
+ const checkClasses = (value) => checkClassEntries(authoredStrings(context, value))
293
+ const reportStyle = (nodes) => {
294
+ for (const node of nodes) {
295
+ if (reported.has(node)) continue
296
+ reported.add(node)
297
+ context.report({ node, messageId: "surface" })
298
+ }
299
+ }
300
+ const checkStyle = (value) => {
301
+ reportStyle(stylePaint(context, value))
302
+ }
172
303
  return {
173
- JSXOpeningElement(node) {
174
- const name = grammarName(context, node.name)
175
- const variant = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "primary"))
176
- if (name?.length !== 1 || !FIELDS.has(name[0]) || !variant) return
177
- if ([...surfaceAncestors(context, node.parent)].some((ancestor) => isSurface(context, ancestor, node))) context.report({ node: variant, messageId: "primary" })
178
- },
179
304
  JSXAttribute(node) {
180
305
  if (["className", "class", "classNames"].includes(node.name.name)) checkClasses(node.value)
306
+ if (node.name.name === "style") checkStyle(node.value)
307
+ },
308
+ JSXSpreadAttribute(node) {
309
+ for (const name of ["className", "class", "classNames"]) checkClassEntries(propStrings(context, node, name))
310
+ const values = propertyValues(context, node.argument, "style")
311
+ if (values.length) values.forEach(checkStyle)
312
+ else reportStyle(typedPropertyStrings(context, node.argument, "style", "style-keys").filter((entry) => paintProperty(entry.text)).map((entry) => entry.node))
181
313
  },
182
314
  CallExpression(node) {
183
315
  if (node.callee.type === "Identifier" && CLASS_BUILDERS.has(node.callee.name)) checkClasses(node)
@@ -187,6 +319,7 @@ export const nestedControlVariant = {
187
319
  },
188
320
  Property(node) {
189
321
  if (["className", "class", "classNames"].includes(propertyName(context, node))) checkClasses(node.value)
322
+ if (propertyName(context, node) === "style") checkStyle(node.value)
190
323
  },
191
324
  }
192
325
  },
@@ -210,13 +343,13 @@ export const noListPanelPadding = {
210
343
  }
211
344
  return {
212
345
  JSXOpeningElement(node) {
346
+ const ancestors = [...surfaceAncestors(context, node.parent)]
347
+ const surfaceIndex = ancestors.findIndex((ancestor) => isSurface(context, ancestor, node))
348
+ if (surfaceIndex < 0) return
213
349
  const name = grammarName(context, node.name)
214
350
  if (name?.[0] === "ListBox" && (name.length === 1 || ["Section", "Header", "SectionHeader"].includes(name[1]))) {
215
351
  check(node)
216
- for (const ancestor of surfaceAncestors(context, node.parent)) {
217
- check(ancestor)
218
- if (isSurface(context, ancestor, node)) break
219
- }
352
+ for (const ancestor of ancestors.slice(0, surfaceIndex + 1)) check(ancestor)
220
353
  } else if (inSectionCaption(context, node)) check(node)
221
354
  },
222
355
  }
@@ -224,7 +357,7 @@ export const noListPanelPadding = {
224
357
  }
225
358
 
226
359
  /** The surface laws ship at error in every composing source tree. */
227
- export const rules = { "nested-control-variant": nestedControlVariant, "no-list-panel-padding": noListPanelPadding }
360
+ export const rules = { "nested-control-variant": nestedControlVariant, "no-list-panel-padding": noListPanelPadding, "no-app-surface-paint": noAppSurfacePaint }
228
361
 
229
362
  /** No app can lower or omit a surface law. */
230
363
  export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))