@bigknoxy/hashpilot 4.8.2 → 4.8.4

package/docs/decisions/README.md

@@ -88,3 +88,26 @@ Format:
 - **Decision:** Add `bun.lock` to `package.json`'s `files` array so it ships in the npm tarball. The existing `install.sh` logic already uses `--frozen-lockfile` when `bun.lock` is present.
 - **Alternatives considered:** (1) Generate a lockfile during install — rejected: defeats the purpose of pinning. (2) Keep `bun.lock` out and accept fresh resolution — rejected: supply-chain pinning gap.
 - **Consequences:** npm-installed packages now include `bun.lock` and install with `--frozen-lockfile`. The npm package size increases slightly. The `else` branch in `install.sh` (lines 423-432) becomes unreachable for current npm installs but is kept as a safe fallback.
+
+## D009-D010 numbering note: D010 (npm install mode-selector fix) was merged
+## to main (#201) during the v4.8.2 hotfix and precedes D009 in the file for
+## the same reason it precedes it in git history — each record captures a
+## decision in merge order.
+
+## D010: npm-sourced installs with a shipped bun.lock use --frozen-lockfile --production
+
+- **Date:** 2026-09-06
+- **PR:** #201
+- **Context:** v4.8.2 shipped broken for the **default npm install path**. D007 (#199) added `bun.lock` to the npm package's `files`; the dependency-mode guard from #194 treated `NPM_INSTALLED=true && bun.lock present` as a fatal ("refusing to guess which dependency mode is correct"). D007 made that guard's fire-branch the *normal* case, so every fresh npm install of v4.8.2 aborted before installing dependencies. The bug passed CI because smoke installs from `@latest` npm — main's run predated the semantic-release publish and tested 4.8.1 (no lockfile); the breakage only surfaced once v4.8.2 reached the registry.
+- **Decision:** The dependency-mode decision now keys off `$NPM_INSTALLED`, not a bare lockfile-presence check. npm source + shipped lock → `bun install --frozen-lockfile --production` (pinned, devDeps skipped). npm source, no lock → `--production` (legacy). git/local + lock → `--frozen-lockfile` (dev wants devDeps). git/local, no lock → hard error (unchanged).
+- **Alternatives considered:** (1) Revert D007 (don't ship bun.lock) — rejected: pinning transitive deps is the correct supply-chain posture; the packaging was not the flaw, the mode-selector was. (2) Remove the #194 guard entirely and let the old `[ -f bun.lock ]` branch run plain `--frozen-lockfile` — rejected: that would pull devDependencies (semantic-release) into npm installs, breaking the smoke's devDep-exclusion assertion and bloating user installs.
+- **Consequences:** npm-installed packages are pinned to the shipped lockfile while still skipping devDeps. **Coverage hole identified:** smoke's npm-path test installs `@latest` (published version), so an unpublished PR branch is never validated against its own packed tarball — add a version-consistency guard so "testing the wrong release" is loud, not silent.
+
+## D009: linesChanged counts each line exactly once via structured LineMetrics
+
+- **Date:** 2026-09-06
+- **PR:** #200 (pending #166 fix)
+- **Context:** Bug B65 (#166). `replaceHash` computed `linesChanged = |Δlines| + countChangedLines(...)`, and `countChangedLines` treated any line missing on one side of a paired comparison as "changed." A pure append of N lines was therefore counted twice (once in the size delta, once in the comparison diffs), reporting 2N.
+- **Decision:** Extract blast-radius math into a reusable, idempotent `LineMetrics` module (`computeLineMetrics`) returning `{ added, removed, modified, changed }` where `changed = added + removed + modified` and each line is counted exactly once. `linesChanged` becomes `changed`. The result now also carries a structured `lineMetrics` breakdown alongside the scalar.
+- **Alternatives considered:** (1) Fix the old formula in place — rejected: the double-count is inherent to adding |Δ| to a positional diff; and the metrics logic would stay buried in `hash-edit`, un-reusable and untestable in isolation. (2) LCS-based diff for exact pairwise alignment — rejected: overkill for blast-radius; position-equality is a correct, predictable metric for range replacement. (3) Keep `countChangedLines` positional semantics — rejected: it is the source of the bug.
+- **Consequences:** `linesChanged` and `message` wording for success results change (both now reflect true touched-line count; message appends a human-readable breakdown). The comparison predicate is injectable (extensible seam). Metrics are pure, idempotent, and dual-format (structured `lineMetrics` + `describeLineMetrics` text). No change to actual edit application or returned file content — metrics-only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigknoxy/hashpilot",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "HashPilot — Global Tool-Agnostic Structured Editing Core for Coding Agents",
   "type": "module",
   "engines": {

package/scripts/install.sh

@@ -405,31 +405,45 @@ log "Installing dependencies..."
 # (e.g. an npm extraction that somehow shipped a lockfile, or a git/local
 # source that's missing one) fails loudly here instead of silently
 # guessing.
-if [ "$NPM_INSTALLED" = "true" ] && [ -f "$SOURCE_DIR/bun.lock" ]; then
-  err "npm-sourced install unexpectedly has a bun.lock — refusing to guess which dependency mode is correct"
-  exit 1
-fi
 if [ "$NPM_INSTALLED" = "false" ] && [ ! -f "$SOURCE_DIR/bun.lock" ]; then
   err "Source is missing bun.lock and wasn't installed from npm — refusing to guess which dependency mode is correct"
   err "(local-clone and --source installs are expected to have bun.lock, same as the git repo does)"
   exit 1
 fi
 
-if [ -f "$SOURCE_DIR/bun.lock" ]; then
+# Dependency mode decided here, not by a bare [ -f bun.lock ] presence check:
+#   - git/local source with bun.lock  -> --frozen-lockfile (dev wants devDeps)
+#   - npm source with bun.lock (D007) -> --frozen-lockfile --production (pinned,
+#     but skip devDeps — the npm package lists them in package.json even though
+#     `files` excludes them; a plain --frozen-lockfile would pull semantic-release)
+#   - npm source without bun.lock     -> --production (legacy, pre-D007)
+if [ "$NPM_INSTALLED" = "true" ]; then
+  # npm always skips devDependencies. When the shipped lockfile is present
+  # (D007), pin to it too; otherwise resolve production deps fresh.
+  if [ -f "$SOURCE_DIR/bun.lock" ]; then
+    detail "bun.lock shipped (npm package) — installing pinned production dependencies"
+    cd "$TARGET_DIR/structured-editing"
+    bun install --frozen-lockfile --production 2>&1 | while IFS= read -r line; do detail "$line"; done
+    cd "$OLDPWD"
+  else
+    # The npm-published package.json still lists devDependencies (npm's
+    # `files` field controls which FILES ship, not which package.json fields
+    # do) — a plain `bun install` would resolve and install semantic-release,
+    # fast-check, and the rest of the dev toolchain for no reason on an end
+    # user's machine. --production skips them; the CLI never needs them.
+    detail "No bun.lock shipped (npm package install) — resolving production dependencies fresh"
+    rm -f "$TARGET_DIR/structured-editing/bun.lock"
+    cd "$TARGET_DIR/structured-editing"
+    bun install --production 2>&1 | while IFS= read -r line; do detail "$line"; done
+    cd "$OLDPWD"
+  fi
+elif [ -f "$SOURCE_DIR/bun.lock" ]; then
   cd "$TARGET_DIR/structured-editing"
   bun install --frozen-lockfile 2>&1 | while IFS= read -r line; do detail "$line"; done
   cd "$OLDPWD"
 else
-  # The npm-published package.json still lists devDependencies (npm's
-  # `files` field controls which FILES ship, not which package.json fields
-  # do) — a plain `bun install` would resolve and install semantic-release,
-  # fast-check, and the rest of the dev toolchain for no reason on an end
-  # user's machine. --production skips them; the CLI never needs them.
-  detail "No bun.lock shipped (npm package install) — resolving production dependencies fresh"
-  rm -f "$TARGET_DIR/structured-editing/bun.lock"
-  cd "$TARGET_DIR/structured-editing"
-  bun install --production 2>&1 | while IFS= read -r line; do detail "$line"; done
-  cd "$OLDPWD"
+  err "Source has no bun.lock and was not installed from npm — nothing to pin against"
+  exit 1
 fi
 detail "Dependencies installed"
 

package/src/core/hash-edit.ts

@@ -5,6 +5,11 @@ import { assertWritable, atomicWrite, PathDeniedError, type AssertWritableOption
 import { recordSnapshot } from "./snapshot";
 import { firstParseError } from "./ast-edit";
 import { readDecoded } from "./encoding";
+import {
+  computeLineMetrics,
+  describeLineMetrics,
+  type LineMetrics,
+} from "./line-metrics";
 
 /**
  * What to do when the anchor hash no longer matches the content at the given range.
@@ -57,6 +62,13 @@ export interface ReplaceHashResult {
    */
   newRange?: { start: number; end: number };
   linesChanged: number;
+  /**
+   * Structured breakdown of the blast radius: `added`, `removed`, `modified`,
+   * and `changed`. `changed` equals `linesChanged`. Never double-counts lines
+   * that are both appended/removed and reflected in the size delta (#166).
+   * Absent on failure paths.
+   */
+  lineMetrics?: LineMetrics;
   stale: boolean;
   message: string;
   diff?: string;
@@ -291,7 +303,8 @@ async function applyReplacement(
   const newRangeText = newContentLines.join("\n");
   const newRangeHash = computeHash(newRangeText);
   const diff = buildDiff(targetStart + 1, targetLines, newContentLines);
-  const linesChanged = Math.abs(newContentLines.length - targetLines.length) + countChangedLines(targetLines, newContentLines);
+  const lineMetrics = computeLineMetrics(targetLines, newContentLines);
+  const linesChanged = lineMetrics.changed;
   const rangeLabel = `range ${targetStart + 1}-${targetEnd}`;
 
   // A hash edit is content-blind: it will happily splice half a function into
@@ -338,12 +351,13 @@ async function applyReplacement(
     fileHash: newFullHash,
     newRange: { start: targetStart + 1, end: targetStart + newContentLines.length },
     linesChanged,
+    lineMetrics,
     stale,
     retries,
     relocatedTo,
     message: dryRun
-      ? `${action} ${targetLines.length} lines with ${newContentLines.length} lines${messageSuffix}`
-      : `${action} ${targetLines.length} lines with ${newContentLines.length} lines${messageSuffix} (${rangeLabel})`,
+      ? `${action} ${targetLines.length} lines with ${newContentLines.length} lines — ${describeLineMetrics(lineMetrics)}${messageSuffix}`
+      : `${action} ${targetLines.length} lines with ${newContentLines.length} lines — ${describeLineMetrics(lineMetrics)}${messageSuffix} (${rangeLabel})`,
     diff,
   };
 }
@@ -404,13 +418,4 @@ function buildDiff(
     }
   }
   return parts.join("\n");
-}
-
-function countChangedLines(oldLines: string[], newLines: string[]): number {
-  let count = 0;
-  const maxLen = Math.max(oldLines.length, newLines.length);
-  for (let i = 0; i < maxLen; i++) {
-    if ((oldLines[i] ?? "") !== (newLines[i] ?? "")) count++;
-  }
-  return count;
 }

package/src/core/index.ts

@@ -6,6 +6,12 @@ export { search, parseZgMarkdown, matchesSource, DEFAULT_SOURCE_GLOBS } from "./
 export type { SearchResult, SearchHit, ZgSearchResult, GrepSearchResult, SearchOptions } from "./search";
 export { replaceHash } from "./hash-edit";
 export type { ReplaceHashResult, ReplaceHashOptions } from "./hash-edit";
+export {
+  computeLineMetrics,
+  describeLineMetrics,
+  computeChangedLinesScore,
+} from "./line-metrics";
+export type { LineMetrics, LineComparer } from "./line-metrics";
 export {
   findSymbols,
   findSymbolsDetailed,

package/src/core/line-metrics.ts

@@ -0,0 +1,95 @@
+/**
+ * LineMetrics — blast-radius metrics for line-level edits.
+ *
+ * Computes how many lines a replace operation touches, WITHOUT double-counting
+ * lines that are both appended/removed AND reflected in the size delta.
+ *
+ * SOLID design:
+ * - Single responsibility: this module only measures line deltas. It does not
+ *   apply edits, write files, or build diffs.
+ * - Open for extension: the comparison predicate is injectable (see
+ *   `countChangedBy`), so callers can define their own notion of "changed"
+ *   (e.g. ignore whitespace) without editing core.
+ * - Idempotent: pure function of its inputs. Same (old, new) → same result.
+ * - Dual-format: `compute` returns a structured, agent-parseable object;
+ *   `describe` renders the same data as human-readable text. Human text is
+ *   generated FROM the structured value, never maintained separately.
+ */
+
+/** Structured line-metrics result (agent-parseable shape). */
+export interface LineMetrics {
+  /** Lines present in new but not old. */
+  added: number;
+  /** Lines present in old but not new. */
+  removed: number;
+  /** Lines present in both but different. */
+  modified: number;
+  /**
+   * Total lines touched by the edit. NEVER double-counts: a line is counted
+   * exactly once — as added, removed, or modified. Pure append of N lines is
+   * `added=N, changed=N` (not `2N`).
+   */
+  changed: number;
+}
+
+/** Predicate defining when a line occupying the same slot is "changed". */
+export type LineComparer = (oldLine: string, newLine: string) => boolean;
+
+/**
+ * Compute line metrics between two line arrays.
+ *
+ * The tricky case (fixed here): a line that exists on only one side of the
+ * comparison is "added" or "removed", NOT "modified". Naive implementations
+ * (e.g. `old[i] ?? "" !== new[i] ?? ""`) count such lines as "modified", so a
+ * pure append of N lines reports N added + N modified = 2N. This module counts
+ * each line exactly once.
+ *
+ * Idempotence guarantee: `compute(a, b) === compute(a, b)` for identical
+ * inputs — no state, no randomness, no mutation.
+ */
+export function computeLineMetrics(
+  oldLines: string[],
+  newLines: string[],
+  isChanged: LineComparer = (a, b) => a !== b,
+): LineMetrics {
+  let added = 0;
+  let removed = 0;
+  let modified = 0;
+
+  const shared = Math.min(oldLines.length, newLines.length);
+  for (let i = 0; i < shared; i++) {
+    if (isChanged(oldLines[i], newLines[i])) modified++;
+  }
+  // Tail beyond the shorter array is purely added or purely removed.
+  if (newLines.length > oldLines.length) {
+    added = newLines.length - oldLines.length;
+  } else if (oldLines.length > newLines.length) {
+    removed = oldLines.length - newLines.length;
+  }
+
+  return { added, removed, modified, changed: added + removed + modified };
+}
+
+/** Human-readable rendering of {@link LineMetrics} (generated from structured). */
+export function describeLineMetrics(m: LineMetrics): string {
+  const parts: string[] = [];
+  if (m.added) parts.push(`${m.added} added`);
+  if (m.removed) parts.push(`${m.removed} removed`);
+  if (m.modified) parts.push(`${m.modified} modified`);
+  const detail = parts.length ? ` (${parts.join(", ")})` : "";
+  return `${m.changed} line${m.changed === 1 ? "" : "s"} touched${detail}`;
+}
+
+/**
+ * Convenience: compute metrics for a range replacement given the OLD target
+ * lines and NEW replacement lines. Keeps the "changed" number available both
+ * as an object and as a plain count for callers that only need the scalar.
+ */
+export function computeChangedLinesScore(
+  oldLines: string[],
+  newLines: string[],
+  isChanged?: LineComparer,
+): { metrics: LineMetrics; changed: number } {
+  const metrics = computeLineMetrics(oldLines, newLines, isChanged);
+  return { metrics, changed: metrics.changed };
+}