@vibe-agent-toolkit/utils 0.1.41 → 0.1.42-rc.1

package/eslint/rules/exempt-path-matcher.cjs

@@ -0,0 +1,265 @@
+/**
+ * Shared exemption matcher for local ESLint rule factories.
+ *
+ * Rules that ban an unsafe primitive have to exempt the ONE file that implements
+ * the safe replacement. Doing that with `filename.includes('path-utils.ts')` is a
+ * silent hole: any file anywhere — in this repo or in a consumer repo running
+ * these rules — whose path merely CONTAINS that string opts itself out. A private
+ * `tools/hooks/path-utils.ts` full of raw `tmpdir()` / `realpathSync()` calls
+ * linted clean for exactly this reason.
+ *
+ * Exemptions are therefore repo-relative paths matched at a path-segment
+ * boundary: the linted filename must either BE the exempt path, or END WITH
+ * `/` + the exempt path. Matching happens on forward slashes — a rule pack whose
+ * whole purpose is enforcing cross-platform path handling must not itself be
+ * `\` vs `/` dependent.
+ *
+ * Three shapes of exemption live here, and every local rule must take one of
+ * them rather than reaching for `includes()` again:
+ *
+ * - `createExemptPathMatcher` — "is this THAT file?" (a named implementation file)
+ * - `createExemptDirectoryMatcher` — "is this file INSIDE that directory?" (a package
+ *   that owns a centralized wrapper)
+ * - `isTestFile` — "is this a test file?" (a category, anchored on the basename's
+ *   extension rather than on a path segment)
+ *
+ * `eslint-rule-factory.cjs`, `path-function-rule-factory.cjs`,
+ * `no-command-direct-factory.cjs` and `no-unix-shell-commands.cjs` all use these.
+ * Do not re-implement any of them: the sibling-factory copy is how the bug
+ * shipped four times in the first place.
+ *
+ * A fourth export, `createConfigurableExemptPathMatcher`, wires the file-shaped
+ * exemption to the rule's own ESLint option so each CONSUMER declares the paths
+ * for its own repo. It also lives here (rather than in each factory) for the same
+ * reason: two copies is how the bug spread last time.
+ */
+
+/** Forward-slash a path and drop any leading `./` or `/` noise used for anchoring. */
+function normalizeForMatch(value) {
+  return String(value).replaceAll('\\', '/').replace(/^(?:\.\/)+/, '');
+}
+
+/**
+ * Build a predicate that reports whether a linted filename is one of `exemptPaths`.
+ *
+ * @param {readonly string[]} exemptPaths - Repo-relative paths, e.g.
+ *   `['packages/utils/src/path-utils.ts']`. A bare basename is accepted by the
+ *   matcher but matches that filename ANYWHERE in the tree (ESLint filenames are
+ *   absolute, so the `endsWith('/' + target)` leg is what fires) — pass the full
+ *   repo-relative path. Rules surface that mistake via
+ *   {@link reportUnanchoredExemptEntries}.
+ * @returns {(filename: string) => boolean} Anchored, separator-agnostic predicate.
+ */
+function createExemptPathMatcher(exemptPaths) {
+  const targets = [...exemptPaths]
+    .map((exemptPath) => normalizeForMatch(exemptPath).replace(/^\/+/, ''))
+    .filter((exemptPath) => exemptPath.length > 0);
+
+  return function isExemptPath(filename) {
+    if (!filename) {
+      return false;
+    }
+    const normalized = normalizeForMatch(filename);
+    return targets.some(
+      (target) => normalized === target || normalized.endsWith(`/${target}`),
+    );
+  };
+}
+
+/**
+ * JSON Schema for the `exemptFiles` rule option, for a rule's `meta.schema`.
+ *
+ * `additionalProperties: false` on purpose: a typo'd option key must be an ESLint
+ * config error, not a silently ignored exemption list (which would read as "the
+ * rule stopped firing for no reason").
+ */
+const EXEMPT_FILES_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    exemptFiles: {
+      type: 'array',
+      items: { type: 'string' },
+      uniqueItems: true,
+    },
+  },
+  additionalProperties: false,
+});
+
+/**
+ * Wire a file-shaped exemption to the rule's `exemptFiles` option.
+ *
+ * An exemption names the ONE file in a SPECIFIC repo that implements the safe
+ * replacement, so it cannot be shipped as a useful default: a package publishing
+ * `packages/utils/src/path-utils.ts` as a built-in exemption hands every consumer
+ * a hole at that path. Hence the empty default here, and hence REPLACE rather
+ * than merge semantics — a consumer's list is the whole list.
+ *
+ * @param {readonly string[]} [defaultPaths] - Fallback used only when the rule is
+ *   configured with no `exemptFiles` option. Ship this empty unless the rule
+ *   itself owns the file (no shipped rule in this package does).
+ * @returns {(context: object) => (filename: string) => boolean} Resolver taking an
+ *   ESLint rule context and returning the anchored predicate for that invocation.
+ */
+function createConfigurableExemptPathMatcher(defaultPaths = []) {
+  const defaultMatcher = createExemptPathMatcher(defaultPaths);
+  const cache = new Map();
+
+  return function exemptMatcherFor(context) {
+    const configured = context.options?.[0]?.exemptFiles;
+    if (!Array.isArray(configured)) {
+      return defaultMatcher;
+    }
+    // JSON, not join(): a delimiter cheap enough to be collision-free is a raw
+    // NUL, which this repo bans in source (git and ripgrep treat the file as
+    // binary and skip its contents), and any printable delimiter can legally
+    // appear in a path.
+    const key = JSON.stringify(configured);
+    let matcher = cache.get(key);
+    if (!matcher) {
+      matcher = createExemptPathMatcher(configured);
+      cache.set(key, matcher);
+    }
+    return matcher;
+  };
+}
+
+/**
+ * `messageId` every rule that accepts `exemptFiles` must declare, so an
+ * unanchored entry is reported through the normal lint channel.
+ *
+ * Not a JSON Schema `pattern` on the option, which would be the obvious place:
+ * the schema sees the RAW string, and `./path-utils.ts` contains a `/` while
+ * normalizing to exactly the same repo-wide exemption as `path-utils.ts`. A
+ * check that the wrong spelling slips past is worse than none. Not a
+ * `process.emitWarning` either — a notice on stderr is not a reported finding
+ * and gets scrolled past.
+ */
+const UNANCHORED_EXEMPT_FILE = 'unanchoredExemptFile';
+
+/**
+ * The `meta.messages` entry for {@link UNANCHORED_EXEMPT_FILE}.
+ *
+ * ESLint filenames are ABSOLUTE, and an exemption matches when the filename ends
+ * with `/` + the entry. So a bare basename does not mean "the file at the repo
+ * root" (as this module's JSDoc used to claim) — it means EVERY file with that
+ * name, anywhere in the tree, including ones added later by someone who never
+ * saw the config. That is the same repo-wide hole the anchoring rewrite closed,
+ * reopened one config entry at a time.
+ */
+const UNANCHORED_EXEMPT_MESSAGE =
+  'exemptFiles entry "{{entry}}" is a bare filename, so it exempts EVERY file named ' +
+  '"{{entry}}" anywhere in the repo — including files added later. Give the ' +
+  'repo-relative path instead (e.g. "packages/utils/src/{{entry}}").';
+
+/**
+ * The configured `exemptFiles` entries that are not anchored to a directory.
+ *
+ * Runs on the NORMALIZED entry, so `./x.ts` and `x.ts` are both caught.
+ *
+ * @param {object} context - ESLint rule context.
+ * @returns {string[]} Offending entries, as the consumer spelled them.
+ */
+function findUnanchoredExemptEntries(context) {
+  const configured = context.options?.[0]?.exemptFiles;
+  if (!Array.isArray(configured)) {
+    return [];
+  }
+  return configured.filter((entry) => {
+    const normalized = normalizeForMatch(entry).replace(/^\/+/, '');
+    return normalized.length > 0 && !normalized.includes('/');
+  });
+}
+
+/**
+ * Report every unanchored `exemptFiles` entry against the `Program` node.
+ *
+ * Deliberately stateless — no "warn once per process" dedupe. ESLint caches
+ * results per file, so a rule that remembers having warned goes SILENT on the
+ * second run against a warm cache, which is precisely when a stale config is
+ * least likely to be noticed.
+ *
+ * @param {object} context - ESLint rule context.
+ * @param {object} node - The `Program` node to anchor the report on.
+ */
+function reportUnanchoredExemptEntries(context, node) {
+  for (const entry of findUnanchoredExemptEntries(context)) {
+    context.report({ node, messageId: UNANCHORED_EXEMPT_FILE, data: { entry } });
+  }
+}
+
+/**
+ * Build a predicate that reports whether a linted filename lives UNDER one of
+ * `exemptDirs`.
+ *
+ * The directory flavor of the same bug: `filename.includes('packages/git/')`
+ * also exempted `vendor/copy-packages/git/` and `tools/my-packages/git/` — any
+ * directory whose name merely ENDS WITH the exempt one. Anchoring means the
+ * directory must start the repo-relative path or be preceded by a `/`.
+ *
+ * @param {readonly string[]} exemptDirs - Repo-relative directories, with or
+ *   without a trailing slash, e.g. `['packages/git/']`.
+ * @returns {(filename: string) => boolean} Anchored, separator-agnostic predicate.
+ */
+function createExemptDirectoryMatcher(exemptDirs) {
+  // Normalize each directory to a `<dir>/` PREFIX rather than stripping trailing
+  // slashes: a trailing-slash strip needs either `/\/+$/` (flagged by
+  // sonarjs/slow-regex) or `.split('/')` (banned repo-wide by this very rule pack).
+  const prefixes = [...exemptDirs]
+    .map((dir) => normalizeForMatch(dir).replace(/^\/+/, ''))
+    .filter((dir) => dir.length > 0)
+    .map((dir) => (dir.endsWith('/') ? dir : `${dir}/`));
+
+  return function isUnderExemptDirectory(filename) {
+    if (!filename) {
+      return false;
+    }
+    const normalized = normalizeForMatch(filename);
+    return prefixes.some(
+      (prefix) => normalized.startsWith(prefix) || normalized.includes(`/${prefix}`),
+    );
+  };
+}
+
+/**
+ * Test-file naming convention, anchored to the END of the BASENAME.
+ *
+ * This is a CATEGORY check, not a path exemption, so `createExemptPathMatcher`
+ * is the wrong tool: there is no repo-relative path to compare against. What
+ * "anchored" means here is that the extension must terminate the last path
+ * segment. `filename.includes('.test.ts')` satisfied neither end — it exempted
+ * `example.test.ts.bak`, a directory named `.test.ts-helpers/`, and (a real
+ * tracked file in this repo) `tsconfig.test.json` via the `.test.js` spelling.
+ *
+ * The repo convention is `*.test.ts` (unit, `*.integration.test.ts`, and
+ * `*.system.test.ts` all land on it); the js/mjs/cjs/mts/tsx variants are
+ * covered because a category predicate that only knew one extension would be
+ * the next silent hole. `.spec.` is deliberately absent — this repo has zero
+ * such files and vitest's `include` globs would not run them.
+ */
+const TEST_FILE_EXTENSION = /\.test\.[cm]?[jt]sx?$/;
+
+/**
+ * @param {string} filename - Path as ESLint reports it (absolute, any separator).
+ * @returns {boolean} True when the file itself is a test file.
+ */
+function isTestFile(filename) {
+  if (!filename) {
+    return false;
+  }
+  const normalized = normalizeForMatch(filename);
+  const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
+  return TEST_FILE_EXTENSION.test(basename);
+}
+
+module.exports = {
+  EXEMPT_FILES_SCHEMA,
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createConfigurableExemptPathMatcher,
+  createExemptDirectoryMatcher,
+  createExemptPathMatcher,
+  findUnanchoredExemptEntries,
+  isTestFile,
+  normalizeForMatch,
+  reportUnanchoredExemptEntries,
+};

package/eslint/rules/no-bare-dynamic-import-path.cjs

@@ -0,0 +1,142 @@
+/**
+ * ESLint rule: no-bare-dynamic-import-path
+ *
+ * Prevents `await import(p)` where `p` is a raw filesystem path.
+ * On Windows, ESM dynamic import of a bare path fails — it requires a `file://`
+ * URL. Observed bug: `await import('D:\\a\\repo\\config.js')` throws.
+ *
+ * Fix: `await import(pathToFileURL(p).href)` from `node:url`, or
+ * `await dynamicImportPath(p)` from `@vibe-agent-toolkit/utils/fs`.
+ *
+ * Heuristic (intentionally narrow — some false positives are preferable to
+ * false negatives for a shift-left lint rule, but the user can suppress per line):
+ *   - String literal starting with `/` or `C:\` style absolute path → flag
+ *   - Call to `path.join`, `path.resolve`, `join`, `resolve`, `safePath.*` → flag
+ *   - Identifier whose name matches /path|file|config|module|dir/i → flag
+ *     (will have false positives on well-named variables that already hold
+ *     file:// URLs; suppress those call-sites with eslint-disable-next-line.)
+ *   - Template literal that embeds a path-shaped call → flag
+ *
+ * Does NOT flag:
+ *   - Relative module specifiers (`./foo.js`, `../bar.js`)
+ *   - Bare package names (`some-pkg`)
+ *   - Expressions ending in `.href` (assume correct `pathToFileURL(x).href`)
+ */
+
+'use strict';
+
+const {
+  SAFE_FS_MODULE,
+  SAFE_MODULE_ONLY_SCHEMA,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+const PATH_CALL_NAMES = new Set(['join', 'resolve']);
+const PATH_OBJECT_NAMES = new Set(['path', 'safePath']);
+const PATH_SHAPED_IDENTIFIER = /path|file|config|module|dir/i;
+const ABSOLUTE_PATH_LITERAL = /^(\/|[A-Za-z]:[\\/])/;
+
+function isPathCallExpression(node) {
+  if (node?.type !== 'CallExpression') return false;
+  const callee = node.callee;
+  // bare call: join(...), resolve(...)
+  if (callee.type === 'Identifier' && PATH_CALL_NAMES.has(callee.name)) {
+    return true;
+  }
+  // member call: path.join, path.resolve, safePath.join, safePath.resolve
+  if (
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    PATH_OBJECT_NAMES.has(callee.object.name) &&
+    callee.property.type === 'Identifier'
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function isHrefAccess(node) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.property.type === 'Identifier' &&
+    node.property.name === 'href'
+  );
+}
+
+function isRelativeOrBareSpecifier(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  if (value.startsWith('./') || value.startsWith('../') || value === '.' || value === '..') {
+    return true;
+  }
+  // Bare package name — no leading slash, no drive letter.
+  if (ABSOLUTE_PATH_LITERAL.test(value)) return false;
+  return !value.includes('\\');
+}
+
+function templateHasPathCall(node) {
+  if (node?.type !== 'TemplateLiteral') return false;
+  return node.expressions.some((expr) => isPathCallExpression(expr));
+}
+
+function classifyImportArgument(arg) {
+  if (!arg) return null;
+
+  // Literal string specifier — flag only if absolute path-shaped.
+  if (arg.type === 'Literal' && typeof arg.value === 'string') {
+    if (isRelativeOrBareSpecifier(arg.value)) return null;
+    if (ABSOLUTE_PATH_LITERAL.test(arg.value)) return 'absolute-literal';
+    return null;
+  }
+
+  // Template literal with a path call embedded.
+  if (arg.type === 'TemplateLiteral') {
+    if (templateHasPathCall(arg)) return 'template-with-path-call';
+    return null;
+  }
+
+  // `pathToFileURL(x).href` or similar — correct form, do not flag.
+  if (isHrefAccess(arg)) return null;
+
+  // path.join(...) / path.resolve(...) / join(...) / resolve(...)
+  if (isPathCallExpression(arg)) return 'path-call';
+
+  // Bare identifier whose name hints at a filesystem path.
+  if (arg.type === 'Identifier' && PATH_SHAPED_IDENTIFIER.test(arg.name)) {
+    return 'path-shaped-identifier';
+  }
+
+  return null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow dynamic `import()` of a filesystem path; wrap with `pathToFileURL(p).href`.',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      useFileUrl:
+        'Dynamic `import()` of a filesystem path fails on Windows. ' +
+        'Wrap with `pathToFileURL(p).href` from `node:url`, or use `dynamicImportPath(p)` from `{{safeModule}}`.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    return {
+      ImportExpression(node) {
+        const kind = classifyImportArgument(node.source);
+        if (kind) {
+          context.report({
+            node,
+            messageId: 'useFileUrl',
+            data: { safeModule: resolveSafeModule(context, SAFE_FS_MODULE) },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-child-process-execSync.cjs

@@ -0,0 +1,23 @@
+/**
+ * ESLint rule: no-child-process-execSync
+ *
+ * Prevents usage of child_process.execSync() in favor of safeExecSync() from `@vibe-agent-toolkit/utils/process`
+ *
+ * Why: execSync() uses shell interpreter which enables command injection attacks.
+ * safeExecSync() uses direct spawn (no shell) with 'which' pattern for security.
+ *
+ * Auto-fix: Replaces execSync() with safeExecSync() and adds required import.
+ */
+
+const factory = require('./eslint-rule-factory.cjs');
+const { SAFE_PROCESS_MODULE } = require('./safe-import.cjs');
+
+module.exports = factory({
+  unsafeFn: 'execSync',
+  unsafeModule: 'node:child_process',
+  safeFn: 'safeExecSync',
+  safeModule: SAFE_PROCESS_MODULE,
+  message: 'Use safeExecSync() from {{safeModule}} instead of child_process.execSync() to prevent command injection (security + cross-platform)',
+  // No baked-in exemption: the file that implements safeExecSync() is
+  // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+});

package/eslint/rules/no-command-direct-factory.cjs

@@ -0,0 +1,246 @@
+/**
+ * ESLint Rule Factory - Command Execution Checking
+ *
+ * Single source of truth for:
+ * 1. How commands can be executed (safeExecSync, spawn, execSync, etc.)
+ * 2. How to check those execution patterns
+ * 3. Creating rules that enforce command restrictions
+ *
+ * This module exports both the factory function and helper utilities
+ * so all command-checking rules reference the same execution patterns.
+ */
+
+const { createExemptDirectoryMatcher } = require('./exempt-path-matcher.cjs');
+
+// ============================================================================
+// COMMAND EXECUTION PATTERNS - Single Source of Truth
+// ============================================================================
+// If we add new execution methods (e.g., safeExecAsync), update this list
+// and all dependent rules automatically benefit.
+
+/**
+ * Check if execSync command string starts with the target command
+ *
+ * @param {Object} firstArg - AST node for first argument
+ * @param {string} command - Command to check for (e.g., 'git')
+ * @returns {boolean} True if command matches
+ */
+function commandMatchesExecSync(firstArg, command) {
+  // Check string literals: execSync('git status')
+  if (firstArg.type === 'Literal' && typeof firstArg.value === 'string') {
+    return firstArg.value.startsWith(`${command} `) || firstArg.value === command;
+  }
+
+  // Check template literals: execSync(`git ${args}`)
+  if (firstArg.type === 'TemplateLiteral' && firstArg.quasis.length > 0) {
+    const firstQuasi = firstArg.quasis[0].value.cooked || firstArg.quasis[0].value.raw;
+    return firstQuasi.startsWith(`${command} `) || firstQuasi === command;
+  }
+
+  return false;
+}
+
+/**
+ * Check shell-free command execution (safeExecSync, spawn, etc.)
+ * @private
+ */
+function checkShellFreeExecution(node, context, shouldReport, messageId) {
+  const firstArg = node.arguments[0];
+
+  if (firstArg.type !== 'Literal') {
+    return;
+  }
+
+  const result = shouldReport(node, firstArg);
+  if (result) {
+    context.report({
+      node,
+      messageId,
+      data: typeof result === 'object' ? result : undefined,
+    });
+  }
+}
+
+/**
+ * Check execSync command execution (shell-based)
+ * @private
+ */
+function checkExecSyncExecution(node, context, shouldReport, messageId) {
+  const firstArg = node.arguments[0];
+  const result = shouldReport(node, firstArg, commandMatchesExecSync);
+
+  if (result) {
+    context.report({
+      node,
+      messageId,
+      data: typeof result === 'object' ? result : undefined,
+    });
+  }
+}
+
+/**
+ * Check if function is a shell-free execution method
+ * @private
+ */
+function isShellFreeExecution(functionName) {
+  return (
+    functionName === 'safeExecSync' ||
+    functionName === 'safeExecResult' ||
+    functionName === 'spawn' ||
+    functionName === 'spawnSync'
+  );
+}
+
+/**
+ * Create a CallExpression checker that validates command execution calls
+ *
+ * This centralizes the logic for detecting command execution patterns across
+ * different ESLint rules, eliminating code duplication.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.context - ESLint rule context
+ * @param {Function} options.shouldReport - Predicate that determines if violation should be reported
+ *   Can return:
+ *   - boolean: true to report with default messageData
+ *   - object: messageData to use for error message
+ *   - falsy: don't report
+ *   Signature: (node, firstArg, matchesExecSync) => boolean | object | falsy
+ * @param {string} options.messageId - ESLint message ID to report
+ * @returns {Object} ESLint CallExpression visitor
+ *
+ * @example
+ * // Simple boolean check:
+ * return {
+ *   CallExpression: createCommandChecker({
+ *     context,
+ *     shouldReport: (node, firstArg) => firstArg.value === 'git',
+ *     messageId: 'noGitDirect',
+ *   }),
+ * };
+ *
+ * @example
+ * // With dynamic messageData:
+ * return {
+ *   CallExpression: createCommandChecker({
+ *     context,
+ *     shouldReport: (node, firstArg) => {
+ *       if (UNIX_COMMANDS.includes(firstArg.value)) {
+ *         return { command: firstArg.value, alternative: getAlt(firstArg.value) };
+ *       }
+ *       return false;
+ *     },
+ *     messageId: 'unixCommand',
+ *   }),
+ * };
+ */
+function createCommandChecker(options) {
+  const { context, shouldReport, messageId } = options;
+
+  return function CallExpression(node) {
+    const functionName = node.callee.name;
+
+    if (node.arguments.length === 0) {
+      return;
+    }
+
+    // Check for shell-free command execution patterns:
+    // - safeExecSync('cmd', ...)
+    // - safeExecResult('cmd', ...)
+    // - spawn('cmd', ...)
+    // - spawnSync('cmd', ...)
+    if (isShellFreeExecution(functionName)) {
+      checkShellFreeExecution(node, context, shouldReport, messageId);
+      return;
+    }
+
+    // Check for execSync('cmd ...') or execSync(`cmd ...`)
+    // Note: execSync is discouraged for security reasons (uses shell)
+    if (functionName === 'execSync') {
+      checkExecSyncExecution(node, context, shouldReport, messageId);
+    }
+  };
+}
+
+// ============================================================================
+// FACTORY FUNCTION - Create Rules for Specific Commands
+// ============================================================================
+
+/**
+ * Factory: Create rule that prevents direct command execution
+ *
+ * @param {Object} config - Rule configuration
+ * @param {string} config.command - Command name to detect (e.g., 'git', 'gh')
+ * @param {string} config.packageName - Package containing wrappers (e.g., '@my-org/git')
+ * @param {string[]} config.availableFunctions - List of available wrapper functions
+ * @param {string} [config.exemptPackage] - Repo-relative directory of the package that
+ *   OWNS the wrappers, e.g. `'packages/git/'`. Matched at a path-segment boundary by
+ *   `exempt-path-matcher.cjs` — NOT as a substring, so `vendor/copy-packages/git/` is
+ *   still linted.
+ * @returns {Object} ESLint rule definition
+ *
+ * @example
+ * // no-git-commands-direct.cjs
+ * const { createNoCommandDirectRule } = require('./no-command-direct-factory.cjs');
+ * module.exports = createNoCommandDirectRule({
+ *   command: 'git',
+ *   packageName: '@my-org/git',
+ *   availableFunctions: ['executeGitCommand()', 'getTreeHash()', 'addNote()'],
+ *   exemptPackage: 'packages/git/',
+ * });
+ */
+
+function createNoCommandDirectRule(config) {
+  const { command, packageName, availableFunctions, exemptPackage } = config;
+
+  const isUnderExemptPackage = createExemptDirectoryMatcher(exemptPackage ? [exemptPackage] : []);
+  const functionList = availableFunctions.join(', ');
+  const messageId = `no${command.charAt(0).toUpperCase()}${command.slice(1)}Direct`;
+
+  return {
+    meta: {
+      type: 'problem',
+      docs: {
+        description: `Enforce use of ${packageName} functions instead of direct ${command} command execution`,
+        category: 'Architecture',
+        recommended: true,
+      },
+      fixable: null, // No auto-fix - requires manual refactoring
+      schema: [],
+      messages: {
+        [messageId]: `Use functions from ${packageName} instead of calling ${command} commands directly. Available functions: ${functionList}.`,
+      },
+    },
+
+    create(context) {
+      // Exempt the package itself (where centralization happens)
+      if (isUnderExemptPackage(context.getFilename())) {
+        return {};
+      }
+
+      return {
+        CallExpression: createCommandChecker({
+          context,
+          shouldReport: (node, firstArg, matchesExecSync) => {
+            // For shell-free execution (safeExecSync, spawn, etc.)
+            if (!matchesExecSync) {
+              return firstArg.value === command;
+            }
+            // For execSync (shell-based)
+            return matchesExecSync(firstArg, command);
+          },
+          messageId,
+        }),
+      };
+    },
+  };
+}
+
+// ============================================================================
+// EXPORTS - Factory + Helpers
+// ============================================================================
+// Export factory as default (for backward compatibility with existing rules)
+// and attach helpers as properties (for new rules like no-unix-shell-commands)
+
+module.exports = createNoCommandDirectRule;
+module.exports.createCommandChecker = createCommandChecker;
+module.exports.commandMatchesExecSync = commandMatchesExecSync;