@devrik-tools/claude-gates 0.2.0 → 0.3.0

package/plugins/gates/hooks/gates/dependency-skills/index.mjs

@@ -1,126 +1,130 @@
-import { readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import {
-  runGate,
-  warn,
-  toolInGroups,
-  writtenPathOf,
-  writtenContentOf,
-} from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'dependency-skills';
-const CONFIG_KEY = 'requireSkillForNewDependency';
-
-const DEFAULT_DEPS_WITHOUT_OWN_API = [
-  'clsx',
-  'classnames',
-  'lodash.debounce',
-  'lodash.throttle',
-  'lodash.merge',
-  'tslib',
-  'core-js',
-  'regenerator-runtime',
-];
-
-function normalize(name) {
-  return name.replace(/^@/, '').replace(/\//g, '-').toLowerCase();
-}
-
-function isExempt(dependencyName, dependenciesWithoutOwnApi) {
-  if (dependencyName.startsWith('@types/')) return true;
-  return dependenciesWithoutOwnApi.includes(dependencyName);
-}
-
-function listSkillDirectories(skillsDirectoryPath) {
-  try {
-    return readdirSync(skillsDirectoryPath, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name);
-  } catch {
-    // No skills directory in this project — nothing to cross-check against.
-    return [];
-  }
-}
-
-// A skill covers a dependency when its normalized name equals the dependency's, or contains
-// it as a whole `-`-segment (a `stripe-payments` skill covers `stripe`). The old check was
-// bidirectional substring, so a skill dir `rip` "matched" `stripe` (rip ⊂ st-rip-e) — a false
-// exemption that silenced the warning for an unreviewed dependency.
-function skillNameMatches(normalizedDependency, skillDirectoryName) {
-  const normalizedSkill = normalize(skillDirectoryName);
-  if (normalizedSkill === normalizedDependency) return true;
-  return normalizedSkill.split('-').includes(normalizedDependency);
-}
-
-function hasMatchingSkill(dependencyName, skillDirectories) {
-  const normalizedDependency = normalize(dependencyName);
-  return skillDirectories.some((skillDirectoryName) =>
-    skillNameMatches(normalizedDependency, skillDirectoryName),
-  );
-}
-
-function needsSkillReview(dependencyName, parameters, skillDirectories) {
-  if (isExempt(dependencyName, parameters.depsWithoutOwnApi)) return false;
-  return !hasMatchingSkill(dependencyName, skillDirectories);
-}
-
-/** Parsed `package.json` dependency names, or null when it cannot be read yet. */
-function dependencyNamesIn(content) {
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    // Mid-edit or partially written package.json — nothing reliable to check yet.
-    return null;
-  }
-  const dependencies = {
-    ...(parsed.dependencies ?? {}),
-    ...(parsed.devDependencies ?? {}),
-  };
-  return Object.keys(dependencies);
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      depsWithoutOwnApi: DEFAULT_DEPS_WITHOUT_OWN_API,
-      projectSkillsDir: '.claude/skills',
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, ['write'])) return;
-
-    const filePath = writtenPathOf(toolInput);
-    if (!filePath.replace(/\\/g, '/').endsWith('package.json')) return;
-
-    const content = writtenContentOf(toolInput);
-    if (!content) return;
-
-    const dependencyNames = dependencyNamesIn(content);
-    if (!dependencyNames || dependencyNames.length === 0) return;
-
-    const skillDirectories = listSkillDirectories(
-      join(process.cwd(), parameters.projectSkillsDir),
-    );
-
-    const unmatched = dependencyNames.filter((name) =>
-      needsSkillReview(name, parameters, skillDirectories),
-    );
-    if (unmatched.length === 0) return;
-
-    warn(
-      GATE_ID,
-      `New dependencies without a matching skill in ${parameters.projectSkillsDir}: ${unmatched.join(', ')}. Consider adding a skill documenting how to use them, or add them to depsWithoutOwnApi if they need none.`,
-    );
-  },
-);
-
-// Deliberately simplified vs. the source guard (guard-dependencies-skills.mjs):
-// dropped the hardcoded alias table (stripe -> stripe-payments, etc.) and the
-// .ai/skills-baseline.json freeze mechanism — that belongs to a separate
-// adopt-stack-and-skills.mjs script that does not exist in this repo. This
-// gate only does simple substring matching between dependency name and skill
-// directory name, both normalized.
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  writtenPathOf,
+  writtenContentOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'dependency-skills';
+const CONFIG_KEY = 'requireSkillForNewDependency';
+
+const DEFAULT_DEPS_WITHOUT_OWN_API = [
+  'clsx',
+  'classnames',
+  'lodash.debounce',
+  'lodash.throttle',
+  'lodash.merge',
+  'tslib',
+  'core-js',
+  'regenerator-runtime',
+];
+
+function normalize(name) {
+  return name.replace(/^@/, '').replace(/\//g, '-').toLowerCase();
+}
+
+function isExempt(dependencyName, dependenciesWithoutOwnApi) {
+  if (dependencyName.startsWith('@types/')) return true;
+  return dependenciesWithoutOwnApi.includes(dependencyName);
+}
+
+function listSkillDirectories(skillsDirectoryPath) {
+  try {
+    return readdirSync(skillsDirectoryPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    // No skills directory in this project — nothing to cross-check against.
+    return [];
+  }
+}
+
+// A skill covers a dependency when its normalized name equals the dependency's, or contains
+// it as a whole `-`-segment (a `stripe-payments` skill covers `stripe`). The old check was
+// bidirectional substring, so a skill dir `rip` "matched" `stripe` (rip ⊂ st-rip-e) — a false
+// exemption that silenced the warning for an unreviewed dependency.
+function skillNameMatches(normalizedDependency, skillDirectoryName) {
+  const normalizedSkill = normalize(skillDirectoryName);
+  if (normalizedSkill === normalizedDependency) return true;
+  return normalizedSkill.split('-').includes(normalizedDependency);
+}
+
+function hasMatchingSkill(dependencyName, skillDirectories) {
+  const normalizedDependency = normalize(dependencyName);
+  return skillDirectories.some((skillDirectoryName) =>
+    skillNameMatches(normalizedDependency, skillDirectoryName),
+  );
+}
+
+function needsSkillReview(dependencyName, parameters, skillDirectories) {
+  if (isExempt(dependencyName, parameters.depsWithoutOwnApi)) return false;
+  return !hasMatchingSkill(dependencyName, skillDirectories);
+}
+
+/** Parsed `package.json` dependency names, or null when it cannot be read yet. */
+function dependencyNamesIn(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // Mid-edit or partially written package.json — nothing reliable to check yet.
+    return null;
+  }
+  const dependencies = {
+    ...(parsed.dependencies ?? {}),
+    ...(parsed.devDependencies ?? {}),
+  };
+  return Object.keys(dependencies);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      depsWithoutOwnApi: DEFAULT_DEPS_WITHOUT_OWN_API,
+      projectSkillsDir: '.claude/skills',
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, ['write'])) return;
+
+    const filePath = writtenPathOf(toolInput);
+    if (!filePath.replace(/\\/g, '/').endsWith('package.json')) return;
+
+    const content = writtenContentOf(toolInput);
+    if (!content) return;
+
+    const dependencyNames = dependencyNamesIn(content);
+    if (!dependencyNames || dependencyNames.length === 0) return;
+
+    const skillDirectories = listSkillDirectories(
+      join(process.cwd(), parameters.projectSkillsDir),
+    );
+
+    const unmatched = dependencyNames.filter((name) =>
+      needsSkillReview(name, parameters, skillDirectories),
+    );
+    if (unmatched.length === 0) return;
+
+    deny(
+      GATE_ID,
+      `New dependencies without a matching skill in ${parameters.projectSkillsDir}: ${unmatched.join(', ')}. ` +
+        'Add a skill documenting how to use each (directory name matching or containing the ' +
+        'package name), OR, if a dependency genuinely needs no skill, declare it in ' +
+        '`depsWithoutOwnApi` in .ai/config.json — that is the explicit opt-out, edited in the ' +
+        'same change. This blocks so an unreviewed dependency is a deliberate choice, not a default.',
+    );
+  },
+);
+
+// Deliberately simplified vs. the source guard (guard-dependencies-skills.mjs):
+// dropped the hardcoded alias table (stripe -> stripe-payments, etc.) and the
+// .ai/skills-baseline.json freeze mechanism — that belongs to a separate
+// adopt-stack-and-skills.mjs script that does not exist in this repo. This
+// gate only does simple substring matching between dependency name and skill
+// directory name, both normalized.

package/plugins/gates/hooks/gates/neutral-spanish/index.mjs

@@ -1,79 +1,104 @@
-import { runGate, warn, toolInGroups, writtenContentOf } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'neutral-spanish';
-const CONFIG_KEY = 'warnNonNeutralSpanish';
-
-const MAX_REPORTED_MARKERS = 8;
-
-// Data strings, not identifiers — never add these to a cSpell dictionary.
-const DEFAULT_REGIONAL_MARKERS = [
-  'tenés',
-  'podés',
-  'querés',
-  'sabés',
-  'hacés',
-  'decís',
-  'venís',
-  'sos',
-  'fijate',
-  'mirá',
-  'pará',
-  'esperá',
-  'dale',
-  'mandale',
-  'contame',
-  'fíjate vos',
-  'acá',
-  'allá',
-  'laburo',
-  'laburar',
-  'quilombo',
-  'posta',
-  'che',
-  'boludo',
-  'pibe',
-  'guita',
-  'al pedo',
-  'un toque',
-  'capaz que',
-  'de una',
-];
-
-function extractText(toolName, toolInput) {
-  if (!toolInGroups(toolName, ['write'])) return '';
-  return writtenContentOf(toolInput);
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      regionalMarkers: DEFAULT_REGIONAL_MARKERS,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    const text = extractText(toolName, toolInput).toLowerCase();
-    if (!text) return;
-
-    const hits = [];
-    for (const marker of parameters.regionalMarkers) {
-      const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      // \p{L} (any Unicode letter) as the non-boundary class, instead of a hand-written
-      // accented-character set, so accented word boundaries are handled correctly without
-      // spelling out literal accented characters in the source (the project keeps its
-      // spell-check dictionary untouched, so no word list may lean on this being a string).
-      const pattern = new RegExp(`(^|[^\\p{L}])${escaped}([^\\p{L}]|$)`, 'iu');
-      if (pattern.test(text)) hits.push(marker);
-    }
-
-    if (hits.length === 0) return;
-
-    const unique = [...new Set(hits)].slice(0, MAX_REPORTED_MARKERS);
-    warn(
-      GATE_ID,
-      `Text being written contains regional Spanish markers: ${unique.join(', ')}. Prefer neutral Spanish unless this is a literal quote or data.`,
-    );
-  },
-);
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  writtenContentOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'neutral-spanish';
+const CONFIG_KEY = 'warnNonNeutralSpanish';
+
+const MAX_REPORTED_MARKERS = 8;
+
+// Escape hatch: when a written file legitimately needs regional text (a literal quote, a
+// test fixture, a captured log, a data sample), placing this marker anywhere in the content
+// tells the gate the regional wording is intentional and lets the write through. A deny (as
+// opposed to the old warn) cannot "advise and let pass", so a legitimate case needs an
+// explicit, greppable opt-out — a marker the author writes on purpose, never one the agent
+// could infer. A project can override it via config (escapeHatch).
+const DEFAULT_ESCAPE_HATCH = 'neutral-spanish:allow';
+
+// Data strings, not identifiers — never add these to a cSpell dictionary.
+// neutral-spanish:allow — this list IS the marker data; the gate must not deny its own source.
+// Now that this gate DENIES (not warns), a marker must be unambiguously regional. Tokens that
+// also occur in neutral Spanish were removed: "de una" (matches "de una lista/vez"), "allá"
+// (standard across the whole language) — a false positive here blocks a legitimate write.
+const DEFAULT_REGIONAL_MARKERS = [
+  'tenés',
+  'podés',
+  'querés',
+  'sabés',
+  'hacés',
+  'decís',
+  'venís',
+  'sos',
+  'fijate',
+  'mirá',
+  'pará',
+  'esperá',
+  'dale',
+  'mandale',
+  'contame',
+  'fíjate vos',
+  'acá',
+  'laburo',
+  'laburar',
+  'quilombo',
+  'posta',
+  'che',
+  'boludo',
+  'pibe',
+  'guita',
+  'al pedo',
+  'un toque',
+  'capaz que', // neutral-spanish:allow (marker data, not prose)
+];
+
+function extractText(toolName, toolInput) {
+  if (!toolInGroups(toolName, ['write'])) return '';
+  return writtenContentOf(toolInput);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      regionalMarkers: DEFAULT_REGIONAL_MARKERS,
+      escapeHatch: DEFAULT_ESCAPE_HATCH,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const text = extractText(toolName, toolInput).toLowerCase();
+    if (!text) return;
+
+    // Explicit opt-out for legitimate regional text (quote/fixture/log/data sample).
+    const escapeHatch = (
+      parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH
+    ).toLowerCase();
+    if (escapeHatch && text.includes(escapeHatch)) return;
+
+    const hits = [];
+    for (const marker of parameters.regionalMarkers) {
+      const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      // \p{L} (any Unicode letter) as the non-boundary class, instead of a hand-written
+      // accented-character set, so accented word boundaries are handled correctly without
+      // spelling out literal accented characters in the source (the project keeps its
+      // spell-check dictionary untouched, so no word list may lean on this being a string).
+      const pattern = new RegExp(`(^|[^\\p{L}])${escaped}([^\\p{L}]|$)`, 'iu');
+      if (pattern.test(text)) hits.push(marker);
+    }
+
+    if (hits.length === 0) return;
+
+    const unique = [...new Set(hits)].slice(0, MAX_REPORTED_MARKERS);
+    deny(
+      GATE_ID,
+      `Text being written contains regional Spanish markers: ${unique.join(', ')}. ` +
+        'Rewrite in neutral Spanish before writing. If the regional wording is intentional ' +
+        `(a literal quote, a test fixture, a captured log, a data sample), add the marker ` +
+        `"${parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH}" somewhere in the content to allow it.`,
+    );
+  },
+);