@bottomlessmargaritas/formatting-configs 1.0.0

package/bin/cli.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+import {
+    existsSync,
+    copyFileSync,
+    mkdirSync,
+    readFileSync,
+    writeFileSync,
+    readdirSync,
+    renameSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { createInterface } from "node:readline";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIGS_DIR = resolve(__dirname, "..", "configs");
+
+const isAuto = process.argv.includes("--auto");
+const isDryRun = process.argv.includes("--dry-run");
+const skipInstall = process.argv.includes("--skip-install");
+
+const PKG_NAME = "@bottomlessmargaritas/formatting-configs";
+
+const SCRIPTS_TO_ADD = {
+    format: 'prettier --write "**/*.{js,jsx,ts,tsx,json,css,scss,md}"',
+    "format:check": 'prettier --check "**/*.{js,jsx,ts,tsx,json,css,scss,md}"',
+    lint: "eslint .",
+    "lint:fix": "eslint . --fix",
+};
+
+const PEER_DEPS = {
+    "@trivago/prettier-plugin-sort-imports": "^4",
+    "@typescript-eslint/parser": "^8",
+    eslint: "^9.0.0",
+    "eslint-config-prettier": "^10",
+    "eslint-plugin-security": "^3",
+    "eslint-plugin-unused-imports": "^4",
+    globals: "^15",
+    prettier: "^3",
+    "typescript-eslint": "^8",
+};
+
+// React-related deps — only installed if project uses React
+const REACT_PEER_DEPS = {
+    "@babel/eslint-parser": "^7",
+    "eslint-plugin-jsx-a11y": "^6",
+    "eslint-plugin-react": "^7",
+    "eslint-plugin-react-hooks": "^5",
+};
+
+function findProjectRoot(startDir) {
+    let dir = startDir;
+    while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, "package.json"))) {
+            return dir;
+        }
+        dir = dirname(dir);
+    }
+    return null;
+}
+
+function getBackupName(filePath) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    return `${filePath}.backup-${timestamp}`;
+}
+
+function detectPackageManager(projectRoot) {
+    if (existsSync(join(projectRoot, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (existsSync(join(projectRoot, "yarn.lock"))) {
+        return "yarn";
+    }
+    if (existsSync(join(projectRoot, "bun.lockb")) || existsSync(join(projectRoot, "bun.lock"))) {
+        return "bun";
+    }
+    return "npm";
+}
+
+function projectUsesReact(projectRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        return "react" in allDeps || "next" in allDeps;
+    } catch {
+        return false;
+    }
+}
+
+async function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase());
+        });
+    });
+}
+
+async function copyConfigFiles(projectRoot) {
+    const configFiles = readdirSync(CONFIGS_DIR);
+    let copied = 0;
+    let backed = 0;
+    let skipped = 0;
+
+    for (const file of configFiles) {
+        const source = join(CONFIGS_DIR, file);
+        const target = join(projectRoot, file);
+
+        if (existsSync(target)) {
+            const sourceContent = readFileSync(source, "utf8");
+            const targetContent = readFileSync(target, "utf8");
+
+            if (sourceContent === targetContent) {
+                skipped++;
+                continue;
+            }
+
+            if (isAuto) {
+                const backupPath = getBackupName(target);
+                if (!isDryRun) {
+                    renameSync(target, backupPath);
+                    copyFileSync(source, target);
+                    console.log(`  ↪ Backed up existing ${file} → ${backupPath.split("/").pop()}`);
+                }
+                backed++;
+                copied++;
+            } else {
+                const answer = await prompt(`  ${file} already exists and differs. Overwrite? (y/n) `);
+                if (answer !== "y") {
+                    skipped++;
+                    continue;
+                }
+
+                const backupPath = getBackupName(target);
+                if (!isDryRun) {
+                    renameSync(target, backupPath);
+                    copyFileSync(source, target);
+                    console.log(`  ↪ Backed up → ${backupPath.split("/").pop()}`);
+                }
+                backed++;
+                copied++;
+            }
+        } else {
+            if (!isDryRun) {
+                copyFileSync(source, target);
+            }
+            copied++;
+        }
+    }
+
+    console.log(`${PKG_NAME}: ${copied} config(s) copied, ${backed} backed up, ${skipped} unchanged`);
+}
+
+function updatePackageJsonScripts(projectRoot) {
+    const pkgPath = join(projectRoot, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+
+    if (!pkg.scripts) {
+        pkg.scripts = {};
+    }
+
+    let added = 0;
+    for (const [name, command] of Object.entries(SCRIPTS_TO_ADD)) {
+        if (!pkg.scripts[name]) {
+            pkg.scripts[name] = command;
+            added++;
+        }
+    }
+
+    if (added > 0) {
+        if (!isDryRun) {
+            writeFileSync(pkgPath, JSON.stringify(pkg, null, 4) + "\n", "utf8");
+        }
+        console.log(`${PKG_NAME}: Added ${added} script(s) to package.json (format, format:check, lint, lint:fix)`);
+    } else {
+        console.log(`${PKG_NAME}: All formatting scripts already present in package.json`);
+    }
+}
+
+function installMissingPeers(projectRoot) {
+    const pkgPath = join(projectRoot, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    const usesReact = projectUsesReact(projectRoot);
+    const requiredDeps = { ...PEER_DEPS, ...(usesReact ? REACT_PEER_DEPS : {}) };
+
+    const missing = Object.entries(requiredDeps)
+        .filter(([name]) => !(name in allDeps))
+        .map(([name, version]) => `${name}@${version}`);
+
+    if (missing.length === 0) {
+        console.log(`${PKG_NAME}: All peer dependencies already installed`);
+        return;
+    }
+
+    const pm = detectPackageManager(projectRoot);
+    const installCmd =
+        pm === "yarn"
+            ? `yarn add --dev ${missing.join(" ")}`
+            : `${pm} add -D ${missing.join(" ")}`;
+
+    console.log(`${PKG_NAME}: Installing ${missing.length} missing peer dep(s) with ${pm}...`);
+
+    if (!isDryRun) {
+        try {
+            execSync(installCmd, { cwd: projectRoot, stdio: "inherit" });
+        } catch {
+            console.warn(`${PKG_NAME}: Peer dependency install failed. Run manually:\n  ${installCmd}`);
+        }
+    } else {
+        console.log(`[dry-run] Would run: ${installCmd}`);
+    }
+}
+
+async function run() {
+    const cwd = process.env.INIT_CWD || process.cwd();
+    const projectRoot = findProjectRoot(cwd);
+
+    if (!projectRoot) {
+        console.error(`${PKG_NAME}: Could not find project root (no package.json found).`);
+        process.exit(1);
+    }
+
+    await copyConfigFiles(projectRoot);
+    updatePackageJsonScripts(projectRoot);
+
+    if (!skipInstall) {
+        installMissingPeers(projectRoot);
+    }
+}
+
+run().catch((err) => {
+    console.error(`${PKG_NAME}:`, err.message);
+    process.exit(1);
+});

package/configs/eslint.config.js

@@ -0,0 +1,168 @@
+import babelParser from '@babel/eslint-parser';
+import tsEslintParser from '@typescript-eslint/parser';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import security from 'eslint-plugin-security';
+import unusedImports from 'eslint-plugin-unused-imports';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config([
+  {
+    ignores: ['build', 'dist', 'node_modules', '**/*.d.ts', '.turbo'],
+  },
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: true,
+    },
+    extends: [security.configs.recommended],
+    plugins: {
+      security,
+      'unused-imports': unusedImports,
+    },
+    rules: {
+      'curly': 'error',
+      'no-console': ['warn', { allow: ['warn', 'info', 'error', 'group'] }],
+      'no-implicit-globals': 'error',
+      'no-param-reassign': ['error', { props: false }],
+      'no-shadow': 'warn',
+      'no-undef': 'error',
+      'no-underscore-dangle': 'off',
+      'no-unreachable': 'warn',
+      'no-unused-expressions': 'error',
+      'no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      'no-useless-escape': 'off',
+      'no-var': 'warn',
+      'object-shorthand': ['error', 'always'],
+      'prefer-const': 'warn',
+      'security/detect-eval-with-expression': 'warn',
+      'security/detect-non-literal-fs-filename': 'warn',
+      'security/detect-non-literal-regexp': 'warn',
+      'security/detect-non-literal-require': 'warn',
+      'security/detect-object-injection': 'off',
+      'security/detect-possible-timing-attacks': 'warn',
+      'unused-imports/no-unused-imports': 'warn',
+    },
+  },
+  {
+    files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+      },
+    },
+  },
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    extends: [...tseslint.configs.recommended],
+    languageOptions: {
+      ...react.configs.flat.recommended.languageOptions,
+      ecmaVersion: 'latest',
+      parser: tsEslintParser,
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+        ecmaVersion: 'latest',
+        project: ['./tsconfig.json'],
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      '@typescript-eslint/ban-ts-comment': ['warn', { 'ts-ignore': 'allow-with-description' }],
+      '@typescript-eslint/consistent-type-definitions': 'off',
+      '@typescript-eslint/consistent-type-imports': [
+        'warn',
+        {
+          fixStyle: 'inline-type-imports',
+          prefer: 'type-imports',
+        },
+      ],
+      '@typescript-eslint/no-empty-object-type': 'warn',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-misused-promises': [
+        'warn',
+        {
+          checksVoidReturn: { attributes: false },
+        },
+      ],
+      '@typescript-eslint/no-require-imports': 'warn',
+      '@typescript-eslint/no-unsafe-assignment': 'warn',
+      '@typescript-eslint/no-unused-expressions': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/require-await': 'off',
+      'no-undef': 'off',
+      'no-var': 'warn',
+      'prefer-const': 'warn',
+    },
+  },
+  {
+    files: ['**/*.tsx'],
+    plugins: {
+      'jsx-a11y': jsxA11y,
+      react,
+      'react-hooks': reactHooks,
+    },
+    settings: {
+      react: { version: 'detect' },
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      ...react.configs.flat.recommended.rules,
+      ...jsxA11y.flatConfigs.recommended.rules,
+      'jsx-a11y/anchor-is-valid': 'warn',
+      'jsx-a11y/click-events-have-key-events': 'off',
+      'jsx-a11y/iframe-has-title': 'off',
+      'jsx-a11y/interactive-supports-focus': 'off',
+      'jsx-a11y/no-autofocus': 'warn',
+      'jsx-a11y/no-noninteractive-element-interactions': 'off',
+      'jsx-a11y/no-static-element-interactions': 'off',
+      'react-hooks/exhaustive-deps': 'warn',
+      'react-hooks/rules-of-hooks': 'warn',
+      'react/display-name': 'warn',
+      'react/jsx-curly-brace-presence': ['error', 'never'],
+      'react/no-unescaped-entities': 'warn',
+      'react/prop-types': 'off',
+      'react/react-in-jsx-scope': 'off',
+    },
+  },
+  {
+    files: [
+      '**/__tests__/**',
+      '**/__mocks__/**',
+      '**/tests/**',
+      '**/*.test.ts',
+      '**/*.test.tsx',
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      'no-console': 'off',
+      'security/detect-non-literal-regexp': 'off',
+    },
+  },
+  eslintConfigPrettier,
+]);

package/configs/prettier.config.js

@@ -0,0 +1,50 @@
+export default {
+  arrowParens: 'always',
+  bracketSpacing: true,
+  htmlWhitespaceSensitivity: 'css',
+  importOrder: [
+    '^react$',
+    '^react-dom',
+    '.*\\.css$',
+    '<THIRD_PARTY_MODULES>',
+    '^[../]',
+    '^[./]',
+  ],
+  importOrderSeparation: true,
+  importOrderSortSpecifiers: true,
+  jsxSingleQuote: true,
+  overrides: [
+    {
+      files: ['*.json'],
+      options: {
+        parser: 'json5',
+        quoteProps: 'preserve',
+        singleQuote: false,
+        trailingComma: 'none',
+      },
+    },
+    {
+      files: ['.*rc'],
+      options: {
+        parser: 'json5',
+        quoteProps: 'preserve',
+        singleQuote: false,
+        trailingComma: 'none',
+      },
+    },
+    {
+      files: ['*.yml', '*.yaml'],
+      options: {
+        singleQuote: true,
+      },
+    },
+  ],
+  plugins: ['@trivago/prettier-plugin-sort-imports'],
+  printWidth: 80,
+  quoteProps: 'as-needed',
+  semi: true,
+  singleQuote: true,
+  tabWidth: 2,
+  trailingComma: 'all',
+  useTabs: false,
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@bottomlessmargaritas/formatting-configs",
+    "version": "1.0.0",
+    "description": "Canonical Prettier and ESLint configs for @nullvoidundefined projects",
+    "type": "module",
+    "bin": {
+        "formatting-configs": "./bin/cli.js"
+    },
+    "files": [
+        "bin/",
+        "configs/"
+    ],
+    "scripts": {
+        "postinstall": "node bin/cli.js --auto"
+    },
+    "peerDependencies": {
+        "@babel/eslint-parser": ">=7",
+        "@trivago/prettier-plugin-sort-imports": ">=4",
+        "@typescript-eslint/parser": ">=8",
+        "eslint": ">=9 <10",
+        "eslint-config-prettier": ">=10",
+        "eslint-plugin-jsx-a11y": ">=6",
+        "eslint-plugin-react": ">=7",
+        "eslint-plugin-react-hooks": ">=5",
+        "eslint-plugin-security": ">=3",
+        "eslint-plugin-unused-imports": ">=4",
+        "globals": ">=15",
+        "prettier": ">=3",
+        "typescript-eslint": ">=8"
+    },
+    "peerDependenciesMeta": {
+        "@babel/eslint-parser": { "optional": true },
+        "eslint-plugin-jsx-a11y": { "optional": true },
+        "eslint-plugin-react": { "optional": true },
+        "eslint-plugin-react-hooks": { "optional": true }
+    },
+    "keywords": [
+        "prettier",
+        "eslint",
+        "formatting",
+        "config"
+    ],
+    "author": "nullvoidundefined",
+    "license": "MIT",
+    "engines": {
+        "node": ">=18"
+    }
+}