@yawlabs/ctxlint 0.22.0 → 0.24.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.24.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/dist/index.js

@@ -24050,6 +24050,80 @@ var init_cli_subcommands = __esm({
   }
 });
 
+// src/utils/markdown.ts
+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 nonProseLineMask(lines) {
+  return classifyLines(lines).map((c3) => c3.fence || c3.comment);
+}
+function htmlCommentLineMask(lines) {
+  return classifyLines(lines).map((c3) => c3.comment);
+}
+function classifyLines(lines) {
+  const out = lines.map(() => ({ fence: false, comment: false }));
+  let inFence = false;
+  let inHtmlComment = false;
+  for (let i2 = 0; i2 < lines.length; i2++) {
+    const raw = lines[i2];
+    const trimmed2 = raw.trimStart();
+    if (trimmed2.startsWith("```")) {
+      out[i2].fence = true;
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      out[i2].fence = true;
+      continue;
+    }
+    const probe = maskCodeSpans(trimmed2, inlineCodeSpans(trimmed2));
+    if (inHtmlComment) {
+      out[i2].comment = true;
+      if (probe.includes("-->")) inHtmlComment = false;
+      continue;
+    }
+    if (HTML_COMMENT.test(probe.replace(HTML_COMMENT_PAIR, ""))) {
+      out[i2].comment = true;
+      inHtmlComment = true;
+    }
+  }
+  return out;
+}
+function stripInlineHtmlComments(line) {
+  return line.replace(HTML_COMMENT_PAIR, (m) => "#".repeat(m.length));
+}
+function htmlCommentSpans(line) {
+  const re2 = /<!--[\s\S]*?-->/g;
+  const spans = [];
+  let m;
+  while ((m = re2.exec(line)) !== null) {
+    spans.push({ start: m.index, end: m.index + m[0].length });
+  }
+  return spans;
+}
+var HTML_COMMENT_PAIR, HTML_COMMENT;
+var init_markdown = __esm({
+  "src/utils/markdown.ts"() {
+    "use strict";
+    init_define_WEB_FIRST_SEGMENTS();
+    HTML_COMMENT_PAIR = /<!--[\s\S]*?-->/g;
+    HTML_COMMENT = /<!--/;
+  }
+});
+
 // src/core/checks/commands.ts
 import * as fs6 from "node:fs";
 import * as path7 from "node:path";
@@ -24112,13 +24186,48 @@ function loadDeniedCommandPrefixes(projectRoot) {
 function isDeniedCommand(cmd, deniedPrefixes) {
   return deniedPrefixes.some((p2) => cmd === p2 || cmd.startsWith(`${p2} `));
 }
+function narrowAtContrastComma(clause) {
+  const idx = clause.lastIndexOf(",");
+  if (idx === -1) return clause;
+  const tail = clause.slice(idx + 1);
+  return RECOMMENDATION_VERB.test(tail) ? tail : clause;
+}
+function isProhibitedAt(rawLine, offset) {
+  const line = stripInlineHtmlComments(rawLine);
+  const masked = maskCodeSpans(line, inlineCodeSpans(line));
+  const prefix = masked.slice(0, Math.max(0, offset));
+  const clause = narrowAtContrastComma(prefix.split(CLAUSE_TERMINATOR).pop() ?? "");
+  return PROHIBITION_TOKEN.test(clause);
+}
+function isProhibitedRef(lines, ref) {
+  return isProhibitedAt(lines[ref.line - 1] ?? "", ref.column - 1);
+}
+function isProhibitedInvocation(lines, inv) {
+  const line = lines[inv.line - 1] ?? "";
+  for (const span of inlineCodeSpans(line)) {
+    if (span.content.trim() === inv.cmd) return isProhibitedAt(line, span.start);
+  }
+  const idx = line.indexOf(inv.cmd);
+  return idx < 0 ? false : isProhibitedAt(line, idx);
+}
 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");
+  const commentLines = htmlCommentLineMask(contentLines);
+  const inHtmlComment = (line, column) => {
+    if (commentLines[line - 1] === true) return true;
+    const offset = column - 1;
+    return htmlCommentSpans(contentLines[line - 1] ?? "").some(
+      (s) => offset >= s.start && offset < s.end
+    );
+  };
   if (!pkgJson) {
-    const skipped = file2.references.commands.find((ref) => wouldNeedPackageJson(ref.value));
+    const skipped = file2.references.commands.find(
+      (ref) => wouldNeedPackageJson(ref.value) && !inHtmlComment(ref.line, ref.column) && !isDeniedCommand(ref.value, deniedPrefixes) && !isProhibitedRef(contentLines, ref)
+    );
     if (skipped) {
       issues.push({
         severity: "info",
@@ -24130,8 +24239,11 @@ async function checkCommands(file2, projectRoot) {
       });
     }
   }
-  issues.push(...checkUnknownSubcommand(file2, projectRoot, pkgJson));
+  issues.push(
+    ...checkUnknownSubcommand(file2, projectRoot, pkgJson, deniedPrefixes, contentLines)
+  );
   for (const ref of file2.references.commands) {
+    if (inHtmlComment(ref.line, ref.column)) continue;
     const cmd = ref.value;
     const masked = analyzeMaskedExitStatus(cmd, pkgJson?.scripts);
     if (masked && !pipefailInScope(file2.content, ref.line)) {
@@ -24145,6 +24257,7 @@ async function checkCommands(file2, projectRoot) {
         suggestion: "Add `set -o pipefail` before the pipeline, drop the filter, or read `${PIPESTATUS[0]}` instead of `$?`."
       });
     }
+    if (isDeniedCommand(cmd, deniedPrefixes) || isProhibitedRef(contentLines, ref)) continue;
     const scriptMatch = cmd.match(NPM_SCRIPT_PATTERN);
     if (scriptMatch && pkgJson) {
       const scriptName = scriptNameFromMatch(scriptMatch);
@@ -24187,7 +24300,6 @@ async function checkCommands(file2, projectRoot) {
         ...pkgJson.optionalDependencies
       };
       if (!(pkgName in allDeps)) {
-        if (isDeniedCommand(cmd, deniedPrefixes)) continue;
         const binPath = path7.join(projectRoot, "node_modules", ".bin", pkgName);
         try {
           fs6.accessSync(binPath);
@@ -24255,7 +24367,7 @@ async function checkCommands(file2, projectRoot) {
   }
   return issues;
 }
-function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
+function checkUnknownSubcommand(file2, projectRoot, pkgJson, deniedPrefixes, contentLines) {
   const bins = ownedBins(pkgJson);
   if (bins.length === 0) return [];
   const invocations = findBinInvocations(file2.content, new Set(bins.map((b2) => b2.name)));
@@ -24263,6 +24375,8 @@ function checkUnknownSubcommand(file2, projectRoot, pkgJson) {
   const resolved = /* @__PURE__ */ new Map();
   const issues = [];
   for (const inv of invocations) {
+    if (isDeniedCommand(inv.cmd, deniedPrefixes)) continue;
+    if (isProhibitedInvocation(contentLines, inv)) continue;
     if (!resolved.has(inv.bin)) {
       const bin = bins.find((b2) => b2.name === inv.bin);
       resolved.set(inv.bin, bin ? knownSubcommands(projectRoot, bin.entry) : null);
@@ -24302,7 +24416,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, RECOMMENDATION_VERB;
 var init_commands = __esm({
   "src/core/checks/commands.ts"() {
     "use strict";
@@ -24311,6 +24425,7 @@ var init_commands = __esm({
     init_fs();
     init_exit_status();
     init_cli_subcommands();
+    init_markdown();
     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,6 +24495,9 @@ 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|$)/;
+    RECOMMENDATION_VERB = /\b(?:run|use|call|invoke|execute|prefer|deploy|install)\b/i;
   }
 });
 
@@ -24650,6 +24768,24 @@ function computeSectionCosts(file2) {
     return { title: s.title, line: s.startLine, tokens: countTokens(body) };
   }).sort((a, b2) => b2.tokens - a.tokens);
 }
+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 fingerprintFiles(paths) {
   return paths.map((p2) => {
     try {
@@ -24725,14 +24861,16 @@ function commandIsEnforced(cmd, settings) {
 function checkHardEnforcement(file2, settings) {
   const issues = [];
   const lines = file2.content.split("\n");
+  const nonProse = nonProseLineMask(lines);
   for (let i2 = 0; i2 < lines.length; i2++) {
-    const line = lines[i2];
-    const match = line.match(INVIOLABLE_WITH_COMMAND);
+    if (nonProse[i2]) continue;
+    const line = stripInlineHtmlComments(lines[i2]);
+    const match = findInviolableCommand(line);
     if (!match) continue;
-    const cmd = canonicalizeCommand(match[2]);
+    const cmd = canonicalizeCommand(match.command);
     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.`;
+    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",
@@ -24787,7 +24925,7 @@ function checkAggregateTierTokens(files, thresholds = DEFAULT_TOKEN_THRESHOLDS)
     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 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";
@@ -24795,6 +24933,7 @@ var init_tier_tokens = __esm({
     init_main3();
     init_tokens();
     init_fs();
+    init_markdown();
     init_tokens2();
     ALWAYS_LOADED_NAMES = [
       "CLAUDE.md",
@@ -24817,7 +24956,8 @@ var init_tier_tokens = __esm({
       ".goose/instructions.md"
     ];
     TOP_SECTIONS_TO_REPORT = 3;
-    INVIOLABLE_WITH_COMMAND = /\b(NEVER|ALWAYS|DON'?T|DO NOT|MUST NOT)\b[^.!?`]{0,80}`([^`]+)`/i;
+    FRAMING_TOKEN = /(?<![\w'.-])(never|always|don'?t|do\s+not|must\s+not)(?![\w'.-])/gi;
+    FRAMING_COMMAND_GAP = 80;
     settingsCache = null;
   }
 });
@@ -28968,7 +29108,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.24.0";
   try {
     const __dir = dirname7(fileURLToPath2(import.meta.url));
     const pkgPath = resolve15(__dir, "../package.json");
@@ -70060,6 +70200,13 @@ __export(cli_exports, {
 });
 import * as fs15 from "node:fs";
 import * as path20 from "node:path";
+function existsAsDirectory(p2) {
+  try {
+    return fs15.statSync(p2).isDirectory();
+  } catch {
+    return false;
+  }
+}
 function validateCheckNames(names, source) {
   const invalid = names.filter((n7) => n7 && !VALID_CHECKS.has(n7));
   if (invalid.length > 0) {
@@ -70083,6 +70230,12 @@ async function runCli() {
     false
   ).option("--no-ignore-file", "Disable .ctxlintignore suppression (see all findings)").option("--watch", "Re-lint on context file changes", false).action(async (projectPath, opts) => {
     const resolvedPath = path20.resolve(projectPath);
+    if (!existsAsDirectory(resolvedPath)) {
+      console.error(
+        `Error: ${resolvedPath} is not an existing directory. Check the path argument.`
+      );
+      process.exit(2);
+    }
     const { config: config2, options, activeChecks } = resolveSession(resolvedPath, opts);
     const spinner = options.format === "text" && !options.quiet ? ora("Scanning for context files...").start() : void 0;
     try {
@@ -70401,7 +70554,7 @@ function resolveDepth(raw) {
 }
 function resolveSession(resolvedPath, opts, throwOnConfigError = false) {
   const configPath = opts.config ? path20.resolve(opts.config) : void 0;
-  const config2 = configPath ? loadConfigFromPath(configPath, throwOnConfigError) : loadConfig(resolvedPath);
+  const config2 = configPath ? loadConfigFromPath(configPath, throwOnConfigError) : loadDiscoveredConfig(resolvedPath, throwOnConfigError);
   const mcpGlobal = opts.mcpGlobal || config2?.mcpGlobal || false;
   const mcpOnly = opts.mcpOnly || config2?.mcpOnly || false;
   const mcpFlag = opts.mcp || mcpGlobal || mcpOnly || config2?.mcp || false;
@@ -70469,6 +70622,16 @@ function resolveSession(resolvedPath, opts, throwOnConfigError = false) {
   const activeChecks = options.checks.filter((c3) => !options.ignore.includes(c3));
   return { config: config2, options, activeChecks };
 }
+function loadDiscoveredConfig(resolvedPath, throwOnError = false) {
+  try {
+    return loadConfig(resolvedPath);
+  } catch (err) {
+    if (throwOnError) throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${detail}`);
+    process.exit(2);
+  }
+}
 function loadConfigFromPath(configPath, throwOnError = false) {
   try {
     return loadConfigFromExplicitPath(configPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.22.0",
+  "version": "0.24.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",