@lar-works/config 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @lar-works/config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The toolchain settings every Lar web repository shares: Oxlint rules (with Lar's own `lar/*` rules for architecture
+boundaries, design-system ownership and blank lines), Oxfmt options, TypeScript configs and test settings, for
+[Vite+](https://viteplus.dev).
+
+```ts
+// vite.config.ts
+import { fmt, lint, test } from '@lar-works/config';
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+    fmt,
+    lint: lint({ apps: ['.'] }),
+    test: { ...test, environment: 'jsdom' },
+});
+```
+
+```json
+// tsconfig.json
+{ "extends": "@lar-works/config/tsconfig/app.json" }
+```

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@lar-works/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Lar's shared toolchain settings: Oxlint rules and plugins, Oxfmt options, TypeScript and test settings.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maddec01/lar-web.git",
+    "directory": "packages/config"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./lint-plugin": "./src/plugins/lar.js",
+    "./tsconfig/app.json": "./tsconfig/app.json",
+    "./tsconfig/library.json": "./tsconfig/library.json",
+    "./tsconfig/node.json": "./tsconfig/node.json"
+  },
+  "files": [
+    "src",
+    "tsconfig"
+  ],
+  "peerDependencies": {
+    "vite-plus": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "typescript": "^7.0.2",
+    "vite-plus": "1.5.0"
+  },
+  "scripts": {
+    "test": "vp test run"
+  }
 }

package/src/index.d.ts

@@ -0,0 +1,23 @@
+import type { UserConfig } from 'vite-plus';
+
+type LintConfig = NonNullable<UserConfig['lint']>;
+type FmtConfig = NonNullable<UserConfig['fmt']>;
+type TestConfig = NonNullable<UserConfig['test']>;
+
+/** Oxfmt: Prettier's output with Lar's widths and quotes, imports sorted, Tailwind classes in Tailwind's order. */
+export declare const fmt: FmtConfig;
+
+export interface LintOptions {
+    /** Each app's root, relative to the repository root (`web`, `apps/web`). */
+    apps?: string[];
+    /** The roots of design-system packages, which own every visual recipe. */
+    designSystems?: string[];
+    /** Extra paths to skip, such as generated API clients. */
+    ignorePatterns?: string[];
+}
+
+/** Oxlint settings for a repository. */
+export declare function lint(options?: LintOptions): LintConfig;
+
+/** Test settings every package's `test` block spreads. */
+export declare const test: TestConfig;

package/src/index.js

@@ -0,0 +1,107 @@
+// The settings every Lar web repository spreads into its root vite.config.ts, so all of them format, lint and test
+// the same way. Plain JavaScript: Vite+ loads config dependencies from node_modules, where Node strips no types.
+
+/** Oxfmt: Prettier's output with Lar's widths and quotes, imports sorted, Tailwind classes in Tailwind's order. */
+export const fmt = {
+    printWidth: 120,
+    tabWidth: 4,
+    singleQuote: true,
+    trailingComma: 'all',
+    sortImports: {
+        groups: [
+            'side_effect_style',
+            'side_effect',
+            ['builtin', 'external', 'type-builtin', 'type-external'],
+            ['internal', 'type-internal', 'parent', 'type-parent', 'sibling', 'type-sibling', 'index', 'type-index'],
+            'unknown',
+        ],
+        internalPattern: ['@/'],
+    },
+    sortTailwindcss: {
+        functions: ['clsx', 'cn', 'tv'],
+    },
+    sortPackageJson: false,
+    ignorePatterns: ['**/generated/**', '**/CHANGELOG.md', 'pnpm-lock.yaml'],
+};
+
+const baseRules = {
+    'no-duplicate-imports': ['error', { allowSeparateTypeImports: true }],
+    'no-unused-expressions': 'error',
+    'no-empty': ['error', { allowEmptyCatch: true }],
+    'no-unused-vars': [
+        'error',
+        {
+            vars: 'all',
+            varsIgnorePattern: '^_',
+            args: 'after-used',
+            argsIgnorePattern: '^_',
+            caughtErrorsIgnorePattern: '^_',
+        },
+    ],
+    'typescript/no-explicit-any': 'error',
+    'typescript/no-require-imports': 'error',
+    'typescript/no-empty-object-type': 'error',
+    'react/rules-of-hooks': 'error',
+    'react/exhaustive-deps': 'warn',
+    'react/only-export-components': ['warn', { allowConstantExport: true }],
+    // Lar apps don't run the React Compiler, so libraries it can't memoize (TanStack Virtual) are fine.
+    'react/incompatible-library': 'off',
+    'lar/padding-lines': 'error',
+};
+
+/** Globs under an app's root; `.` is the repository root itself. */
+const under = (root, glob) => (root === '.' ? glob : `${root}/${glob}`);
+const sourceFiles = (root) => [under(root, 'src/**/*.ts'), under(root, 'src/**/*.tsx')];
+
+/**
+ * Oxlint settings for a repository.
+ *
+ * @param {object} options
+ * @param {string[]} [options.apps] Each app's root, relative to the repository root (`.`, `web`, `apps/web`).
+ *   Its `src` follows Lar's layers (app, features, shared, services) and holds no visual recipes.
+ * @param {string[]} [options.designSystems] The roots of design-system packages, which own every visual recipe.
+ * @param {string[]} [options.ignorePatterns] Extra paths to skip, such as generated API clients.
+ */
+export function lint({ apps = [], designSystems = [], ignorePatterns = [] } = {}) {
+    return {
+        plugins: ['typescript', 'react', 'unicorn', 'oxc', 'import', 'vitest'],
+        jsPlugins: ['@lar-works/config/lint-plugin'],
+        categories: { correctness: 'error' },
+        env: { browser: true, es2024: true },
+        ignorePatterns: ['**/dist/**', '**/storybook-static/**', '**/coverage/**', ...ignorePatterns],
+        options: { typeAware: true, typeCheck: true },
+        rules: baseRules,
+        overrides: [
+            ...apps.map((app) => ({
+                files: sourceFiles(app),
+                rules: {
+                    'lar/boundaries': ['error', { role: 'app' }],
+                    'lar/no-visual-recipes': 'error',
+                },
+            })),
+            ...apps.map((app) => ({
+                files: [under(app, 'src/app/**/*.tsx'), under(app, 'src/features/**/*.tsx')],
+                rules: { 'max-lines': ['error', { max: 250, skipBlankLines: true, skipComments: true }] },
+            })),
+            ...designSystems.map((designSystem) => ({
+                files: sourceFiles(designSystem),
+                rules: { 'lar/boundaries': ['error', { role: 'design-system' }] },
+            })),
+            {
+                files: ['**/*.test.ts', '**/*.test.tsx', '**/*.test.mjs', '**/test/**', '**/*.stories.tsx'],
+                rules: {
+                    'max-lines': 'off',
+                    'react/only-export-components': 'off',
+                    'vitest/require-mock-type-parameters': 'off',
+                    'vitest/no-conditional-expect': 'off',
+                },
+            },
+        ],
+    };
+}
+
+/** Test settings every package's `test` block spreads: logs only from failing tests, no performance hints. */
+export const test = {
+    silent: 'passed-only',
+    experimental: { diagnostics: false },
+};

package/src/plugins/lar.js

@@ -0,0 +1,274 @@
+// Lar's own Oxlint rules. Oxlint loads this file as a JS plugin (`jsPlugins`), so it is plain JavaScript with no
+// imports: it runs from whichever repository's node_modules holds it.
+//
+// lar/boundaries         keeps an app's layers (app, features, shared, services) and the design system apart.
+// lar/no-visual-recipes  keeps every visual decision inside the design system: apps compose its components.
+
+import path from 'node:path';
+
+const sourcePath = (filename) => filename.replaceAll(path.sep, '/').split('/src/').slice(1).join('/src/');
+const isTest = (filename) => /(?:\.test[.-]|\.stories\.|\/test\/|\/testing\/|-test[.-])/.test(filename);
+const isPublicEntry = (rest) => ['', '/index', '/index.ts', '/index.tsx'].includes(rest);
+
+/** Resolves aliases and relative imports, so moving a file cannot bypass the boundaries. */
+function importedPath(filename, specifier) {
+    if (specifier.startsWith('@/')) return specifier.slice(2);
+
+    if (specifier.startsWith('.')) return sourcePath(path.resolve(path.dirname(filename), specifier));
+
+    return undefined;
+}
+
+/** Packages only the design system may use: apps reach them through its public API. */
+const designSystemOnly = /^(@ninna-ui\/|lucide-react(\/|$)|@radix-ui\/|@floating-ui\/|tailwind-merge$|clsx$)/;
+
+/** Application state, routing and localization, which design-system components receive as props instead. */
+const applicationState = /^(react-i18next|i18next|react-router|react-router-dom|@tanstack\/react-query|zustand)(\/|$)/;
+
+const designSystemPackage = '@lar-works/design-system';
+
+const boundaries = {
+    meta: {
+        type: 'problem',
+        schema: [
+            {
+                type: 'object',
+                properties: { role: { enum: ['app', 'design-system'] } },
+                additionalProperties: false,
+            },
+        ],
+        messages: { boundary: '{{reason}}' },
+    },
+    create(context) {
+        const role = context.options[0]?.role ?? 'app';
+        const filename = context.filename;
+        const source = sourcePath(filename);
+
+        if (!source || isTest(filename)) return {};
+
+        const report = (node, reason) => context.report({ node, messageId: 'boundary', data: { reason } });
+
+        function checkDesignSystem(node, specifier) {
+            if (applicationState.test(specifier))
+                report(
+                    node,
+                    'Design-system components receive labels, values and callbacks; they do not own application state, routing or localization.',
+                );
+
+            const target = importedPath(filename, specifier);
+
+            if (
+                target &&
+                /^[^/]+(?:\/index(?:\.tsx?)?)?$/.test(target) &&
+                !target.startsWith('index') &&
+                ['ImportDeclaration', 'ImportExpression'].includes(node.type)
+            )
+                report(node, 'Inside the design system, import the owning module directly to avoid barrel cycles.');
+        }
+
+        function checkApp(node, specifier) {
+            const sourceFeature = source.match(/^features\/([^/]+)\//)?.[1];
+            const target = importedPath(filename, specifier);
+
+            if (!target) {
+                if (designSystemOnly.test(specifier))
+                    report(
+                        node,
+                        `Use the ${designSystemPackage} public API; only the design system uses ${specifier}.`,
+                    );
+
+                if (specifier.startsWith(designSystemPackage) && source.startsWith('services/'))
+                    report(node, 'Services own data access and server state, never UI.');
+
+                return;
+            }
+
+            if (source.startsWith('shared/') && /^(app|features|services)\//.test(target))
+                report(node, 'Shared foundations cannot depend on application, features or services.');
+
+            if (source.startsWith('services/') && /^(app|features)\//.test(target))
+                report(node, 'Services own data access and server state, never UI.');
+
+            if (sourceFeature && target.startsWith('app/'))
+                report(node, 'Features cannot depend on the application composition root.');
+
+            const targetFeature = target.match(/^features\/([^/]+)(.*)$/);
+
+            if (targetFeature && sourceFeature !== targetFeature[1] && !isPublicEntry(targetFeature[2]))
+                report(node, 'Cross-feature consumers must use the feature public API.');
+
+            if (targetFeature && sourceFeature === targetFeature[1] && isPublicEntry(targetFeature[2]))
+                report(node, 'Inside a feature, import the owning module directly to avoid barrel cycles.');
+
+            if (target.startsWith('test/') || /\.test[.-]|-test[.-]/.test(target))
+                report(node, 'Test support must not enter the application dependency graph.');
+        }
+
+        function check(node) {
+            const specifier = node.source?.value;
+
+            if (typeof specifier !== 'string') return;
+
+            if (role === 'design-system') checkDesignSystem(node, specifier);
+            else checkApp(node, specifier);
+        }
+
+        return {
+            ImportDeclaration: check,
+            ImportExpression: check,
+            ExportNamedDeclaration: check,
+            ExportAllDeclaration: check,
+        };
+    },
+};
+
+const rawElements = /^(h1|h2|h3|h4|h5|h6|p|button|input|select|textarea|svg)$/;
+
+/** Design-system components whose geometry and colour props are looks: apps pick a named recipe instead. */
+const recipeComponents =
+    /^(Text|Heading|Link|Button|IconButton|Badge|Stack|Inline|Grid|Avatar|Loading|StatusIndicator|Alert)$/;
+const lookProps = /^(size|color|weight|gap|radius|minChildWidth|fontSize|lineHeight|letterSpacing)$/;
+
+/** Form controls, whose styling and geometry the design system owns entirely. */
+const formControls = /^(Input|Select|Field|FormField|Textarea)$/;
+const formLookProps = /^(fullWidth|size|variant|color)$/;
+
+const noVisualRecipes = {
+    meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+            className:
+                'Visual recipes belong in the design system, not application code. Use or add a component there.',
+            style: 'Inline styles belong in the design system. Use or add a component there.',
+            element:
+                'Use the design-system component for <{{name}}> so typography, accessibility, styling and loading stay consistent.',
+            lookProp:
+                'Choose a semantic recipe instead of `{{prop}}`: typography, geometry, colour and spacing belong to the design system.',
+        },
+    },
+    create(context) {
+        if (isTest(context.filename)) return {};
+
+        /** The local names this file imports from the design system; only their props are checked. */
+        const designSystemNames = new Set();
+
+        return {
+            ImportDeclaration(node) {
+                if (typeof node.source.value !== 'string' || !node.source.value.startsWith(designSystemPackage)) return;
+
+                for (const specifier of node.specifiers) designSystemNames.add(specifier.local.name);
+            },
+            JSXAttribute(node) {
+                const name = node.name?.name;
+                const element = node.parent?.name;
+
+                if (name === 'className') context.report({ node, messageId: 'className' });
+                else if (name === 'style') context.report({ node, messageId: 'style' });
+                else if (
+                    element?.type === 'JSXIdentifier' &&
+                    designSystemNames.has(element.name) &&
+                    typeof name === 'string' &&
+                    ((recipeComponents.test(element.name) && lookProps.test(name)) ||
+                        (formControls.test(element.name) && formLookProps.test(name)))
+                )
+                    context.report({ node, messageId: 'lookProp', data: { prop: name } });
+            },
+            JSXOpeningElement(node) {
+                if (node.name?.type === 'JSXIdentifier' && rawElements.test(node.name.name))
+                    context.report({ node, messageId: 'element', data: { name: node.name.name } });
+            },
+        };
+    },
+};
+
+const blocks = new Set(['ClassDeclaration', 'IfStatement', 'WhileStatement', 'SwitchStatement', 'TryStatement']);
+
+/** The statement kinds ESLint's padding-line-between-statements names, for the ones Lar's rule uses. */
+function kind(node) {
+    if (node.type === 'ExpressionStatement' && typeof node.directive === 'string') return 'directive';
+
+    if (node.type === 'ImportDeclaration') return 'import';
+
+    if (node.type === 'VariableDeclaration') return 'variable';
+
+    if (node.type === 'ReturnStatement') return 'return';
+
+    if (node.type === 'FunctionDeclaration' || blocks.has(node.type)) return 'block';
+
+    return 'other';
+}
+
+/** Whether a blank line must, may or need not separate two statements: the last matching row wins, as in ESLint. */
+function padding(prev, next) {
+    let result = 'any';
+
+    if (prev === 'directive') result = next === 'directive' ? 'any' : 'always';
+
+    if (prev === 'import') result = next === 'import' ? 'any' : 'always';
+
+    if (next === 'variable' || prev === 'variable') result = 'always';
+
+    if (prev === 'variable' && next === 'variable') result = 'any';
+
+    if (next === 'block' || prev === 'block') result = 'always';
+
+    if (next === 'return') result = 'always';
+
+    return result;
+}
+
+const range = (node) => node.range ?? [node.start, node.end];
+
+/**
+ * Lar's blank lines between statements, which Prettier and Oxfmt leave alone: after directives and imports, around
+ * variable declarations, around blocks (class, function, if, while, switch, try) and before a return.
+ */
+const paddingLines = {
+    meta: {
+        type: 'layout',
+        fixable: 'whitespace',
+        schema: [],
+        messages: { expected: 'Expected a blank line before this statement.' },
+    },
+    create(context) {
+        const text = context.sourceCode.text;
+
+        function checkList(statements) {
+            for (let index = 1; index < statements.length; index += 1) {
+                const prev = statements[index - 1];
+                const next = statements[index];
+
+                if (padding(kind(prev), kind(next)) !== 'always') continue;
+
+                const between = text.slice(range(prev)[1], range(next)[0]);
+
+                if (/\n[ \t]*\r?\n/.test(between)) continue;
+
+                context.report({
+                    node: next,
+                    messageId: 'expected',
+                    fix(fixer) {
+                        const lineEnd = text.indexOf('\n', range(prev)[1]);
+
+                        if (lineEnd === -1 || lineEnd > range(next)[0]) return null;
+
+                        return fixer.insertTextAfterRange([lineEnd, lineEnd], '\n');
+                    },
+                });
+            }
+        }
+
+        return {
+            Program: (node) => checkList(node.body),
+            BlockStatement: (node) => checkList(node.body),
+            StaticBlock: (node) => checkList(node.body),
+            SwitchCase: (node) => checkList(node.consequent),
+        };
+    },
+};
+
+export default {
+    meta: { name: 'lar' },
+    rules: { boundaries, 'no-visual-recipes': noVisualRecipes, 'padding-lines': paddingLines },
+};

package/tsconfig/app.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "display": "Lar web app",
+    "compilerOptions": {
+        "target": "es2023",
+        "lib": ["es2023", "dom", "dom.iterable"],
+        "module": "preserve",
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx",
+        "types": ["vite-plus/client"],
+        "strict": true,
+        "noEmit": true,
+        "allowImportingTsExtensions": true,
+        "erasableSyntaxOnly": true,
+        "verbatimModuleSyntax": true,
+        "noUncheckedIndexedAccess": true,
+        "noFallthroughCasesInSwitch": true,
+        "resolveJsonModule": true,
+        "skipLibCheck": true
+    }
+}

package/tsconfig/library.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "display": "Lar web library",
+    "extends": "./app.json",
+    "compilerOptions": {
+        "noEmit": false,
+        "declaration": true,
+        "emitDeclarationOnly": true,
+        "allowImportingTsExtensions": false,
+        "isolatedDeclarations": false
+    }
+}

package/tsconfig/node.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "display": "Lar Node scripts and configs",
+    "compilerOptions": {
+        "target": "es2023",
+        "lib": ["es2023"],
+        "module": "nodenext",
+        "moduleResolution": "nodenext",
+        "types": ["node"],
+        "strict": true,
+        "noEmit": true,
+        "allowImportingTsExtensions": true,
+        "erasableSyntaxOnly": true,
+        "verbatimModuleSyntax": true,
+        "noUncheckedIndexedAccess": true,
+        "skipLibCheck": true
+    }
+}