@rexezuge/tooling 0.0.0-stage → 1.0.1

package/src/eslint.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import { defineRepoLintConfig } from './eslint';
+
+/**
+ * Structural checks on the produced flat config.
+ *
+ * These do not run ESLint — a rule that has to be observed linting is a rule this
+ * suite cannot afford, and the repos' own suites lint their trees. What is asserted
+ * here is the part that is a *decision* rather than a lint result: which paths are
+ * ignored, which rules are errors rather than warnings, and that the boundary table
+ * and the dynamic-`import()` guard agree with each other. A regression in any of
+ * those is a config that silently stops gating something.
+ */
+
+/** The only glob syntax the config uses: `**`, `*`, and `{a,b}` alternation. */
+function globToRegExp(pattern: string): RegExp {
+  const escape = (char: string): string => char.replaceAll(/[$()+.?[\\\]^{|}]/g, String.raw`\$&`);
+  let out = '';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index] as string;
+    if (char === '*' && pattern[index + 1] === '*') {
+      out += '.*';
+      index += 1;
+      if (pattern[index + 1] === '/') index += 1;
+    } else if (char === '*') {
+      out += '[^/]*';
+    } else if (char === '{') {
+      const end = pattern.indexOf('}', index);
+      const alternatives = pattern
+        .slice(index + 1, end)
+        .split(',')
+        .map((alternative) => escape(alternative));
+      out += `(?:${alternatives.join('|')})`;
+      index = end;
+    } else {
+      out += escape(char);
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** Every config object in the array, flattened through any nested arrays. */
+function entries(config: unknown): Array<Record<string, unknown>> {
+  const out: Array<Record<string, unknown>> = [];
+  for (const entry of config as unknown[]) {
+    if (Array.isArray(entry)) {
+      out.push(...entries(entry));
+    } else if (typeof entry === 'object' && entry !== null) {
+      out.push(entry as Record<string, unknown>);
+    }
+  }
+  return out;
+}
+
+/**
+ * True when the entry applies to `path`.
+ *
+ * An entry with no `files` key is global — the prettier block and the plugin presets
+ * are written that way, so a matcher that required `files` would report them as
+ * applying to nothing and the config's most important decision would look absent.
+ */
+function covers(entry: Record<string, unknown>, path: string): boolean {
+  const files = entry['files'];
+  if (!Array.isArray(files)) return true;
+  return files.some((pattern) => typeof pattern === 'string' && globToRegExp(pattern).test(path));
+}
+
+/** Every rule that applies to `path`, later entries winning. */
+function rulesOf(config: unknown, path: string): Record<string, unknown> {
+  const rules: Record<string, unknown> = {};
+  for (const entry of entries(config)) {
+    if (covers(entry, path)) Object.assign(rules, entry['rules']);
+  }
+  return rules;
+}
+
+/** JSON of every rule block in the config. Rules are plain data; plugins are not. */
+function rulesJson(config: unknown): string {
+  return entries(config)
+    .map((entry) => JSON.stringify(entry['rules'] ?? {}))
+    .join('\n');
+}
+
+const config = defineRepoLintConfig({ scope: '@fixture' });
+
+describe('defineRepoLintConfig', () => {
+  it('ignores the generated and build trees but not the test suite', () => {
+    const ignores = (config[0] as { ignores?: string[] }).ignores ?? [];
+    expect(ignores).toContain('apps/api/src/generated/**');
+    expect(ignores).toContain('apps/web/dist/**');
+    // `test/**` is deliberately absent: Edge-Sonic's decision, and the one the
+    // other source repos had the opposite of.
+    expect(ignores.some((pattern) => pattern.startsWith('test/'))).toBe(false);
+  });
+
+  it('makes formatting drift an error, not a warning', () => {
+    // `pnpm run lint` is `eslint --fix --quiet`, and `--quiet` discards warnings: a
+    // `prettier/prettier` warning is a gate that has never run.
+    expect(rulesOf(config, 'src/anything.ts')['prettier/prettier']).toBe('error');
+  });
+
+  it('gives web files browser globals in addition to node globals', () => {
+    // The sources linted apps/web under globals.node only, so window and document
+    // read as undefined globals — and the vitest web config runs those suites under
+    // jsdom, so the lint environment disagreed with the execution environment.
+    const webEntries = entries(config).filter((entry) => covers(entry, 'apps/web/src/main.tsx'));
+    const browser = webEntries
+      .map((entry) => Object.keys((entry as { languageOptions?: { globals?: Record<string, unknown> } }).languageOptions?.globals ?? {}))
+      .flat();
+    expect(browser).toContain('window');
+    expect(browser).toContain('document');
+    // And the node globals survive: a shared file touching both still lints.
+    expect(browser).toContain('process');
+  });
+
+  it('keeps the three plugin families on', () => {
+    // sonarjs / unicorn / regexp are each a preset spread into the array; a preset
+    // that failed to import would leave the array without their rule blocks.
+    const all = rulesJson(config);
+    expect(all).toContain('unicorn/');
+    expect(all).toContain('sonarjs/');
+    expect(all).toContain('regexp/');
+  });
+
+  it('parameterizes the boundary rules by scope', () => {
+    const rules = rulesJson(config);
+    expect(rules).toContain('@fixture/backend-data');
+    expect(rules).not.toContain('@durable-dav/backend-data');
+  });
+
+  it('bans a backend package from the SPA, with a message that says why', () => {
+    const rules = rulesJson(config);
+    expect(rules).toContain('ships zero backend dependencies');
+  });
+
+  it('mirrors every boundary in a dynamic-import guard', () => {
+    const syntax = rulesOf(config, 'packages/backend-runtime/src/x.ts')['no-restricted-syntax'];
+    expect(Array.isArray(syntax)).toBe(true);
+    // `no-restricted-imports` reads ImportDeclaration only, so the same boundary has
+    // to be stated for ImportExpression too — that hole was load-bearing in
+    // Edge-Sonic, where the credential path reached a banned module through it.
+    expect(JSON.stringify(syntax)).toContain("ImportExpression[source.type='Literal']");
+    expect(JSON.stringify(syntax)).toContain('@fixture/backend-data');
+  });
+
+  it('relaxes the Vitest idioms in tests but not the correctness rules', () => {
+    const rules = rulesOf(config, 'test/schema.test.ts');
+    expect(rules['@typescript-eslint/unbound-method']).toBe('off');
+    expect(rules['unicorn/prefer-https']).toBe('off');
+    expect(rules['sonarjs/no-clear-text-protocols']).toBe('off');
+    // Unused variables stay on in tests, at exactly the severity the product
+    // source gets: a dead fake is a defect, not an artefact of test shape.
+    expect(rules['@typescript-eslint/no-unused-vars']).toStrictEqual(
+      rulesOf(config, 'src/anything.ts')['@typescript-eslint/no-unused-vars'],
+    );
+  });
+
+  it('accepts extra layers without losing the canonical ones', () => {
+    const extended = defineRepoLintConfig({
+      scope: '@fixture',
+      extraLayers: [
+        {
+          dir: 'apps/api/src/endpoints',
+          ban: ['@fixture/backend-data/dao'],
+          allowTypeImports: true,
+          message: 'route classes must not import DAOs directly',
+        },
+      ],
+    });
+    const rules = rulesJson(extended);
+    expect(rules).toContain('route classes must not import DAOs directly');
+    expect(rules).toContain('zero-dependency base layer');
+    expect(rules).toContain('ships zero backend dependencies');
+  });
+});

package/src/eslint.ts

@@ -0,0 +1,257 @@
+/**
+ * The converged ESLint flat config for a monorepo in the Rexezuge family.
+ *
+ * Provenance: the base is Durable-DAV's `eslint.config.mjs` (380+ lines, the most
+ * elaborate of the nine repos, with the layered `no-restricted-imports` boundary
+ * rules). Merged in from the other three stacks that share the same plugin set:
+ *
+ * - **Edge-Sonic** — `test/**` is *not* ignored (it is linted like everything else,
+ *   with a narrow override block for Vitest idioms), and `unicorn/prefer-ternary`
+ *   is off. Edge-Sonic is also the source for the dynamic-`import()` boundary
+ *   guard and its `apps/web` layer block.
+ * - **Mail-Meow** — `prettier/prettier` is an **error**, not a warning.
+ * - **AWS-AccessBridge** — the `apps/api` DAO/service boundary uses
+ *   `allowTypeImports` where the source repos do not. It is also the source for
+ *   the anchored skip patterns and the symlink-safe walk that came out of its own
+ *   backlog.
+ *
+ * Canonical decisions, and why each one:
+ *
+ * 1. **`prettier/prettier: 'error'`.** Three of the four source repos had it at
+ *    `warn`, which under `eslint --quiet` is unenforceable — a gate nobody can see
+ *    is a gate that has never run. Formatting drift is therefore a hard failure.
+ * 2. **The layered boundary rules are parameterized by `scope`.** Every source
+ *    repo wrote the same seven blocks with a different npm scope hardcoded; the
+ *    factory takes `scope` (`'@myapp'`) and generates the `@myapp/*` patterns.
+ *    The table itself lives in {@link ./eslint-boundaries}.
+ * 3. **`test/**` is linted, not ignored.** Durable-DAV/AWS/Mail-Meow ignored it;
+ *    Edge-Sonic does not, and records why: ~200 KB of test code had accumulated
+ *    violations that nothing reported.
+ * 4. **`apps/web` is a layer in its own right**, banned from every `@scope/*`
+ *    package. Edge-Sonic is the only source with that block; the others had none,
+ *    which is how their layer table's "may import: the browser" was a convention
+ *    rather than a gate. A backend package imported by the SPA compiles and then
+ *    fails at bundle time, with the error pointing at the bundler.
+ * 5. **jsdom + node globals for web files.** The sources ran `globals.node` only;
+ *    `apps/web` needs browser globals as well, and the vitest config for the SPA
+ *    runs under jsdom, so the lint environment matches the test environment.
+ * 6. **`eslint-plugin-react-hooks` is NOT imported here.** The kit stays
+ *    zero-dependency, and the plugin belongs to the app that has JSX. A consumer
+ *    appends it — the README shows the four lines.
+ *
+ * The rule bodies live in {@link ./eslint-rules} and the boundary table in
+ * {@link ./eslint-boundaries}; this file is the assembly. A repo that needs a
+ * boundary the canonical table does not name passes `extraLayers` — see
+ * {@link RepoLintConfigOptions}.
+ */
+
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import unicorn from 'eslint-plugin-unicorn';
+import { configs as sonarjsConfigs } from 'eslint-plugin-sonarjs';
+import pluginRegexp from 'eslint-plugin-regexp';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import prettier from 'eslint-plugin-prettier';
+import type { FlatConfig } from 'typescript-eslint';
+import { DEFAULT_PROJECT_DIRS, layerBans, restrictedDynamicImports, restrictedImports } from './eslint-boundaries';
+import type { LayerBan } from './eslint-boundaries';
+import { SONARJS_RULES, TEST_RULES, TYPESCRIPT_RULES, UNICORN_RULES } from './eslint-rules';
+
+/**
+ * What `defineRepoLintConfig` accepts.
+ */
+export interface RepoLintConfigOptions {
+  /**
+   * The consuming repo's npm scope, e.g. `'@myapp'`. Every `no-restricted-imports`
+   * pattern in the boundary rules is derived from it, so the same factory serves
+   * all nine repos.
+   */
+  readonly scope: string;
+  /**
+   * The workspace directories the layered boundary rules are scoped to, as repo-
+   * relative globs. Defaults to the canonical layout the nine repos share.
+   */
+  readonly projectDirs?: readonly string[];
+  /**
+   * Extra ignore globs, merged with the canonical set.
+   */
+  readonly extraIgnores?: readonly string[];
+  /**
+   * Where `projectService` resolves the tsconfig from. Defaults to the directory
+   * ESLint is invoked in, which is the repo root in every CI job.
+   */
+  readonly tsconfigRootDir?: string;
+  /**
+   * Extra boundary layers, appended to the canonical table.
+   *
+   * The escape valve for a repo whose layout has a boundary the canonical table
+   * does not name — AWS-AccessBridge's `apps/api/src/endpoints/**` rule ("route
+   * classes must not import DAOs directly") and its `aws4fetch` ban are the shape.
+   * Same {@link LayerBan} form, so `extraLayers` flows through the
+   * `no-restricted-imports` and the `no-restricted-syntax` guard alike.
+   */
+  readonly extraLayers?: readonly LayerBan[];
+}
+
+/**
+ * One argument to `tseslint.config()`.
+ */
+type ConfigInput = Parameters<typeof tseslint.config>[number];
+
+/**
+ * A plugin preset or config object as the source repos pass it.
+ */
+type MaybeConfig = FlatConfig.Config | readonly FlatConfig.Config[];
+
+/**
+ * Bridge a third-party preset into `tseslint.config()`.
+ *
+ * `sonarjs`' `recommended` preset is typed as a union that includes the legacy
+ * config shape, which `tseslint.config()` does not accept — but ESLint accepts it
+ * at runtime, which is the only thing that matters here. One checked assertion,
+ * rather than forking the plugin's own types.
+ */
+function asConfig(config: MaybeConfig): ConfigInput {
+  return config as ConfigInput;
+}
+
+/**
+ * Bridge a rule block onto `tseslint.config()`'s `rules` field.
+ *
+ * The blocks in `eslint-rules.ts` are written as ESLint expects them —
+ * `'off' | 'warn' | 'error' | [level, ...options]` — but spelled as data so a
+ * rule's reason comment sits beside the rule itself. ESLint's own `RuleEntry`
+ * union is narrower than the data shape, and widening every entry to that union
+ * would buy nothing; one assertion here, with the reason, is the cheaper and
+ * more honest of the two.
+ */
+function asRules(block: Readonly<Record<string, unknown>>): FlatConfig.Config['rules'] {
+  return block as FlatConfig.Config['rules'];
+}
+
+/**
+ * Build the repo's flat config.
+ *
+ * Consumed from the repo root as three lines:
+ *
+ * ```js
+ * // eslint.config.mjs
+ * import { defineRepoLintConfig } from '@rexezuge/tooling/eslint';
+ * export default defineRepoLintConfig({ scope: '@myapp' });
+ * ```
+ */
+export function defineRepoLintConfig(options: RepoLintConfigOptions): FlatConfig.ConfigArray {
+  const { scope } = options;
+  const projectDirs = options.projectDirs ?? DEFAULT_PROJECT_DIRS;
+  const canonical = layerBans(scope).filter((layer) => projectDirs.some((dir) => layer.dir.startsWith(dir)));
+  const extra = options.extraLayers ?? [];
+  const bans = [...canonical, ...extra];
+
+  return tseslint.config(
+    {
+      ignores: [
+        'eslint.config.mjs',
+        'eslint.config.js',
+        'scripts/**',
+        'worker-configuration.d.ts',
+        'local/**',
+        'app/dist/**',
+        'apps/web/dist/**',
+        'apps/*/dist/**',
+        'src/generated/**',
+        'apps/api/src/generated/**',
+        'coverage/**',
+        'coverage-integration/**',
+        'coverage-web/**',
+        'node_modules/**',
+        ...(options.extraIgnores ?? []),
+      ],
+    },
+
+    // Base: globals for all JS/TS source files. Node is the floor because the
+    // scripts and the workers both run on it; the web block below adds browser
+    // globals rather than replacing them, so a shared file that touches both
+    // (there are several in `shared/`) still lints.
+    {
+      files: ['**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}'],
+      languageOptions: {
+        globals: globals.node,
+      },
+    },
+
+    // Type-aware TS rules, scoped to TS files only.
+    {
+      files: ['**/*.{ts,mts,cts,tsx}'],
+      extends: tseslint.configs.recommendedTypeChecked,
+      languageOptions: {
+        parserOptions: {
+          projectService: true,
+          tsconfigRootDir: options.tsconfigRootDir ?? process.cwd(),
+        },
+      },
+    },
+
+    // --- typescript-eslint overrides (identical in all four source stacks) ---
+    {
+      files: ['**/*.{ts,mts,cts,tsx}'],
+      rules: asRules(TYPESCRIPT_RULES),
+    },
+
+    // --- Unicorn: modern JS/TS quality rules ---
+    asConfig(unicorn.configs['flat/recommended']),
+    {
+      rules: asRules(UNICORN_RULES),
+    },
+
+    // --- SonarJS: code smell and bug detection ---
+    asConfig(sonarjsConfigs.recommended),
+    {
+      rules: asRules(SONARJS_RULES),
+    },
+
+    // --- Regexp: static analysis for regular expressions ---
+    asConfig(pluginRegexp.configs['flat/recommended']),
+
+    // --- Prettier: formatting drift is a hard error ---
+    //
+    // Mail-Meow's decision, adopted repo-wide because the alternative is
+    // unenforceable: `pnpm run lint` is `eslint --fix --quiet` in three of the
+    // four source repos, and `--quiet` discards every warning, so a
+    // `prettier/prettier` *warning* is a silent no-op. 242 files were in that
+    // state in Edge-Sonic: the gate had never run.
+    asConfig(eslintConfigPrettier),
+    {
+      plugins: { prettier },
+      rules: {
+        'prettier/prettier': 'error',
+      },
+    },
+
+    // --- Import direction guardrails (parameterized by scope) ---
+    ...restrictedImports(bans),
+    ...restrictedDynamicImports(bans),
+
+    // --- Web: browser globals, matching the jsdom test environment ---
+    //
+    // The sources linted `apps/web` under `globals.node` only, so `window`,
+    // `document` and `localStorage` read as undefined globals. The vitest web
+    // config runs those suites under jsdom; the lint environment should agree
+    // with the environment the code is executed in, or the rule is reporting
+    // something untrue about how the file behaves.
+    {
+      files: ['apps/web/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}'],
+      languageOptions: {
+        globals: { ...globals.node, ...globals.browser },
+      },
+    },
+
+    // --- Test suite ---
+    //
+    // `test/**` is deliberately NOT in the ignores list above. See TEST_RULES
+    // for the override block and the reasoning behind it.
+    {
+      files: ['test/**/*.{ts,tsx,mts,cts}', '**/*.test.{ts,tsx,mts,cts}', '**/*.spec.{ts,tsx,mts,cts}'],
+      rules: asRules(TEST_RULES),
+    },
+  );
+}

package/src/functions/pages-proxy.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { createPagesProxy } from './pages-proxy';
+import type { PagesProxyEnv } from './pages-proxy';
+
+function fakeEnv(): { env: PagesProxyEnv; seen: { url: string; method: string; headers: Headers; body: string | null }[] } {
+  const seen: { url: string; method: string; headers: Headers; body: string | null }[] = [];
+  const env: PagesProxyEnv = {
+    API_WORKER: {
+      async fetch(request: Request): Promise<Response> {
+        seen.push({
+          url: request.url,
+          method: request.method,
+          headers: new Headers(request.headers),
+          body: request.method === 'GET' || request.method === 'HEAD' ? null : await request.text(),
+        });
+        return new Response('ok', { status: 200 });
+      },
+    },
+  };
+  return { env, seen };
+}
+
+const onRequest = createPagesProxy();
+
+describe('createPagesProxy', () => {
+  it('forwards the URL verbatim and rewrites the three X-Forwarded headers', async () => {
+    const { env, seen } = fakeEnv();
+    const request = new Request('https://pages.example.com/user/volumes?page=2', { method: 'GET' });
+    const response = await onRequest({ request, env } as never);
+    expect(response.status).toBe(200);
+    expect(seen[0]?.url).toBe('https://pages.example.com/user/volumes?page=2');
+    expect(seen[0]?.headers.get('X-Forwarded-Host')).toBe('pages.example.com');
+    expect(seen[0]?.headers.get('X-Forwarded-Proto')).toBe('https');
+    expect(seen[0]?.headers.get('X-Forwarded-Uri')).toBe('/user/volumes?page=2');
+  });
+
+  it('forwards a body for non-GET/HEAD', async () => {
+    const { env, seen } = fakeEnv();
+    await onRequest({
+      request: new Request('https://pages.example.com/user/volumes', { method: 'PUT', body: '{"a":1}' }),
+      env,
+    } as never);
+    expect(seen[0]?.body).toBe('{"a":1}');
+  });
+
+  it('replaces X-Forwarded-For from CF-Connecting-IP, never trusting a caller value', async () => {
+    const { env, seen } = fakeEnv();
+    // The client IP arrives as a request header (the edge sets it), and any
+    // caller-supplied X-Forwarded-For must be displaced by it, never kept.
+    const headers = new Headers({ 'X-Forwarded-For': '1.2.3.4', 'CF-Connecting-IP': '9.9.9.9' });
+    await onRequest({ request: new Request('https://pages.example.com/', { headers }), env } as never);
+    expect(seen[0]?.headers.get('X-Forwarded-For')).toBe('9.9.9.9');
+  });
+
+  it('strips hop-by-hop and client-forwarding headers', async () => {
+    const { env, seen } = fakeEnv();
+    const headers = new Headers({
+      Connection: 'keep-alive',
+      'Proxy-Authorization': 'Basic x',
+      Forwarded: 'for=1.2.3.4',
+      'X-Real-Ip': '1.2.3.4',
+      'True-Client-IP': '1.2.3.4',
+    });
+    await onRequest({ request: new Request('https://pages.example.com/', { headers }), env } as never);
+    const forwarded = seen[0]?.headers;
+    expect(forwarded?.get('Connection')).toBeNull();
+    expect(forwarded?.get('Proxy-Authorization')).toBeNull();
+    expect(forwarded?.get('Forwarded')).toBeNull();
+    expect(forwarded?.get('X-Real-Ip')).toBeNull();
+    expect(forwarded?.get('True-Client-IP')).toBeNull();
+  });
+});