@yawlabs/ctxlint 0.22.0 → 0.23.0

package/.pre-commit-hooks.yaml

@@ -4,7 +4,7 @@
   # Version-pinned so a checkout at `rev: vX.Y.Z` runs exactly that release
   # of ctxlint — matches the pinning done by `ctxlint init`. release.sh keeps
   # this in sync with package.json on each bump.
-  entry: npx @yawlabs/ctxlint@0.22.0 --strict
+  entry: npx @yawlabs/ctxlint@0.23.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/dist/index.js

@@ -24050,84 +24050,443 @@ var init_cli_subcommands = __esm({
   }
 });
 
-// src/core/checks/commands.ts
+// src/core/checks/tokens.ts
+function resolveTokenThresholds(overrides) {
+  if (!overrides) return DEFAULT_TOKEN_THRESHOLDS;
+  const merged = { ...DEFAULT_TOKEN_THRESHOLDS, ...overrides };
+  if (merged.info >= merged.warning || merged.warning >= merged.error) {
+    console.error(
+      `Warning: token thresholds should satisfy info < warning < error (got ${merged.info}, ${merged.warning}, ${merged.error}) \u2014 using defaults`
+    );
+    return DEFAULT_TOKEN_THRESHOLDS;
+  }
+  return merged;
+}
+async function checkTokens(file2, _projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+  const issues = [];
+  const tokens = file2.totalTokens;
+  if (tokens >= thresholds.error) {
+    issues.push({
+      severity: "error",
+      check: "tokens",
+      ruleId: "tokens/excessive",
+      line: 1,
+      message: `${tokens.toLocaleString()} tokens \u2014 consumes significant context window space`,
+      suggestion: "Consider splitting into focused sections or removing redundant content."
+    });
+  } else if (tokens >= thresholds.warning) {
+    issues.push({
+      severity: "warning",
+      check: "tokens",
+      ruleId: "tokens/large",
+      line: 1,
+      message: `${tokens.toLocaleString()} tokens \u2014 large context file`,
+      suggestion: "Consider trimming \u2014 research shows diminishing returns past ~300 lines."
+    });
+  } else if (tokens >= thresholds.info) {
+    issues.push({
+      severity: "info",
+      check: "tokens",
+      ruleId: "tokens/info",
+      line: 1,
+      message: `Uses ~${tokens.toLocaleString()} tokens per session`
+    });
+  }
+  return issues;
+}
+function checkAggregateTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+  const total = files.reduce((sum, f) => sum + f.tokens, 0);
+  if (total >= thresholds.aggregate && files.length > 1) {
+    return {
+      severity: "warning",
+      check: "tokens",
+      ruleId: "tokens/aggregate",
+      line: 0,
+      message: `${files.length} context files consume ${total.toLocaleString()} tokens combined`,
+      suggestion: "Consider consolidating or trimming to reduce per-session context cost."
+    };
+  }
+  return null;
+}
+var DEFAULT_TOKEN_THRESHOLDS;
+var init_tokens2 = __esm({
+  "src/core/checks/tokens.ts"() {
+    "use strict";
+    init_define_WEB_FIRST_SEGMENTS();
+    DEFAULT_TOKEN_THRESHOLDS = {
+      info: 1e3,
+      warning: 3e3,
+      error: 8e3,
+      aggregate: 5e3,
+      tierBreakdown: 1e3,
+      tierAggregate: 4e3
+    };
+  }
+});
+
+// src/core/checks/tier-tokens.ts
 import * as fs6 from "node:fs";
+import * as os2 from "node:os";
 import * as path7 from "node:path";
-function isManagerBuiltin(manager, sub) {
-  return PM_MANAGER_BUILTINS[manager]?.has(sub) ?? false;
+function hasFrontmatterList(content, field) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return false;
+  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
+  for (let i2 = 1; i2 < lines.length; i2++) {
+    const line = lines[i2];
+    if (line.trim() === "---") return false;
+    const match = line.match(fieldPattern);
+    if (match) {
+      const val = match[1].trim();
+      if (val && val !== "[]") return true;
+      for (let j3 = i2 + 1; j3 < lines.length; j3++) {
+        const next = lines[j3];
+        if (next.trim() === "---") return false;
+        if (next.trim() === "") continue;
+        if (next.trim().startsWith("- ")) return true;
+        break;
+      }
+    }
+  }
+  return false;
 }
-function scriptNameFromMatch(match) {
-  const [, manager, explicitRun, name] = match;
-  if (name.startsWith("-")) return null;
-  if (manager && !explicitRun && PM_BUILTIN_SUBCOMMANDS.has(name)) return null;
-  if (manager && !explicitRun && isManagerBuiltin(manager, name)) return null;
-  return name;
+function frontmatterScalar(content, field) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return null;
+  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
+  for (let i2 = 1; i2 < lines.length; i2++) {
+    if (lines[i2].trim() === "---") return null;
+    const match = lines[i2].match(fieldPattern);
+    if (match) return match[1].trim().replace(/^['"]|['"]$/g, "") || null;
+  }
+  return null;
 }
-function extractNpxPackage(cmd) {
-  if (!/^npx\b/.test(cmd)) return null;
-  const tokens = cmd.split(/\s+/).slice(1);
-  for (let i2 = 0; i2 < tokens.length; i2++) {
-    const t2 = tokens[i2];
-    if (t2 === "-p" || t2 === "--package") {
-      const v2 = tokens[i2 + 1];
-      if (v2 && !v2.startsWith("-")) return v2;
-      continue;
+function isAlwaysLoaded(file2) {
+  const rel = file2.relativePath.replace(/\\/g, "/");
+  if (rel.endsWith(".mdc")) return false;
+  if (rel.startsWith(".github/instructions/")) return false;
+  if (rel.includes("/rules/")) {
+    if (hasFrontmatterList(file2.content, "paths")) return false;
+    if (hasFrontmatterList(file2.content, "globs")) return false;
+    if (rel.includes(".windsurf/rules/")) {
+      const trigger = frontmatterScalar(file2.content, "trigger");
+      if (trigger && trigger.toLowerCase() !== "always_on") return false;
     }
-    if (t2.startsWith("-p=") || t2.startsWith("--package=")) {
-      return t2.slice(t2.indexOf("=") + 1) || null;
+    return true;
+  }
+  const basename4 = rel.split("/").pop() ?? "";
+  for (const name of ALWAYS_LOADED_NAMES) {
+    if (name.includes("/")) {
+      if (rel === name || rel.endsWith("/" + name)) return true;
+    } else if (basename4 === name) {
+      return true;
     }
-    if (t2.startsWith("-")) continue;
-    return t2;
+  }
+  return false;
+}
+function computeSectionCosts(file2) {
+  if (file2.sections.length === 0) return [];
+  const hasH2 = file2.sections.some((s) => s.level === 2);
+  const topLevel = hasH2 ? 2 : 1;
+  const lines = file2.content.split("\n");
+  return file2.sections.filter((s) => s.level === topLevel).map((s) => {
+    const body = lines.slice(s.startLine - 1, s.endLine).join("\n");
+    return { title: s.title, line: s.startLine, tokens: countTokens(body) };
+  }).sort((a, b2) => b2.tokens - a.tokens);
+}
+function inlineCodeSpans(line) {
+  const spans = [];
+  const re2 = /`([^`]+)`/g;
+  let m;
+  while ((m = re2.exec(line)) !== null) {
+    spans.push({ start: m.index, end: m.index + m[0].length, content: m[1] });
+  }
+  return spans;
+}
+function maskCodeSpans(line, spans) {
+  let out = line;
+  for (const s of spans) {
+    out = out.slice(0, s.start) + "#".repeat(s.end - s.start) + out.slice(s.end);
+  }
+  return out;
+}
+function findInviolableCommand(line) {
+  const spans = inlineCodeSpans(line);
+  if (spans.length === 0) return null;
+  const masked = maskCodeSpans(line, spans);
+  FRAMING_TOKEN.lastIndex = 0;
+  let m;
+  while ((m = FRAMING_TOKEN.exec(masked)) !== null) {
+    const token = m[1];
+    if (token === token.toLowerCase()) continue;
+    const afterIdx = m.index + m[0].length;
+    const span = spans.find((s) => s.start >= afterIdx);
+    if (!span) continue;
+    const gap = masked.slice(afterIdx, span.start);
+    if (gap.length > FRAMING_COMMAND_GAP || /[.!?]/.test(gap)) continue;
+    return { framing: token, command: span.content };
   }
   return null;
 }
-function wouldNeedPackageJson(cmd) {
-  const scriptMatch = cmd.match(NPM_SCRIPT_PATTERN);
-  if (scriptMatch && scriptNameFromMatch(scriptMatch) !== null) return true;
-  const shorthandMatch = cmd.match(PKG_SHORTHAND_PATTERN);
-  if (shorthandMatch && !isManagerBuiltin(shorthandMatch[1], shorthandMatch[2])) return true;
-  return /^npx\b/.test(cmd) || PKG_DEPENDENT_TOOL_PATTERN.test(cmd);
+function fingerprintFiles(paths) {
+  return paths.map((p2) => {
+    try {
+      const st2 = fs6.statSync(p2);
+      return `${st2.mtimeMs}:${st2.size}`;
+    } catch {
+      return "absent";
+    }
+  }).join("|");
 }
-function loadDeniedCommandPrefixes(projectRoot) {
-  const prefixes = [];
-  for (const rel of ["settings.json", "settings.local.json"]) {
+function loadSettingsSources(projectRoot, includeGlobal) {
+  const candidates = [
+    path7.join(projectRoot, ".claude", "settings.json"),
+    path7.join(projectRoot, ".claude", "settings.local.json")
+  ];
+  if (includeGlobal) {
+    candidates.push(path7.join(os2.homedir(), ".claude", "settings.json"));
+  }
+  const fingerprint = fingerprintFiles(candidates);
+  if (settingsCache?.root === projectRoot && settingsCache.includeGlobal === includeGlobal && settingsCache.fingerprint === fingerprint) {
+    return settingsCache.data;
+  }
+  const sources = [];
+  for (const p2 of candidates) {
     let content;
     try {
-      content = stripBom(fs6.readFileSync(path7.join(projectRoot, ".claude", rel), "utf-8"));
+      content = stripBom(fs6.readFileSync(p2, "utf-8"));
     } catch {
       continue;
     }
-    const data = parse2(content, [], { allowTrailingComma: true });
-    const deny = data?.permissions?.deny;
-    if (!Array.isArray(deny)) continue;
-    for (const entry of deny) {
-      if (typeof entry !== "string") continue;
-      const inner = entry.replace(/^[A-Za-z]+\((.*)\)$/, "$1");
-      const prefix = inner.replace(/:?\*+$/, "").trim();
-      if (prefix) prefixes.push(prefix);
+    const errors = [];
+    const data = parse2(content, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+      console.warn(
+        `ctxlint: could not parse ${p2}: ${printParseErrorCode(errors[0].error)} at offset ${errors[0].offset}`
+      );
+      continue;
     }
+    if (!data || typeof data !== "object") continue;
+    sources.push(data);
   }
-  return prefixes;
+  settingsCache = { root: projectRoot, includeGlobal, fingerprint, data: sources };
+  return sources;
 }
-function isDeniedCommand(cmd, deniedPrefixes) {
-  return deniedPrefixes.some((p2) => cmd === p2 || cmd.startsWith(`${p2} `));
+function canonicalizeCommand(backticked) {
+  const beforeFlags = backticked.trim().split(/\s+--?/, 1)[0];
+  return beforeFlags.replace(/\s+/g, " ");
 }
-async function checkCommands(file2, projectRoot) {
-  const issues = [];
-  const pkgJson = loadPackageJson(projectRoot);
-  const makefile = loadMakefile(projectRoot);
-  const deniedPrefixes = loadDeniedCommandPrefixes(projectRoot);
-  if (!pkgJson) {
-    const skipped = file2.references.commands.find((ref) => wouldNeedPackageJson(ref.value));
-    if (skipped) {
-      issues.push({
-        severity: "info",
-        check: "commands",
-        ruleId: "commands/package-json-missing",
-        line: skipped.line,
-        message: "package.json missing or unparseable \u2014 command checks skipped",
-        suggestion: "Add a parseable package.json at the project root so script, npx, and tool references can be validated."
-      });
+function buildCommandPattern(cmd) {
+  const tokens = cmd.split(/\s+/).filter(Boolean);
+  const escaped = tokens.map((t2) => t2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  if (tokens.length === 1) {
+    return new RegExp(`(?<![A-Za-z0-9_\\-])${escaped[0]}(?![A-Za-z0-9_\\-])`, "i");
+  }
+  const body = escaped.join("[\\s\\-_]+");
+  return new RegExp(`(?<![A-Za-z0-9])${body}(?![A-Za-z0-9])`, "i");
+}
+function commandIsEnforced(cmd, settings) {
+  const pattern = buildCommandPattern(cmd);
+  for (const s of settings) {
+    for (const entry of [...s.permissions?.deny ?? [], ...s.permissions?.ask ?? []]) {
+      if (pattern.test(entry)) return true;
+    }
+    for (const h2 of [...s.hooks?.PreToolUse ?? [], ...s.hooks?.Stop ?? []]) {
+      if (pattern.test(h2.matcher || "")) return true;
+      for (const sub of h2.hooks ?? []) {
+        if (pattern.test(sub.command || "")) return true;
+      }
+    }
+  }
+  return false;
+}
+function checkHardEnforcement(file2, settings) {
+  const issues = [];
+  const lines = file2.content.split("\n");
+  for (let i2 = 0; i2 < lines.length; i2++) {
+    const line = lines[i2];
+    const match = findInviolableCommand(line);
+    if (!match) continue;
+    const cmd = canonicalizeCommand(match.command);
+    if (!cmd) continue;
+    if (commandIsEnforced(cmd, settings)) continue;
+    const suggestion = match.framing.toUpperCase() === "ALWAYS" ? `Rules in always-loaded files are advisory. For \`${cmd}\`, add a hook in .claude/settings.json (e.g. a PreToolUse or Stop hook that runs or verifies \`${cmd}\`) so the requirement doesn't depend on the agent remembering.` : `Rules in always-loaded files are advisory. For \`${cmd}\`, add a PreToolUse hook (or permissions.deny entry) in .claude/settings.json so the command is physically blocked.`;
+    issues.push({
+      severity: "info",
+      check: "tier-tokens",
+      ruleId: "tier-tokens/hard-enforcement-missing",
+      line: i2 + 1,
+      message: `Inviolable framing ("${line.trim().slice(0, 80)}") without a hook to back it up`,
+      suggestion
+    });
+  }
+  return issues;
+}
+async function checkTierTokens(file2, projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS, includeGlobal = false) {
+  if (!isAlwaysLoaded(file2)) return [];
+  const issues = [];
+  const threshold = thresholds.tierBreakdown;
+  if (file2.totalTokens >= threshold) {
+    const sectionCosts = computeSectionCosts(file2);
+    if (sectionCosts.length > 0) {
+      const top = sectionCosts.slice(0, TOP_SECTIONS_TO_REPORT);
+      const heaviest = top[0];
+      const pct = Math.round(heaviest.tokens / file2.totalTokens * 100);
+      const detail = top.map((s) => `  - "${s.title}" (L${s.line}): ~${s.tokens.toLocaleString()} tokens`).join("\n");
+      issues.push({
+        severity: "info",
+        check: "tier-tokens",
+        ruleId: "tier-tokens/section-breakdown",
+        line: heaviest.line,
+        message: `${file2.totalTokens.toLocaleString()} tokens loaded every session \u2014 heaviest top-level section${top.length === 1 ? "" : "s"}:`,
+        detail,
+        suggestion: `"${heaviest.title}" is ~${heaviest.tokens.toLocaleString()} tokens (${pct}% of file). Consider demoting to an on-demand tier (skill, subagent, or memory) so it loads only when relevant.`
+      });
+    }
+  }
+  const settings = loadSettingsSources(projectRoot, includeGlobal);
+  issues.push(...checkHardEnforcement(file2, settings));
+  return issues;
+}
+function checkAggregateTierTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+  const alwaysLoaded = files.filter(isAlwaysLoaded);
+  if (alwaysLoaded.length < 2) return null;
+  const total = alwaysLoaded.reduce((sum, f) => sum + f.totalTokens, 0);
+  const threshold = thresholds.tierAggregate;
+  if (total < threshold) return null;
+  const breakdown = alwaysLoaded.slice().sort((a, b2) => b2.totalTokens - a.totalTokens).slice(0, 5).map((f) => `  - ${f.relativePath}: ~${f.totalTokens.toLocaleString()} tokens`).join("\n");
+  return {
+    severity: "warning",
+    check: "tier-tokens",
+    ruleId: "tier-tokens/aggregate",
+    line: 0,
+    message: `${alwaysLoaded.length} always-loaded files total ${total.toLocaleString()} tokens \u2014 loaded every session`,
+    detail: breakdown,
+    suggestion: "Consider moving the largest files or their heaviest sections to on-demand tiers (skills, subagents, memory)."
+  };
+}
+var ALWAYS_LOADED_NAMES, TOP_SECTIONS_TO_REPORT, FRAMING_TOKEN, FRAMING_COMMAND_GAP, settingsCache;
+var init_tier_tokens = __esm({
+  "src/core/checks/tier-tokens.ts"() {
+    "use strict";
+    init_define_WEB_FIRST_SEGMENTS();
+    init_main3();
+    init_tokens();
+    init_fs();
+    init_tokens2();
+    ALWAYS_LOADED_NAMES = [
+      "CLAUDE.md",
+      "CLAUDE.local.md",
+      "AGENTS.md",
+      "AGENTS.override.md",
+      "AGENT.md",
+      "GEMINI.md",
+      ".cursorrules",
+      ".windsurfrules",
+      ".clinerules",
+      ".aiderules",
+      ".continuerules",
+      ".rules",
+      ".goosehints",
+      "replit.md",
+      ".github/copilot-instructions.md",
+      ".junie/guidelines.md",
+      ".junie/AGENTS.md",
+      ".goose/instructions.md"
+    ];
+    TOP_SECTIONS_TO_REPORT = 3;
+    FRAMING_TOKEN = /(?<![\w'.-])(never|always|don'?t|do\s+not|must\s+not)(?![\w'.-])/gi;
+    FRAMING_COMMAND_GAP = 80;
+    settingsCache = null;
+  }
+});
+
+// src/core/checks/commands.ts
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
+function isManagerBuiltin(manager, sub) {
+  return PM_MANAGER_BUILTINS[manager]?.has(sub) ?? false;
+}
+function scriptNameFromMatch(match) {
+  const [, manager, explicitRun, name] = match;
+  if (name.startsWith("-")) return null;
+  if (manager && !explicitRun && PM_BUILTIN_SUBCOMMANDS.has(name)) return null;
+  if (manager && !explicitRun && isManagerBuiltin(manager, name)) return null;
+  return name;
+}
+function extractNpxPackage(cmd) {
+  if (!/^npx\b/.test(cmd)) return null;
+  const tokens = cmd.split(/\s+/).slice(1);
+  for (let i2 = 0; i2 < tokens.length; i2++) {
+    const t2 = tokens[i2];
+    if (t2 === "-p" || t2 === "--package") {
+      const v2 = tokens[i2 + 1];
+      if (v2 && !v2.startsWith("-")) return v2;
+      continue;
+    }
+    if (t2.startsWith("-p=") || t2.startsWith("--package=")) {
+      return t2.slice(t2.indexOf("=") + 1) || null;
+    }
+    if (t2.startsWith("-")) continue;
+    return t2;
+  }
+  return null;
+}
+function wouldNeedPackageJson(cmd) {
+  const scriptMatch = cmd.match(NPM_SCRIPT_PATTERN);
+  if (scriptMatch && scriptNameFromMatch(scriptMatch) !== null) return true;
+  const shorthandMatch = cmd.match(PKG_SHORTHAND_PATTERN);
+  if (shorthandMatch && !isManagerBuiltin(shorthandMatch[1], shorthandMatch[2])) return true;
+  return /^npx\b/.test(cmd) || PKG_DEPENDENT_TOOL_PATTERN.test(cmd);
+}
+function loadDeniedCommandPrefixes(projectRoot) {
+  const prefixes = [];
+  for (const rel of ["settings.json", "settings.local.json"]) {
+    let content;
+    try {
+      content = stripBom(fs7.readFileSync(path8.join(projectRoot, ".claude", rel), "utf-8"));
+    } catch {
+      continue;
+    }
+    const data = parse2(content, [], { allowTrailingComma: true });
+    const deny = data?.permissions?.deny;
+    if (!Array.isArray(deny)) continue;
+    for (const entry of deny) {
+      if (typeof entry !== "string") continue;
+      const inner = entry.replace(/^[A-Za-z]+\((.*)\)$/, "$1");
+      const prefix = inner.replace(/:?\*+$/, "").trim();
+      if (prefix) prefixes.push(prefix);
+    }
+  }
+  return prefixes;
+}
+function isDeniedCommand(cmd, deniedPrefixes) {
+  return deniedPrefixes.some((p2) => cmd === p2 || cmd.startsWith(`${p2} `));
+}
+function isProhibitedMention(lines, ref) {
+  const line = lines[ref.line - 1] ?? "";
+  const masked = maskCodeSpans(line, inlineCodeSpans(line));
+  const prefix = masked.slice(0, Math.max(0, ref.column - 1));
+  const clause = prefix.split(CLAUSE_TERMINATOR).pop() ?? "";
+  return PROHIBITION_TOKEN.test(clause);
+}
+async function checkCommands(file2, projectRoot) {
+  const issues = [];
+  const pkgJson = loadPackageJson(projectRoot);
+  const makefile = loadMakefile(projectRoot);
+  const deniedPrefixes = loadDeniedCommandPrefixes(projectRoot);
+  const contentLines = file2.content.split("\n");
+  if (!pkgJson) {
+    const skipped = file2.references.commands.find((ref) => wouldNeedPackageJson(ref.value));
+    if (skipped) {
+      issues.push({
+        severity: "info",
+        check: "commands",
+        ruleId: "commands/package-json-missing",
+        line: skipped.line,
+        message: "package.json missing or unparseable \u2014 command checks skipped",
+        suggestion: "Add a parseable package.json at the project root so script, npx, and tool references can be validated."
+      });
     }
   }
   issues.push(...checkUnknownSubcommand(file2, projectRoot, pkgJson));
@@ -24188,9 +24547,10 @@ async function checkCommands(file2, projectRoot) {
       };
       if (!(pkgName in allDeps)) {
         if (isDeniedCommand(cmd, deniedPrefixes)) continue;
-        const binPath = path7.join(projectRoot, "node_modules", ".bin", pkgName);
+        if (isProhibitedMention(contentLines, ref)) continue;
+        const binPath = path8.join(projectRoot, "node_modules", ".bin", pkgName);
         try {
-          fs6.accessSync(binPath);
+          fs7.accessSync(binPath);
         } catch {
           issues.push({
             severity: "warning",
@@ -24238,9 +24598,9 @@ async function checkCommands(file2, projectRoot) {
         ...pkgJson.optionalDependencies
       };
       if (!(pkgName in allDeps)) {
-        const binPath = path7.join(projectRoot, "node_modules", ".bin", tool);
+        const binPath = path8.join(projectRoot, "node_modules", ".bin", tool);
         try {
-          fs6.accessSync(binPath);
+          fs7.accessSync(binPath);
         } catch {
           issues.push({
             severity: "warning",
@@ -24284,7 +24644,7 @@ function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
 }
 function loadMakefile(projectRoot) {
   try {
-    return stripBom(fs6.readFileSync(path7.join(projectRoot, "Makefile"), "utf-8"));
+    return stripBom(fs7.readFileSync(path8.join(projectRoot, "Makefile"), "utf-8"));
   } catch {
     return null;
   }
@@ -24302,7 +24662,7 @@ function hasMakeTarget(makefile, target) {
   const pattern = new RegExp(`^${escaped}\\s*:(?!:?=)`, "m");
   return pattern.test(makefile);
 }
-var NPM_SCRIPT_PATTERN, MAKE_PATTERN, PM_BUILTIN_SUBCOMMANDS, PM_MANAGER_BUILTINS, PKG_DEPENDENT_TOOL_PATTERN, BIN_TO_PACKAGE, PKG_SHORTHAND_PATTERN;
+var NPM_SCRIPT_PATTERN, MAKE_PATTERN, PM_BUILTIN_SUBCOMMANDS, PM_MANAGER_BUILTINS, PKG_DEPENDENT_TOOL_PATTERN, BIN_TO_PACKAGE, PKG_SHORTHAND_PATTERN, PROHIBITION_TOKEN, CLAUSE_TERMINATOR;
 var init_commands = __esm({
   "src/core/checks/commands.ts"() {
     "use strict";
@@ -24311,6 +24671,7 @@ var init_commands = __esm({
     init_fs();
     init_exit_status();
     init_cli_subcommands();
+    init_tier_tokens();
     NPM_SCRIPT_PATTERN = /^(?:npm\s+run|(pnpm|yarn|bun)(?:\s+(run))?)\s+(\S+)/;
     MAKE_PATTERN = /^make\s+\S/;
     PM_BUILTIN_SUBCOMMANDS = /* @__PURE__ */ new Set([
@@ -24380,17 +24741,19 @@ var init_commands = __esm({
       tsc: "typescript"
     };
     PKG_SHORTHAND_PATTERN = /^(npm|pnpm|yarn|bun)\s+(test|start|build|dev|lint|format|check|typecheck|clean|serve|preview|e2e)\b/;
+    PROHIBITION_TOKEN = /\b(?:never|don['’]?t|do\s+not|must\s+not|avoid)\b/i;
+    CLAUSE_TERMINATOR = /[.!?;—]|\s--(?=\s|$)/;
   }
 });
 
 // src/core/checks/staleness.ts
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 async function checkStaleness(file2, projectRoot) {
   const issues = [];
   if (!await isGitRepo(projectRoot)) {
     return issues;
   }
-  const relativePath = path8.relative(projectRoot, file2.filePath).replace(/\\/g, "/");
+  const relativePath = path9.relative(projectRoot, file2.filePath).replace(/\\/g, "/");
   const lastModified = await getFileLastModified(projectRoot, relativePath);
   if (!lastModified || isNaN(lastModified.getTime())) {
     return issues;
@@ -24506,322 +24869,6 @@ var init_suppressions = __esm({
   }
 });
 
-// src/core/checks/tokens.ts
-function resolveTokenThresholds(overrides) {
-  if (!overrides) return DEFAULT_TOKEN_THRESHOLDS;
-  const merged = { ...DEFAULT_TOKEN_THRESHOLDS, ...overrides };
-  if (merged.info >= merged.warning || merged.warning >= merged.error) {
-    console.error(
-      `Warning: token thresholds should satisfy info < warning < error (got ${merged.info}, ${merged.warning}, ${merged.error}) \u2014 using defaults`
-    );
-    return DEFAULT_TOKEN_THRESHOLDS;
-  }
-  return merged;
-}
-async function checkTokens(file2, _projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
-  const issues = [];
-  const tokens = file2.totalTokens;
-  if (tokens >= thresholds.error) {
-    issues.push({
-      severity: "error",
-      check: "tokens",
-      ruleId: "tokens/excessive",
-      line: 1,
-      message: `${tokens.toLocaleString()} tokens \u2014 consumes significant context window space`,
-      suggestion: "Consider splitting into focused sections or removing redundant content."
-    });
-  } else if (tokens >= thresholds.warning) {
-    issues.push({
-      severity: "warning",
-      check: "tokens",
-      ruleId: "tokens/large",
-      line: 1,
-      message: `${tokens.toLocaleString()} tokens \u2014 large context file`,
-      suggestion: "Consider trimming \u2014 research shows diminishing returns past ~300 lines."
-    });
-  } else if (tokens >= thresholds.info) {
-    issues.push({
-      severity: "info",
-      check: "tokens",
-      ruleId: "tokens/info",
-      line: 1,
-      message: `Uses ~${tokens.toLocaleString()} tokens per session`
-    });
-  }
-  return issues;
-}
-function checkAggregateTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
-  const total = files.reduce((sum, f) => sum + f.tokens, 0);
-  if (total >= thresholds.aggregate && files.length > 1) {
-    return {
-      severity: "warning",
-      check: "tokens",
-      ruleId: "tokens/aggregate",
-      line: 0,
-      message: `${files.length} context files consume ${total.toLocaleString()} tokens combined`,
-      suggestion: "Consider consolidating or trimming to reduce per-session context cost."
-    };
-  }
-  return null;
-}
-var DEFAULT_TOKEN_THRESHOLDS;
-var init_tokens2 = __esm({
-  "src/core/checks/tokens.ts"() {
-    "use strict";
-    init_define_WEB_FIRST_SEGMENTS();
-    DEFAULT_TOKEN_THRESHOLDS = {
-      info: 1e3,
-      warning: 3e3,
-      error: 8e3,
-      aggregate: 5e3,
-      tierBreakdown: 1e3,
-      tierAggregate: 4e3
-    };
-  }
-});
-
-// src/core/checks/tier-tokens.ts
-import * as fs7 from "node:fs";
-import * as os2 from "node:os";
-import * as path9 from "node:path";
-function hasFrontmatterList(content, field) {
-  const lines = content.split("\n");
-  if (lines[0]?.trim() !== "---") return false;
-  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
-  for (let i2 = 1; i2 < lines.length; i2++) {
-    const line = lines[i2];
-    if (line.trim() === "---") return false;
-    const match = line.match(fieldPattern);
-    if (match) {
-      const val = match[1].trim();
-      if (val && val !== "[]") return true;
-      for (let j3 = i2 + 1; j3 < lines.length; j3++) {
-        const next = lines[j3];
-        if (next.trim() === "---") return false;
-        if (next.trim() === "") continue;
-        if (next.trim().startsWith("- ")) return true;
-        break;
-      }
-    }
-  }
-  return false;
-}
-function frontmatterScalar(content, field) {
-  const lines = content.split("\n");
-  if (lines[0]?.trim() !== "---") return null;
-  const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.*)$`);
-  for (let i2 = 1; i2 < lines.length; i2++) {
-    if (lines[i2].trim() === "---") return null;
-    const match = lines[i2].match(fieldPattern);
-    if (match) return match[1].trim().replace(/^['"]|['"]$/g, "") || null;
-  }
-  return null;
-}
-function isAlwaysLoaded(file2) {
-  const rel = file2.relativePath.replace(/\\/g, "/");
-  if (rel.endsWith(".mdc")) return false;
-  if (rel.startsWith(".github/instructions/")) return false;
-  if (rel.includes("/rules/")) {
-    if (hasFrontmatterList(file2.content, "paths")) return false;
-    if (hasFrontmatterList(file2.content, "globs")) return false;
-    if (rel.includes(".windsurf/rules/")) {
-      const trigger = frontmatterScalar(file2.content, "trigger");
-      if (trigger && trigger.toLowerCase() !== "always_on") return false;
-    }
-    return true;
-  }
-  const basename4 = rel.split("/").pop() ?? "";
-  for (const name of ALWAYS_LOADED_NAMES) {
-    if (name.includes("/")) {
-      if (rel === name || rel.endsWith("/" + name)) return true;
-    } else if (basename4 === name) {
-      return true;
-    }
-  }
-  return false;
-}
-function computeSectionCosts(file2) {
-  if (file2.sections.length === 0) return [];
-  const hasH2 = file2.sections.some((s) => s.level === 2);
-  const topLevel = hasH2 ? 2 : 1;
-  const lines = file2.content.split("\n");
-  return file2.sections.filter((s) => s.level === topLevel).map((s) => {
-    const body = lines.slice(s.startLine - 1, s.endLine).join("\n");
-    return { title: s.title, line: s.startLine, tokens: countTokens(body) };
-  }).sort((a, b2) => b2.tokens - a.tokens);
-}
-function fingerprintFiles(paths) {
-  return paths.map((p2) => {
-    try {
-      const st2 = fs7.statSync(p2);
-      return `${st2.mtimeMs}:${st2.size}`;
-    } catch {
-      return "absent";
-    }
-  }).join("|");
-}
-function loadSettingsSources(projectRoot, includeGlobal) {
-  const candidates = [
-    path9.join(projectRoot, ".claude", "settings.json"),
-    path9.join(projectRoot, ".claude", "settings.local.json")
-  ];
-  if (includeGlobal) {
-    candidates.push(path9.join(os2.homedir(), ".claude", "settings.json"));
-  }
-  const fingerprint = fingerprintFiles(candidates);
-  if (settingsCache?.root === projectRoot && settingsCache.includeGlobal === includeGlobal && settingsCache.fingerprint === fingerprint) {
-    return settingsCache.data;
-  }
-  const sources = [];
-  for (const p2 of candidates) {
-    let content;
-    try {
-      content = stripBom(fs7.readFileSync(p2, "utf-8"));
-    } catch {
-      continue;
-    }
-    const errors = [];
-    const data = parse2(content, errors, { allowTrailingComma: true });
-    if (errors.length > 0) {
-      console.warn(
-        `ctxlint: could not parse ${p2}: ${printParseErrorCode(errors[0].error)} at offset ${errors[0].offset}`
-      );
-      continue;
-    }
-    if (!data || typeof data !== "object") continue;
-    sources.push(data);
-  }
-  settingsCache = { root: projectRoot, includeGlobal, fingerprint, data: sources };
-  return sources;
-}
-function canonicalizeCommand(backticked) {
-  const beforeFlags = backticked.trim().split(/\s+--?/, 1)[0];
-  return beforeFlags.replace(/\s+/g, " ");
-}
-function buildCommandPattern(cmd) {
-  const tokens = cmd.split(/\s+/).filter(Boolean);
-  const escaped = tokens.map((t2) => t2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-  if (tokens.length === 1) {
-    return new RegExp(`(?<![A-Za-z0-9_\\-])${escaped[0]}(?![A-Za-z0-9_\\-])`, "i");
-  }
-  const body = escaped.join("[\\s\\-_]+");
-  return new RegExp(`(?<![A-Za-z0-9])${body}(?![A-Za-z0-9])`, "i");
-}
-function commandIsEnforced(cmd, settings) {
-  const pattern = buildCommandPattern(cmd);
-  for (const s of settings) {
-    for (const entry of [...s.permissions?.deny ?? [], ...s.permissions?.ask ?? []]) {
-      if (pattern.test(entry)) return true;
-    }
-    for (const h2 of [...s.hooks?.PreToolUse ?? [], ...s.hooks?.Stop ?? []]) {
-      if (pattern.test(h2.matcher || "")) return true;
-      for (const sub of h2.hooks ?? []) {
-        if (pattern.test(sub.command || "")) return true;
-      }
-    }
-  }
-  return false;
-}
-function checkHardEnforcement(file2, settings) {
-  const issues = [];
-  const lines = file2.content.split("\n");
-  for (let i2 = 0; i2 < lines.length; i2++) {
-    const line = lines[i2];
-    const match = line.match(INVIOLABLE_WITH_COMMAND);
-    if (!match) continue;
-    const cmd = canonicalizeCommand(match[2]);
-    if (!cmd) continue;
-    if (commandIsEnforced(cmd, settings)) continue;
-    const suggestion = match[1].toUpperCase() === "ALWAYS" ? `Rules in always-loaded files are advisory. For \`${cmd}\`, add a hook in .claude/settings.json (e.g. a PreToolUse or Stop hook that runs or verifies \`${cmd}\`) so the requirement doesn't depend on the agent remembering.` : `Rules in always-loaded files are advisory. For \`${cmd}\`, add a PreToolUse hook (or permissions.deny entry) in .claude/settings.json so the command is physically blocked.`;
-    issues.push({
-      severity: "info",
-      check: "tier-tokens",
-      ruleId: "tier-tokens/hard-enforcement-missing",
-      line: i2 + 1,
-      message: `Inviolable framing ("${line.trim().slice(0, 80)}") without a hook to back it up`,
-      suggestion
-    });
-  }
-  return issues;
-}
-async function checkTierTokens(file2, projectRoot, thresholds = DEFAULT_TOKEN_THRESHOLDS, includeGlobal = false) {
-  if (!isAlwaysLoaded(file2)) return [];
-  const issues = [];
-  const threshold = thresholds.tierBreakdown;
-  if (file2.totalTokens >= threshold) {
-    const sectionCosts = computeSectionCosts(file2);
-    if (sectionCosts.length > 0) {
-      const top = sectionCosts.slice(0, TOP_SECTIONS_TO_REPORT);
-      const heaviest = top[0];
-      const pct = Math.round(heaviest.tokens / file2.totalTokens * 100);
-      const detail = top.map((s) => `  - "${s.title}" (L${s.line}): ~${s.tokens.toLocaleString()} tokens`).join("\n");
-      issues.push({
-        severity: "info",
-        check: "tier-tokens",
-        ruleId: "tier-tokens/section-breakdown",
-        line: heaviest.line,
-        message: `${file2.totalTokens.toLocaleString()} tokens loaded every session \u2014 heaviest top-level section${top.length === 1 ? "" : "s"}:`,
-        detail,
-        suggestion: `"${heaviest.title}" is ~${heaviest.tokens.toLocaleString()} tokens (${pct}% of file). Consider demoting to an on-demand tier (skill, subagent, or memory) so it loads only when relevant.`
-      });
-    }
-  }
-  const settings = loadSettingsSources(projectRoot, includeGlobal);
-  issues.push(...checkHardEnforcement(file2, settings));
-  return issues;
-}
-function checkAggregateTierTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
-  const alwaysLoaded = files.filter(isAlwaysLoaded);
-  if (alwaysLoaded.length < 2) return null;
-  const total = alwaysLoaded.reduce((sum, f) => sum + f.totalTokens, 0);
-  const threshold = thresholds.tierAggregate;
-  if (total < threshold) return null;
-  const breakdown = alwaysLoaded.slice().sort((a, b2) => b2.totalTokens - a.totalTokens).slice(0, 5).map((f) => `  - ${f.relativePath}: ~${f.totalTokens.toLocaleString()} tokens`).join("\n");
-  return {
-    severity: "warning",
-    check: "tier-tokens",
-    ruleId: "tier-tokens/aggregate",
-    line: 0,
-    message: `${alwaysLoaded.length} always-loaded files total ${total.toLocaleString()} tokens \u2014 loaded every session`,
-    detail: breakdown,
-    suggestion: "Consider moving the largest files or their heaviest sections to on-demand tiers (skills, subagents, memory)."
-  };
-}
-var ALWAYS_LOADED_NAMES, TOP_SECTIONS_TO_REPORT, INVIOLABLE_WITH_COMMAND, settingsCache;
-var init_tier_tokens = __esm({
-  "src/core/checks/tier-tokens.ts"() {
-    "use strict";
-    init_define_WEB_FIRST_SEGMENTS();
-    init_main3();
-    init_tokens();
-    init_fs();
-    init_tokens2();
-    ALWAYS_LOADED_NAMES = [
-      "CLAUDE.md",
-      "CLAUDE.local.md",
-      "AGENTS.md",
-      "AGENTS.override.md",
-      "AGENT.md",
-      "GEMINI.md",
-      ".cursorrules",
-      ".windsurfrules",
-      ".clinerules",
-      ".aiderules",
-      ".continuerules",
-      ".rules",
-      ".goosehints",
-      "replit.md",
-      ".github/copilot-instructions.md",
-      ".junie/guidelines.md",
-      ".junie/AGENTS.md",
-      ".goose/instructions.md"
-    ];
-    TOP_SECTIONS_TO_REPORT = 3;
-    INVIOLABLE_WITH_COMMAND = /\b(NEVER|ALWAYS|DON'?T|DO NOT|MUST NOT)\b[^.!?`]{0,80}`([^`]+)`/i;
-    settingsCache = null;
-  }
-});
-
 // src/utils/similarity.ts
 function jaccardSimilarityFromSets(a, b2, opts = {}) {
   const bothEmptyIsIdentical = opts.bothEmptyIsIdentical ?? false;
@@ -28968,7 +29015,7 @@ import { readFileSync as readFileSync8 } from "node:fs";
 import { resolve as resolve15, dirname as dirname7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function loadVersion() {
-  if (true) return "0.21.0";
+  if (true) return "0.23.0";
   try {
     const __dir = dirname7(fileURLToPath2(import.meta.url));
     const pkgPath = resolve15(__dir, "../package.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "mcpName": "io.github.YawLabs/ctxlint",
   "description": "Lint your AI agent context files, MCP server configs, and session data against your actual codebase",
   "bin": {
@@ -13,6 +13,7 @@
   "scripts": {
     "build": "node build.mjs",
     "dev": "node build.mjs",
+    "prepublishOnly": "node build.mjs",
     "generate": "node scripts/generate-catalog-prose.mjs",
     "generate:check": "node scripts/generate-catalog-prose.mjs --check",
     "pretest": "node build.mjs",