@storm-software/eslint-plugin-bun 0.0.2

package/dist/helpers/bun-workspace.d.ts

@@ -0,0 +1,48 @@
+interface BunWorkspacePackageJson {
+    catalog?: Record<string, string>;
+    catalogs?: Record<string, Record<string, string>>;
+    workspaces?: string[] | {
+        packages?: string[];
+        catalog?: Record<string, string>;
+        catalogs?: Record<string, Record<string, string>>;
+    };
+    [key: string]: unknown;
+}
+type CatalogName = "default" | (string & {});
+interface SpecifierConflicts {
+    conflicts: boolean;
+    newCatalogName: string;
+    existingSpecifier?: string;
+}
+interface BunWorkspace {
+    filepath: string;
+    setContent: (content: string) => void;
+    hasChanged: () => boolean;
+    hasQueue: () => boolean;
+    clearQueue: () => void;
+    queueChange: (fn: (workspace: BunWorkspace) => void, order?: "pre" | "post") => void;
+    toJSON: () => BunWorkspacePackageJson;
+    toString: () => string;
+    setPackage: (catalog: CatalogName, packageName: string, specifier: string) => void;
+    setPackageNoConflicts: (catalog: CatalogName, packageName: string, specifier: string) => void;
+    getPackageCatalogs: (packageName: string) => string[];
+    hasSpecifierConflicts: (catalog: CatalogName, packageName: string, specifier: string) => SpecifierConflicts;
+    getCatalogData: () => {
+        catalog?: Record<string, string>;
+        catalogs?: Record<string, Record<string, string>>;
+    };
+    getWorkspacePackagePatterns: () => string[];
+}
+/**
+ * Find and parse the Bun workspace root `package.json` that holds catalogs.
+ *
+ * Catalogs live in root `package.json` (top-level or under `workspaces`), not
+ * `pnpm-workspace.yaml`. See https://bun.com/docs/pm/catalogs
+ */
+declare function readBunWorkspace(cwd?: string): BunWorkspace;
+declare function getBunWorkspace(cwd?: string): BunWorkspace;
+declare function resetBunWorkspaceCache(): void;
+declare function isRootWorkspacePackageJson(filename: string, cwd?: string): boolean;
+declare function collectWorkspacePackageJsonPaths(workspaceRoot: BunWorkspace): string[];
+
+export { type BunWorkspace, type BunWorkspacePackageJson, type CatalogName, type SpecifierConflicts, collectWorkspacePackageJsonPaths, getBunWorkspace, isRootWorkspacePackageJson, readBunWorkspace, resetBunWorkspaceCache };

package/dist/helpers/bun-workspace.mjs

@@ -0,0 +1,265 @@
+import fs from 'node:fs';
+import process from 'node:process';
+import { findUpSync } from 'find-up-simple';
+import { dirname, normalize, resolve } from 'pathe';
+import { globSync } from 'tinyglobby';
+
+// src/helpers/bun-workspace.ts
+function isWorkspaceObject(workspaces) {
+  return Boolean(workspaces) && typeof workspaces === "object" && !Array.isArray(workspaces);
+}
+function detectCatalogRoot(data) {
+  if (data.catalog || data.catalogs) {
+    return "top";
+  }
+  if (isWorkspaceObject(data.workspaces) && (data.workspaces.catalog || data.workspaces.catalogs)) {
+    return "workspaces";
+  }
+  return isWorkspaceObject(data.workspaces) ? "workspaces" : "top";
+}
+function normalizeCatalogName(name) {
+  return name.replace(/\^/g, "h").replace(/~/g, "t").replace(/\./g, "_").replace(/</g, "l").replace(/>/g, "g").replace(/=/g, "e").replace(/\*/g, "s").replace(/@/g, "a").replace(/\|/g, "p").replace(/&/g, "n").replace(/-/g, "m").replace(/\+/g, "u").replace(/\s/g, "_");
+}
+function sortObjectKeys(input) {
+  return Object.fromEntries(
+    Object.entries(input).sort(([left], [right]) => left.localeCompare(right))
+  );
+}
+function isWorkspaceRootPackageJson(data) {
+  return Boolean(
+    data.workspaces || data.catalog || data.catalogs
+  );
+}
+function readBunWorkspace(cwd = process.cwd()) {
+  const filepath = findUpSync("package.json", {
+    cwd,
+    type: "file"
+  });
+  if (!filepath) {
+    throw new Error("package.json not found");
+  }
+  let current = filepath;
+  let content = fs.readFileSync(current, "utf8");
+  let data = JSON.parse(content);
+  while (!isWorkspaceRootPackageJson(data)) {
+    const searchFrom = dirname(dirname(current));
+    const next = findUpSync("package.json", {
+      cwd: searchFrom,
+      type: "file"
+    });
+    if (!next || normalize(next) === normalize(current)) {
+      break;
+    }
+    current = next;
+    content = fs.readFileSync(current, "utf8");
+    data = JSON.parse(content);
+  }
+  if (!isWorkspaceRootPackageJson(data)) {
+    throw new Error(
+      "Bun workspace root package.json with workspaces/catalog not found"
+    );
+  }
+  let hasChanged = false;
+  let queueTimer;
+  const queue = [];
+  let catalogRoot = detectCatalogRoot(data);
+  const write = () => {
+    if (!fs.existsSync(current)) {
+      return;
+    }
+    fs.writeFileSync(current, `${JSON.stringify(data, null, 2)}
+`);
+  };
+  const clearQueue = () => {
+    if (queueTimer != null) {
+      clearTimeout(queueTimer);
+      queueTimer = void 0;
+    }
+    queue.length = 0;
+  };
+  const getCatalogContainer = () => {
+    if (catalogRoot === "workspaces") {
+      if (!isWorkspaceObject(data.workspaces)) {
+        data.workspaces = {
+          packages: Array.isArray(data.workspaces) ? data.workspaces : [],
+          catalog: {},
+          catalogs: {}
+        };
+      }
+      return data.workspaces;
+    }
+    return data;
+  };
+  const getCatalogData = () => {
+    const container = getCatalogContainer();
+    return {
+      catalog: container.catalog,
+      catalogs: container.catalogs
+    };
+  };
+  const setPackage = (catalogName, packageName, specifier) => {
+    const container = getCatalogContainer();
+    if (catalogName === "default") {
+      container.catalog ??= {};
+      if (container.catalog[packageName] !== specifier) {
+        container.catalog[packageName] = specifier;
+        container.catalog = sortObjectKeys(container.catalog);
+        hasChanged = true;
+      }
+      return;
+    }
+    container.catalogs ??= {};
+    container.catalogs[catalogName] ??= {};
+    if (container.catalogs[catalogName][packageName] !== specifier) {
+      container.catalogs[catalogName][packageName] = specifier;
+      container.catalogs[catalogName] = sortObjectKeys(
+        container.catalogs[catalogName]
+      );
+      container.catalogs = sortObjectKeys(container.catalogs);
+      hasChanged = true;
+    }
+  };
+  const hasSpecifierConflicts = (catalogName, packageName, specifier) => {
+    const { catalog, catalogs } = getCatalogData();
+    const existingSpecifier = catalogName === "default" ? catalog?.[packageName] : catalogs?.[catalogName]?.[packageName];
+    if (existingSpecifier === specifier) {
+      return {
+        conflicts: false,
+        newCatalogName: catalogName,
+        existingSpecifier
+      };
+    }
+    if (existingSpecifier) {
+      const versionSuffix = normalizeCatalogName(specifier);
+      const newCatalogName = catalogName === "default" ? `conflicts_${packageName}_${versionSuffix}` : `conflicts_${catalogName}_${versionSuffix}`;
+      return {
+        conflicts: true,
+        existingSpecifier,
+        newCatalogName
+      };
+    }
+    return {
+      conflicts: false,
+      newCatalogName: catalogName
+    };
+  };
+  const getPackageCatalogs = (packageName) => {
+    const found = [];
+    const { catalog, catalogs } = getCatalogData();
+    if (catalogs) {
+      for (const name of Object.keys(catalogs)) {
+        if (catalogs[name]?.[packageName]) {
+          found.push(name);
+        }
+      }
+    }
+    if (catalog?.[packageName]) {
+      found.push("default");
+    }
+    return found;
+  };
+  const workspace2 = {
+    filepath: current,
+    setContent(newContent) {
+      content = newContent;
+      data = JSON.parse(newContent);
+      catalogRoot = detectCatalogRoot(data);
+      hasChanged = false;
+    },
+    hasChanged: () => hasChanged,
+    hasQueue: () => queueTimer != null,
+    clearQueue,
+    queueChange(fn, order) {
+      if (order === "pre") {
+        queue.unshift(fn);
+      } else {
+        queue.push(fn);
+      }
+      if (queueTimer != null) {
+        clearTimeout(queueTimer);
+      }
+      queueTimer = setTimeout(() => {
+        queueTimer = void 0;
+        const clone = [...queue];
+        queue.length = 0;
+        for (const queued of clone) {
+          queued(workspace2);
+        }
+        if (hasChanged) {
+          write();
+        }
+      }, 1e3);
+    },
+    toJSON: () => data,
+    toString: () => `${JSON.stringify(data, null, 2)}
+`,
+    setPackage,
+    setPackageNoConflicts(catalogName, packageName, specifier) {
+      const { newCatalogName } = hasSpecifierConflicts(
+        catalogName,
+        packageName,
+        specifier
+      );
+      setPackage(newCatalogName, packageName, specifier);
+    },
+    getPackageCatalogs,
+    hasSpecifierConflicts,
+    getCatalogData,
+    getWorkspacePackagePatterns() {
+      if (Array.isArray(data.workspaces)) {
+        return data.workspaces;
+      }
+      if (isWorkspaceObject(data.workspaces) && data.workspaces.packages) {
+        return data.workspaces.packages;
+      }
+      return [];
+    }
+  };
+  return workspace2;
+}
+var WORKSPACE_CACHE_TIME = 1e4;
+var workspaceLastRead;
+var workspace;
+function getBunWorkspace(cwd = process.cwd()) {
+  if (workspaceLastRead && workspace && !workspace.hasQueue() && Date.now() - workspaceLastRead > WORKSPACE_CACHE_TIME) {
+    workspace = void 0;
+  }
+  if (!workspace) {
+    workspace = readBunWorkspace(cwd);
+    workspaceLastRead = Date.now();
+  }
+  return workspace;
+}
+function resetBunWorkspaceCache() {
+  workspace?.clearQueue();
+  workspace = void 0;
+  workspaceLastRead = void 0;
+}
+function isRootWorkspacePackageJson(filename, cwd = process.cwd()) {
+  try {
+    const root = getBunWorkspace(cwd);
+    return normalize(root.filepath) === normalize(filename);
+  } catch {
+    return false;
+  }
+}
+function collectWorkspacePackageJsonPaths(workspaceRoot) {
+  const root = resolve(dirname(workspaceRoot.filepath));
+  const patterns = workspaceRoot.getWorkspacePackagePatterns();
+  const dirs = patterns.length ? globSync(patterns, {
+    cwd: root,
+    dot: false,
+    ignore: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/build/**"
+    ],
+    absolute: true,
+    expandDirectories: false,
+    onlyDirectories: true
+  }) : [];
+  dirs.push(root);
+  return dirs.map((dir) => resolve(dir, "package.json")).filter((path) => fs.existsSync(path)).sort();
+}
+
+export { collectWorkspacePackageJsonPaths, getBunWorkspace, isRootWorkspacePackageJson, readBunWorkspace, resetBunWorkspaceCache };

package/dist/helpers/create-rule.d.ts

@@ -0,0 +1,9 @@
+import { RuleWithMetaAndName } from '@typescript-eslint/utils/eslint-utils';
+import { Rule } from 'eslint';
+
+type RuleModule<T extends readonly unknown[]> = Rule.RuleModule & {
+    defaultOptions: T;
+};
+declare const createRule: <TOptions extends readonly unknown[], TMessageIds extends string>({ name, meta, ...rule }: Readonly<RuleWithMetaAndName<TOptions, TMessageIds>>) => RuleModule<TOptions>;
+
+export { type RuleModule, createRule };

package/dist/helpers/create-rule.mjs

@@ -0,0 +1,42 @@
+import defu from 'defu';
+
+// src/helpers/create-rule.ts
+function RuleCreator(urlCreator) {
+  return function createNamedRule({
+    name,
+    meta,
+    ...rule
+  }) {
+    return createRuleInfo({
+      meta: {
+        ...meta,
+        docs: {
+          ...meta.docs,
+          url: urlCreator(name)
+        }
+      },
+      ...rule
+    });
+  };
+}
+function createRuleInfo({
+  create,
+  defaultOptions,
+  meta
+}) {
+  return {
+    create: ((context) => {
+      const optionsWithDefault = context.options.map((options, index) => {
+        return defu(defaultOptions?.[index] ?? {}, options);
+      });
+      return create(context, optionsWithDefault);
+    }),
+    defaultOptions: defaultOptions ?? {},
+    meta
+  };
+}
+var createRule = RuleCreator(
+  (ruleName) => `https://docs.stormsoftware.com/projects/storm-ops/eslint-plugin-bun/rules/${ruleName}.md`
+);
+
+export { createRule };

package/dist/helpers/iterate-dependencies.d.ts

@@ -0,0 +1,11 @@
+import { RuleContext } from '@typescript-eslint/utils/ts-eslint';
+
+declare function getPackageJsonRootNode(context: RuleContext<string, unknown[]>): any | undefined;
+declare function iterateDependencies(context: RuleContext<string, unknown[]>, fields: string[]): Generator<{
+    packageName: string;
+    specifier: string;
+    property: any;
+}, void, unknown>;
+declare function getObjectPath(obj: Record<string, unknown>, path: string[]): Record<string, string> | undefined;
+
+export { getObjectPath, getPackageJsonRootNode, iterateDependencies };

package/dist/helpers/iterate-dependencies.mjs

@@ -0,0 +1,63 @@
+// src/helpers/iterate-dependencies.ts
+function getPackageJsonRootNode(context) {
+  if (!context.filename.endsWith("package.json")) {
+    return void 0;
+  }
+  const ast = context.sourceCode.ast;
+  const root = ast.body[0];
+  if (root?.expression?.type === "JSONObjectExpression") {
+    return root.expression;
+  }
+  return void 0;
+}
+function* iterateDependencies(context, fields) {
+  const root = getPackageJsonRootNode(context);
+  if (!root) {
+    return;
+  }
+  for (const fieldName of fields) {
+    const path = fieldName.split(".");
+    let node = root;
+    for (const segment of path) {
+      const item = node.properties?.find(
+        (property) => property.key.type === "JSONLiteral" && property.key.value === segment
+      );
+      if (!item?.value || item.value.type !== "JSONObjectExpression") {
+        node = void 0;
+        break;
+      }
+      node = item.value;
+    }
+    if (!node || node === root || !node.properties) {
+      continue;
+    }
+    for (const property of node.properties) {
+      if (property.value.type !== "JSONLiteral" || property.key.type !== "JSONLiteral") {
+        continue;
+      }
+      if (typeof property.value.value !== "string") {
+        continue;
+      }
+      yield {
+        packageName: String(property.key.value),
+        specifier: String(property.value.value),
+        property
+      };
+    }
+  }
+}
+function getObjectPath(obj, path) {
+  let current = obj;
+  for (const key of path) {
+    if (!current || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[key];
+    if (!current) {
+      return void 0;
+    }
+  }
+  return current;
+}
+
+export { getObjectPath, getPackageJsonRootNode, iterateDependencies };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { RuleModule } from './helpers/create-rule.js';
+import { Linter, ESLint } from 'eslint';
+export { configs } from './configs/index.js';
+import { plugin } from './plugin.js';
+import '@typescript-eslint/utils/eslint-utils';
+
+/**
+ * ESLint plugin for Storm Software to enforce Bun catalog usage across monorepo packages.
+ *
+ * Catalog versions are stored in the workspace root `package.json` (`catalog` /
+ * `catalogs`, top-level or under `workspaces`), matching Bun's catalog protocol:
+ * https://bun.com/docs/pm/catalogs
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```js
+ * import bun from "@storm-software/eslint-plugin-bun";
+ *
+ * export default [
+ *   ...bun.configs.recommended,
+ * ];
+ * ```
+ *
+ * @see [Storm Software](https://stormsoftware.com) for more information about our projects and licensing.
+ */
+declare const eslintPlugin: ESLint.Plugin;
+
+declare const rules: {
+    "json-enforce-catalog": RuleModule<[{
+        allowedProtocols?: string[];
+        autofix?: boolean;
+        defaultCatalog?: string;
+        reuseExistingCatalog?: boolean;
+        conflicts?: "new-catalog" | "overrides" | "error";
+        fields?: string[];
+        ignore?: string[];
+    }]>;
+    "json-valid-catalog": RuleModule<[{
+        autoInsert?: boolean;
+        autoInsertDefaultSpecifier?: string;
+        autofix?: boolean;
+        fields?: string[];
+    }]>;
+    "json-no-unused-catalog-item": RuleModule<[]>;
+    "json-no-duplicate-catalog-item": RuleModule<[{
+        allow?: string[];
+    }]>;
+};
+type RuleDefinitions = (typeof plugin)["rules"];
+type RuleOptions = {
+    [K in keyof RuleDefinitions]: RuleDefinitions[K]["defaultOptions"];
+};
+type Rules = {
+    [K in keyof RuleOptions]: Linter.RuleEntry<RuleOptions[K]>;
+};
+
+export { type RuleOptions, type Rules, eslintPlugin as default, rules };