contextpruner 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,8 @@ actually in your tree and reports:
 - **Dead** — rules that match nothing,
 - **Drift** — rules in one config but not another,
 - **Conflict** — rules that contradict each other, including an enforced rule
-  that hard-blocks a file you pinned Keep or Skim.
+  that hard-blocks a file you pinned Keep or Skim, or a path you declared
+  `keep:` in `.contextpruner`.
 
 It exits non-zero when it finds issues, so it drops straight into CI or a
 pre-commit hook.
@@ -43,6 +44,13 @@ contextpruner lint [--config <path>]... [--fix] [--json]
   safely.
 - `--json` — emit the full report as JSON.
 
+If the repo root has a committed `.contextpruner` file, its
+`keep: <path-or-glob>` lines (enforcement exceptions — paths that must stay
+readable by agents, even untracked ones like docs inside `node_modules/`)
+drop any enforced rule covering them from the expected rule set, exactly as
+the generate automation does — so lint, `--fix`, and generation always agree.
+Unrecognized lines are reported as a warning and ignored.
+
 **Exit codes:** `0` clean · `1` issues found · `2` usage/auth error.
 
 ## In CI

package/dist/index.js

@@ -63,6 +63,8 @@ var CONTEXT_SLICE_FACTOR = 0.05;
 var DEFAULT_CONTEXT_WINDOW_TOKENS = 1e6;
 var MONTHLY_SAVINGS_CAP_USD = 200;
 var MAX_MANIFEST_FILES = 2e4;
+var MAX_OVERRIDE_DECLARATIONS = 200;
+var MAX_PATH_LENGTH = 1024;
 var OVERSIZED_FILE_BYTES = 1048576;
 
 // ../../lib/engine/rules.ts
@@ -574,6 +576,37 @@ function generateMarkdownRules(filename, input) {
   return lines.join("\n");
 }
 
+// ../../lib/engine/overridesFile.ts
+var OVERRIDES_FILENAME = ".contextpruner";
+var KEEP_LINE = /^keep:\s*(.+)$/;
+function isValidDeclaration(declaration) {
+  return declaration.length > 0 && declaration.length <= MAX_PATH_LENGTH && !declaration.includes("\0") && !declaration.includes("\\") && !declaration.startsWith("/") && declaration.split("/").every((seg) => seg !== "..");
+}
+function parseOverridesFile(source) {
+  const keep = [];
+  const seen = /* @__PURE__ */ new Set();
+  const unknownLines = [];
+  for (const raw of source.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const match = KEEP_LINE.exec(line);
+    const declaration = match?.[1]?.trim();
+    if (declaration !== void 0 && isValidDeclaration(declaration)) {
+      if (!seen.has(declaration)) {
+        seen.add(declaration);
+        if (keep.length < MAX_OVERRIDE_DECLARATIONS) keep.push(declaration);
+      }
+    } else {
+      unknownLines.push(line);
+    }
+  }
+  return { keep, unknownLines };
+}
+function representativePathsFor(declaration) {
+  const literal = declaration.replace(/\*+/g, "cpx");
+  return declaration.includes("*") ? [literal] : [literal, `${literal}/cpx`];
+}
+
 // ../../lib/engine/parseConfig.ts
 var GLOB_BULLET = /^- `(.+)`$/;
 var OVERRIDE_BULLET = /^- (Keep|Skim|Prune) \([^)]*\): `(.+)`$/;
@@ -753,7 +786,13 @@ function computeSavings(bytesTotal, bytesKept, options = {}) {
 // ../../lib/engine/prune.ts
 var MAX_PRIORITY_GLOBS = 5;
 function prune(files, options = {}) {
-  const overrides = options.verdictOverrides ?? {};
+  const declarations = options.keepDeclarations ?? [];
+  const overrides = {
+    ...Object.fromEntries(
+      declarations.filter((declaration) => !declaration.includes("*")).map((path) => [path, "KEEP"])
+    ),
+    ...options.verdictOverrides
+  };
   const classified = files.map((file) => {
     const base = classify(file);
     const pinned = Object.hasOwn(overrides, file.path) ? overrides[file.path] : void 0;
@@ -816,7 +855,15 @@ function prune(files, options = {}) {
     windowClamped: pinnedSavings.windowClamped
   };
   for (const glob of options.extraExcludeGlobs ?? []) excludeGlobs.add(glob);
-  const enforced = deriveEnforcedRules(classified);
+  const pinDemoted = deriveEnforcedRules(classified);
+  const declDemoted = demoteEnforcedGlobs(
+    pinDemoted.globs,
+    declarations.flatMap(representativePathsFor)
+  );
+  const enforced = {
+    globs: declDemoted.globs,
+    demoted: [...pinDemoted.demoted, ...declDemoted.demoted]
+  };
   const priorityGlobs = [...keptBytesByDir.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, MAX_PRIORITY_GLOBS).map(([dir]) => `${dir}/**`);
   const generatorInput = {
     generatedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
@@ -914,11 +961,14 @@ var IGNORE_GENERATOR_BY_TITLE = {
   ".codeiumignore": generateCodeiumIgnore
 };
 var IGNORE_TITLE_RE = /^# (\.[a-z]+ignore) — enforced AI context rules/m;
-function buildFixedEnforcedConfig(files, userConfig, format, pins = { keep: [], skim: [] }) {
+function buildFixedEnforcedConfig(files, userConfig, format, pins = { keep: [], skim: [] }, keepDeclarations = []) {
   const classified = files.map(classify);
   const enforcedGlobs = demoteEnforcedGlobs(
     deriveEnforcedRules(classified).globs,
-    effectivePinnedPaths(classified, pins)
+    [
+      ...effectivePinnedPaths(classified, pins),
+      ...keepDeclarations.flatMap(representativePathsFor)
+    ]
   ).globs;
   if (format === "claudeSettings") {
     if (!parseEnforcedConfig(userConfig, "claudeSettings").recognized) {
@@ -983,10 +1033,16 @@ function dialectLine(glob, format) {
 function expectedEnforcedGlobs(classified, pinnedPaths) {
   return demoteEnforcedGlobs(deriveEnforcedRules(classified).globs, pinnedPaths).globs;
 }
-function enforcedFindings(classified, paths, enforced, pinnedPaths) {
+function enforcedFindings(classified, paths, enforced, pinnedPaths, keepDeclarations) {
   const findings = [];
-  const expected = expectedEnforcedGlobs(classified, pinnedPaths);
+  const expected = expectedEnforcedGlobs(classified, [
+    ...pinnedPaths,
+    ...keepDeclarations.flatMap(representativePathsFor)
+  ]);
   const expectedSet = new Set(expected);
+  const declarationReps = keepDeclarations.map(
+    (declaration) => [declaration, representativePathsFor(declaration)]
+  );
   for (const config of enforced) {
     const have = new Set(config.engineGlobs);
     for (const glob of expected) {
@@ -1023,6 +1079,17 @@ function enforcedFindings(classified, paths, enforced, pinnedPaths) {
           });
         }
       }
+      for (const [declaration, representatives] of declarationReps) {
+        if (representatives.some(matches)) {
+          findings.push({
+            kind: "conflict",
+            severity: "high",
+            glob,
+            path: declaration,
+            message: `\`${declaration}\` is declared keep in ${OVERRIDES_FILENAME} but ${config.name} still hard-blocks it via \`${dialectLine(glob, config.format)}\``
+          });
+        }
+      }
     }
     for (const line of config.foreignLines) {
       findings.push({
@@ -1101,14 +1168,25 @@ function reconcile(files, configs, options = {}) {
     keep: keepPins,
     skim: skimPins
   });
+  const declarations = options.keepDeclarations ?? [];
+  const demotionPaths = [
+    ...pinnedPaths,
+    ...declarations.flatMap(representativePathsFor)
+  ];
   if ((primary.format ?? "markdown") !== "markdown") {
     const parsedPrimary = parseEnforcedConfig(
       primary.source,
       primary.format
     );
     if (!parsedPrimary.recognized) return empty2;
-    const findings2 = enforcedFindings(classified, paths, enforced, pinnedPaths);
-    const expected = expectedEnforcedGlobs(classified, pinnedPaths);
+    const findings2 = enforcedFindings(
+      classified,
+      paths,
+      enforced,
+      pinnedPaths,
+      declarations
+    );
+    const expected = expectedEnforcedGlobs(classified, demotionPaths);
     const have = new Set(parsedPrimary.engineGlobs);
     const present = expected.filter((glob) => have.has(glob)).length;
     const coveragePct2 = expected.length === 0 ? 100 : Math.floor(present / expected.length * 100);
@@ -1241,7 +1319,9 @@ function reconcile(files, configs, options = {}) {
       }
     }
   }
-  findings.push(...enforcedFindings(classified, paths, enforced, pinnedPaths));
+  findings.push(
+    ...enforcedFindings(classified, paths, enforced, pinnedPaths, declarations)
+  );
   let junkBytes = 0;
   let prunedBytes = 0;
   for (const file of classified) {
@@ -1454,6 +1534,11 @@ async function runLint(deps) {
   if (files.length === 0) {
     return { text: "No tracked files found.", exitCode: 2, channel: "stderr" };
   }
+  const overridesSource = deps.readConfig(OVERRIDES_FILENAME);
+  const parsedOverrides = parseOverridesFile(overridesSource ?? "");
+  const overridesWarning = parsedOverrides.unknownLines.length > 0 ? `
+  \u26A0 ${OVERRIDES_FILENAME}: ignored ${parsedOverrides.unknownLines.length} unrecognized line${parsedOverrides.unknownLines.length === 1 ? "" : "s"} (${parsedOverrides.unknownLines.map((l) => `"${l}"`).join(", ")}) \u2014 only \`keep: <path-or-glob>\` lines are read.
+` : "";
   if (deps.fix) {
     const pins = { keep: [], skim: [] };
     for (const c of configs) {
@@ -1474,7 +1559,13 @@ async function runLint(deps) {
         });
         result = buildFixedConfig(files, source, void 0, spared);
       } else {
-        result = buildFixedEnforcedConfig(files, source, format, pins);
+        result = buildFixedEnforcedConfig(
+          files,
+          source,
+          format,
+          pins,
+          parsedOverrides.keep
+        );
       }
       if (!result.fixable) {
         unfixable.push(name);
@@ -1485,34 +1576,36 @@ async function runLint(deps) {
     }
     if (fixed.length > 0) {
       return {
-        text: `Fixed ${fixed.join(", ")}. Re-run without --fix to confirm.`,
+        text: `${overridesWarning}Fixed ${fixed.join(", ")}. Re-run without --fix to confirm.`,
         exitCode: 0,
         channel: "stdout"
       };
     }
     if (unfixable.length === configs.length) {
       return {
-        text: `Nothing to fix \u2014 ${unfixable.join(", ")} ${unfixable.length === 1 ? "has" : "have"} no ContextPruner managed block (or, for .claude/settings.json, could not be merged safely).`,
+        text: `${overridesWarning}Nothing to fix \u2014 ${unfixable.join(", ")} ${unfixable.length === 1 ? "has" : "have"} no ContextPruner managed block (or, for .claude/settings.json, could not be merged safely).`,
         exitCode: 2,
         channel: "stderr"
       };
     }
     const skipped = unfixable.length > 0 ? ` Skipped ${unfixable.join(", ")} (no ContextPruner managed block, or unmergeable).` : "";
     return {
-      text: `Nothing to fix \u2014 your configs already match the tree.${skipped}`,
+      text: `${overridesWarning}Nothing to fix \u2014 your configs already match the tree.${skipped}`,
       exitCode: 0,
       channel: "stdout"
     };
   }
-  const report = reconcile(files, configs);
+  const report = reconcile(files, configs, {
+    keepDeclarations: parsedOverrides.keep
+  });
   const kept = report.findings.filter((f) => !isFalseDead(f));
   const filtered = { ...report, findings: kept };
-  const text = deps.json ? JSON.stringify(filtered, null, 2) : formatReport(filtered);
+  const text = deps.json ? JSON.stringify(filtered, null, 2) : `${overridesWarning}${formatReport(filtered)}`;
   return { text, exitCode: exitCodeFor(filtered), channel: "stdout" };
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 var HELP = `contextpruner lint \u2014 check your AI-context config against your repo
 
 Usage:
@@ -1530,6 +1623,11 @@ Options:
   -h, --help        Show this help.
   -v, --version     Show the version.
 
+Exceptions:
+  \`keep: <path-or-glob>\` lines in a committed .contextpruner file mark paths
+  that must stay readable by agents. Lint expects their covering enforced
+  rules to be absent, and --fix keeps those rules out.
+
 Auth:
   export CONTEXTPRUNER_API_KEY=cp_live_...   (create one at
   https://contextpruner.app/account). Only your key is sent \u2014 the file tree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextpruner",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Lint your AI-context config files (AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules) against your repo — find missing, dead, drifting, and conflicting rules.",
   "keywords": [
     "AGENTS.md",