larrylint 0.1.0 → 0.2.0

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 or handlers importing each other. It also catches the mistakes that only show up in Studio or in production, like schema fields that never reach the component, fallbacks that never apply, or cookies written after orchestr has sent the headers.
 
 ## Usage
 
@@ -25,17 +25,57 @@ npx larrylint init
 
 After that, `eslint .` and your editor report larrylint's rules next to your own.
 
+`token-namespaces` reads the app's installed `@laioutr-core/canonical-types`, so install the app's dependencies first. larrylint stops with an error when it's 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, and handlers get API clients from the orchestr context. Utils are the bottom layer, followed by composables, components and sections. |
+| `larrylint/heavy-imports` | Sections, blocks and plugins load the packages in `heavyPackages` with `import()`: frontend-core imports every section and block up front, and plugins run on every page, 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 whole options object 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 Nitro plugin, so only handler files belong there. |
+| `larrylint/orchestr-cookies` | Cookies and headers are only written in `extendRequest()` and action handlers, since query, link and resolver handlers and `use()` middleware can run after the headers are sent. Cookies go through frontend-core's `setManagedCookie()` and `deleteManagedCookie()`, which the Studio preview needs. |
+| `larrylint/handler-exports` | Handler files export their handler as default. Without one, the build fails. |
+| `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/token-namespaces` | Your own tokens stay out of the namespaces of Laioutr's canonical types, like `ecommerce/`, where a later canonical-types release or another app can take the same id. |
+
+### Sections and blocks
+
+| Rule | Description |
+| --- | --- |
+| `larrylint/definition-folder` | `defineSection()` lives in `app/sections/` and `defineBlock()` in `app/blocks/` (or `section/` and `block/`), and every `.vue` there has one. |
+| `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 picker and AI agents read through Laioutr's MCP server. |
+| `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`: frontend-core passes all blocks of a slot as one Fragment. |
+| `larrylint/reserved-field-names` | No top-level schema fields named `key`, `ref`, `ref_for`, `ref_key`, `class` or `style`, which Vue handles itself, and no `slots` on sections, which frontend-core overwrites. |
+| `larrylint/field-name-case` | Top-level schema field names have no `-` and don't start with `$`: Vue camelizes the one and rejects the other. |
+| `larrylint/required-fields` | Schema fields have no `required`, which Studio ignores. Give them a `default` instead. |
+| `larrylint/unused-fields` | The component reads every schema field it defines, directly, through the section it's a block of, or in another field's `if`, so editors don't get fields that do nothing. |
+| `larrylint/dead-fallbacks` | No `??` fallbacks that never apply: frontend-core fills unset pickers with their first option, checkboxes with `false` and text fields with `''`. |
+
+### Frontend
+
+| Rule | Description |
+| --- | --- |
+| `larrylint/button-type` | No `type` on the ui-kit buttons: they always render their `button-type` prop, so `type="submit"` silently renders a dead button. Autofixable. |
+| `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, or ends up as an unhandled rejection. |
+| `larrylint/resolve-result` | Nothing tests the result of `linkResolver.resolve()`: a link it can't resolve comes back as a `#…` fallback, not as an empty value. |
+| `larrylint/hand-built-links` | Links to pages come from `linkResolver`, not from paths like `` `/hotels/${slug}` ``: page paths are set per page and language in Studio, and each market adds its own prefix, like `/en`. |
+| `larrylint/internal-anchors` | Internal and resolved links use `<NuxtLink>`: a plain `<a>` reloads the page and breaks Studio's navigation sync. |
+
 ## Layout
 
 larrylint expects the layout of Laioutr's [app starter](https://github.com/laioutr/app-starter):
@@ -45,29 +85,28 @@ src/
 ├── module.ts                  # build time
 └── runtime/
     ├── app/
-    │   ├── sections/          # Section*.vue with defineSection()
-    │   ├── blocks/            # Block*.vue with defineBlock()
+    │   ├── sections/          # defineSection() components, or section/
+    │   ├── blocks/            # defineBlock() components, or block/
     │   ├── components/
     │   ├── composables/
     │   ├── overrides/         # replacements for upstream components
     │   ├── plugins/
+    │   ├── shared-fields/     # schema fields sections and blocks share
+    │   ├── theme/
     │   └── utils/
     ├── server/
     │   ├── orchestr/
-    │   │   ├── <domain>/      # *.query.ts, *.resolver.ts, *.link.ts, *.action.ts, *.template.ts, *.page-index.ts
+    │   │   ├── <entity>/      # *.query.ts, *.resolver.ts, *.link.ts, *.action.ts, *.template.ts, *.page-index.ts
     │   │   └── 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
 ```
 
-A domain is a folder in `server/orchestr/`, together with the `server/utils/` folder of the same name. Other folders in `server/utils/`, like `tracking/`, hold shared helpers that every domain may use.
-
 ## Baseline
 
 On an existing codebase, `larrylint init` records all current violations in `larrylint-baseline.json`, counted per file and rule. A file stays quiet as long as it has no more violations of a rule than recorded. Once it gets more, all of them show again, like ESLint's bulk suppressions. The baseline applies in your editor, in `eslint .` and in the CLI.
@@ -80,12 +119,12 @@ 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. `heavyPackages` lists the packages that sections, blocks and plugins must load with `import()`, for `heavy-imports`. Set it in your `package.json`:
 
 ```json
 {
   "larrylint": {
-    "sharedDomains": ["product"]
+    "heavyPackages": ["leaflet"]
   }
 }
 ```
@@ -96,7 +135,7 @@ Or in a `larrylint.config.ts`:
 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.2.0";
+var description = "Opinionated rules for Laioutr apps, as an ESLint preset and a CLI.";
 export { description, name, version };