claudex-setup 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -15,6 +15,25 @@
 - README and docs now reflect snapshot artifacts, governance export, and the Claude-native skill path
 - packaged content and public-facing counts are now aligned with the current CLAUDEX state
 
+## [1.14.0] - 2026-04-03
+
+### Added
+- Check-level test matrix: 327 verified scenarios across all 84 checks
+- Golden matrix: 12 repo profile tests with expected results
+
+### Fixed
+- `hooks` check now detects hooks in settings.json (not only .claude/hooks/ dir)
+- `context7Mcp` check now reads .mcp.json
+- `skillUsesPaths` now traverses skill subdirectories (skills/name/SKILL.md)
+- `lintCommand` now matches npm/yarn/pnpm/bun lint commands
+
+## [1.13.0] - 2026-04-03
+
+### Added
+- 10 new checks (74→84): project description, directory structure, multiple hook types, stop-failure hook, skill paths, MCP env config, gitignore local settings, .env.example, package scripts, type checking
+- 15 new tests (58→73): history/compare/trend, new checks structure, CLI commands, deny depth, negative instructions, --require flag
+- All references updated to 74→84 checks
+
 ## [1.12.0] - 2026-04-03
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # claudex-setup
 
-> Score your repo's Claude Code setup against 74 checks. See what's missing, apply only what you approve with rollback, and benchmark the impact — without breaking existing config.
+> Score your repo's Claude Code setup against 84 checks. See what's missing, apply only what you approve with rollback, and benchmark the impact — without breaking existing config.
 
 [![npm version](https://img.shields.io/npm/v/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
 [![npm downloads](https://img.shields.io/npm/dm/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
@@ -89,7 +89,7 @@ Most common gaps found: missing secrets protection, no deny rules, no mermaid di
       design: none (0/2)
      devops: none (0/4)
 
-  29/74 checks passing
+  29/84 checks passing
   Next command: npx claudex-setup setup
 ```
 
@@ -105,7 +105,7 @@ That prints a compact top-3 quick scan with one clear next command.
 
 | Command | What it does |
 |---------|-------------|
-| `npx claudex-setup` | **Discover** - Score 0-100 against 74 checks |
+| `npx claudex-setup` | **Discover** - Score 0-100 against 84 checks |
 | `npx claudex-setup discover` | **Discover** - Alias for audit mode |
 | `npx claudex-setup setup` | **Starter** - Smart CLAUDE.md + hooks + commands + agents |
 | `npx claudex-setup starter` | **Starter** - Alias for setup mode |
@@ -305,7 +305,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.12.0
+      - uses: DnaFin/claudex-setup@v1.14.0
         with:
           threshold: 50
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Score your repo's Claude Code setup against 62 checks. See gaps, apply fixes selectively with rollback, govern hooks and permissions, and benchmark impact — without breaking existing config.",
   "main": "src/index.js",
   "bin": {

package/src/techniques.js

@@ -116,7 +116,7 @@ const TECHNIQUES = {
     name: 'CLAUDE.md contains a lint command',
     check: (ctx) => {
       const md = ctx.fileContent('CLAUDE.md') || '';
-      return /eslint|prettier|ruff|black|clippy|golangci-lint|rubocop/.test(md);
+      return /eslint|prettier|ruff|black|clippy|golangci-lint|rubocop|npm run lint|yarn lint|pnpm lint|bun lint/.test(md);
     },
     impact: 'high',
     rating: 4,
@@ -413,7 +413,12 @@ const TECHNIQUES = {
   hooks: {
     id: 19,
     name: 'Hooks for automation',
-    check: (ctx) => ctx.hasDir('.claude/hooks') && ctx.dirFiles('.claude/hooks').length > 0,
+    check: (ctx) => {
+      if (ctx.hasDir('.claude/hooks') && ctx.dirFiles('.claude/hooks').length > 0) return true;
+      const shared = ctx.jsonFile('.claude/settings.json') || {};
+      const local = ctx.jsonFile('.claude/settings.local.json') || {};
+      return !!(shared.hooks && Object.keys(shared.hooks).length > 0) || !!(local.hooks && Object.keys(local.hooks).length > 0);
+    },
     impact: 'high',
     rating: 4,
     category: 'automation',
@@ -717,9 +722,12 @@ const TECHNIQUES = {
     id: 110,
     name: 'Context7 MCP for real-time docs',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.mcpServers) return false;
-      return Object.keys(settings.mcpServers).some(k => /context7/i.test(k));
+      const shared = ctx.jsonFile('.claude/settings.json') || {};
+      const local = ctx.jsonFile('.claude/settings.local.json') || {};
+      const mcp = ctx.jsonFile('.mcp.json') || {};
+      const all = { ...(shared.mcpServers || {}), ...(local.mcpServers || {}), ...(mcp.mcpServers || {}) };
+      if (Object.keys(all).length === 0) return false;
+      return Object.keys(all).some(k => /context7/i.test(k));
     },
     impact: 'medium',
     rating: 4,
@@ -1114,6 +1122,145 @@ const TECHNIQUES = {
     template: null
   },
 
+  // --- New checks: depth round 2 ---
+  projectDescriptionInClaudeMd: {
+    id: 2022,
+    name: 'CLAUDE.md describes what the project does',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      return /what.*does|overview|purpose|about|description|project.*is/i.test(md) && md.length > 100;
+    },
+    impact: 'high', rating: 4, category: 'memory',
+    fix: 'Start CLAUDE.md with a clear project description. Claude needs to know what your project does.',
+    template: null
+  },
+
+  directoryStructureInClaudeMd: {
+    id: 2023,
+    name: 'CLAUDE.md documents directory structure',
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      return /src\/|app\/|lib\/|structure|director|folder/i.test(md);
+    },
+    impact: 'medium', rating: 4, category: 'memory',
+    fix: 'Document your directory structure in CLAUDE.md so Claude navigates your codebase efficiently.',
+    template: null
+  },
+
+  multipleHookTypes: {
+    id: 2024,
+    name: '2+ hook event types configured',
+    check: (ctx) => {
+      const shared = ctx.jsonFile('.claude/settings.json') || {};
+      const local = ctx.jsonFile('.claude/settings.local.json') || {};
+      const hooks = { ...(shared.hooks || {}), ...(local.hooks || {}) };
+      return Object.keys(hooks).length >= 2;
+    },
+    impact: 'medium', rating: 3, category: 'automation',
+    fix: 'Add at least 2 hook types (e.g. PostToolUse for linting + SessionStart for initialization).',
+    template: null
+  },
+
+  stopFailureHook: {
+    id: 2025,
+    name: 'StopFailure or error handling hook',
+    check: (ctx) => {
+      const shared = ctx.jsonFile('.claude/settings.json') || {};
+      const local = ctx.jsonFile('.claude/settings.local.json') || {};
+      return !!(shared.hooks?.StopFailure || shared.hooks?.Stop || local.hooks?.StopFailure || local.hooks?.Stop);
+    },
+    impact: 'low', rating: 3, category: 'automation',
+    fix: 'Add a StopFailure hook to log errors for debugging. Helps track why Claude stops unexpectedly.',
+    template: null
+  },
+
+  skillUsesPaths: {
+    id: 2026,
+    name: 'At least one skill uses paths for scoping',
+    check: (ctx) => {
+      if (!ctx.hasDir('.claude/skills')) return null;
+      const entries = ctx.dirFiles('.claude/skills');
+      if (entries.length === 0) return null;
+      for (const entry of entries) {
+        // Skills can be files or dirs with SKILL.md inside
+        const direct = ctx.fileContent(`.claude/skills/${entry}`) || '';
+        if (/paths:/i.test(direct)) return true;
+        const nested = ctx.fileContent(`.claude/skills/${entry}/SKILL.md`) || '';
+        if (/paths:/i.test(nested)) return true;
+      }
+      return false;
+    },
+    impact: 'low', rating: 3, category: 'workflow',
+    fix: 'Add paths to skill frontmatter to scope when skills activate (e.g. paths: ["src/**/*.ts"]).',
+    template: null
+  },
+
+  mcpHasEnvConfig: {
+    id: 2027,
+    name: 'MCP servers have environment configuration',
+    check: (ctx) => {
+      const shared = ctx.jsonFile('.claude/settings.json') || {};
+      const local = ctx.jsonFile('.claude/settings.local.json') || {};
+      const mcp = ctx.jsonFile('.mcp.json') || {};
+      const allServers = { ...(shared.mcpServers || {}), ...(local.mcpServers || {}), ...(mcp.mcpServers || {}) };
+      if (Object.keys(allServers).length === 0) return null;
+      return Object.values(allServers).some(s => s.env && Object.keys(s.env).length > 0);
+    },
+    impact: 'low', rating: 3, category: 'tools',
+    fix: 'Configure environment variables for MCP servers that need authentication (e.g. GITHUB_TOKEN).',
+    template: null
+  },
+
+  gitIgnoreClaudeLocal: {
+    id: 2028,
+    name: '.gitignore excludes settings.local.json',
+    check: (ctx) => {
+      const gitignore = ctx.fileContent('.gitignore') || '';
+      return /settings\.local\.json|settings\.local/i.test(gitignore);
+    },
+    impact: 'medium', rating: 4, category: 'git',
+    fix: 'Add .claude/settings.local.json to .gitignore. Personal overrides should not be committed.',
+    template: null
+  },
+
+  envExampleExists: {
+    id: 2029,
+    name: '.env.example or .env.template exists',
+    check: (ctx) => {
+      return !!(ctx.fileContent('.env.example') || ctx.fileContent('.env.template') || ctx.fileContent('.env.sample'));
+    },
+    impact: 'low', rating: 3, category: 'hygiene',
+    fix: 'Add .env.example so new developers know which environment variables are needed.',
+    template: null
+  },
+
+  packageJsonHasScripts: {
+    id: 2030,
+    name: 'package.json has dev/test/build scripts',
+    check: (ctx) => {
+      const pkg = ctx.jsonFile('package.json');
+      if (!pkg) return null;
+      const scripts = pkg.scripts || {};
+      const has = (k) => !!scripts[k];
+      return has('test') || has('dev') || has('build') || has('start');
+    },
+    impact: 'medium', rating: 3, category: 'hygiene',
+    fix: 'Add scripts to package.json (test, dev, build). Claude uses these for verification.',
+    template: null
+  },
+
+  typeCheckingConfigured: {
+    id: 2031,
+    name: 'Type checking configured (TypeScript or similar)',
+    check: (ctx) => {
+      return !!(ctx.fileContent('tsconfig.json') || ctx.fileContent('jsconfig.json') ||
+        ctx.fileContent('pyrightconfig.json') || ctx.fileContent('mypy.ini'));
+    },
+    impact: 'medium', rating: 3, category: 'quality',
+    fix: 'Add type checking configuration. Type-safe code produces fewer Claude errors.',
+    template: null
+  },
+
   noDeprecatedPatterns: {
     id: 2009,
     name: 'No deprecated patterns detected',