|
| 1 | +import { defineConfig, globalIgnores } from "eslint/config"; |
| 2 | +import tseslint from "typescript-eslint"; |
| 3 | + |
| 4 | +// Provider modules the core must never import (R2.19, R12.34). |
| 5 | +const forbiddenModules = [ |
| 6 | + "@aws-sdk", |
| 7 | + "@descope", |
| 8 | + "@hocuspocus", |
| 9 | + "@hono", |
| 10 | + "pg", |
| 11 | + "kysely", |
| 12 | + "pg-boss", |
| 13 | + "hono", |
| 14 | + "ws", |
| 15 | + "crossws", |
| 16 | + "pino", |
| 17 | + "rate-limiter-flexible", |
| 18 | + "yjs", |
| 19 | + "y-protocols", |
| 20 | +]; |
| 21 | +const forbiddenImportPatterns = forbiddenModules.flatMap((m) => [m, `${m}/*`]); |
| 22 | +const forbiddenSourceRegex = `^(?:${forbiddenModules.map((m) => m.replace(/[-/]/g, "\\$&")).join("|")})(?:$|[^\\w-])`; |
| 23 | +const importMessage = |
| 24 | + "packages/core must not import provider SDKs or runtime libraries; use a port interface (R2.19)."; |
| 25 | +const envMessage = |
| 26 | + "packages/core must not read process.env in packages/core; only the config adapter reads the environment (R2.19)."; |
| 27 | + |
| 28 | +const envRules = [ |
| 29 | + { |
| 30 | + selector: "MemberExpression[object.name='process'][property.name='env']", |
| 31 | + message: envMessage, |
| 32 | + }, |
| 33 | + { |
| 34 | + selector: "MemberExpression[object.name='process'][property.value='env']", |
| 35 | + message: envMessage, |
| 36 | + }, |
| 37 | + { |
| 38 | + selector: "MemberExpression[object.property.name='process'][property.name='env']", |
| 39 | + message: envMessage, |
| 40 | + }, |
| 41 | + { |
| 42 | + selector: "VariableDeclarator[init.name='process'] > ObjectPattern > Property[key.name='env']", |
| 43 | + message: envMessage, |
| 44 | + }, |
| 45 | +]; |
| 46 | + |
| 47 | +// Server-only libraries: never in the browser client or the shared libraries (R11.1). |
| 48 | +const serverOnlyModules = ["hono", "@hono", "@hocuspocus/server", "kysely", "pg", "pino", "pg-boss", "crossws", "rate-limiter-flexible"]; |
| 49 | +const serverOnlyPatterns = serverOnlyModules.flatMap((m) => [m, `${m}/*`]); |
| 50 | +const serverOnlyMessage = "Server-only library: not allowed here; the browser client and shared libraries stay provider-free (R11.1)."; |
| 51 | +const adapterPackage = (name) => `@tektum/grimoire-adapter-${name}`; |
| 52 | +const adaptersExcept = (name) => ["@tektum/grimoire-adapter-*", `!${adapterPackage(name)}`]; |
| 53 | +const adapterLayerMessage = |
| 54 | + "An adapter may import only @tektum/grimoire-core and its own library: never another adapter or anything under apps/ (R2.18)."; |
| 55 | +const escapeRegex = (s) => s.replace(/[-/]/g, "\\$&"); |
| 56 | +const dynamicRulesFor = (sourceRegex, message) => [ |
| 57 | + { selector: `ImportExpression[source.value=/${sourceRegex}/]`, message }, |
| 58 | + { selector: `CallExpression[callee.name='require'][arguments.0.value=/${sourceRegex}/]`, message }, |
| 59 | + // A template literal without expressions is a plain string: refuse it by module name too. |
| 60 | + { selector: `ImportExpression[source.type='TemplateLiteral'][source.expressions.length=0][source.quasis.0.value.cooked=/${sourceRegex}/]`, message }, |
| 61 | + { |
| 62 | + selector: `CallExpression[callee.name='require'][arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0][arguments.0.quasis.0.value.cooked=/${sourceRegex}/]`, |
| 63 | + message, |
| 64 | + }, |
| 65 | +]; |
| 66 | +const dynamicImportRules = dynamicRulesFor(forbiddenSourceRegex, importMessage); |
| 67 | +const serverOnlyRegex = `^(?:${serverOnlyModules.map(escapeRegex).join("|")})(?:$|[^\\w-])`; |
| 68 | +const appsRegex = "^@tektum\\/grimoire-(?:server|web)(?:$|\\/)"; |
| 69 | +const allAdaptersRegex = "^@tektum\\/grimoire-adapter-"; |
| 70 | +const adapterNames = ["auth-descope", "auth-dev", "auth-fake", "collab-hocuspocus", "config-env", "db-kysely", "logger-json", "markdown-milkdown"]; |
| 71 | + |
| 72 | +// Packages whose imports are restricted the same way: no adapters, no apps, no server-only libraries. |
| 73 | +const noAdaptersNoServerOnly = (message) => ({ |
| 74 | + patterns: [ |
| 75 | + { group: serverOnlyPatterns, message: serverOnlyMessage }, |
| 76 | + { group: ["@tektum/grimoire-adapter-*", "@tektum/grimoire-server", "@tektum/grimoire-server/*", "@tektum/grimoire-web", "@tektum/grimoire-web/*"], message }, |
| 77 | + ], |
| 78 | +}); |
| 79 | +const noAdaptersNoServerOnlySyntax = (message) => [ |
| 80 | + ...dynamicRulesFor(serverOnlyRegex, serverOnlyMessage), |
| 81 | + ...dynamicRulesFor(`${allAdaptersRegex}|${appsRegex}`, message), |
| 82 | +]; |
| 83 | + |
| 84 | +const webMessage = "apps/web may not import adapters or apps/server; it may use @tektum/grimoire-core (contracts are silent, so core is allowed) (R11.1)."; |
| 85 | +const libMessage = "Shared libraries may not import adapters, apps or server-only libraries (R2.18, R11.1)."; |
| 86 | +const composeMessage = |
| 87 | + "Only apps/server/src/composition.ts constructs adapters; elsewhere import adapter packages as types only (contracts section 1, R2.18)."; |
| 88 | + |
| 89 | +// Relative specifiers that name another package's directory (the scan test in packages/core/test/boundaries is the |
| 90 | +// authority: it resolves every relative specifier and fails when it leaves the package). |
| 91 | +const relativeMessage = "Do not reach into another package by a relative path; import it by package name (R2.18)."; |
| 92 | +// Anchored to relative specifiers (`./` or `../`): a bare package subpath such as `crossws/adapters/node` must not match. |
| 93 | +const relativePatterns = [{ regex: "^\\.{1,2}\\/(?:.*\\/)?(?:packages|apps|adapters)(?:\\/|$)", message: relativeMessage }]; |
| 94 | +// Indirect loaders would bypass every import rule: createRequire, process.mainModule, eval and Function. |
| 95 | +const loaderMessage = "Indirect module loading and code evaluation bypass the import rules; use a literal import (R2.18)."; |
| 96 | +// The whole module is banned (not just the name): `import m from "node:module"; m.createRequire` would pass importNames. |
| 97 | +const loaderPaths = ["node:module", "module"].map((name) => ({ name, message: loaderMessage })); |
| 98 | +const restrictedImports = (patterns = [], paths = []) => [ |
| 99 | + "error", |
| 100 | + { paths: [...paths, ...loaderPaths], patterns: [...patterns, ...relativePatterns] }, |
| 101 | +]; |
| 102 | + |
| 103 | +// Only string literals (and expression-free templates, which the module rules above read as strings) may be imported |
| 104 | +// dynamically, so the module rules cannot be bypassed. |
| 105 | +const nonLiteralMessage = "Dynamic import() and require() take a plain string literal, so the import rules can see the module."; |
| 106 | +const nonLiteralRules = [ |
| 107 | + { |
| 108 | + selector: "ImportExpression:not([source.type='Literal']):not([source.type='TemplateLiteral'][source.expressions.length=0])", |
| 109 | + message: nonLiteralMessage, |
| 110 | + }, |
| 111 | + { |
| 112 | + selector: |
| 113 | + "CallExpression[callee.name='require']:not([arguments.0.type='Literal']):not([arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0])", |
| 114 | + message: nonLiteralMessage, |
| 115 | + }, |
| 116 | +]; |
| 117 | +nonLiteralRules.push( |
| 118 | + { selector: "MemberExpression[object.name='process'][property.name='mainModule']", message: loaderMessage }, |
| 119 | + { selector: "MemberExpression[object.name='process'][property.value='mainModule']", message: loaderMessage }, |
| 120 | + { selector: "CallExpression[callee.name='eval']", message: loaderMessage }, |
| 121 | + { selector: "CallExpression[callee.name='Function']", message: loaderMessage }, |
| 122 | + { selector: "NewExpression[callee.name='Function']", message: loaderMessage }, |
| 123 | + { selector: "MemberExpression[object.name='globalThis'][property.name=/^(?:eval|Function)$/]", message: loaderMessage }, |
| 124 | +); |
| 125 | +// Our own code that genuinely imports a computed path (each reasoned here; both are the only such files). |
| 126 | +const nonLiteralExempt = [ |
| 127 | + "packages/adapters/db-kysely/src/index.ts", // loads migration files by path for Kysely's migration provider |
| 128 | + "packages/core/test/boundaries/reference-excluded.test.ts", // imports the repository's vitest.config.js by file URL |
| 129 | +]; |
| 130 | +const scope = (files, imports, syntax, exempt = []) => [ |
| 131 | + { files, ignores: exempt, rules: { "no-restricted-imports": imports, "no-restricted-syntax": ["error", ...syntax, ...nonLiteralRules] } }, |
| 132 | + ...(exempt.length |
| 133 | + ? [{ files: exempt, rules: { "no-restricted-imports": imports, "no-restricted-syntax": ["error", ...syntax] } }] |
| 134 | + : []), |
| 135 | +]; |
| 136 | + |
| 137 | +export default defineConfig([ |
| 138 | + globalIgnores(["reference/**", "**/node_modules/**", "**/dist/**", "**/coverage/**", "packages/core/test/boundaries/fixtures/**"]), |
| 139 | + tseslint.configs.recommended, |
| 140 | + // Every workspace package: no relative reach into other packages, no computed dynamic imports. |
| 141 | + ...scope(["apps/**", "packages/**"], restrictedImports(), [], nonLiteralExempt), |
| 142 | + ...scope( |
| 143 | + ["packages/core/**"], |
| 144 | + restrictedImports( |
| 145 | + [{ group: forbiddenImportPatterns, message: importMessage }], |
| 146 | + [ |
| 147 | + { name: "process", message: envMessage }, |
| 148 | + { name: "node:process", message: envMessage }, |
| 149 | + ], |
| 150 | + ), |
| 151 | + [...envRules, ...dynamicImportRules], |
| 152 | + nonLiteralExempt.filter((f) => f.startsWith("packages/core/")), |
| 153 | + ), |
| 154 | + // Adapters: core and own library only. |
| 155 | + ...adapterNames.flatMap((name) => |
| 156 | + scope( |
| 157 | + [`packages/adapters/${name}/**`], |
| 158 | + restrictedImports([ |
| 159 | + { group: adaptersExcept(name), message: adapterLayerMessage }, |
| 160 | + { group: ["@tektum/grimoire-server", "@tektum/grimoire-server/*", "@tektum/grimoire-web", "@tektum/grimoire-web/*"], message: adapterLayerMessage }, |
| 161 | + ]), |
| 162 | + dynamicRulesFor(`^@tektum\\/grimoire-adapter-(?!${escapeRegex(name)}(?:$|\\/))|${appsRegex}`, adapterLayerMessage), |
| 163 | + nonLiteralExempt.filter((f) => f.startsWith(`packages/adapters/${name}/`)), |
| 164 | + ), |
| 165 | + ), |
| 166 | + // apps/web: no server-only libraries, adapters or apps/server. |
| 167 | + ...scope(["apps/web/**"], restrictedImports(noAdaptersNoServerOnly(webMessage).patterns), noAdaptersNoServerOnlySyntax(webMessage)), |
| 168 | + ...scope( |
| 169 | + ["packages/editor-schema/**", "packages/api-client/**"], |
| 170 | + restrictedImports(noAdaptersNoServerOnly(libMessage).patterns), |
| 171 | + noAdaptersNoServerOnlySyntax(libMessage), |
| 172 | + ), |
| 173 | + // apps/server: adapters only as types, except in composition.ts (the one place adapters are constructed). |
| 174 | + { |
| 175 | + files: ["apps/server/src/**"], |
| 176 | + ignores: ["apps/server/src/composition.ts", "apps/server/src/cli.ts"], |
| 177 | + rules: { |
| 178 | + "no-restricted-imports": restrictedImports([{ group: ["@tektum/grimoire-adapter-*"], allowTypeImports: true, message: composeMessage }]), |
| 179 | + "no-restricted-syntax": ["error", ...dynamicRulesFor(allAdaptersRegex, composeMessage), ...nonLiteralRules], |
| 180 | + }, |
| 181 | + }, |
| 182 | + // composition.ts and cli.ts (the migration command line, a second composition root; reported to the manager in |
| 183 | + // M1-T02c) construct adapters, so only the relative-path and computed-import rules apply to them. |
| 184 | + ...scope(["apps/server/src/composition.ts", "apps/server/src/cli.ts"], restrictedImports(), []), |
| 185 | +]); |
0 commit comments