@evertondgn/solid-tooling 0.3.0 → 0.4.0

package/README.md

@@ -1,9 +1,11 @@
 # @evertondgn/solid-tooling
 
-Lint preset, formatter config, TypeScript configs and test configs for SolidJS 2
-applications built with [Vite+](https://viteplus.dev/guide/).
+Lint preset, formatter config, TypeScript configs, test configs, the Knip and
+Stylelint configs and the Vite+ application config for SolidJS 2 applications
+built with [Vite+](https://viteplus.dev/guide/).
 
-The package contains the lint, format, TypeScript and test setup of
+The package contains the lint, format, TypeScript, test, build, dead code and
+CSS lint setup of
 [boilerplate_solidjs](https://github.com/everton-dgn/boilerplate_solidjs), a
 SolidJS application template. Applications created from it install the package
 instead of copying the files, so a rule change reaches them through a version
@@ -24,15 +26,24 @@ exact versions the package is tested with. Install the versions listed in its
 `peerDependencies`. `typescript` is not a peer dependency: the package is tested
 with the version in its `devDependencies`.
 
-`eslint-plugin-solid` comes with the package, so the application does not
-declare it.
+`eslint-plugin-solid`, `stylelint` and `stylelint-use-nesting` come with the
+package, so the application does not declare them.
 
-The test entries need the test tools the application already runs:
+Some entries need tools the application already runs:
 
-| Entry          | The application installs                                                       |
-| -------------- | ------------------------------------------------------------------------------ |
-| `./vitest`     | `@vitest/browser-playwright`, `@vitest/coverage-v8`, `happy-dom`, `playwright` |
-| `./playwright` | `@playwright/test`, an optional peer dependency pinned like the others         |
+| Entry          | The application installs                                                        |
+| -------------- | ------------------------------------------------------------------------------- |
+| `./vitest`     | `@vitest/browser-playwright`, `@vitest/coverage-v8`, `happy-dom`, `playwright`  |
+| `./playwright` | `@playwright/test`, an optional peer dependency pinned like the others          |
+| `./knip`       | `knip` and `filesystem-routing`, optional peer dependencies pinned the same way |
+
+`./vite` also needs the test tools of `./vitest`, and loads four plugin
+packages: `@solidjs/vite-plugin`, `nitro`, `filesystem-routing` and
+`unplugin-icons`. They are optional peer dependencies pinned like the others.
+Install the versions listed in `peerDependencies` as direct dependencies of the
+application: Bun applies `overrides` and `patchedDependencies` only from the
+root `package.json`, and the Knip plugin of `unplugin-icons` only turns on with
+a direct dependency.
 
 ## Install
 
@@ -86,12 +97,20 @@ projects:
 | `dom`     | `src/**/*.dom.test.{ts,tsx}`     | happy-dom at `http://localhost/en`               |
 | `browser` | `src/**/*.browser.test.{ts,tsx}` | Chromium through Playwright, with the CSS loaded |
 
+`defineSolidApp` from `./vite` already calls `solidTest`. An application that
+builds its own Vite config calls it directly:
+
 ```ts
 // vite.config.ts
 import { solidTest } from '@evertondgn/solid-tooling/vitest'
+import solid from '@solidjs/vite-plugin'
+import { defineConfig } from 'vite-plus'
 
 export default defineConfig({
-  test: solidTest({ root: import.meta.dirname, plugins: componentPlugins })
+  test: solidTest({
+    root: import.meta.dirname,
+    plugins: () => [solid({ serverFunctions: true })]
+  })
 })
 ```
 
@@ -106,7 +125,8 @@ before each browser test.
 The `node` project does not load the Solid and routing plugins, so a plugin of
 the preset serves `server-only`, `virtual:file-routes` and
 `virtual:solid-server-function-handler`. Knip does not know `server-only`, a
-virtual module of `@solidjs/vite-plugin`: list it in `ignoreDependencies`.
+virtual module of `@solidjs/vite-plugin`: pass it in the `ignoreDependencies` of
+[`defineKnipConfig`](#knip).
 
 `definePlaywrightConfig` builds the Playwright config from the application root:
 
@@ -132,6 +152,257 @@ Each serial suite gets its own project: `markdown` runs with one worker,
 `serverLogs` runs last as the teardown of the others, and `publicationLoad` runs
 alone, against two servers, with `TEST_PUBLICATION_LOAD=true`.
 
+## Application config
+
+`defineSolidApp` returns the whole `vite.config.ts` of a boilerplate
+application: the Solid, routing, icons and Nitro plugins, the headers of the
+static files, the build, CSS, server and preview blocks, the `vp run` tasks, and
+`lint`, `fmt` and `test` from the presets above.
+
+```ts
+// vite.config.ts
+import { defineSolidApp } from '@evertondgn/solid-tooling/vite'
+
+import { SECURITY_HEADERS } from './src/middleware/securityHeaders/constants.ts'
+
+export default defineSolidApp({
+  root: import.meta.dirname,
+  middleware: './src/middleware/index.ts',
+  securityHeaders: SECURITY_HEADERS,
+  staticPaths: ['/favicon/**']
+})
+```
+
+| Option            | Default                 | Use                                                                                                                              |
+| ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `root`            | required                | Application folder. `.env`, `.env.test`, `project.inlang/settings.json` and the icon folders resolve from it                     |
+| `securityHeaders` | required                | Values of `strict-transport-security`, `x-content-type-options` and `cross-origin-resource-policy` for the static files          |
+| `middleware`      | none                    | `start.middleware` of the Solid plugin. It has to sit inside the application folder                                              |
+| `serverSetup`     | `serverFunctions: true` | `serverFunctions.serverSetup` of the Solid plugin                                                                                |
+| `e2e`             | production paths        | `{ middleware, routes }` for `--mode e2e`: the middleware chain and the route folder of the fixtures, without route types        |
+| `icons`           | none                    | Own `unplugin-icons` collections, as name to folder                                                                              |
+| `publicAssets`    | none                    | `publicAssets` of Nitro. Each entry needs a `baseURL`, which also gets the static headers                                        |
+| `staticPaths`     | none                    | Other static paths that get the headers, such as `/favicon/**`                                                                   |
+| `routeRules`      | none                    | More Nitro route rules, applied after the static ones. A rule with the same path replaces the static one                         |
+| `extend`          | none                    | `(context) => ({ plugins, nitroModules })`, for plugins and Nitro modules the application still owns                             |
+| `tasks`           | none                    | Adds or replaces `vp run` tasks by name                                                                                          |
+| `workspace`       | none                    | `{ dependsOn, inputs }` for an application inside a monorepo, whose `bun.lock`, `bunfig.toml` and package builds sit at the root |
+
+The preset fixes the rest:
+
+- Plugins, in this order: the `extend` plugins, `unplugin-icons` (Solid
+  compiler, `aria-hidden` on every icon), `@solidjs/vite-plugin` with SSR and
+  server functions, `filesystem-routing` with HTTP methods and the route types
+  in `src/@types/routes.d.ts`, and Nitro with the `vercel` preset. The `dom` and
+  `browser` test projects get the `extend` plugins, the icons, Solid with server
+  functions only and the routes. The `test` mode loads no application plugin and
+  reads `.env.test` into `process.env`.
+- The static headers go to `/assets/**`, each `publicAssets` folder, the
+  `staticPaths`, `/<locale>/**.md` for each locale of
+  `project.inlang/settings.json`, `/llms.txt`, `/llms-full.txt`, `/sitemap.xml`,
+  `/sitemaps/pages/**` and `/_markdown/static.json`. The static files leave the
+  CDN without going through the middleware, so these rules give them the headers
+  the middleware writes on the other responses.
+- `build.manifest` only in the `e2e` mode, which the `TEST_PREBUILT` check of
+  `./playwright` relies on, and no comments in the output.
+- Lightning CSS, with CSS Modules classes named `[content-hash]_[local]`.
+- `resolve.tsconfigPaths`, and the dev server and the preview on the `HOST` and
+  `PORT` of `.env`. The dev server forwards the browser console to the terminal.
+
+The plugins are imported inside `lazyPlugins`, so `vp lint`, `vp fmt` and
+`vp check` read the config without loading them.
+
+Nitro compiles the route rules with the `preMerge` of h3, which refuses rules
+that overlap in part, such as `/pt/blog/**` next to `/pt/**.md`, and falls back
+to its simple mode, with the same result and a warning. `defineSolidApp` throws
+when a `publicAssets` entry has no `baseURL`, or one with a trailing slash, and
+when a static path does not start with `/`. Build, dev and preview fail to load
+the plugins when a `publicAssets` folder or a static path sits inside a locale
+folder.
+
+### `extend`
+
+`extend` runs inside `lazyPlugins`: once for the application in build, dev and
+preview (`target: 'app'`), and once for each test project with a Vite server
+(`target: 'test'`). Every load of the config calls it again, so a build also
+calls it for the two test projects, whose plugins Vite does not use; keep side
+effects out of it. It never runs while Vite+ only reads the config. Return new
+plugin instances on each call. The `plugins` go before the fixed ones, and the
+`nitroModules` go to Nitro; the `test` target ignores them. One call returns
+both, so a value that a plugin and a module share, such as a build id, stays the
+same.
+
+```ts
+export default defineSolidApp({
+  root: import.meta.dirname,
+  securityHeaders: SECURITY_HEADERS,
+  async extend() {
+    const { i18nPlugin } = await import('./tooling/i18n/i18nPlugin/index.ts')
+    return { plugins: [i18nPlugin()] }
+  }
+})
+```
+
+### Tasks
+
+| Task                | Command                                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `i18n-generate`     | `bun tooling/i18n/generate.ts`                                                                          |
+| `lint-css`          | `bun tooling/css/check.ts`                                                                              |
+| `dead-code-project` | `knip-bun --config tooling/knip.ts`, then again with `--strict`                                         |
+| `lint-project`      | `vp lint`, after `lint-css`                                                                             |
+| `check-project`     | `vp fmt --check && vp lint`, after `lint-css`                                                           |
+| `typecheck-node`    | `tsc --project tsconfig.node.json`                                                                      |
+| `test-tooling`      | `node --test` over `tooling/**/__tests__` except `tooling/release/`, three workers on CI, with no cache |
+
+The commands run the scripts of the boilerplate layout. An application without
+one of them replaces the task through `tasks`. Knip reads task commands only
+from a `run.tasks` block written in `vite.config.ts`, so it does not see these:
+list the scripts they run as Knip entries.
+
+With `workspace`, the cache inputs read `bun.lock`, `bunfig.toml` and the
+`inputs` from the workspace root, and `lint-css`, `dead-code-project` and
+`typecheck-node` depend on the tasks in `dependsOn`:
+
+```ts
+workspace: {
+  dependsOn: ['@evertondgn/solid-tooling#build'],
+  inputs: ['packages/solid-tooling/dist/**']
+}
+```
+
+### Changing the result
+
+Wrap the result in `defineConfig` and merge what the application needs. Vite+
+removes the plugins it injected before it injects them again, so they are not
+duplicated:
+
+```ts
+import { defineSolidApp } from '@evertondgn/solid-tooling/vite'
+import { defineConfig, mergeConfig } from 'vite-plus'
+
+const app = defineSolidApp({ root: import.meta.dirname, securityHeaders })
+
+export default defineConfig(env =>
+  mergeConfig(app(env), { server: { strictPort: true } })
+)
+```
+
+## Knip
+
+`defineKnipConfig` returns the Knip config of the application as a function, the
+form Knip accepts as the default export of its config file:
+
+```ts
+// tooling/knip.ts
+import path from 'node:path'
+
+import { defineKnipConfig } from '@evertondgn/solid-tooling/knip'
+
+export default defineKnipConfig({
+  root: path.resolve(import.meta.dirname, '..'),
+  ignoreDependencies: ['server-only']
+})
+```
+
+Run it with `knip-bun --config tooling/knip.ts`, then with `--strict`. The
+config lists:
+
+- `src/entry-server.tsx`, `src/entry-client.tsx`, `src/middleware/index.ts`,
+  `env.ts` and `paraglide/runtime.js` as production entries. The Solid plugin
+  and the Paraglide runtime load them by path, and Knip does not read the Solid
+  plugin when `vite.config.ts` imports it with `import()`, as `./vite` does. An
+  application that imports `solid()` statically, with `start`, passes
+  `solidPluginImport: 'static'`: Knip's Solid plugin then finds the first four
+  itself, and listing them again would be a configuration hint.
+- Every page and HTTP handler that `filesystem-routing` finds in `src/routes/`,
+  as production entries, and in `src/tests/fixtures/routes/` and
+  `src/tests/fixtures/e2e/routes/`, as test entries. The `filesystem-routing`
+  plugin of Knip is turned off, because it takes every file of `src/routes/` as
+  an entry and would hide unused helpers next to the routes.
+- `src/**/*.{ts,tsx}` and `tooling/**/*.ts` as the project, with the tests out
+  of the production files.
+
+The config turns on `treatConfigHintsAsErrors`, and Knip reports an entry or a
+project pattern without files as a configuration hint. So each default above
+enters only when the application has the file or the folder.
+
+| Option               | Default           | Use                                                            |
+| -------------------- | ----------------- | -------------------------------------------------------------- |
+| `root`               | required          | The application folder                                         |
+| `configFile`         | `tooling/knip.ts` | Path of the config file, relative to `root`                    |
+| `entry`              | none              | More entries, such as a public API that only test fixtures use |
+| `solidPluginImport`  | `'lazy'`          | `'static'` when `vite.config.ts` imports `solid()` statically  |
+| `ignoreBinaries`     | none              | Passed to Knip as is                                           |
+| `ignoreDependencies` | none              | Passed to Knip as is                                           |
+| `ignoreIssues`       | none              | Passed to Knip, merged with the entry for `configFile`         |
+| `exclude`            | none              | Issue types to leave out, such as `catalogReferences`          |
+
+Knip adds the file given to `--config` to the entries in production mode, and
+`--strict` only accepts `dependencies` there, so it reports this package as an
+unlisted dependency of the config file. The config ignores `unlisted` issues in
+`configFile` only: an import of this package from `src/` is still reported. An
+application that keeps the config somewhere else passes its path in
+`configFile`.
+
+Nothing that depends on the application is a default. An ignore that matches
+nothing is a configuration hint too, so `server-only` and the binaries of the
+scripts are options. For a key without an option, wrap the function:
+
+```ts
+const configure = defineKnipConfig({ root })
+
+export default async function configureKnip() {
+  return { ...(await configure()), ignoreUnresolved: ['virtual:example'] }
+}
+```
+
+## CSS lint
+
+`checkCss(root)` lints `src/**/*.css` with Stylelint and the CSS policy of the
+boilerplate, and checks the name of every CSS file in `src/` as
+`project/css-filename` does for imports: `styles.module.css`, or `camelCase.css`
+inside `src/theme/`. It returns the report and whether anything failed:
+
+```ts
+// tooling/css/check.ts
+import path from 'node:path'
+import process from 'node:process'
+
+import { checkCss } from '@evertondgn/solid-tooling/stylelint'
+
+const { report, hasErrors } = await checkCss(
+  path.resolve(import.meta.dirname, '../..')
+)
+
+process.stdout.write(report)
+if (hasErrors) process.exitCode = 1
+```
+
+`defineStylelintConfig(root)` returns the Stylelint config that `checkCss` uses.
+The policy:
+
+- Classes use snake_case, nesting goes at most two levels deep, and adjacent
+  state selectors and media queries are nested (`stylelint-use-nesting`).
+- Unknown or invalid properties, values, units, selectors, at-rules and media
+  features are errors, as are deprecated and unmatchable selectors.
+- Outside `src/theme/`, colors, gradients, radii, shadows, font sizes and
+  weights and `z-index` come from tokens with `var()`, from the matching token
+  family. Literal colors, color functions and system colors are errors.
+- Inside `src/theme/`, the token rules are off, so the theme can define the
+  values with `oklch()`, `oklab()`, `color-mix()`, `light-dark()` and system
+  colors. Hex, named colors and the `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`
+  and `color()` functions are still errors there.
+- `var()` and animation names resolve against `src/theme/tokens/**/*.css` and
+  `src/theme/class/animation.css`. Stylelint stops the whole run when a
+  reference matches no file, so each one is passed only when it exists.
+- An exception needs a `stylelint-disable` comment with the reason after `--`.
+
+`stylelint` and `stylelint-use-nesting` are dependencies of this package. The
+config passes the plugin by a path resolved from the package, because Stylelint
+looks up a plugin name from the application and its working directory, where it
+is not installed.
+
 ## Project layout the preset expects
 
 The rules match file paths relative to the folder where lint runs, so run it
@@ -275,6 +546,7 @@ overrides: [
 | `./fmt`                  | `fmt`: the formatter config                                               |
 | `./tsconfig.base.json`   | Compiler options, without application paths                               |
 | `./tsconfig.app.json`    | The base plus the `types` and `include` of the boilerplate layout         |
+| `./vite`                 | `defineSolidApp(options)`, the whole `vite.config.ts` of an application   |
 | `./vitest`               | `solidTest(options)`, the `test` block of `vite.config.ts`                |
 | `./playwright`           | `definePlaywrightConfig(options)`, the Playwright config                  |
 | `./vitest-setup/browser` | Setup file of the browser project, loaded by `./vitest`                   |
@@ -284,11 +556,14 @@ overrides: [
 | `./architecture-plugin`  | The `architecture` rule                                                   |
 | `./solid-plugin`         | Re-export of `eslint-plugin-solid`                                        |
 | `./css-filename`         | `cssFilenameError(path)`, the CSS naming check, for a script outside lint |
+| `./knip`                 | `defineKnipConfig(options)`, the Knip config                              |
+| `./stylelint`            | `checkCss(root)` and `defineStylelintConfig(root)`, the CSS lint          |
 
-An application imports `./lint`, `./fmt`, `./vitest`, `./playwright` and one of
-the TypeScript configs. The plugin entries exist because Oxlint loads plugins by
-specifier, from the application; the setup and teardown entries are loaded by
-the test presets.
+An application imports `./vite`, which brings `./lint`, `./fmt` and `./vitest`
+along, `./playwright`, `./knip`, `./stylelint` and one of the TypeScript
+configs. An application that only lints imports `./lint` and `./fmt`. The plugin
+entries exist because Oxlint loads plugins by specifier, from the application;
+the setup and teardown entries are loaded by the test presets.
 
 ## Formatter
 
@@ -348,6 +623,15 @@ break the `@/` imports of the end-to-end tests.
   (`.node.test`, `.dom.test`, `.browser.test`, `.e2e.test`), page tests in
   `src/tests/pages/`, Paraglide output in `paraglide/` and `.env.test` at the
   root.
+- The Knip and CSS configs expect the same layout: pages in `src/routes/`,
+  fixture routes in `src/tests/fixtures/` and the theme in `src/theme/`.
+- The Knip config ignores every unlisted dependency in its own file, not only
+  this package.
+- `./vite` expects the same layout: its tasks run scripts in `tooling/`, and the
+  Markdown rules need the locale prefix of the Paraglide `urlPatterns` in every
+  URL. Nitro always uses the `vercel` preset. The plugin packages are pinned, so
+  a new version of Solid, Nitro, the router or the icons plugin needs a package
+  version tested with it.
 
 ## Versions
 

package/dist/has-match-BITlj0EE.mjs

@@ -0,0 +1,9 @@
+import { glob } from "node:fs/promises";
+// src/has-match.ts
+async function hasMatch({ root, pattern }) {
+	const matches = glob(pattern, { cwd: root });
+	const { done } = await matches.next();
+	await matches.return?.();
+	return !done;
+}
+export { hasMatch as t };

package/dist/knip.d.mts

@@ -0,0 +1,12 @@
+import { KnipConfiguration } from "knip";
+type AppSettings = Pick<KnipConfiguration, 'ignoreBinaries' | 'ignoreDependencies' | 'ignoreIssues' | 'exclude'>;
+type SolidPluginImport = 'lazy' | 'static';
+type KnipOptions = AppSettings & {
+  root: string;
+  configFile?: string;
+  entry?: string[];
+  solidPluginImport?: SolidPluginImport;
+};
+type ConfigureKnip = () => Promise<KnipConfiguration>;
+export declare function defineKnipConfig({ root, configFile, entry, solidPluginImport, ignoreBinaries, ignoreDependencies, ignoreIssues, exclude }: KnipOptions): ConfigureKnip;
+export {};

package/dist/knip.mjs

@@ -0,0 +1,92 @@
+import { t as hasMatch } from "./has-match-BITlj0EE.mjs";
+import path from "node:path";
+import { PageFileSystemRouter } from "filesystem-routing";
+import { DEFAULT_EXTENSIONS } from "filesystem-routing/vite";
+// src/knip/index.ts
+const DEFAULT_CONFIG_FILE = "tooling/knip.ts";
+const SOLID_ENTRIES = [
+	"src/entry-server.tsx",
+	"src/entry-client.tsx",
+	"src/middleware/index.ts",
+	"env.ts"
+];
+const RUNTIME_ENTRIES = ["paraglide/runtime.js"];
+const ROUTE_DIRECTORIES = [
+	{
+		directory: "src/routes",
+		isProduction: true
+	},
+	{
+		directory: "src/tests/fixtures/routes",
+		isProduction: false
+	},
+	{
+		directory: "src/tests/fixtures/e2e/routes",
+		isProduction: false
+	}
+];
+const TOOLING_PROJECT = "tooling/**/*.ts";
+function isModuleRef(value) {
+	return typeof value === "object" && value !== null && "src" in value && typeof value.src === "string";
+}
+function routeSources(route) {
+	return Object.entries(route).flatMap(([key, value]) => key.startsWith("$") && isModuleRef(value) ? [value.src] : []);
+}
+async function discoverRouteModules({ root, directory, isProduction }) {
+	const routes = await new PageFileSystemRouter({
+		dir: path.join(root, directory),
+		extensions: DEFAULT_EXTENSIONS,
+		httpMethods: true
+	}).getRoutes();
+	return [...new Set(routes.flatMap((route) => routeSources(route)))].map((source) => path.relative(root, source) + (isProduction ? "!" : ""));
+}
+async function conventionEntries({ root, patterns }) {
+	return (await Promise.all(patterns.map(async (pattern) => await hasMatch({
+		root,
+		pattern
+	}) ? [`${pattern}!`] : []))).flat();
+}
+function defineKnipConfig({ root, configFile = DEFAULT_CONFIG_FILE, entry = [], solidPluginImport = "lazy", ignoreBinaries, ignoreDependencies, ignoreIssues = {}, exclude }) {
+	const patterns = solidPluginImport === "static" ? RUNTIME_ENTRIES : [...SOLID_ENTRIES, ...RUNTIME_ENTRIES];
+	return async function configureKnip() {
+		const [conventions, routes, hasTooling] = await Promise.all([
+			conventionEntries({
+				root,
+				patterns
+			}),
+			Promise.all(ROUTE_DIRECTORIES.map((route) => discoverRouteModules({
+				root,
+				...route
+			}))),
+			hasMatch({
+				root,
+				pattern: TOOLING_PROJECT
+			})
+		]);
+		const configIssues = ignoreIssues[configFile] ?? [];
+		return {
+			entry: [.../* @__PURE__ */ new Set([
+				...conventions,
+				...entry,
+				...routes.flat()
+			])],
+			project: [
+				"src/**/*.{ts,tsx}!",
+				...hasTooling ? [TOOLING_PROJECT] : [],
+				"!src/tests/**!",
+				"!src/**/__tests__/**!",
+				"!src/**/*.test.{ts,tsx}!"
+			],
+			"filesystem-routing": false,
+			...ignoreBinaries ? { ignoreBinaries } : {},
+			...ignoreDependencies ? { ignoreDependencies } : {},
+			ignoreIssues: {
+				...ignoreIssues,
+				[configFile]: [.../* @__PURE__ */ new Set([...configIssues, "unlisted"])]
+			},
+			...exclude ? { exclude } : {},
+			treatConfigHintsAsErrors: true
+		};
+	};
+}
+export { defineKnipConfig };