@ankurhalder/codebase-snapshot 2.1.0 → 2.1.1

package/dist/bin.js

@@ -52,7 +52,13 @@ function compareManifests(before, after) {
   };
 }
 function loadManifest(target) {
-  const manifestPath = fs.statSync(target).isDirectory() ? path.join(target, "manifest.json") : target;
+  let isDirectory;
+  try {
+    isDirectory = fs.statSync(target).isDirectory();
+  } catch {
+    throw new Error(`No snapshot found at ${target}: the path does not exist.`);
+  }
+  const manifestPath = isDirectory ? path.join(target, "manifest.json") : target;
   let raw;
   try {
     raw = fs.readFileSync(manifestPath, "utf8");
@@ -68,6 +74,9 @@ function loadManifest(target) {
   if (!parsed || !Array.isArray(parsed.files)) {
     throw new Error(`${manifestPath} is not a snapshot manifest (no "files" array).`);
   }
+  if (!parsed.counts || typeof parsed.counts !== "object") {
+    throw new Error(`${manifestPath} is not a snapshot manifest (no "counts" object).`);
+  }
   return parsed;
 }
 function renderDiffText(diff) {
@@ -948,11 +957,12 @@ import * as fs3 from "fs";
 import * as path3 from "path";
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
-    const branch = childProcess.execSync("git rev-parse --abbrev-ref HEAD", {
+    const reported = childProcess.execSync("git rev-parse --abbrev-ref HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8"
-    }).trim() || fallbackBranch;
+    }).trim();
+    const branch = !reported || reported === "HEAD" ? fallbackBranch : reported;
     const commit = childProcess.execSync("git rev-parse HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
@@ -1573,6 +1583,9 @@ async function loadConfigFileDetailed(cwd) {
       if (snapshotKey && typeof snapshotKey === "object") {
         return { config: snapshotKey, file: pkgJsonPath, warnings, errors };
       }
+      if (snapshotKey !== void 0) {
+        warnings.push(`${pkgJsonPath}: the "snapshot" key must be an object; it was ignored.`);
+      }
     } catch (err) {
       const message = err.message;
       warnings.push(message);
@@ -4295,6 +4308,7 @@ function validateSnapshot(configInput) {
       drift.missingOnDisk.push(snapshotFile);
     }
   }
+  drift.missingOnDisk = [...new Set(drift.missingOnDisk)];
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
     config.budgets.default,
@@ -4554,7 +4568,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.0";
+var GENERATOR_VERSION = "2.1.1";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto3.createHash("sha256").update(input).digest("hex");
@@ -4798,7 +4812,9 @@ function artifactWarnings(artifacts) {
     );
   }
   if (ARTIFACT_NAMES.every((name) => artifacts[name] === false)) {
-    messages.push("every artifact is disabled: the snapshot directory will be empty.");
+    messages.push(
+      "every artifact is disabled: only the .codebase-snapshot ownership marker will be written."
+    );
   }
   return messages;
 }
@@ -5253,9 +5269,32 @@ function parseCliArgs(argv) {
       strict: true
     });
   } catch (err) {
-    throw new UsageError(err.message);
+    const message = err.message;
+    const ambiguous = /^Option '(--[^']+)' argument is ambiguous/i.exec(message);
+    if (ambiguous) {
+      throw new UsageError(
+        `${ambiguous[1]} received a value that looks like another flag (for example a negative number). Use the "--option=value" form, and note that sizes must be positive.`
+      );
+    }
+    throw new UsageError(message);
   }
   const values = parsed.values;
+  for (const [name, spec] of Object.entries(CLI_OPTIONS)) {
+    if (spec.type !== "string") continue;
+    const raw = values[name];
+    if (raw !== void 0 && String(raw).trim() === "") {
+      throw new UsageError(`--${name} requires a value (received an empty string).`);
+    }
+  }
+  if (values.cwd !== void 0) {
+    const target = String(values.cwd);
+    if (!fs10.existsSync(target)) {
+      throw new UsageError(`--cwd directory does not exist: ${target}`);
+    }
+    if (!fs10.statSync(target).isDirectory()) {
+      throw new UsageError(`--cwd is not a directory: ${target}`);
+    }
+  }
   if (values.help) {
     process.stdout.write(`${USAGE}
 `);
@@ -5473,6 +5512,9 @@ function renderValidateText(result) {
     for (const missing of result.drift.missingOnDisk.slice(0, 20)) {
       warn(`  - deleted: ${missing}`);
     }
+    for (const mismatch of result.drift.totalsMismatches.slice(0, 20)) {
+      warn(`  - counts: ${mismatch}`);
+    }
   }
   for (const warning of result.warnings) warn(`  \u26A0 ${warning}`);
 }
@@ -5603,9 +5645,23 @@ ${USAGE}
       info(
         `   - Total size:    ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
       );
-      info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
-      info(`   - Reports:       ${resolved.outDir}/reports/ (project-tree, navigation, audit)`);
-      info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      const { artifacts } = resolved;
+      if (artifacts.parts) {
+        info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
+      }
+      const reports = [
+        artifacts.projectTree && "project-tree",
+        artifacts.navigation && "navigation",
+        artifacts.audit && "audit"
+      ].filter(Boolean);
+      if (reports.length > 0) {
+        info(`   - Reports:       ${resolved.outDir}/reports/ (${reports.join(", ")})`);
+      }
+      if (artifacts.manifest) info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      if (artifacts.monolith) info(`   - Monolith:      ${resolved.outDir}/full-codebase.{json,md}`);
+      if (reports.length === 0 && !artifacts.parts && !artifacts.manifest && !artifacts.monolith) {
+        info(`   - Artifacts:     all disabled (only the ownership marker was written)`);
+      }
       info(`   - Fingerprint:   ${manifest.fingerprint}`);
       info(`   - Integrity:     ${manifest.validation.status}`);
       if (manifest.warnings.length > 0) {
@@ -5622,6 +5678,14 @@ ${USAGE}
     }
     return manifest.validation.status === "passed" ? 0 : 1;
   } catch (err) {
+    const code = err.code;
+    if (code === "EPERM" || code === "EACCES") {
+      warn(
+        `\u274C Cannot write the snapshot: permission denied under ${resolved.outDir}. Check the directory's permissions or choose another --out-dir.`
+      );
+      warn(`   (${err.message})`);
+      return 1;
+    }
     warn(`\u274C Failed to generate snapshot: ${err.message}`);
     return 1;
   }

package/dist/{chunk-QEIOXPMU.js → chunk-SUOJL5EX.js}

@@ -1678,11 +1678,12 @@ function detectPreset(cwd, forced) {
 }
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
-    const branch = childProcess.execSync("git rev-parse --abbrev-ref HEAD", {
+    const reported = childProcess.execSync("git rev-parse --abbrev-ref HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8"
-    }).trim() || fallbackBranch;
+    }).trim();
+    const branch = !reported || reported === "HEAD" ? fallbackBranch : reported;
     const commit = childProcess.execSync("git rev-parse HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
@@ -2303,6 +2304,9 @@ async function loadConfigFileDetailed(cwd) {
       if (snapshotKey && typeof snapshotKey === "object") {
         return { config: snapshotKey, file: pkgJsonPath, warnings, errors };
       }
+      if (snapshotKey !== void 0) {
+        warnings.push(`${pkgJsonPath}: the "snapshot" key must be an object; it was ignored.`);
+      }
     } catch (err) {
       const message = err.message;
       warnings.push(message);
@@ -3417,6 +3421,7 @@ function validateSnapshot(configInput) {
       drift.missingOnDisk.push(snapshotFile);
     }
   }
+  drift.missingOnDisk = [...new Set(drift.missingOnDisk)];
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
     config.budgets.default,
@@ -3828,7 +3833,13 @@ function compareManifests(before, after) {
   };
 }
 function loadManifest(target) {
-  const manifestPath = fs9.statSync(target).isDirectory() ? path10.join(target, "manifest.json") : target;
+  let isDirectory;
+  try {
+    isDirectory = fs9.statSync(target).isDirectory();
+  } catch {
+    throw new Error(`No snapshot found at ${target}: the path does not exist.`);
+  }
+  const manifestPath = isDirectory ? path10.join(target, "manifest.json") : target;
   let raw;
   try {
     raw = fs9.readFileSync(manifestPath, "utf8");
@@ -3844,6 +3855,9 @@ function loadManifest(target) {
   if (!parsed || !Array.isArray(parsed.files)) {
     throw new Error(`${manifestPath} is not a snapshot manifest (no "files" array).`);
   }
+  if (!parsed.counts || typeof parsed.counts !== "object") {
+    throw new Error(`${manifestPath} is not a snapshot manifest (no "counts" object).`);
+  }
   return parsed;
 }
 function renderDiffText(diff) {
@@ -4514,7 +4528,7 @@ async function runInit(options) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.0";
+var GENERATOR_VERSION = "2.1.1";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto.createHash("sha256").update(input).digest("hex");
@@ -4758,7 +4772,9 @@ function artifactWarnings(artifacts) {
     );
   }
   if (ARTIFACT_NAMES.every((name) => artifacts[name] === false)) {
-    messages.push("every artifact is disabled: the snapshot directory will be empty.");
+    messages.push(
+      "every artifact is disabled: only the .codebase-snapshot ownership marker will be written."
+    );
   }
   return messages;
 }
@@ -5089,5 +5105,5 @@ async function generateSnapshotAsync(configInput, options) {
 }
 
 export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, unknownPresetMessage, validateSnapshot };
-//# sourceMappingURL=chunk-QEIOXPMU.js.map
-//# sourceMappingURL=chunk-QEIOXPMU.js.map
+//# sourceMappingURL=chunk-SUOJL5EX.js.map
+//# sourceMappingURL=chunk-SUOJL5EX.js.map

package/dist/cli.cjs

@@ -81,7 +81,13 @@ function compareManifests(before, after) {
   };
 }
 function loadManifest(target) {
-  const manifestPath = fs9__namespace.statSync(target).isDirectory() ? path10__namespace.join(target, "manifest.json") : target;
+  let isDirectory;
+  try {
+    isDirectory = fs9__namespace.statSync(target).isDirectory();
+  } catch {
+    throw new Error(`No snapshot found at ${target}: the path does not exist.`);
+  }
+  const manifestPath = isDirectory ? path10__namespace.join(target, "manifest.json") : target;
   let raw;
   try {
     raw = fs9__namespace.readFileSync(manifestPath, "utf8");
@@ -97,6 +103,9 @@ function loadManifest(target) {
   if (!parsed || !Array.isArray(parsed.files)) {
     throw new Error(`${manifestPath} is not a snapshot manifest (no "files" array).`);
   }
+  if (!parsed.counts || typeof parsed.counts !== "object") {
+    throw new Error(`${manifestPath} is not a snapshot manifest (no "counts" object).`);
+  }
   return parsed;
 }
 function renderDiffText(diff) {
@@ -959,11 +968,12 @@ function detectPreset(cwd, forced) {
 }
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
-    const branch = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
+    const reported = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8"
-    }).trim() || fallbackBranch;
+    }).trim();
+    const branch = !reported || reported === "HEAD" ? fallbackBranch : reported;
     const commit = childProcess__namespace.execSync("git rev-parse HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
@@ -1584,6 +1594,9 @@ async function loadConfigFileDetailed(cwd) {
       if (snapshotKey && typeof snapshotKey === "object") {
         return { config: snapshotKey, file: pkgJsonPath, warnings, errors };
       }
+      if (snapshotKey !== void 0) {
+        warnings.push(`${pkgJsonPath}: the "snapshot" key must be an object; it was ignored.`);
+      }
     } catch (err) {
       const message = err.message;
       warnings.push(message);
@@ -4274,6 +4287,7 @@ function validateSnapshot(configInput) {
       drift.missingOnDisk.push(snapshotFile);
     }
   }
+  drift.missingOnDisk = [...new Set(drift.missingOnDisk)];
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
     config.budgets.default,
@@ -4533,7 +4547,7 @@ function validateSnapshot(configInput) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.0";
+var GENERATOR_VERSION = "2.1.1";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");
@@ -4777,7 +4791,9 @@ function artifactWarnings(artifacts) {
     );
   }
   if (ARTIFACT_NAMES.every((name) => artifacts[name] === false)) {
-    messages.push("every artifact is disabled: the snapshot directory will be empty.");
+    messages.push(
+      "every artifact is disabled: only the .codebase-snapshot ownership marker will be written."
+    );
   }
   return messages;
 }
@@ -5244,9 +5260,32 @@ function parseCliArgs(argv) {
       strict: true
     });
   } catch (err) {
-    throw new UsageError(err.message);
+    const message = err.message;
+    const ambiguous = /^Option '(--[^']+)' argument is ambiguous/i.exec(message);
+    if (ambiguous) {
+      throw new UsageError(
+        `${ambiguous[1]} received a value that looks like another flag (for example a negative number). Use the "--option=value" form, and note that sizes must be positive.`
+      );
+    }
+    throw new UsageError(message);
   }
   const values = parsed.values;
+  for (const [name, spec] of Object.entries(CLI_OPTIONS)) {
+    if (spec.type !== "string") continue;
+    const raw = values[name];
+    if (raw !== void 0 && String(raw).trim() === "") {
+      throw new UsageError(`--${name} requires a value (received an empty string).`);
+    }
+  }
+  if (values.cwd !== void 0) {
+    const target = String(values.cwd);
+    if (!fs9__namespace.existsSync(target)) {
+      throw new UsageError(`--cwd directory does not exist: ${target}`);
+    }
+    if (!fs9__namespace.statSync(target).isDirectory()) {
+      throw new UsageError(`--cwd is not a directory: ${target}`);
+    }
+  }
   if (values.help) {
     process.stdout.write(`${USAGE}
 `);
@@ -5464,6 +5503,9 @@ function renderValidateText(result) {
     for (const missing of result.drift.missingOnDisk.slice(0, 20)) {
       warn(`  - deleted: ${missing}`);
     }
+    for (const mismatch of result.drift.totalsMismatches.slice(0, 20)) {
+      warn(`  - counts: ${mismatch}`);
+    }
   }
   for (const warning of result.warnings) warn(`  \u26A0 ${warning}`);
 }
@@ -5594,9 +5636,23 @@ ${USAGE}
       info(
         `   - Total size:    ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
       );
-      info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
-      info(`   - Reports:       ${resolved.outDir}/reports/ (project-tree, navigation, audit)`);
-      info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      const { artifacts } = resolved;
+      if (artifacts.parts) {
+        info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
+      }
+      const reports = [
+        artifacts.projectTree && "project-tree",
+        artifacts.navigation && "navigation",
+        artifacts.audit && "audit"
+      ].filter(Boolean);
+      if (reports.length > 0) {
+        info(`   - Reports:       ${resolved.outDir}/reports/ (${reports.join(", ")})`);
+      }
+      if (artifacts.manifest) info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      if (artifacts.monolith) info(`   - Monolith:      ${resolved.outDir}/full-codebase.{json,md}`);
+      if (reports.length === 0 && !artifacts.parts && !artifacts.manifest && !artifacts.monolith) {
+        info(`   - Artifacts:     all disabled (only the ownership marker was written)`);
+      }
       info(`   - Fingerprint:   ${manifest.fingerprint}`);
       info(`   - Integrity:     ${manifest.validation.status}`);
       if (manifest.warnings.length > 0) {
@@ -5613,6 +5669,14 @@ ${USAGE}
     }
     return manifest.validation.status === "passed" ? 0 : 1;
   } catch (err) {
+    const code = err.code;
+    if (code === "EPERM" || code === "EACCES") {
+      warn(
+        `\u274C Cannot write the snapshot: permission denied under ${resolved.outDir}. Check the directory's permissions or choose another --out-dir.`
+      );
+      warn(`   (${err.message})`);
+      return 1;
+    }
     warn(`\u274C Failed to generate snapshot: ${err.message}`);
     return 1;
   }

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, renderExplainText } from './chunk-QEIOXPMU.js';
+import { parseByteSize, GENERATOR_VERSION, ARTIFACT_NAMES, getPreset, unknownPresetMessage, MIN_MAX_PART_BYTES, loadConfigFileDetailed, resolveConfig, validateSnapshot, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, GENERATOR_NAME, runInit, PromptCancelled, renderExplainText } from './chunk-SUOJL5EX.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseArgs } from 'util';
@@ -142,9 +142,32 @@ function parseCliArgs(argv) {
       strict: true
     });
   } catch (err) {
-    throw new UsageError(err.message);
+    const message = err.message;
+    const ambiguous = /^Option '(--[^']+)' argument is ambiguous/i.exec(message);
+    if (ambiguous) {
+      throw new UsageError(
+        `${ambiguous[1]} received a value that looks like another flag (for example a negative number). Use the "--option=value" form, and note that sizes must be positive.`
+      );
+    }
+    throw new UsageError(message);
   }
   const values = parsed.values;
+  for (const [name, spec] of Object.entries(CLI_OPTIONS)) {
+    if (spec.type !== "string") continue;
+    const raw = values[name];
+    if (raw !== void 0 && String(raw).trim() === "") {
+      throw new UsageError(`--${name} requires a value (received an empty string).`);
+    }
+  }
+  if (values.cwd !== void 0) {
+    const target = String(values.cwd);
+    if (!fs.existsSync(target)) {
+      throw new UsageError(`--cwd directory does not exist: ${target}`);
+    }
+    if (!fs.statSync(target).isDirectory()) {
+      throw new UsageError(`--cwd is not a directory: ${target}`);
+    }
+  }
   if (values.help) {
     process.stdout.write(`${USAGE}
 `);
@@ -362,6 +385,9 @@ function renderValidateText(result) {
     for (const missing of result.drift.missingOnDisk.slice(0, 20)) {
       warn(`  - deleted: ${missing}`);
     }
+    for (const mismatch of result.drift.totalsMismatches.slice(0, 20)) {
+      warn(`  - counts: ${mismatch}`);
+    }
   }
   for (const warning of result.warnings) warn(`  \u26A0 ${warning}`);
 }
@@ -492,9 +518,23 @@ ${USAGE}
       info(
         `   - Total size:    ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
       );
-      info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
-      info(`   - Reports:       ${resolved.outDir}/reports/ (project-tree, navigation, audit)`);
-      info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      const { artifacts } = resolved;
+      if (artifacts.parts) {
+        info(`   - Parts written: ${manifest.counts.partsCount} under ${resolved.outDir}/parts/`);
+      }
+      const reports = [
+        artifacts.projectTree && "project-tree",
+        artifacts.navigation && "navigation",
+        artifacts.audit && "audit"
+      ].filter(Boolean);
+      if (reports.length > 0) {
+        info(`   - Reports:       ${resolved.outDir}/reports/ (${reports.join(", ")})`);
+      }
+      if (artifacts.manifest) info(`   - Manifest:      ${resolved.outDir}/manifest.json`);
+      if (artifacts.monolith) info(`   - Monolith:      ${resolved.outDir}/full-codebase.{json,md}`);
+      if (reports.length === 0 && !artifacts.parts && !artifacts.manifest && !artifacts.monolith) {
+        info(`   - Artifacts:     all disabled (only the ownership marker was written)`);
+      }
       info(`   - Fingerprint:   ${manifest.fingerprint}`);
       info(`   - Integrity:     ${manifest.validation.status}`);
       if (manifest.warnings.length > 0) {
@@ -511,6 +551,14 @@ ${USAGE}
     }
     return manifest.validation.status === "passed" ? 0 : 1;
   } catch (err) {
+    const code = err.code;
+    if (code === "EPERM" || code === "EACCES") {
+      warn(
+        `\u274C Cannot write the snapshot: permission denied under ${resolved.outDir}. Check the directory's permissions or choose another --out-dir.`
+      );
+      warn(`   (${err.message})`);
+      return 1;
+    }
     warn(`\u274C Failed to generate snapshot: ${err.message}`);
     return 1;
   }

package/dist/index.cjs

@@ -1707,11 +1707,12 @@ function detectPreset(cwd, forced) {
 }
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
-    const branch = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
+    const reported = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8"
-    }).trim() || fallbackBranch;
+    }).trim();
+    const branch = !reported || reported === "HEAD" ? fallbackBranch : reported;
     const commit = childProcess__namespace.execSync("git rev-parse HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
@@ -2332,6 +2333,9 @@ async function loadConfigFileDetailed(cwd) {
       if (snapshotKey && typeof snapshotKey === "object") {
         return { config: snapshotKey, file: pkgJsonPath, warnings, errors };
       }
+      if (snapshotKey !== void 0) {
+        warnings.push(`${pkgJsonPath}: the "snapshot" key must be an object; it was ignored.`);
+      }
     } catch (err) {
       const message = err.message;
       warnings.push(message);
@@ -3446,6 +3450,7 @@ function validateSnapshot(configInput) {
       drift.missingOnDisk.push(snapshotFile);
     }
   }
+  drift.missingOnDisk = [...new Set(drift.missingOnDisk)];
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
     config.budgets.default,
@@ -3857,7 +3862,13 @@ function compareManifests(before, after) {
   };
 }
 function loadManifest(target) {
-  const manifestPath = fs9__namespace.statSync(target).isDirectory() ? path10__namespace.join(target, "manifest.json") : target;
+  let isDirectory;
+  try {
+    isDirectory = fs9__namespace.statSync(target).isDirectory();
+  } catch {
+    throw new Error(`No snapshot found at ${target}: the path does not exist.`);
+  }
+  const manifestPath = isDirectory ? path10__namespace.join(target, "manifest.json") : target;
   let raw;
   try {
     raw = fs9__namespace.readFileSync(manifestPath, "utf8");
@@ -3873,6 +3884,9 @@ function loadManifest(target) {
   if (!parsed || !Array.isArray(parsed.files)) {
     throw new Error(`${manifestPath} is not a snapshot manifest (no "files" array).`);
   }
+  if (!parsed.counts || typeof parsed.counts !== "object") {
+    throw new Error(`${manifestPath} is not a snapshot manifest (no "counts" object).`);
+  }
   return parsed;
 }
 function renderDiffText(diff) {
@@ -4543,7 +4557,7 @@ async function runInit(options) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.0";
+var GENERATOR_VERSION = "2.1.1";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");
@@ -4787,7 +4801,9 @@ function artifactWarnings(artifacts) {
     );
   }
   if (ARTIFACT_NAMES.every((name) => artifacts[name] === false)) {
-    messages.push("every artifact is disabled: the snapshot directory will be empty.");
+    messages.push(
+      "every artifact is disabled: only the .codebase-snapshot ownership marker will be written."
+    );
   }
   return messages;
 }

package/dist/index.d.cts

@@ -497,7 +497,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "2.1.0";
+declare const GENERATOR_VERSION = "2.1.1";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */

package/dist/index.d.ts

@@ -497,7 +497,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "2.1.0";
+declare const GENERATOR_VERSION = "2.1.1";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */

package/dist/index.js

@@ -1,3 +1,3 @@
-export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-QEIOXPMU.js';
+export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-SUOJL5EX.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/docs/install.md

@@ -12,6 +12,20 @@ Requires **Node.js 18 or newer**.
 npx @ankurhalder/codebase-snapshot generate
 ```
 
+If that exits with **no output and no error** instead of generating, your npm has
+resolved the bare spec to a placeholder manifest that carries no executable — npm creates
+a `0.0.0-stage` placeholder version during staged publishing, and some npm builds pick it
+when no version is given. Pin the version or the tag and it works:
+
+```bash
+npx @ankurhalder/codebase-snapshot@latest generate
+npx @ankurhalder/codebase-snapshot@2 generate
+```
+
+`npx -p @ankurhalder/codebase-snapshot codebase-snapshot generate`, `pnpm dlx`,
+`yarn dlx` and `bunx` are unaffected. A normal `npm install -D` followed by `npx snap`
+is unaffected too, and is the more reproducible choice for a project.
+
 Equivalent one-liners for other clients:
 
 ```bash
@@ -68,7 +82,7 @@ if the generator version is reproducible.
 
 ```bash
 npx @ankurhalder/codebase-snapshot@2 generate
-pnpm dlx @ankurhalder/codebase-snapshot@2.1.0 generate
+pnpm dlx @ankurhalder/codebase-snapshot@2.1.1 generate
 ```
 
 ## Verified clients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
   "keywords": [
     "codebase",