@askviraj/linter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viraj Patel
+
+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/dist/auto.js

@@ -0,0 +1,4 @@
+import { createConfig } from "./config-factory.js";
+import { loadYamlOptions } from "./config-loader.js";
+const config = createConfig(loadYamlOptions(process.cwd()));
+export default config;

package/dist/cli/args.js

@@ -0,0 +1,96 @@
+import { ParseError } from "./types.js";
+export function parseArgs(rawArgs) {
+    const flags = {
+        init: false,
+        force: false,
+        fix: false,
+        cache: false,
+        quiet: false,
+        ignore: true,
+        debug: false,
+        version: false,
+        help: false,
+    };
+    let cacheLocation;
+    let format;
+    let maxWarnings;
+    const positional = [];
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === undefined) {
+            break;
+        }
+        switch (arg) {
+            case "--init":
+                flags.init = true;
+                break;
+            case "--force":
+                flags.force = true;
+                break;
+            case "--fix":
+                flags.fix = true;
+                break;
+            case "--cache":
+                flags.cache = true;
+                break;
+            case "--quiet":
+                flags.quiet = true;
+                break;
+            case "--no-ignore":
+                flags.ignore = false;
+                break;
+            case "--debug":
+                flags.debug = true;
+                break;
+            case "--version":
+            case "-v":
+                flags.version = true;
+                break;
+            case "--help":
+            case "-h":
+                flags.help = true;
+                break;
+            case "--cache-location": {
+                const next = rawArgs[++i];
+                if (!next) {
+                    throw new ParseError("--cache-location requires a path argument");
+                }
+                cacheLocation = next;
+                break;
+            }
+            case "--format":
+            case "-f": {
+                const next = rawArgs[++i];
+                if (!next) {
+                    throw new ParseError("--format requires a format name");
+                }
+                format = next;
+                break;
+            }
+            case "--max-warnings": {
+                const next = rawArgs[++i];
+                if (!next || Number.isNaN(Number(next))) {
+                    throw new ParseError("--max-warnings requires a number");
+                }
+                maxWarnings = Number(next);
+                break;
+            }
+            case "--":
+                for (let j = i + 1; j < rawArgs.length; j++) {
+                    const remaining = rawArgs[j];
+                    if (remaining !== undefined) {
+                        positional.push(remaining);
+                    }
+                }
+                i = rawArgs.length;
+                break;
+            default:
+                if (arg.startsWith("-")) {
+                    throw new ParseError(`Unknown flag: ${arg}`);
+                }
+                positional.push(arg);
+                break;
+        }
+    }
+    return { flags, cacheLocation, format, maxWarnings, positional };
+}

package/dist/cli/commands/help.js

@@ -0,0 +1,18 @@
+export function runHelp() {
+    console.log(`@askviraj/linter [options] [files...]
+
+Options:
+  --init              Scaffold eslint.config.mjs and .config/linter.yaml
+  --force             Overwrite existing files when used with --init
+  --fix               Automatically fix problems
+  --cache             Only check changed files
+  --cache-location    Path to the cache file or directory
+  --no-ignore         Disable use of ignore files
+  --quiet             Report errors only
+  --debug             Enable debug logging
+  --format, -f        Use a specific output format
+  --max-warnings      Number of warnings to trigger nonzero exit code
+  --version, -v       Show version
+  --help, -h          Show help
+`);
+}

package/dist/cli/commands/init.js

@@ -0,0 +1,153 @@
+import { applyEdits, findNodeAtLocation, getNodeValue, modify, parseTree, } from "jsonc-parser";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { resolve } from "node:path";
+const ESLINT_CONFIG_MJS = `// Auto-generated by @askviraj/linter
+// Run \`npx @askviraj/linter --init\` to regenerate.
+export { default } from "@askviraj/linter/auto";
+`;
+const LINTER_YAML = `# @askviraj/linter configuration
+#
+# Add custom ignores, rule overrides, and additional config blocks below.
+
+version: 1
+
+# ignores:
+#   - "**/generated/**"
+#   - "**/*.d.ts"
+#
+# overrides:
+#   typescript:
+#     rules:
+#       "@typescript-eslint/no-explicit-any": "error"
+#
+# configs:
+#   - name: "custom"
+#     files: ["**/*.ts"]
+#     rules: {}
+`;
+const VSCODE_SETTINGS = {
+    "eslint.useFlatConfig": true,
+};
+/**
+ * Read an existing .vscode/settings.json and update/add eslint.useFlatConfig.
+ * Uses jsonc-parser so comments, trailing commas, and formatting are preserved.
+ */
+function updateVsCodeSettings(existingPath) {
+    const text = readFileSync(existingPath, "utf-8");
+    const root = parseTree(text);
+    if (!root) {
+        // Completely unparseable — fall back to a fresh object.
+        return {
+            content: JSON.stringify(VSCODE_SETTINGS, null, 2) + "\n",
+            action: "updated",
+        };
+    }
+    const node = findNodeAtLocation(root, ["eslint.useFlatConfig"]);
+    if (node) {
+        const value = getNodeValue(node);
+        if (value === true) {
+            return { content: text, action: "up-to-date" };
+        }
+        // Replace existing value.
+        const edits = modify(text, ["eslint.useFlatConfig"], true, {
+            formattingOptions: { tabSize: 2, insertSpaces: true, eol: "\n" },
+        });
+        return { content: applyEdits(text, edits), action: "updated" };
+    }
+    // Property missing — add it.
+    const edits = modify(text, ["eslint.useFlatConfig"], true, {
+        formattingOptions: { tabSize: 2, insertSpaces: true, eol: "\n" },
+    });
+    return { content: applyEdits(text, edits), action: "updated" };
+}
+export function runInit(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const actions = [];
+    let settingsError;
+    // 1. eslint.config.mjs
+    const eslintConfigPath = resolve(cwd, "eslint.config.mjs");
+    const eslintExisted = existsSync(eslintConfigPath);
+    if (eslintExisted && !options.force) {
+        actions.push({ path: eslintConfigPath, action: "skipped" });
+    }
+    else {
+        try {
+            writeFileSync(eslintConfigPath, ESLINT_CONFIG_MJS);
+            actions.push({
+                path: eslintConfigPath,
+                action: eslintExisted ? "overwritten" : "created",
+            });
+        }
+        catch (e) {
+            throw new Error(`Failed to write ${eslintConfigPath}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    // 2. .config/linter.yaml
+    const configDir = resolve(cwd, ".config");
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    const linterYamlPath = resolve(configDir, "linter.yaml");
+    const linterExisted = existsSync(linterYamlPath);
+    if (linterExisted && !options.force) {
+        actions.push({ path: linterYamlPath, action: "skipped" });
+    }
+    else {
+        try {
+            writeFileSync(linterYamlPath, LINTER_YAML);
+            actions.push({
+                path: linterYamlPath,
+                action: linterExisted ? "overwritten" : "created",
+            });
+        }
+        catch (e) {
+            throw new Error(`Failed to write ${linterYamlPath}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    // 3. .vscode/settings.json
+    const vscodeDir = resolve(cwd, ".vscode");
+    if (!existsSync(vscodeDir)) {
+        mkdirSync(vscodeDir, { recursive: true });
+    }
+    const settingsPath = resolve(vscodeDir, "settings.json");
+    if (existsSync(settingsPath)) {
+        try {
+            const result = updateVsCodeSettings(settingsPath);
+            if (result.action === "up-to-date") {
+                actions.push({ path: settingsPath, action: "up-to-date" });
+            }
+            else {
+                writeFileSync(settingsPath, result.content);
+                actions.push({ path: settingsPath, action: "updated" });
+            }
+        }
+        catch (e) {
+            settingsError = e instanceof Error ? e.message : String(e);
+            actions.push({ path: settingsPath, action: "failed" });
+        }
+    }
+    else {
+        try {
+            writeFileSync(settingsPath, JSON.stringify(VSCODE_SETTINGS, null, 2) + "\n");
+            actions.push({ path: settingsPath, action: "created" });
+        }
+        catch (e) {
+            throw new Error(`Failed to write ${settingsPath}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    console.log("Initialized @askviraj/linter:");
+    for (const { path, action } of actions) {
+        console.log(`  [${action}] ${path}`);
+    }
+    const skipped = actions.filter(a => a.action === "skipped");
+    if (skipped.length > 0) {
+        console.log("");
+        console.log("Some files were skipped because they already exist. Use --force to overwrite.");
+    }
+    if (settingsError) {
+        throw new Error(`Failed to update ${settingsPath}: ${settingsError}\n`
+            + "The file contains invalid JSONC. Fix the file and try again.");
+    }
+    console.log("");
+    console.log("Note: If you have VS Code open, restart the ESLint server (", "Cmd+Shift+P → 'ESLint: Restart ESLint Server'", ") or restart VS Code for changes to take effect.");
+}

package/dist/cli/commands/lint.js

@@ -0,0 +1,47 @@
+import { ESLint } from "eslint";
+import { createRequire } from "node:module";
+import { createConfig } from "../../config-factory.js";
+import { loadYamlOptions } from "../../config-loader.js";
+const require = createRequire(import.meta.url);
+export async function runLint(args) {
+    if (args.flags.debug) {
+        const debug = require("debug");
+        debug.enable("eslint:*,-eslint:code-path,eslintrc:*");
+    }
+    const targets = args.positional.length > 0 ? args.positional : ["."];
+    const config = createConfig(loadYamlOptions(process.cwd()));
+    const eslint = new ESLint({
+        overrideConfigFile: true,
+        overrideConfig: config,
+        fix: args.flags.fix,
+        cache: args.flags.cache,
+        cacheLocation: args.cacheLocation,
+        errorOnUnmatchedPattern: false,
+        ignore: args.flags.ignore,
+    });
+    let results;
+    try {
+        results = await eslint.lintFiles(targets);
+    }
+    catch (e) {
+        throw new Error(e instanceof Error ? e.message : String(e), { cause: e });
+    }
+    if (args.flags.fix) {
+        await ESLint.outputFixes(results);
+    }
+    if (args.flags.quiet) {
+        results = ESLint.getErrorResults(results);
+    }
+    const formatter = await eslint.loadFormatter(args.format);
+    const output = await formatter.format(results);
+    if (output) {
+        console.log(output);
+    }
+    const errorCount = results.reduce((sum, r) => sum + r.errorCount, 0);
+    const warningCount = results.reduce((sum, r) => sum + r.warningCount, 0);
+    const failed = errorCount > 0
+        || (args.maxWarnings !== undefined
+            && args.maxWarnings >= 0
+            && warningCount > args.maxWarnings);
+    return failed ? 1 : 0;
+}

package/dist/cli/commands/version.js

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve, } from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+function getPackageVersion(name, requireFn) {
+    try {
+        const mainPath = requireFn.resolve(name);
+        let dir = dirname(mainPath);
+        while (dir !== dirname(dir)) {
+            const pkgPath = resolve(dir, "package.json");
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+                if (pkg.name === name && pkg.version) {
+                    return pkg.version;
+                }
+            }
+            catch {
+                // Continue walking up.
+            }
+            dir = dirname(dir);
+        }
+    }
+    catch {
+        // Package main not resolvable; try fallback.
+    }
+    try {
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(moduleDir, "..", "..", "..", "node_modules", name, "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (pkg.name === name && pkg.version) {
+            return pkg.version;
+        }
+    }
+    catch {
+        // Not found in node_modules either.
+    }
+    return undefined;
+}
+export function runVersion() {
+    let ownVersion;
+    let deps;
+    try {
+        const ownPkgPath = require.resolve("../../../package.json");
+        const ownPkg = JSON.parse(readFileSync(ownPkgPath, "utf-8"));
+        ownVersion = ownPkg.version;
+        deps = ownPkg.dependencies;
+    }
+    catch {
+        throw new Error("Failed to read package metadata.");
+    }
+    if (!ownVersion) {
+        throw new Error("Package version not found.");
+    }
+    const patterns = [
+        /^eslint$/,
+        /^@eslint\//,
+        /^@typescript-eslint\//,
+        /^typescript-eslint$/,
+        /^@html-eslint\//,
+        /^@poupe\/eslint-plugin-/,
+        /^eslint-plugin-/,
+    ];
+    const depNames = deps
+        ? Object.keys(deps).filter(name => patterns.some(pattern => pattern.test(name)))
+        : [];
+    const pluginVersions = [];
+    for (const name of depNames) {
+        const version = getPackageVersion(name, require);
+        if (version) {
+            pluginVersions.push({ name, version });
+        }
+    }
+    pluginVersions.sort((a, b) => a.name.localeCompare(b.name));
+    console.log(`v${ownVersion}`);
+    console.log("------");
+    const eslintEntry = pluginVersions.find(p => p.name === "eslint");
+    if (eslintEntry) {
+        console.log(`eslint v${eslintEntry.version}`);
+    }
+    for (const { name, version } of pluginVersions) {
+        if (name !== "eslint") {
+            console.log(`${name} v${version}`);
+        }
+    }
+}

package/dist/cli/runner.js

@@ -0,0 +1,28 @@
+import { parseArgs } from "./args.js";
+import { runHelp } from "./commands/help.js";
+import { runInit } from "./commands/init.js";
+import { runLint } from "./commands/lint.js";
+import { runVersion } from "./commands/version.js";
+export async function run(rawArgs) {
+    try {
+        const args = parseArgs(rawArgs);
+        if (args.flags.help) {
+            runHelp();
+            return;
+        }
+        if (args.flags.version) {
+            runVersion();
+            return;
+        }
+        if (args.flags.init) {
+            runInit({ force: args.flags.force });
+            return;
+        }
+        const exitCode = await runLint(args);
+        process.exit(exitCode);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : e);
+        process.exit(1);
+    }
+}

package/dist/cli/types.js

@@ -0,0 +1,6 @@
+export class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ParseError";
+    }
+}

package/dist/config/ignores.js

@@ -0,0 +1,12 @@
+import { globalIgnores } from "eslint/config";
+export const ignores = globalIgnores([
+    "**/node_modules/",
+    "**/dist/",
+    "**/.turbo/",
+    "**/.astro/",
+    "**/*.d.ts",
+    "**/AGENTS.md",
+    ".agents/**/*.md",
+    ".claude/**/*.md",
+    ".github/**/*.md",
+]);

package/dist/config/index.js

@@ -0,0 +1,29 @@
+import { defineConfig } from "eslint/config";
+import { ignores } from "./ignores.js";
+import { astroConfig } from "./presets/astro.js";
+import { cssConfig } from "./presets/css.js";
+import { htmlConfig } from "./presets/html.js";
+import { javascriptConfig } from "./presets/javascript.js";
+import { jsonConfig } from "./presets/json.js";
+import { jsoncConfig } from "./presets/jsonc.js";
+import { markdownTsConfig } from "./presets/markdown-ts.js";
+import { markdownConfig } from "./presets/markdown.js";
+import { tomlConfig } from "./presets/toml.js";
+import { typescriptConfig } from "./presets/typescript.js";
+import { yamlConfig } from "./presets/yaml.js";
+export function composeBaseConfig() {
+    return defineConfig([
+        ignores,
+        javascriptConfig,
+        typescriptConfig,
+        astroConfig,
+        jsonConfig,
+        jsoncConfig,
+        markdownConfig,
+        markdownTsConfig,
+        yamlConfig,
+        tomlConfig,
+        htmlConfig,
+        cssConfig,
+    ]);
+}

package/dist/config/jsonc-files.js

@@ -0,0 +1,6 @@
+export const JSONC_FILES = [
+    "**/tsconfig.json",
+    "**/tsconfig.*.json",
+    "**/tsconfig-strict.json",
+    "**/.vscode/*.json",
+];

package/dist/config/presets/astro.js

@@ -0,0 +1,25 @@
+import tsParser from "@typescript-eslint/parser";
+import astroParser from "astro-eslint-parser";
+import astro from "eslint-plugin-astro";
+import globals from "globals";
+export const astroConfig = {
+    name: "astro",
+    files: ["**/*.astro"],
+    plugins: { astro },
+    languageOptions: {
+        globals: {
+            ...globals.node,
+            ...globals.astro,
+        },
+        parser: astroParser,
+        parserOptions: {
+            parser: tsParser,
+            extraFileExtensions: [".astro"],
+            sourceType: "module",
+        },
+    },
+    extends: [astro.configs.recommended],
+    rules: {
+        "no-unreachable": "off",
+    },
+};

package/dist/config/presets/css.js

@@ -0,0 +1,10 @@
+import css from "@eslint/css";
+import tailwindcss from "@poupe/eslint-plugin-tailwindcss";
+export const cssConfig = {
+    files: ["**/*.css"],
+    extends: [css.configs.recommended, tailwindcss.configs["recommended"]],
+    name: "css",
+    rules: {
+        "css/no-invalid-at-rules": "off",
+    },
+};

package/dist/config/presets/html.js

@@ -0,0 +1,11 @@
+import html from "@html-eslint/eslint-plugin";
+export const htmlConfig = {
+    extends: [html.configs.recommended],
+    files: ["**/*.html"],
+    language: "html/html",
+    name: "html",
+    plugins: { html },
+    rules: {
+        "html/indent": ["error", 2],
+    },
+};

package/dist/config/presets/javascript.js

@@ -0,0 +1,17 @@
+import js from "@eslint/js";
+import globals from "globals";
+export const javascriptConfig = {
+    extends: [js.configs.recommended],
+    files: ["**/*.{js,mjs,cjs,jsx}"],
+    languageOptions: {
+        globals: {
+            ...globals.browser,
+            ...globals.node,
+        },
+    },
+    name: "javascript",
+    plugins: { js },
+    rules: {
+        "no-console": "warn",
+    },
+};

package/dist/config/presets/json.js

@@ -0,0 +1,18 @@
+import json from "@eslint/json";
+import { JSONC_FILES } from "../jsonc-files.js";
+export const jsonConfig = {
+    extends: [json.configs.recommended],
+    files: ["**/*.json"],
+    ignores: JSONC_FILES,
+    language: "json/json",
+    name: "json",
+    plugins: { json },
+    rules: {
+        "json/no-duplicate-keys": "error",
+        "json/no-empty-keys": "error",
+        "json/no-unnormalized-keys": "error",
+        "json/no-unsafe-values": "error",
+        "json/sort-keys": "off",
+        "json/top-level-interop": "error",
+    },
+};

package/dist/config/presets/jsonc.js

@@ -0,0 +1,21 @@
+import json from "@eslint/json";
+import { JSONC_FILES } from "../jsonc-files.js";
+export const jsoncConfig = {
+    extends: [json.configs.recommended],
+    files: ["**/*.jsonc", ...JSONC_FILES],
+    language: "json/jsonc",
+    languageOptions: {
+        allowComments: true,
+        allowTrailingCommas: true,
+    },
+    name: "jsonc",
+    plugins: { json },
+    rules: {
+        "json/no-duplicate-keys": "error",
+        "json/no-empty-keys": "error",
+        "json/no-unnormalized-keys": "error",
+        "json/no-unsafe-values": "error",
+        "json/sort-keys": "off",
+        "json/top-level-interop": "error",
+    },
+};

package/dist/config/presets/markdown-ts.js

@@ -0,0 +1,9 @@
+export const markdownTsConfig = {
+    name: "markdown-typescript",
+    files: ["**/*.md/*.ts", "**/*.md/*.tsx"],
+    rules: {
+        "@typescript-eslint/no-unused-vars": "off",
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-unused-expressions": "off",
+    },
+};

package/dist/config/presets/markdown.js

@@ -0,0 +1,21 @@
+import markdown from "@eslint/markdown";
+export const markdownConfig = {
+    extends: [markdown.configs.recommended],
+    files: ["**/*.md"],
+    name: "markdown",
+    plugins: { markdown },
+    settings: { "markdown/frontmatter": true },
+    rules: {
+        "markdown/no-missing-label-refs": "off",
+        "markdown/no-bare-urls": "error",
+        "markdown/no-duplicate-headings": ["error", { checkSiblingsOnly: true }],
+        "markdown/no-empty-images": "error",
+        "markdown/no-empty-links": "error",
+        "markdown/no-missing-link-fragments": "error",
+        "markdown/no-multiple-h1": "error",
+        "markdown/no-reference-like-urls": "error",
+        "markdown/no-reversed-media-syntax": "error",
+        "markdown/no-space-in-emphasis": "error",
+        "markdown/table-column-count": "error",
+    },
+};

package/dist/config/presets/toml.js

@@ -0,0 +1,9 @@
+import eslintPluginToml from "eslint-plugin-toml";
+export const tomlConfig = {
+    extends: [eslintPluginToml.configs.recommended],
+    files: ["**/*.toml"],
+    language: "toml/toml",
+    name: "toml",
+    plugins: { toml: eslintPluginToml },
+    rules: {},
+};

package/dist/config/presets/typescript.js

@@ -0,0 +1,33 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+export const typescriptConfig = {
+    extends: [js.configs.recommended, tseslint.configs.recommended],
+    files: ["**/*.{ts,mts,cts,tsx}"],
+    ignores: ["**/*.md/*.ts", "**/*.md/*.tsx"],
+    languageOptions: {
+        globals: {
+            ...globals.browser,
+            ...globals.node,
+        },
+    },
+    name: "typescript",
+    plugins: {
+        js,
+        tseslint,
+    },
+    rules: {
+        "@typescript-eslint/no-empty-object-type": "off",
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-this-alias": "off",
+        "@typescript-eslint/no-unsafe-function-type": "off",
+        "@typescript-eslint/no-unused-vars": [
+            "error",
+            {
+                argsIgnorePattern: "^(_.*|.*Schema)$",
+                varsIgnorePattern: "^(_.*|.*Schema)$",
+            },
+        ],
+        "require-yield": "off",
+    },
+};

package/dist/config/presets/yaml.js

@@ -0,0 +1,10 @@
+import yaml from "eslint-plugin-yml";
+import * as yamlParser from "yaml-eslint-parser";
+export const yamlConfig = {
+    extends: [yaml.configs["flat/recommended"]],
+    files: ["**/*.yaml", "**/*.yml"],
+    languageOptions: { parser: yamlParser },
+    name: "yaml",
+    plugins: { yml: yaml },
+    rules: {},
+};

package/dist/config-factory.js

@@ -0,0 +1,24 @@
+import { globalIgnores } from "eslint/config";
+import baseConfig from "./eslint.config.js";
+export function createConfig(options = { version: 1 }) {
+    const configs = [];
+    if (options.ignores && options.ignores.length > 0) {
+        configs.push(globalIgnores(options.ignores));
+    }
+    for (const base of baseConfig) {
+        const clone = { ...base };
+        const override = base.name ? options.overrides?.[base.name] : undefined;
+        if (override?.rules) {
+            clone.rules = {
+                ...base.rules,
+                ...override.rules,
+            };
+        }
+        configs.push(clone);
+    }
+    if (options.configs) {
+        configs.push(...options.configs);
+    }
+    return configs;
+}
+export default createConfig;

package/dist/config-loader.js

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync, } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+export function findLinterYaml(startDir) {
+    let dir = startDir;
+    while (true) {
+        const candidate = resolve(dir, ".config", "linter.yaml");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = resolve(dir, "..");
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return undefined;
+}
+export function loadYamlOptions(startDir) {
+    const yamlPath = findLinterYaml(startDir);
+    if (!yamlPath) {
+        return { version: 1 };
+    }
+    const content = readFileSync(yamlPath, "utf-8");
+    let parsed;
+    try {
+        parsed = parse(content) || {};
+    }
+    catch (e) {
+        throw new Error(`Failed to parse ${yamlPath}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    if (!("version" in parsed)) {
+        throw new Error(`Missing required "version" key in ${yamlPath}`);
+    }
+    const knownKeys = new Set(["version", "ignores", "overrides", "configs"]);
+    for (const key of Object.keys(parsed)) {
+        if (!knownKeys.has(key)) {
+            console.warn(`[@askviraj/linter] Warning: unknown key "${key}" in .config/linter.yaml`);
+        }
+    }
+    return parsed;
+}

package/dist/eslint.config.js

@@ -0,0 +1,2 @@
+import { composeBaseConfig } from "./config/index.js";
+export default composeBaseConfig();

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./cli/runner.js";
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@askviraj/linter",
+  "version": "1.0.0",
+  "description": "A linter & formatter CLI for JavaScript, TypeScript, Astro, JSON, JSONC, CSS, HTML, Markdown, YAML, TOML, and more.",
+  "keywords": [
+    "lint",
+    "linter",
+    "eslint",
+    "cli",
+    "command-line",
+    "interface",
+    "javascript",
+    "typescript",
+    "astro",
+    "json",
+    "jsonc",
+    "css",
+    "html",
+    "markdown",
+    "yaml",
+    "toml"
+  ],
+  "homepage": "https://github.com/virajp/linter",
+  "bugs": {
+    "url": "https://github.com/virajp/linter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/virajp/linter.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Viraj Patel",
+    "email": "askviraj@gmail.com",
+    "url": "https://github.com/virajp"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./auto": "./dist/auto.js"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "linter": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test tests/unit",
+    "test:all": "bun run build && bun test",
+    "test:integration": "bun run build && bun test tests/integration"
+  },
+  "dependencies": {
+    "@eslint/css": "1.1.0",
+    "@eslint/js": "10.0.1",
+    "@eslint/json": "1.2.0",
+    "@eslint/markdown": "8.0.1",
+    "@html-eslint/eslint-plugin": "0.59.0",
+    "@poupe/eslint-plugin-tailwindcss": "0.3.1",
+    "@typescript-eslint/parser": "8.59.1",
+    "astro-eslint-parser": "1.4.0",
+    "eslint": "10.2.1",
+    "eslint-plugin-astro": "1.7.0",
+    "eslint-plugin-toml": "1.3.1",
+    "eslint-plugin-yml": "3.3.1",
+    "globals": "17.5.0",
+    "jsonc-parser": "3.3.1",
+    "typescript-eslint": "8.59.1",
+    "yaml": "2.8.3",
+    "yaml-eslint-parser": "2.0.0"
+  },
+  "devDependencies": {
+    "@bun-security-scanner/osv": "1.0.0",
+    "@types/bun": "1.3.13",
+    "@types/node": "25.6.0",
+    "sort-package-json": "3.6.1",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "eslint": "^10.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,172 @@
+# @askviraj/linter
+
+A self-contained linter CLI for JavaScript, TypeScript, Astro, JSON, JSONC, CSS,
+HTML, Markdown, YAML, TOML, and more. It bundles ESLint and all plugins so you
+don't have to install them in every project.
+
+## Features
+
+- **Zero-config** — Works out of the box with an opinionated flat config
+- **Self-contained** — Bundles ESLint and all plugins; no peer dependency
+  headaches
+- **Multi-language** — One command lints 10+ file types
+- **Fast** — Optional caching and native Bun support
+- **VS Code ready** — First-class integration with the official ESLint extension
+
+## Installation
+
+No installation required for one-off use:
+
+```bash
+# Via Bun
+bunx --bun @askviraj/linter
+
+# Via npx
+npx @askviraj/linter
+```
+
+Install locally for faster repeated runs:
+
+```bash
+# With Bun
+bun install --dev @askviraj/linter
+
+# With npm
+npm install --save-dev @askviraj/linter
+```
+
+## Quick Start
+
+```bash
+# Lint the current directory
+bunx --bun @askviraj/linter
+
+# Lint specific files or directories
+bunx --bun @askviraj/linter src/ tests/
+
+# Auto-fix issues
+bunx --bun @askviraj/linter --fix
+
+# Scaffold config files for your project
+bunx --bun @askviraj/linter --init
+```
+
+## Supported File Types
+
+| Language   | Extensions                                  |
+| ---------- | ------------------------------------------- |
+| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx`               |
+| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx`               |
+| Astro      | `.astro`                                    |
+| JSON       | `.json`                                     |
+| JSONC      | `.jsonc`, `tsconfig.json`, `.vscode/*.json` |
+| Markdown   | `.md`                                       |
+| CSS        | `.css`                                      |
+| YAML       | `.yaml`, `.yml`                             |
+| TOML       | `.toml`                                     |
+| HTML       | `.html`                                     |
+
+## CLI Reference
+
+| Flag                      | Short | Description                                                                      |
+| ------------------------- | ----- | -------------------------------------------------------------------------------- |
+| `--init`                  |       | Scaffold `eslint.config.mjs`, `.config/linter.yaml`, and `.vscode/settings.json` |
+| `--force`                 |       | Overwrite existing files when used with `--init`                                 |
+| `--fix`                   |       | Automatically fix problems                                                       |
+| `--cache`                 |       | Only check changed files                                                         |
+| `--cache-location <path>` |       | Path to the cache file or directory                                              |
+| `--no-ignore`             |       | Disable use of ignore files                                                      |
+| `--quiet`                 |       | Report errors only                                                               |
+| `--debug`                 |       | Enable ESLint debug logging                                                      |
+| `--format`, `-f <name>`   |       | Use a specific output format                                                     |
+| `--max-warnings <n>`      |       | Number of warnings to trigger nonzero exit code                                  |
+| `--version`, `-v`         |       | Show version and plugin versions                                                 |
+| `--help`, `-h`            |       | Show help                                                                        |
+
+Positional arguments are treated as file or directory targets. Defaults to `.`
+when none are provided. Use `--` to pass file names that look like flags (for
+example, `linter -- --fix.js`).
+
+## Configuration
+
+### `.config/linter.yaml`
+
+Create this file in your repo to customize the bundled config:
+
+```yaml
+version: 1
+
+ignores:
+  - "**/generated/**"
+  - "**/*.d.ts"
+
+overrides:
+  typescript:
+    rules:
+      "@typescript-eslint/no-explicit-any": "error"
+
+configs:
+  - name: "custom"
+    files: [ "**/*.test.ts" ]
+    rules:
+      "no-console": "off"
+```
+
+#### Supported keys
+
+| Key         | Type                        | Description                                               |
+| ----------- | --------------------------- | --------------------------------------------------------- |
+| `version`   | `number \| string`          | **Required.** Schema version (currently `1`).             |
+| `ignores`   | `string[]`                  | Additional global ignore patterns.                        |
+| `overrides` | `Record<string, { rules }>` | Rule overrides keyed by preset name.                      |
+| `configs`   | `unknown[]`                 | Raw ESLint config objects appended after the base config. |
+
+#### Preset names for `overrides`
+
+Use these names in the `overrides` section:
+
+- `javascript`
+- `typescript`
+- `astro`
+- `json`
+- `jsonc`
+- `markdown`
+- `markdown-typescript`
+- `yaml`
+- `toml`
+- `html`
+- `css`
+
+### Scaffolding
+
+Run `--init` to create the following files in your project:
+
+- `eslint.config.mjs` — imports `@askviraj/linter/auto`
+- `.config/linter.yaml` — your customization file
+- `.vscode/settings.json` — enables flat config mode
+
+Use `--force` to overwrite existing files.
+
+## VS Code Integration
+
+The package exports `@askviraj/linter/auto` for use with the
+`dbaeumer.vscode-eslint` extension.
+
+After running `--init`, VS Code discovers `eslint.config.mjs` and loads the
+bundled config automatically. Edit `.config/linter.yaml` to customize rules; the
+extension picks up changes without restarting.
+
+## How It Works
+
+1. `npx` or `bunx` installs `@askviraj/linter` and its dependencies in a
+   temporary or local `node_modules`.
+2. The bundled CLI reads `.config/linter.yaml` from the target repo (if present)
+   to load user customizations.
+3. It builds the ESLint config by merging YAML overrides with the bundled base
+   config.
+4. ESLint's programmatic API lints the current working directory. Plugins are
+   resolved from the package's own `node_modules`, not the target repo's.
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.