larrylint 0.1.0 → 0.1.1

package/README.md

@@ -5,9 +5,9 @@
 [![NPM last update][npm-last-update-src]][npm-last-update-href]
 [![License][license-src]][license-href]
 
-Opinionated structure rules for [Laioutr](https://laioutr.com) apps: an ESLint preset for your editor and a CLI for CI.
+Opinionated rules for [Laioutr](https://laioutr.com) apps: an ESLint preset for your editor and a CLI for CI.
 
-Laioutr apps are Nuxt modules with a lot of moving parts: sections and blocks, orchestr handlers, middleware, API clients, server routes. larrylint keeps them where they belong and stops the imports that make a codebase drift, like app code pulling in server code, handlers importing each other, or one business domain reaching into another.
+Laioutr apps are Nuxt modules with a lot of moving parts: sections and blocks, orchestr handlers, middleware, API clients, server routes. larrylint keeps them where they belong and stops the imports that make a codebase drift, like app code pulling in server code, handlers importing each other, or one business domain reaching into another. It also catches the mistakes that only show up in Studio or in production, like schema fields that never reach the component, links Studio can't follow, or cookies the page cache hands to every visitor.
 
 ## Usage
 
@@ -25,17 +25,76 @@ npx larrylint init
 
 After that, `eslint .` and your editor report larrylint's rules next to your own.
 
+`ui-kit-tags` and `token-namespaces` read the app's installed `@laioutr-core/ui-kit`, `@laioutr-core/ui` and `@laioutr-core/canonical-types`, so install the app's dependencies first. larrylint stops with an error when one of them is missing.
+
 ## Rules
 
-| Rule                           | What it checks                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `larrylint/layers`             | App code doesn't import server code and vice versa; shared code imports neither. Runtime code doesn't import build-time code. Nothing imports orchestr handlers. Handlers and server utils don't import from `server/client/`, and only handlers and media libraries import middleware. Utils are the bottom layer. Domains stay apart. |
-| `larrylint/orchestr-files`     | Laioutr loads every file in `orchestr/` as a server plugin, so only handler files belong there, in a domain folder, exporting nothing but their handler.                                                                                                                                                                              |
-| `larrylint/definitions`        | `defineSection()` lives in `app/sections/Section*.vue`, `defineBlock()` in `app/blocks/Block*.vue`, with a `component` name that matches the file and no top-level schema fields named `style`, `class`, `key`, `ref`, `is`, `slot`, `refFor` or `refKey`, which Vue swallows before they reach the component.                                                                                                                                                                                    |
-| `larrylint/button-type`        | No `type` on the ui-kit button: it always renders its `button-type` prop, so `type="submit"` silently renders a dead button. Autofixable.                                                                                                                                                                                             |
+### Structure
+
+| Rule | Description |
+| --- | --- |
+| `larrylint/layers` | App, server and shared code stay apart, and runtime code doesn't import build-time code, or `node:` modules outside the server. Nothing imports orchestr handlers, only handlers and media libraries import middleware, and API clients stay out of handlers and server utils. Utils are the bottom layer, followed by composables, components and sections. Domains stay apart. |
+| `larrylint/known-folders` | Runtime files live in the folders of the [layout](#layout), where the other rules know what to check. |
+| `larrylint/heavy-imports` | Sections, blocks and plugins load the packages in `heavyPackages` with `import()`. Laioutr registers them globally, so a static import lands in the chunk every page loads. |
+| `larrylint/config-keys` | Runtime config keys like `'@laioutr-app/shopware'` are the app itself or one of its dependencies, otherwise the config is missing at runtime. |
+| `larrylint/public-config` | The module doesn't copy its options into `runtimeConfig.public`, which reaches the browser with every token among them. |
 
 Type imports are fine across most layers, since they don't end up in the bundle.
 
+### Orchestr
+
+| Rule | Description |
+| --- | --- |
+| `larrylint/orchestr-files` | Laioutr loads every file in `orchestr/` as a server plugin, so only handler files belong there. |
+| `larrylint/orchestr-cookies` | Handlers and middleware don't set cookies or redirect, since the page cache replays the response to every visitor. |
+| `larrylint/handler-domains` | Handlers live in a domain folder, e.g. `orchestr/<domain>/`. |
+| `larrylint/handler-exports` | Handler files export their handler as default and nothing else. |
+| `larrylint/handler-context` | Handlers take config and clients from the middleware context and the request from their arguments, not from `useRuntimeConfig()` or `useEvent()`. |
+| `larrylint/resolver-undefined` | Component resolvers resolve fields to empty values like `''`, not `undefined` or `null`, which Studio shows as "...". |
+| `larrylint/resolver-passthrough` | Component resolvers use `passthrough.get()`: `require()` fails the whole resolver when another query didn't set the value. |
+| `larrylint/action-errors` | Actions return client errors as a status in their output. A thrown 4xx arrives as a failed action, since the action transport drops status codes. |
+| `larrylint/middleware-files` | `server/middleware/` only holds orchestr and Nitro middleware; helpers go to `server/utils/`. |
+| `larrylint/initware-throws` | `extendRequest()` doesn't throw, directly or through a function it calls: it runs before every query, so a throw takes down every page. |
+| `larrylint/orchestr-meta` | `defineOrchestr.meta({ app })` is the package name, which traces use to tell which app's middleware ran. |
+| `larrylint/token-namespaces` | Your own tokens stay out of the namespaces of Laioutr's canonical types, like `ecommerce/`, where registration order decides which handler wins. |
+| `larrylint/token-nullable` | Entity component tokens have no nullable top-level fields, which Studio can't bind. |
+
+### Sections and blocks
+
+| Rule | Description |
+| --- | --- |
+| `larrylint/definition-folder` | `defineSection()` lives in `app/sections/` and `defineBlock()` in `app/blocks/`, and every `.vue` there has one. |
+| `larrylint/definition-prefix` | Sections are named `Section*.vue`, blocks `Block*.vue`. |
+| `larrylint/component-name` | The `component` of a definition matches its file name. |
+| `larrylint/definition-description` | Definitions have a `studio.description`, which Studio shows in its section and block picker. |
+| `larrylint/root-id` | The root element has no `id`: frontend-core replaces it with its own. |
+| `larrylint/single-root` | Sections and blocks render one root element, also through a component they wrap. Otherwise Vue drops the `data-lfc-*` markers frontend-core adds. |
+| `larrylint/slot-children` | Nothing counts slot children with `.length`: Studio passes all blocks of a slot as one Fragment. |
+| `larrylint/reserved-field-names` | No top-level schema fields named `style`, `class`, `key`, `ref`, `is`, `slot`, `refFor` or `refKey`, which Vue swallows before they reach the component. |
+| `larrylint/field-name-case` | Top-level schema fields are camelCase, since they become props. |
+| `larrylint/required-fields` | Schema fields have no `required`, which Studio ignores. Give them a `default` instead. |
+| `larrylint/schema-groups` | Schema groups are Studio's panels, in the order Content, Design, Rules. |
+| `larrylint/unused-fields` | The component reads every schema field it defines, so editors don't get fields that do nothing. |
+| `larrylint/dead-fallbacks` | No `??` fallbacks or `undefined` checks on props that are never `undefined`: unset checkbox, select, radio and toggle fields arrive as `false`, unset text fields as `''`. |
+
+### Frontend
+
+| Rule | Description |
+| --- | --- |
+| `larrylint/button-type` | No `type` on the ui-kit button: it always renders its `button-type` prop, so `type="submit"` silently renders a dead button. Autofixable. |
+| `larrylint/ui-kit-tags` | `<l-*>` tags are ui-kit or ui components. Anything else renders nothing. |
+| `larrylint/mutation-errors` | An awaited or dropped `mutateAsync()` handles its error. Otherwise a failed mutation replaces the whole section or block with frontend-core's "Retry" state. |
+| `larrylint/orchestr-store` | Components read orchestr data through composables, not `useOrchestrStore()`. |
+| `larrylint/resolve-result` | Nothing tests the result of `linkResolver.resolve()`, which is never empty: a link it can't resolve comes back as a `#missing-required-params…` string. |
+| `larrylint/hand-built-links` | Internal links come from `linkResolver`, not from paths like `` `/hotels/${slug}` ``, which break when a page type's route changes. |
+| `larrylint/internal-anchors` | Internal links use `<NuxtLink>`: a plain `<a>` reloads the page and breaks Studio's navigation sync. |
+
+### Canonical types
+
+| Rule | What it checks |
+| --- | --- |
+| `larrylint/money` | Money amounts are integers in minor units, e.g. `1999` for 19.99, and currencies are ISO 4217 codes like `EUR`. |
+
 ## Layout
 
 larrylint expects the layout of Laioutr's [app starter](https://github.com/laioutr/app-starter):
@@ -51,6 +110,8 @@ src/
     │   ├── composables/
     │   ├── overrides/         # replacements for upstream components
     │   ├── plugins/
+    │   ├── shared-fields/     # schema fields sections and blocks share
+    │   ├── theme/
     │   └── utils/
     ├── server/
     │   ├── orchestr/
@@ -58,9 +119,9 @@ src/
     │   │   └── plugins/
     │   ├── middleware/        # orchestr middleware and the builders handlers use
     │   ├── client/            # API clients, nothing else
-    │   ├── api/               # server routes
+    │   ├── api/               # server routes, or routes/
     │   ├── plugins/           # Nitro plugins
-    │   ├── media-library/
+    │   ├── media-library/     # or media-libraries/
     │   └── utils/
     │       └── <domain>/
     └── shared/                # code for both the app and the server
@@ -80,12 +141,18 @@ npx larrylint --baseline
 
 ## Configuration
 
-Most apps need none. To let every domain import a domain, add it to `sharedDomains` in your `package.json`:
+Most apps need none. Two options tune the rules:
+
+- `sharedDomains`: domains every other domain may import, for `layers`.
+- `heavyPackages`: packages that sections, blocks and plugins must load with `import()`, for `heavy-imports`.
+
+Set them in your `package.json`:
 
 ```json
 {
   "larrylint": {
-    "sharedDomains": ["product"]
+    "sharedDomains": ["product"],
+    "heavyPackages": ["leaflet"]
   }
 }
 ```
@@ -97,6 +164,7 @@ import { defineLarrylintConfig } from 'larrylint'
 
 export default defineLarrylintConfig({
   sharedDomains: ['product'],
+  heavyPackages: ['leaflet'],
 })
 ```
 

package/dist/_chunks/check.mjs

@@ -1,8 +1,7 @@
-import { larrylint, readBaseline } from "./preset.mjs";
-import { relative } from "pathe";
+import { applyBaseline, larrylint } from "./preset.mjs";
 import tsParser from "@typescript-eslint/parser";
-import { ESLint } from "eslint";
 import vueParser from "vue-eslint-parser";
+import { ESLint } from "eslint";
 const PARSERS = [
 	{ ignores: ["**/*.d.ts"] },
 	{
@@ -42,35 +41,4 @@ async function check(cwd, options = {}) {
 		...applyBaseline(cwd, results)
 	};
 }
-function applyBaseline(cwd, results) {
-	const baseline = readBaseline(cwd);
-	const violations = {};
-	let baselined = 0;
-	let improved = 0;
-	const filtered = results.map((result) => {
-		const path = relative(cwd, result.filePath);
-		const perRule = {};
-		const relevant = result.messages.filter((message) => message.fatal || message.ruleId?.startsWith("larrylint/"));
-		for (const { ruleId } of relevant) if (ruleId) perRule[ruleId] = (perRule[ruleId] ?? 0) + 1;
-		if (Object.keys(perRule).length > 0) violations[path] = perRule;
-		const messages = relevant.filter(({ ruleId }) => !ruleId || perRule[ruleId] > (baseline[path]?.[ruleId] ?? 0));
-		baselined += relevant.length - messages.length;
-		return {
-			...result,
-			messages,
-			errorCount: messages.filter((message) => message.severity === 2).length,
-			fatalErrorCount: messages.filter((message) => message.fatal).length,
-			warningCount: messages.filter((message) => message.severity === 1).length,
-			fixableErrorCount: messages.filter((message) => message.severity === 2 && message.fix).length,
-			fixableWarningCount: messages.filter((message) => message.severity === 1 && message.fix).length
-		};
-	});
-	for (const [path, rules] of Object.entries(baseline)) for (const [rule, allowed] of Object.entries(rules)) if ((violations[path]?.[rule] ?? 0) < allowed) improved++;
-	return {
-		results: filtered,
-		violations,
-		baselined,
-		improved
-	};
-}
 export { check };

package/dist/_chunks/check2.mjs

@@ -2,8 +2,8 @@ import { BASELINE_FILE, countViolations, writeBaseline } from "./preset.mjs";
 import { cwdArgs } from "../cli/index.mjs";
 import { check } from "./check.mjs";
 import process from "node:process";
-import { existsSync } from "node:fs";
 import { join, resolve } from "pathe";
+import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import { consola } from "consola";
 var check_default = defineCommand({

package/dist/_chunks/init.mjs

@@ -2,13 +2,27 @@ import { BASELINE_FILE, countViolations, writeBaseline } from "./preset.mjs";
 import { cwdArgs } from "../cli/index.mjs";
 import { check } from "./check.mjs";
 import process from "node:process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "pathe";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { defineCommand } from "citty";
 import { consola } from "consola";
 import { addDevDependency, detectPackageManager } from "nypm";
 import { readPackageJSON } from "pkg-types";
 import { parseModule } from "magicast";
+function appendItem(code, container, items, text) {
+	const closing = container.end - 1;
+	const last = items.at(-1);
+	const insert = (at, insertion) => ({
+		start: at,
+		end: at,
+		text: insertion
+	});
+	if (!last) return insert(closing, text);
+	if (!code.slice(container.start, container.end).includes("\n")) return insert(last.end, `, ${text}`);
+	const indent = code.slice(code.lastIndexOf("\n", last.start) + 1, last.start).match(/^[ \t]*/)[0];
+	const comma = code.indexOf(",", last.end);
+	return comma !== -1 && comma < closing ? insert(comma + 1, `\n${indent}${text},`) : insert(last.end, `,\n${indent}${text}`);
+}
 const CONFIG_FILES = [
 	"eslint.config.js",
 	"eslint.config.mjs",
@@ -92,20 +106,6 @@ function isComposer(call, imports) {
 	const factory = node.callee.type === "Identifier" ? imports.find((item) => item.local === node.callee.name) : void 0;
 	return factory ? COMPOSERS.test(factory.from) : false;
 }
-function appendItem(code, container, items, text) {
-	const closing = container.end - 1;
-	const last = items.at(-1);
-	const insert = (at, insertion) => ({
-		start: at,
-		end: at,
-		text: insertion
-	});
-	if (!last) return insert(closing, text);
-	if (!code.slice(container.start, container.end).includes("\n")) return insert(last.end, `, ${text}`);
-	const indent = code.slice(code.lastIndexOf("\n", last.start) + 1, last.start).match(/^[ \t]*/)[0];
-	const comma = code.indexOf(",", last.end);
-	return comma !== -1 && comma < closing ? insert(comma + 1, `\n${indent}${text},`) : insert(last.end, `,\n${indent}${text}`);
-}
 var init_default = defineCommand({
 	meta: {
 		name: "init",

package/dist/_chunks/package.mjs

@@ -1,4 +1,4 @@
 var name = "larrylint";
-var version = "0.1.0";
-var description = "Opinionated structure rules for Laioutr apps, as an ESLint preset and a CLI.";
+var version = "0.1.1";
+var description = "Opinionated rules for Laioutr apps, as an ESLint preset and a CLI.";
 export { description, name, version };