@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.
- package/CHANGELOG.md +14 -1
- package/README.md +36 -84
- package/brand-values.mjs +1 -1
- package/docs/hooks-folder.md +5 -3
- package/docs/native-controls.md +1 -5
- package/docs/next-conventions.md +8 -8
- package/docs/size-and-state-budget.md +22 -0
- package/docs/surface-rules.md +11 -9
- package/drawing.mjs +4 -66
- package/hooks-folder.mjs +5 -3
- package/index.mjs +7 -25
- package/landmark.mjs +0 -3
- package/lib/class-text.mjs +29 -0
- package/lib/config.mjs +4 -6
- package/lib/drawing-scope.mjs +15 -0
- package/lib/typed-class-values.mjs +10 -1
- package/lib/why.mjs +10 -40
- package/next-conventions.mjs +33 -16
- package/package.json +4 -3
- package/runtime/knowledge/grammars/index.yaml +102 -0
- package/runtime/knowledge/hfs/canon-pins.yaml +22 -8
- package/runtime/knowledge/hfs/fe-stack.yaml +7 -0
- package/runtime/knowledge/hfs/slots.yaml +3 -3
- package/runtime/modules/kernel/removed-vocabulary.yaml +29 -0
- package/runtime/scripts/hfs/architecture/config.mjs +8 -8
- package/runtime/scripts/hfs/declaration-shape.mjs +8 -2
- package/runtime/scripts/hfs/rule-catalog.mjs +2 -2
- package/runtime/scripts/hfs/slots.mjs +1 -0
- package/runtime/scripts/hfs/view.mjs +1 -0
- package/runtime/scripts/lib/grammar-lint.mjs +48 -0
- package/size-and-state-budget.mjs +116 -4
- package/surface-rules.mjs +159 -26
- package/tokens.mjs +5 -217
- package/app-shell.mjs +0 -161
- package/docs/app-shell.md +0 -50
- package/docs/grammar-boundary.md +0 -57
- package/docs/status-colors.md +0 -32
- package/grammar-boundary.mjs +0 -203
- package/icon.mjs +0 -310
- package/lib/app-shell-cluster.mjs +0 -66
- package/lib/app-shell-create.mjs +0 -33
- package/lib/app-shell-owner-source.mjs +0 -124
- package/lib/app-shell-owner.mjs +0 -65
- package/lib/app-shell-scope.mjs +0 -79
- package/lib/app-shell-visible.mjs +0 -92
- package/lib/app-shell.mjs +0 -148
- package/lib/status-tones.generated.mjs +0 -9
- package/menu-entries.mjs +0 -133
- package/runtime/modules/goal/source-phrases.yaml +0 -95
- package/runtime/scripts/lib/source-phrases.mjs +0 -34
- package/status-colors.mjs +0 -137
- package/typography.mjs +0 -78
- 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
|
|
277
|
-
* source, every app and every workspace package that depends on
|
|
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,
|
|
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 {
|
|
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 {
|
|
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`
|
|
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", "
|
|
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 (
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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
|
-
|
|
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
|
|
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:
|
|
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:
|
|
251
|
+
docs: { description: "ANATOMY-2: Grammar context supplies field variants; nested Tabs cannot force primary." },
|
|
157
252
|
schema: [],
|
|
158
253
|
messages: {
|
|
159
|
-
|
|
160
|
-
|
|
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
|
|
166
|
-
for (const entry of
|
|
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
|
|
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"]))
|