@sssb/eslint-plugin 0.0.0 → 0.3.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/LICENSE +21 -0
- package/package.json +40 -5
- package/src/app-config.js +401 -0
- package/src/check-fences.d.ts +20 -0
- package/src/check-fences.js +269 -0
- package/src/import-ban.js +150 -0
- package/src/index.d.ts +22 -0
- package/src/index.js +31 -0
- package/src/patterns.js +318 -0
- package/src/probes.js +129 -0
- package/src/rules.js +611 -0
- package/README.md +0 -3
package/src/patterns.js
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
// THE FENCES' VOCABULARY: every import pattern and syntax selector an sssb/* rule enforces, named once. Each
|
|
2
|
+
// pattern is written in no-restricted-imports' own shape ({ group } or { regex }, and a message) and is matched
|
|
3
|
+
// exactly as that rule matches it (./import-ban.js), but no fence is carried by no-restricted-imports or
|
|
4
|
+
// no-restricted-syntax any more: a later config block that sets either rule REPLACES the earlier setting for the
|
|
5
|
+
// files it matches (the merge trap), and an adopter's own blocks come after the preset and are free to set
|
|
6
|
+
// both. Every fence is a rule with an id of its own (ADR-0014, part 4).
|
|
7
|
+
|
|
8
|
+
// EVERY extension a fence names. ESLint lints all eight in an SSSB app (its own defaults are .js, .mjs and .cjs,
|
|
9
|
+
// typescript-eslint's recommended config adds .ts, .tsx, .mts and .cts, and the react block adds .jsx), so a
|
|
10
|
+
// fence that names a DIRECTORY has to hold for each of them. The fences used to say `*.{ts,tsx}`, which let a
|
|
11
|
+
// `.mjs` file in an app's src/ import a vendor SDK, read process.env or take the raw db handle with a green lint.
|
|
12
|
+
// The runner-shaped carve-outs do NOT take their extensions from here (TEST_FILES and STORY_FILES below, the
|
|
13
|
+
// next.config and instrumentation ones in ./app-config.js): each names what its runner actually picks up, and a
|
|
14
|
+
// file the runner does not pick up keeps every ban.
|
|
15
|
+
export const SRC_EXT = '{ts,tsx,mts,cts,js,jsx,mjs,cjs}'
|
|
16
|
+
// vitest's include globs name `*.test.{ts,tsx}` and nothing else, so a `.test.mjs` under src/ is an ordinary
|
|
17
|
+
// module that a route can import, and it stays fenced.
|
|
18
|
+
export const TEST_FILES = '**/*.test.{ts,tsx}'
|
|
19
|
+
// Ladle's stories glob, extension for extension.
|
|
20
|
+
export const STORY_FILES = '**/*.stories.{js,jsx,ts,tsx}'
|
|
21
|
+
|
|
22
|
+
// Vendor SDKs may only be imported inside an adapters directory: packages/kit/src/adapters/ for SSSB's ports,
|
|
23
|
+
// an app's src/adapters/real/ for a port the app owns (ADR-0012, addendum 2026-11-16). Two rules enforce the
|
|
24
|
+
// one list: sssb/no-vendor-import sees declarations, sssb/no-dynamic-vendor-import sees import(), require() and
|
|
25
|
+
// a type-position import('…').
|
|
26
|
+
export const vendorSdkPattern = {
|
|
27
|
+
group: [
|
|
28
|
+
'@clerk/*',
|
|
29
|
+
'@aws-sdk/*',
|
|
30
|
+
'@anthropic-ai/*',
|
|
31
|
+
'@sentry/*',
|
|
32
|
+
'posthog-js',
|
|
33
|
+
'posthog-js/*',
|
|
34
|
+
'posthog-node',
|
|
35
|
+
'mailgun.js',
|
|
36
|
+
'mailgun.js/*',
|
|
37
|
+
'pg',
|
|
38
|
+
'pg/*',
|
|
39
|
+
],
|
|
40
|
+
message:
|
|
41
|
+
"Vendor SDKs may only be imported inside an adapters directory: packages/kit/src/adapters/ for SSSB's " +
|
|
42
|
+
'ports, apps/<app>/src/adapters/real/ for a port the app owns (docs/recipes/app-owned-adapter.md). ' +
|
|
43
|
+
'Code against the port instead (see CONTRIBUTING.md).',
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// An app's real adapter is reached through the app's adapter registry (src/adapters/index.ts), the module that
|
|
47
|
+
// picks the fake in simulated mode — the role SSSB's exports map plays for SSSB's own real adapters. Matches
|
|
48
|
+
// `@/…/adapters/real` and its ordinary relative spellings (`../adapters/real`, `../../adapters/real`), and
|
|
49
|
+
// nothing that starts with `@sssb/kit/`, so SSSB's three published real-mode components stay importable. It reads
|
|
50
|
+
// the specifier as written: an unnormalized one (`../adapters/fake/../real/kv`) gets past it, as a computed
|
|
51
|
+
// specifier gets past every import rule.
|
|
52
|
+
//
|
|
53
|
+
// DECLARATIONS only, and deliberately so: a dynamic import inside an `!isSimulated` branch is exactly how a
|
|
54
|
+
// real-mode-only component is reached (SSSB's own sign-in form is loaded that way by the app's sign-in page).
|
|
55
|
+
export const appRealAdapterPattern = {
|
|
56
|
+
regex: '^(?:@|\\.{1,2})/(?:.*/)?adapters/real(?:/|$)',
|
|
57
|
+
message:
|
|
58
|
+
"Reach the app's real adapters through its registry (apps/<app>/src/adapters/index.ts), which serves " +
|
|
59
|
+
'the fake in simulated mode — a static import loads the vendor in every run mode and skips the fake. ' +
|
|
60
|
+
'A real-mode-only component is the exception, reached by import() inside an !isSimulated branch the ' +
|
|
61
|
+
"way SSSB's sign-in form is (docs/recipes/app-owned-adapter.md).",
|
|
62
|
+
}
|
|
63
|
+
// INSIDE the app's adapters directory the rule is stricter: real/ is reached only by `import()`, and the
|
|
64
|
+
// registry's `await import('./real/index')` when !isSimulated is the one place that should do it. A static import
|
|
65
|
+
// from a fake would load the vendor SDK into a simulated `pnpm dev`, and from the registry it would load it in
|
|
66
|
+
// every mode. Matches `./real`, `../real`, `../../adapters/real` and `@/…/adapters/real`.
|
|
67
|
+
export const appRealAdapterStaticPattern = {
|
|
68
|
+
regex: '^(?:@/(?:.*/)?adapters|\\.{1,2}(?:/.*)?)/real(?:/|$)',
|
|
69
|
+
message:
|
|
70
|
+
"Inside apps/<app>/src/adapters, real/ is loaded only with import() — the registry's " +
|
|
71
|
+
"`await import('./real/index')` when !isSimulated. A static import loads the vendor SDK in simulated " +
|
|
72
|
+
'mode too (docs/recipes/app-owned-adapter.md).',
|
|
73
|
+
}
|
|
74
|
+
// SSSB publishes a few of its own real adapters (`@sssb/kit/adapters/real/*`: the real-adapter set, the LLM client, S3 storage, the
|
|
75
|
+
// real-mode forms and providers, the migrate handler). Importing one loads its vendor SDK, so outside the app's own
|
|
76
|
+
// real adapters (which may build on one, as an app-owned storage adapter builds on `createS3Storage`) a module
|
|
77
|
+
// reaches one only by import(), the way the sign-in page loads SSSB's sign-in form when !isSimulated. DECLARATIONS
|
|
78
|
+
// only, like the app's own real-adapter rule, less a declaration that is type-only as a whole (`import type`,
|
|
79
|
+
// `export type … from`), which loads nothing (`allowTypeOnly`, ./import-ban.js); an inline `import { type X }` does.
|
|
80
|
+
export const kitRealAdapterPattern = {
|
|
81
|
+
regex: '^@sssb/kit/adapters/real/',
|
|
82
|
+
message:
|
|
83
|
+
"Outside the app's own real adapters (src/adapters/real/), SSSB's real adapters (@sssb/kit/adapters/real/*) " +
|
|
84
|
+
'are loaded only with import(), when !isSimulated: a static import loads the vendor SDK in simulated mode ' +
|
|
85
|
+
"too. Reach SSSB's ports through its registry (@sssb/kit/adapters/index) (docs/recipes/app-owned-adapter.md).",
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// Hermetic dev: next/font/google fetches from Google Fonts at build, so pnpm dev would phone home. Self-host
|
|
89
|
+
// via next/font/local instead.
|
|
90
|
+
export const nextFontPattern = {
|
|
91
|
+
group: ['next/font/google', 'next/font/google/*'],
|
|
92
|
+
message:
|
|
93
|
+
'next/font/google phones home to Google Fonts at build — banned to keep dev hermetic (CLAUDE.md); use next/font/local.',
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// THE FRAMEWORK/APP FENCE (ADR-0012), which holds inside packages/kit only. The framework IS a package, so the
|
|
97
|
+
// fence is a package boundary: nothing inside it may reach the host app's code. The app's `@/*` alias still
|
|
98
|
+
// resolves from anywhere in SSSB's repo (tsconfig paths are global), so it is banned wholesale, along with the
|
|
99
|
+
// app's seed package. The `@sssb/app-config/*` seam is the one sanctioned door; it is DELIBERATELY distinct from
|
|
100
|
+
// `@/app-config/*` so the fenced form stays bannable.
|
|
101
|
+
//
|
|
102
|
+
// A `regex`, not a `group`: the `@/*` group (gitignore syntax, through the `ignore` package) does not match an
|
|
103
|
+
// empty segment, and an app's tsconfig maps `@/*` to `./src/*`, so `@//domain/tickets` reached app code past it.
|
|
104
|
+
// So `@` followed by ANY slash is the alias, and `@app` then slashes then `seed` is the seed; nothing published is
|
|
105
|
+
// named either way. A fuzz of some 7,000 spellings against TypeScript's resolver found no other alias spelling.
|
|
106
|
+
const appCodePattern = {
|
|
107
|
+
regex: String.raw`^(@[\\/]|@app[\\/]+seed([\\/]|$))`,
|
|
108
|
+
message:
|
|
109
|
+
'Framework code (packages/kit) must reach app content only through the seam — import from the ' +
|
|
110
|
+
"@sssb/app-config/* alias (apps/*/src/app-config/*), never the app's @/* alias or @app/seed (ADR-0012).",
|
|
111
|
+
}
|
|
112
|
+
// HOW A SPECIFIER CAN REACH APP CODE, every way, and which piece of the fence holds each. Three review rounds each
|
|
113
|
+
// found a new spelling, so the fence is built from this list rather than from the spellings:
|
|
114
|
+
// 1. an alias: `@/…` and `@app/seed…` (appCodePattern);
|
|
115
|
+
// 2. a PATH (`./`, `../`, `/`, `\`, or a `file:` URL): wherever it is spelled to go, it lands somewhere, symlinks
|
|
116
|
+
// and all (sssb/no-path-to-app-code resolves it and asks where);
|
|
117
|
+
// 3. a package or alias specifier that climbs out of itself with `..` (bareTraversalPattern);
|
|
118
|
+
// 4. a specifier through a `node_modules` directory, where pnpm links the apps and the seed among other workspace
|
|
119
|
+
// packages (nodeModulesPathPattern);
|
|
120
|
+
// 5. an app's package by name: SSSB depends on no app package, so a bare `showcase` resolves to nothing.
|
|
121
|
+
// Out of reach of every import rule, here as everywhere: a computed specifier (`import(name)`), a `data:` URL,
|
|
122
|
+
// whose module can name a file of its own, and a require not called by that name (`createRequire(…)(…)`,
|
|
123
|
+
// `module.require(…)`).
|
|
124
|
+
//
|
|
125
|
+
// A specifier that matches two of these patterns is two findings, in both halves: each half reports every pattern
|
|
126
|
+
// that matches. Nothing is exempted from one pattern because another "already bans it": the traversal ban once
|
|
127
|
+
// exempted `@/…` and `@app/seed…` that way, and missed `@\..\..\apps\…` and then `@//../../apps/…`, two spellings
|
|
128
|
+
// (1)'s group does not match. A double report on a strange specifier costs less than a hole.
|
|
129
|
+
//
|
|
130
|
+
// (3) `@sssb/app-config/../seed` resolves to the app's seed through the one door the fence leaves open, and
|
|
131
|
+
// `@scope/../../apps/…`, `.x/../../apps/…` and `lodash/../../packages/seed/src/index` resolve out of node_modules
|
|
132
|
+
// into app code (TypeScript's resolver does, and Node's `require()` when the specifier spells the file's
|
|
133
|
+
// extension); no package specifier has a reason to say `..`. Banned in any specifier that is not a path (a `./`,
|
|
134
|
+
// `../`, `/` or `\` path, or a `file:` URL, is (2)'s).
|
|
135
|
+
const bareTraversalPattern = {
|
|
136
|
+
regex: String.raw`^(?!\.{1,2}([\\/]|$))(?![\\/])(?!file:)(.*[\\/])?\.\.([\\/]|$)`,
|
|
137
|
+
message:
|
|
138
|
+
'Framework code (packages/kit) must reach app content only through the seam — a `..` in a package or ' +
|
|
139
|
+
'alias specifier climbs out of it, into app code the seam does not register. Import the module directly ' +
|
|
140
|
+
'(ADR-0012).',
|
|
141
|
+
}
|
|
142
|
+
// (4) `.pnpm/node_modules/showcase/src/…`, or `../../node_modules/.pnpm/node_modules/@app/seed/…`: a package
|
|
143
|
+
// reached by where pnpm put it rather than by its name. Nothing in SSSB imports through node_modules.
|
|
144
|
+
export const nodeModulesPathPattern = {
|
|
145
|
+
regex: String.raw`(^|[\\/])node_modules([\\/]|$)`,
|
|
146
|
+
message:
|
|
147
|
+
'Framework code (packages/kit) must reach app content only through the seam, and imports a package by its ' +
|
|
148
|
+
'name, never through node_modules: pnpm links every workspace package there, the apps and the seed among ' +
|
|
149
|
+
'them (ADR-0012).',
|
|
150
|
+
}
|
|
151
|
+
export const appCodePatterns = [appCodePattern, bareTraversalPattern, nodeModulesPathPattern]
|
|
152
|
+
// @sssb/kit/core is pure TypeScript (ADR-0006).
|
|
153
|
+
export const coreFrameworkPattern = {
|
|
154
|
+
group: ['react', 'react-*', 'next', 'next/*', 'next-intl', 'next-intl/*', '@mantine/*'],
|
|
155
|
+
message: '@sssb/kit/core is pure TypeScript — no framework imports (ADR-0006).',
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// THE TENANCY BAN's selectors (ADR-0004), enforced by sssb/no-raw-db-handle. They used to be no-restricted-syntax
|
|
159
|
+
// selectors, re-listed in every block that bans getDb, and the merge trap dropped one of them for every route,
|
|
160
|
+
// page and component (a later block's list replaced the earlier one for those files).
|
|
161
|
+
// These aim at the ACT — naming `getDb` — rather than one syntactic shape of it, because shape-matching was
|
|
162
|
+
// bypassed twice. They do NOT catch every indirection and cannot: a name built at runtime (`db['get' + 'Db']()`)
|
|
163
|
+
// still walks past them, and no lint rule can chase an arbitrary alias. A key held in a variable is caught where
|
|
164
|
+
// the string is written (getDbStringSelector). The real boundary is RLS in the database; this is a fast, local
|
|
165
|
+
// reminder.
|
|
166
|
+
//
|
|
167
|
+
// The history is why they look like this: a call-expression selector missed `const { getDb } = db`, and adding a
|
|
168
|
+
// destructuring selector still left `db.getDb.bind(db)`, `db['getDb']()` and destructuring in a function
|
|
169
|
+
// PARAMETER. So the MemberExpression form subsumes the original call form, and the ObjectPattern form deliberately
|
|
170
|
+
// carries no `VariableDeclarator >` ancestor, which is what makes a destructured parameter count. A key spelled as
|
|
171
|
+
// a template literal with no expressions (``db[`getDb`]``) or quoted (`const { 'getDb': g } = db`) names it just
|
|
172
|
+
// the same, so both match too.
|
|
173
|
+
//
|
|
174
|
+
// A KEY can name something three ways: an identifier (`.name`, `{ name }`), a string (`['name']`,
|
|
175
|
+
// `{ 'name': x }`), or a template literal with no expressions. Every name these selectors aim at (getDb, `env` on
|
|
176
|
+
// `process` or imported from it, a run-mode variable) is matched in all three: through anyKey, or, for getDb's
|
|
177
|
+
// member access, the dot selector for the identifier and quotedKey for the other two. `path` is the esquery path
|
|
178
|
+
// to the key; `name` is a quoted string or a regex. quotedKey leaves out the identifier because in a computed
|
|
179
|
+
// access an identifier is a VARIABLE (`db[k]`), not the name. The anyKey selectors on `process` keep it, so
|
|
180
|
+
// `process[env]` with `env` a variable is reported too. A key wrapped in a TypeScript assertion is out of these
|
|
181
|
+
// selectors' reach: `process.env['APP_MODE' as const]` passes, and `db['getDb' as const]` is caught only because
|
|
182
|
+
// its string is (getDbStringSelector).
|
|
183
|
+
const quotedKey = (path, name) =>
|
|
184
|
+
`:matches([${path}.value=${name}], [${path}.expressions.length=0][${path}.quasis.0.value.cooked=${name}])`
|
|
185
|
+
const anyKey = (path, name) =>
|
|
186
|
+
`:matches([${path}.name=${name}], [${path}.value=${name}], ` +
|
|
187
|
+
`[${path}.expressions.length=0][${path}.quasis.0.value.cooked=${name}])`
|
|
188
|
+
export const getDbSelector = {
|
|
189
|
+
selector: 'MemberExpression[property.name="getDb"]',
|
|
190
|
+
message:
|
|
191
|
+
"App code and SSSB's screens must not use the raw db handle — use db.withTenant() (or a @sssb/kit/db helper) so RLS tenant context is set (ADR-0004).",
|
|
192
|
+
}
|
|
193
|
+
export const getDbComputedSelector = {
|
|
194
|
+
selector: `MemberExpression[computed=true]${quotedKey('property', '"getDb"')}`,
|
|
195
|
+
message:
|
|
196
|
+
"Reaching the raw db handle as db['getDb'] bypasses the same rule — use db.withTenant() (or a @sssb/kit/db helper) so RLS tenant context is set (ADR-0004).",
|
|
197
|
+
}
|
|
198
|
+
export const getDbDestructureSelector = {
|
|
199
|
+
selector: `ObjectPattern > Property${anyKey('key', '"getDb"')}`,
|
|
200
|
+
message:
|
|
201
|
+
'Destructuring getDb out of the db port bypasses the same rule — use db.withTenant() (or a @sssb/kit/db helper) so RLS tenant context is set (ADR-0004).',
|
|
202
|
+
}
|
|
203
|
+
// The name as a STRING anywhere else: `Reflect.get(db, 'getDb')`, `Object.getOwnPropertyDescriptor(db,
|
|
204
|
+
// 'getDb')`, a key held in a variable (`const k = 'getDb'; db[k]()`). Reaching the handle that way needs the
|
|
205
|
+
// string, so the string is the finding. What is left out:
|
|
206
|
+
// - a computed member's key: the computed selector above reports it (no double report). A destructured key is
|
|
207
|
+
// reported by the destructure selector, and is left out with the rest of the keys below.
|
|
208
|
+
// - a key that DEFINES a member rather than reading one: a quoted key in an object literal, a class (abstract and
|
|
209
|
+
// accessor members included), or a type (`{ 'getDb': … }`, `'getDb'() {}`,
|
|
210
|
+
// `interface P { 'getDb'(): unknown }`), as the unquoted key is.
|
|
211
|
+
// - a TypeScript type position (`Pick<DbPort, 'getDb'>`), which loads nothing.
|
|
212
|
+
// - in a TEST FILE only, a spy's key (`vi.spyOn(db, 'getDb')`), which is how a route test asserts the raw handle
|
|
213
|
+
// is never taken. A spy calls through to the original, so anywhere else it IS the raw handle; the rule checks
|
|
214
|
+
// the file name for this one. RESIDUAL, accepted: in a test the spy calls through too, so a route test that
|
|
215
|
+
// calls it (`vi.spyOn(db, 'getDb')()`) does take the handle. The ban guards the code under test; a test that
|
|
216
|
+
// reaches past it is a review matter.
|
|
217
|
+
export const getDbStringSelector = {
|
|
218
|
+
selector:
|
|
219
|
+
':matches(Literal[value="getDb"], TemplateLiteral[expressions.length=0][quasis.0.value.cooked="getDb"])' +
|
|
220
|
+
':not(MemberExpression[computed=true] > .property)' +
|
|
221
|
+
':not(:matches(Property, MethodDefinition, PropertyDefinition, AccessorProperty, TSAbstractMethodDefinition, ' +
|
|
222
|
+
'TSAbstractPropertyDefinition, TSAbstractAccessorProperty, TSPropertySignature, TSMethodSignature) > .key)' +
|
|
223
|
+
':not(TSLiteralType > .literal)',
|
|
224
|
+
message:
|
|
225
|
+
"Naming getDb as a string (Reflect.get(db, 'getDb'), a key held in a variable) reaches the same raw handle — use " +
|
|
226
|
+
'db.withTenant() (or a @sssb/kit/db helper) so RLS tenant context is set (ADR-0004).',
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
// process.env, and the import form — `import { env }`, or a default or namespace import, from
|
|
230
|
+
// `process`/`node:process` — which reads the same object under another name (a type-only import, or
|
|
231
|
+
// `import { cwd }`, does not). It closes that one form: re-exporting `env` from `node:process`, or
|
|
232
|
+
// `const { env } = process`, still gets past, as any alias does (`globalThis.process.env` included).
|
|
233
|
+
// `process['env']` is not an alias, it is the same name spelled as a key (anyKey).
|
|
234
|
+
export const processEnvSelector = {
|
|
235
|
+
selector:
|
|
236
|
+
`:matches(MemberExpression[object.name="process"]${anyKey('property', '"env"')}, ` +
|
|
237
|
+
'ImportDeclaration[importKind!="type"][source.value=/^(node:)?process$/] > ' +
|
|
238
|
+
`:matches(ImportSpecifier${anyKey('imported', '"env"')}, ImportDefaultSpecifier, ImportNamespaceSpecifier))`,
|
|
239
|
+
message:
|
|
240
|
+
"process.env is read ONLY inside an adapters directory — packages/kit/src/adapters, or an app's own " +
|
|
241
|
+
'apps/<app>/src/adapters/real (CLAUDE.md) — deployment/service params come from the app ' +
|
|
242
|
+
"config/params.ts, run mode from @sssb/kit/adapters (isSimulated/isDemoMode). SSSB's own two secret readers " +
|
|
243
|
+
"in packages/kit are exempted by file in SSSB's eslint.config.mjs.",
|
|
244
|
+
}
|
|
245
|
+
// An app's real adapter may read its OWN configuration from process.env, but never the run mode. That is SSSB's:
|
|
246
|
+
// `appMode`/`isSimulated`/`isDemoMode` from @sssb/kit/adapters/index, whose import also runs the fail-closed
|
|
247
|
+
// production guard. A second reader of APP_MODE can disagree with it (SSSB treats a legacy `APP_MODE=fake` as
|
|
248
|
+
// simulated) and never runs the guard. Matched: the variable read as a key of `process.env` in any of anyKey's
|
|
249
|
+
// three spellings, with `env` itself in any of them too (`process['env'].APP_MODE`), and destructuring in a
|
|
250
|
+
// declaration, an assignment or a parameter default. No lint rule chases an alias (`const env = process.env;
|
|
251
|
+
// env.APP_MODE`, or `env` imported from `node:process`).
|
|
252
|
+
const RUN_MODE_ENV = '/^(APP_MODE|DEMO_MODE|E2E_BUILD)$/'
|
|
253
|
+
const runModeEnvMessage =
|
|
254
|
+
"Run mode is SSSB's — import isSimulated/isDemoMode/appMode from @sssb/kit/adapters/index. An app adapter " +
|
|
255
|
+
"that reads APP_MODE, DEMO_MODE or E2E_BUILD itself can disagree with SSSB's registry and skips its " +
|
|
256
|
+
'fail-closed production guard (docs/recipes/app-owned-adapter.md).'
|
|
257
|
+
export const runModeEnvSelector = {
|
|
258
|
+
selector:
|
|
259
|
+
`MemberExpression[object.object.name="process"]${anyKey('object.property', '"env"')}` +
|
|
260
|
+
anyKey('property', RUN_MODE_ENV),
|
|
261
|
+
message: runModeEnvMessage,
|
|
262
|
+
}
|
|
263
|
+
// Destructuring in a declaration, an assignment, or a parameter default — each puts `process.env` on the right of
|
|
264
|
+
// the pattern under a different parent node.
|
|
265
|
+
export const runModeEnvDestructureSelector = {
|
|
266
|
+
selector:
|
|
267
|
+
`:matches(VariableDeclarator[init.object.name="process"]${anyKey('init.property', '"env"')}, ` +
|
|
268
|
+
`AssignmentExpression[right.object.name="process"]${anyKey('right.property', '"env"')}, ` +
|
|
269
|
+
`AssignmentPattern[right.object.name="process"]${anyKey('right.property', '"env"')}) > ObjectPattern > ` +
|
|
270
|
+
`Property${anyKey('key', RUN_MODE_ENV)}`,
|
|
271
|
+
message: runModeEnvMessage,
|
|
272
|
+
}
|
|
273
|
+
// Inside an app's adapters directory, only the registry loads real/. A fake, or a second module, doing
|
|
274
|
+
// `await import('../real/kv')` would put the vendor SDK behind code that never asks the run mode. The static
|
|
275
|
+
// form is appRealAdapterStaticPattern; this is the dynamic one.
|
|
276
|
+
const REAL_DIR = '/(^|[/])real([/]|$)/'
|
|
277
|
+
export const appRealAdapterDynamicSelector = {
|
|
278
|
+
selector: `ImportExpression:matches([source.value=${REAL_DIR}], [source.quasis.0.value.cooked=${REAL_DIR}])`,
|
|
279
|
+
message:
|
|
280
|
+
"Only the app's registry (apps/<app>/src/adapters/index.ts) loads real/, with import() when " +
|
|
281
|
+
'!isSimulated. Anywhere else in the adapters directory it would load the vendor SDK without asking the ' +
|
|
282
|
+
'run mode (docs/recipes/app-owned-adapter.md).',
|
|
283
|
+
}
|
|
284
|
+
// i18n (ADR-0008): these attributes carry user-visible copy, which jsx-no-literals can't see (ignoreProps:true).
|
|
285
|
+
// Route them through next-intl (a t() call), never a string literal. Stories are carved out (they render
|
|
286
|
+
// fixtures, not shipped UI).
|
|
287
|
+
export const a11yLiteralSelector = {
|
|
288
|
+
selector: "JSXAttribute[name.name=/^(aria-label|placeholder|title|alt)$/][value.type='Literal']",
|
|
289
|
+
message:
|
|
290
|
+
'aria-label/placeholder/title/alt carry user-visible copy — route them through next-intl (t()), never a string literal (ADR-0008).',
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
// Every pattern frozen, its lists included: the rules read them when they run, and an app's config is code that could
|
|
294
|
+
// reach this module by its file path.
|
|
295
|
+
for (const pattern of [
|
|
296
|
+
vendorSdkPattern,
|
|
297
|
+
appRealAdapterPattern,
|
|
298
|
+
appRealAdapterStaticPattern,
|
|
299
|
+
kitRealAdapterPattern,
|
|
300
|
+
nextFontPattern,
|
|
301
|
+
appCodePattern,
|
|
302
|
+
bareTraversalPattern,
|
|
303
|
+
nodeModulesPathPattern,
|
|
304
|
+
coreFrameworkPattern,
|
|
305
|
+
getDbSelector,
|
|
306
|
+
getDbComputedSelector,
|
|
307
|
+
getDbDestructureSelector,
|
|
308
|
+
getDbStringSelector,
|
|
309
|
+
processEnvSelector,
|
|
310
|
+
runModeEnvSelector,
|
|
311
|
+
runModeEnvDestructureSelector,
|
|
312
|
+
appRealAdapterDynamicSelector,
|
|
313
|
+
a11yLiteralSelector,
|
|
314
|
+
]) {
|
|
315
|
+
if (pattern.group) Object.freeze(pattern.group)
|
|
316
|
+
Object.freeze(pattern)
|
|
317
|
+
}
|
|
318
|
+
Object.freeze(appCodePatterns)
|
package/src/probes.js
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
// THE FENCE PROBES `sssb check-fences` lints through an app's real, composed config: one virtual file per zone, at a
|
|
2
|
+
// path relative to the app, whose code every fence the preset applies there must report. Nothing is written to
|
|
3
|
+
// disk. Positive probes, bar one: the file a lint-exceptions.mjs entry names must NOT report (check-fences.js, step
|
|
4
|
+
// 3), since the app declared it exempt. Otherwise an app that bans MORE than the preset (a vendor SDK in its own real
|
|
5
|
+
// adapters, say) is tightening a fence, not loosening one, and check-fences leaves it alone.
|
|
6
|
+
//
|
|
7
|
+
// SSSB's own repository runs the same probes through its root config (tests/lint/check-fences.test.ts), so a probe
|
|
8
|
+
// that stops matching what the preset enforces fails there first.
|
|
9
|
+
|
|
10
|
+
/** The name every probe file carries, so it can never be a file the app has. */
|
|
11
|
+
export const PROBE = '__sssb_fence_probe__'
|
|
12
|
+
|
|
13
|
+
const IMPORTS_VENDOR = "import { S3Client } from '@aws-sdk/client-s3'\nexport const client = S3Client\n"
|
|
14
|
+
const LOADS_VENDOR = "export const load = () => import('@aws-sdk/client-s3')\n"
|
|
15
|
+
const READS_ENV = 'export const region = process.env.AWS_REGION\n'
|
|
16
|
+
const TAKES_RAW_DB = 'export const load = (db) => db.getDb()\n'
|
|
17
|
+
const IMPORTS_KIT_REAL =
|
|
18
|
+
"import { createS3Storage } from '@sssb/kit/adapters/real/s3-storage'\nexport const s3 = createS3Storage\n"
|
|
19
|
+
const SCREEN =
|
|
20
|
+
'export const Card = () => <p>Saved to the edge</p>\nexport const Save = () => <button aria-label="Save">x</button>\n'
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* @typedef {{ path: string, code: string, fires: string[] }} Probe
|
|
24
|
+
* `fires` lists the sssb/* rules that must each report at least once.
|
|
25
|
+
* @type {Probe[]}
|
|
26
|
+
*/
|
|
27
|
+
export const PROBES = [
|
|
28
|
+
{
|
|
29
|
+
path: `src/domain/${PROBE}.ts`,
|
|
30
|
+
code:
|
|
31
|
+
`${IMPORTS_VENDOR}${LOADS_VENDOR}${READS_ENV}${TAKES_RAW_DB}${IMPORTS_KIT_REAL}` +
|
|
32
|
+
"import { kv } from '@/adapters/real/kv'\nexport { kv }\n" +
|
|
33
|
+
"import { Inter } from 'next/font/google'\nexport const font = Inter\n",
|
|
34
|
+
fires: [
|
|
35
|
+
'sssb/no-vendor-import',
|
|
36
|
+
'sssb/no-dynamic-vendor-import',
|
|
37
|
+
'sssb/no-process-env',
|
|
38
|
+
'sssb/no-raw-db-handle',
|
|
39
|
+
'sssb/no-real-adapter-import',
|
|
40
|
+
'sssb/no-kit-real-adapter-import',
|
|
41
|
+
'sssb/no-next-font-google',
|
|
42
|
+
],
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
path: `config/${PROBE}.ts`,
|
|
46
|
+
code: `${IMPORTS_VENDOR}${READS_ENV}${IMPORTS_KIT_REAL}`,
|
|
47
|
+
fires: ['sssb/no-vendor-import', 'sssb/no-process-env', 'sssb/no-kit-real-adapter-import'],
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
path: `src/app/api/${PROBE}/route.ts`,
|
|
51
|
+
code: `${IMPORTS_VENDOR}${READS_ENV}${TAKES_RAW_DB}${IMPORTS_KIT_REAL}`,
|
|
52
|
+
fires: [
|
|
53
|
+
'sssb/no-vendor-import',
|
|
54
|
+
'sssb/no-process-env',
|
|
55
|
+
'sssb/no-raw-db-handle',
|
|
56
|
+
'sssb/no-kit-real-adapter-import',
|
|
57
|
+
],
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
path: `src/app/${PROBE}.tsx`,
|
|
61
|
+
code: SCREEN,
|
|
62
|
+
fires: ['sssb/no-jsx-literals', 'sssb/no-literal-a11y-copy'],
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
path: `src/components/${PROBE}.tsx`,
|
|
66
|
+
code: `${SCREEN}${READS_ENV}${TAKES_RAW_DB}${IMPORTS_KIT_REAL}`,
|
|
67
|
+
fires: [
|
|
68
|
+
'sssb/no-jsx-literals',
|
|
69
|
+
'sssb/no-literal-a11y-copy',
|
|
70
|
+
'sssb/no-process-env',
|
|
71
|
+
'sssb/no-raw-db-handle',
|
|
72
|
+
'sssb/no-kit-real-adapter-import',
|
|
73
|
+
],
|
|
74
|
+
},
|
|
75
|
+
{
|
|
76
|
+
path: `src/demo-static/${PROBE}.tsx`,
|
|
77
|
+
code: SCREEN,
|
|
78
|
+
fires: ['sssb/no-jsx-literals'],
|
|
79
|
+
},
|
|
80
|
+
// A route's or a screen's test keeps the tenancy ban; any test keeps the mkdtemp ban, and any test in src/ the ban
|
|
81
|
+
// on a static import of SSSB's real adapters.
|
|
82
|
+
{
|
|
83
|
+
path: `src/components/${PROBE}.test.tsx`,
|
|
84
|
+
code: `${TAKES_RAW_DB}import { mkdtempSync } from 'node:fs'\nexport const dir = mkdtempSync('x')\n${IMPORTS_KIT_REAL}`,
|
|
85
|
+
fires: ['sssb/no-raw-db-handle', 'sssb/no-direct-mkdtemp', 'sssb/no-kit-real-adapter-import'],
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
path: `tests/e2e/${PROBE}.spec.ts`,
|
|
89
|
+
code: `import { mkdtempSync } from 'node:fs'\nexport const dir = mkdtempSync('x')\n${IMPORTS_VENDOR}`,
|
|
90
|
+
fires: ['sssb/no-direct-mkdtemp', 'sssb/no-vendor-import'],
|
|
91
|
+
},
|
|
92
|
+
// The registry and the fakes keep the vendor and process.env bans, load real/ only through the registry's
|
|
93
|
+
// import(), and never import SSSB's real adapters.
|
|
94
|
+
{
|
|
95
|
+
path: `src/adapters/fake/${PROBE}.tsx`,
|
|
96
|
+
code:
|
|
97
|
+
`${IMPORTS_VENDOR}${LOADS_VENDOR}${READS_ENV}` +
|
|
98
|
+
"import { kv } from '../real/kv'\nimport { form } from '@sssb/kit/adapters/real/sign-in-form'\n" +
|
|
99
|
+
"export { kv, form }\nexport const loadReal = () => import('../real/kv')\n" +
|
|
100
|
+
'export const Save = () => <button aria-label="Save">x</button>\n',
|
|
101
|
+
fires: [
|
|
102
|
+
'sssb/no-vendor-import',
|
|
103
|
+
'sssb/no-dynamic-vendor-import',
|
|
104
|
+
'sssb/no-process-env',
|
|
105
|
+
'sssb/no-static-real-adapter-import',
|
|
106
|
+
'sssb/no-kit-real-adapter-import',
|
|
107
|
+
'sssb/no-dynamic-real-adapter-import',
|
|
108
|
+
'sssb/no-literal-a11y-copy',
|
|
109
|
+
'sssb/no-jsx-literals',
|
|
110
|
+
],
|
|
111
|
+
},
|
|
112
|
+
// An app's real adapter may import its vendor and read its own configuration, but never the run mode.
|
|
113
|
+
{
|
|
114
|
+
path: `src/adapters/real/${PROBE}.tsx`,
|
|
115
|
+
code:
|
|
116
|
+
'export const mode = process.env.APP_MODE\n' +
|
|
117
|
+
"import { Inter } from 'next/font/google'\nexport const font = Inter\n" +
|
|
118
|
+
'export const Save = () => <button aria-label="Save">Save</button>\n',
|
|
119
|
+
fires: [
|
|
120
|
+
'sssb/no-run-mode-env',
|
|
121
|
+
'sssb/no-next-font-google',
|
|
122
|
+
'sssb/no-literal-a11y-copy',
|
|
123
|
+
'sssb/no-jsx-literals',
|
|
124
|
+
],
|
|
125
|
+
},
|
|
126
|
+
]
|
|
127
|
+
|
|
128
|
+
/** What a module named in lint-exceptions.mjs is linted with: the act the exception lets through. */
|
|
129
|
+
export const EXCEPTION_PROBE_CODE = TAKES_RAW_DB
|