larrylint 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Frederik Bußmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# 🦙 larrylint
+
+[![Github Actions][github-actions-src]][github-actions-href]
+[![NPM version][npm-version-src]][npm-version-href]
+[![NPM last update][npm-last-update-src]][npm-last-update-href]
+[![License][license-src]][license-href]
+
+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. 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
+
+Check the Laioutr app in the current folder. No install and no config needed:
+
+```sh
+npx larrylint
+```
+
+Set it up for good. This installs larrylint, adds its rules to your `eslint.config`, and records existing violations in a baseline so only new code has to follow the rules:
+
+```sh
+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
+
+### 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):
+
+```
+src/
+├── module.ts                  # build time
+└── runtime/
+    ├── app/
+    │   ├── sections/          # Section*.vue with defineSection()
+    │   ├── blocks/            # Block*.vue with defineBlock()
+    │   ├── 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
+    │   │   └── plugins/
+    │   ├── middleware/        # orchestr middleware and the builders handlers use
+    │   ├── client/            # API clients, nothing else
+    │   ├── api/               # server routes, or routes/
+    │   ├── plugins/           # Nitro plugins
+    │   ├── 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.
+
+After fixing old violations, shrink the baseline:
+
+```sh
+npx larrylint --baseline
+```
+
+## Configuration
+
+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"],
+    "heavyPackages": ["leaflet"]
+  }
+}
+```
+
+Or in a `larrylint.config.ts`:
+
+```ts
+import { defineLarrylintConfig } from 'larrylint'
+
+export default defineLarrylintConfig({
+  sharedDomains: ['product'],
+  heavyPackages: ['leaflet'],
+})
+```
+
+## ESLint
+
+`larrylint init` adds the rules to your `eslint.config` for you. To do it by hand with `@nuxt/eslint-config` or `@antfu/eslint-config`:
+
+```js
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
+import larrylint from 'larrylint'
+
+export default createConfigForNuxt().append(larrylint())
+```
+
+With a plain array, like `@laioutr/eslint-config`:
+
+```js
+import config from '@laioutr/eslint-config/nuxt-module'
+import larrylint from 'larrylint'
+
+export default [...config, ...(await larrylint())]
+```
+
+The preset only brings rules, no parsers or style rules, so it runs on top of whatever your config already uses.
+
+## CLI
+
+```sh
+larrylint [--cwd <folder>] [--fix] [--baseline]
+larrylint init [--cwd <folder>]
+```
+
+- `--fix` fixes what can be fixed automatically.
+- `--baseline` records the current violations in `larrylint-baseline.json`.
+
+The CLI only runs larrylint's rules, independent of your ESLint setup, and exits with code 1 on new violations.
+
+## License
+
+Published under the [MIT License](https://github.com/bussmann-io/larrylint/tree/main/LICENSE).
+
+[github-actions-src]: https://github.com/bussmann-io/larrylint/actions/workflows/test.yml/badge.svg
+[github-actions-href]: https://github.com/bussmann-io/larrylint/actions
+
+[npm-version-src]: https://img.shields.io/npm/v/larrylint/latest.svg?style=flat&colorA=18181B&colorB=31C553
+[npm-version-href]: https://npmjs.com/package/larrylint
+
+[npm-last-update-src]: https://img.shields.io/npm/last-update/larrylint.svg?style=flat&colorA=18181B&colorB=31C553
+[npm-last-update-href]: https://npmjs.com/package/larrylint
+
+[license-src]: https://img.shields.io/github/license/bussmann-io/larrylint.svg?style=flat&colorA=18181B&colorB=31C553
+[license-href]: https://github.com/bussmann-io/larrylint/tree/main/LICENSE

package/dist/_chunks/check.mjs

@@ -0,0 +1,44 @@
+import { applyBaseline, larrylint } from "./preset.mjs";
+import tsParser from "@typescript-eslint/parser";
+import vueParser from "vue-eslint-parser";
+import { ESLint } from "eslint";
+const PARSERS = [
+	{ ignores: ["**/*.d.ts"] },
+	{
+		files: ["**/*.{ts,mts,cts}"],
+		languageOptions: { parser: tsParser }
+	},
+	{
+		files: ["**/*.vue"],
+		languageOptions: {
+			parser: vueParser,
+			parserOptions: {
+				parser: tsParser,
+				extraFileExtensions: [".vue"]
+			}
+		}
+	}
+];
+async function check(cwd, options = {}) {
+	const eslint = new ESLint({
+		cwd,
+		overrideConfigFile: true,
+		overrideConfig: [
+			...PARSERS,
+			...await larrylint({ cwd }),
+			{
+				linterOptions: { reportUnusedDisableDirectives: "off" },
+				settings: { larrylint: { baseline: false } }
+			}
+		],
+		fix: options.fix,
+		errorOnUnmatchedPattern: false
+	});
+	const results = await eslint.lintFiles(["src"]);
+	if (options.fix) await ESLint.outputFixes(results);
+	return {
+		eslint,
+		...applyBaseline(cwd, results)
+	};
+}
+export { check };

package/dist/_chunks/check2.mjs

@@ -0,0 +1,50 @@
+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 { join, resolve } from "pathe";
+import { existsSync } from "node:fs";
+import { defineCommand } from "citty";
+import { consola } from "consola";
+var check_default = defineCommand({
+	meta: {
+		name: "check",
+		description: "Check the Laioutr app in the current folder."
+	},
+	args: {
+		...cwdArgs,
+		fix: {
+			type: "boolean",
+			description: "Fix what can be fixed automatically."
+		},
+		baseline: {
+			type: "boolean",
+			description: `Record all current violations in ${BASELINE_FILE}, so only new ones fail.`
+		}
+	},
+	run: async ({ args }) => {
+		const cwd = resolve(args.cwd);
+		if (!existsSync(join(cwd, "src/runtime"))) {
+			consola.warn(`No src/runtime/ in ${cwd}. larrylint checks Laioutr apps, run it in the app's folder.`);
+			process.exitCode = 1;
+			return;
+		}
+		const { eslint, results, violations, baselined, improved } = await check(cwd, { fix: args.fix });
+		if (args.baseline) {
+			writeBaseline(cwd, violations);
+			const total = countViolations(violations);
+			consola.success(total > 0 ? `Recorded ${total} violations in ${Object.keys(violations).length} files in ${BASELINE_FILE}.` : "No violations, nothing to record.");
+			return;
+		}
+		const output = await (await eslint.loadFormatter("stylish")).format(results);
+		if (output) process.stdout.write(`${output}\n`);
+		if (baselined > 0) consola.info(`${baselined} known violations are recorded in ${BASELINE_FILE}.`);
+		if (improved > 0) consola.info(`${improved} baseline entries have fewer violations now. Run larrylint --baseline to lock that in.`);
+		if (results.some((result) => result.errorCount > 0)) {
+			process.exitCode = 1;
+			return;
+		}
+		consola.success(baselined > 0 ? "No new violations." : "No violations.");
+	}
+});
+export { check_default as default };

package/dist/_chunks/init.mjs

@@ -0,0 +1,149 @@
+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 { 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",
+	"eslint.config.cjs",
+	"eslint.config.ts",
+	"eslint.config.mts",
+	"eslint.config.cts"
+];
+const COMPOSERS = /^(?:@nuxt\/eslint-config(?:\/flat)?|@antfu\/eslint-config|eslint-flat-config-utils)$|\/\.nuxt\/eslint\.config\.mjs$/;
+const CONFIG_FUNCTIONS = /* @__PURE__ */ new Set(["defineConfig", "extendConfig"]);
+const NEW_ESLINT_CONFIG = `import larrylint from 'larrylint'\n\nexport default larrylint()\n`;
+const MANUAL_SNIPPET = `import larrylint from 'larrylint'
+
+export default [
+  // ...your config
+  ...(await larrylint()),
+]`;
+function wireEslintConfig(cwd) {
+	const file = CONFIG_FILES.map((name) => join(cwd, name)).find((path) => existsSync(path));
+	if (!file) {
+		const created = join(cwd, "eslint.config.mjs");
+		writeFileSync(created, NEW_ESLINT_CONFIG);
+		return {
+			status: "created",
+			file: created
+		};
+	}
+	const result = addLarrylint(readFileSync(file, "utf8"));
+	if (typeof result === "string") {
+		writeFileSync(file, result);
+		return {
+			status: "updated",
+			file
+		};
+	}
+	return {
+		status: result,
+		file
+	};
+}
+function addLarrylint(code) {
+	const mod = parseModule(code);
+	const imports = Object.values(mod.imports);
+	if (imports.some((item) => item.from === "larrylint")) return "present";
+	const body = mod.$ast.body;
+	const exported = body.find((node) => node.type === "ExportDefaultDeclaration")?.declaration;
+	let edit;
+	if (exported?.type === "ArrayExpression") edit = appendItem(code, exported, exported.elements, "...(await larrylint())");
+	else if (exported?.type === "CallExpression" && isComposer(exported, imports)) {
+		const indent = code.slice(exported.start, exported.end).match(/\n([ \t]*)\.[a-z]/i)?.[1];
+		edit = {
+			start: exported.end,
+			end: exported.end,
+			text: `${indent === void 0 ? "" : `\n${indent}`}.append(larrylint())`
+		};
+	} else if (exported?.type === "CallExpression" && exported.callee.type === "Identifier" && CONFIG_FUNCTIONS.has(exported.callee.name)) edit = appendItem(code, exported, exported.arguments, "await larrylint()");
+	else if (exported?.type === "Identifier") edit = extendBinding(body, exported, imports);
+	if (!edit) return "unknown";
+	const lastImport = body.filter((node) => node.type === "ImportDeclaration").at(-1);
+	const importLine = `import larrylint from 'larrylint'${(lastImport ? code.slice(lastImport.start, lastImport.end).endsWith(";") : false) ? ";" : ""}`;
+	let result = `${code.slice(0, edit.start)}${edit.text}${code.slice(edit.end)}`;
+	result = lastImport ? `${result.slice(0, lastImport.end)}\n${importLine}${result.slice(lastImport.end)}` : `${importLine}\n\n${result}`;
+	return result;
+}
+function extendBinding(body, identifier, imports) {
+	const imported = imports.find((item) => item.local === identifier.name);
+	const declared = body.flatMap((node) => node.type === "VariableDeclaration" ? node.declarations : []).find((declarator) => declarator.id.name === identifier.name);
+	return (imported ? COMPOSERS.test(imported.from) : declared?.init?.type === "CallExpression" && isComposer(declared.init, imports)) ? {
+		start: identifier.end,
+		end: identifier.end,
+		text: ".append(larrylint())"
+	} : {
+		start: identifier.start,
+		end: identifier.end,
+		text: `[...${identifier.name}, ...(await larrylint())]`
+	};
+}
+function isComposer(call, imports) {
+	let node = call;
+	while (node.callee.type === "MemberExpression" && node.callee.object.type === "CallExpression") node = node.callee.object;
+	const factory = node.callee.type === "Identifier" ? imports.find((item) => item.local === node.callee.name) : void 0;
+	return factory ? COMPOSERS.test(factory.from) : false;
+}
+var init_default = defineCommand({
+	meta: {
+		name: "init",
+		description: "Set up larrylint in the Laioutr app in the current folder."
+	},
+	args: cwdArgs,
+	run: async ({ args }) => {
+		const cwd = resolve(args.cwd);
+		if (!existsSync(join(cwd, "package.json")) || !existsSync(join(cwd, "src/runtime"))) {
+			consola.error(`${cwd} doesn't look like a Laioutr app: it needs a package.json and a src/runtime/ folder.`);
+			process.exitCode = 1;
+			return;
+		}
+		const pkg = await readPackageJSON(cwd);
+		if (pkg.dependencies?.larrylint || pkg.devDependencies?.larrylint) consola.info("larrylint is already installed.");
+		else {
+			const packageManager = await detectPackageManager(cwd);
+			const workspace = packageManager?.name === "pnpm" ? existsSync(join(cwd, "pnpm-workspace.yaml")) : packageManager?.name === "yarn" && Boolean(pkg.workspaces);
+			consola.start("Installing larrylint...");
+			await addDevDependency("larrylint", {
+				cwd,
+				packageManager,
+				workspace,
+				silent: true
+			});
+			consola.success("Installed larrylint.");
+		}
+		const wired = wireEslintConfig(cwd);
+		const file = relative(cwd, wired.file);
+		if (wired.status === "created") consola.success(`Created ${file} with the larrylint rules.`);
+		else if (wired.status === "updated") consola.success(`Added the larrylint rules to ${file}.`);
+		else if (wired.status === "present") consola.info(`${file} already uses larrylint.`);
+		else consola.warn(`Couldn't add larrylint to ${file} automatically. Add it like this:\n\n${MANUAL_SNIPPET}\n`);
+		const { violations } = await check(cwd);
+		writeBaseline(cwd, violations);
+		const total = countViolations(violations);
+		if (total > 0) consola.info(`Recorded ${total} existing violations in ${Object.keys(violations).length} files in ${BASELINE_FILE}. New code has to follow the rules; run larrylint --baseline after fixing old violations.`);
+		else consola.success("No violations found.");
+	}
+});
+export { init_default as default };

package/dist/_chunks/package.mjs

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