git-span 1.0.131

package/README.md

@@ -0,0 +1,16 @@
+# git span
+
+`git span` tracks implicit semantic dependencies in a git repository — line-range or whole-file anchors that participate in a coupling no schema, type, or test enforces. Each span names its anchors, optionally carries a `why` sentence defining the subsystem they collectively form (recommended on every span), and surfaces drift via `git span stale` when those anchors diverge from their anchored state.
+
+The primary CLI surface lives in `src/cli/mod.rs`. Run `git span --help` or `git span stale --help` for flag reference.
+
+### Upgrading from the sqlite cache
+
+The trail cache now lives at `<common_dir>/span/cache/v1/` as a BLAKE3-keyed content-addressed filesystem store. The previous sqlite-backed cache at `<common_dir>/span/cache/span_cache.sqlite` (or `<git_dir>/span/cache/span_cache.sqlite` on older per-worktree installations), along with its `-shm` and `-wal` companions, is unused and can be removed with a single `rm -f <common_dir>/span/cache/span_cache.sqlite*` (and the `<git_dir>` variant if present). Nothing reads those files anymore; `git span doctor --gc-trail-cache` operates only on the new store.
+
+## Profiling
+
+Perf investigation tooling is documented in [`./docs/profiling.md`](./docs/profiling.md):
+
+- **Flame graph capture** — `perf record` + `inferno-flamegraph` recipe for identifying hot functions.
+- **`--perf-trace <path>`** — opt-in per-anchor wall-clock CSV emitter for `git span stale`; CSV schema, usage constraints, and quick analysis snippets are documented there.

package/bin/git-span.exe

@@ -0,0 +1,6 @@
+git-span placeholder. scripts/postinstall.js replaces this file
+with the native binary for your platform. The name ends in .exe and the
+first line intentionally has NO "#!" shebang so npm/yarn/pnpm cmd-shim
+generates a direct-exec wrapper that runs on Windows; Unix ignores the
+.exe suffix and execs by mode bit. If you are seeing this text, the
+postinstall step did not run.

package/man/git-span.1

@@ -0,0 +1,172 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH git-span 1  "git-span 1.0.131" 
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH NAME
+git\-span \- Track implicit semantic dependencies in a git repo.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH SYNOPSIS
+\fBgit\-span\fR [\fB\-\-perf\fR] [\fB\-\-span\-dir\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIsubcommands\fR]
+.SH DESCRIPTION
+.B git span
+tracks implicit semantic dependencies in a Git repository: couplings between
+line ranges (or whole files), in code or prose, that no schema, type, or test
+enforces.
+Each
+.B span
+anchors the participating anchors and carries a durable
+.I why
+\[em] one prose sentence that names the relationship the anchored set holds
+and survives a rewrite of either side.
+.PP
+The standing question at commit time: did this change create or rely on a
+coupling that is not visible from the lines themselves?
+.PP
+.B Writing the why.
+Name the relationship the anchors hold in one prose sentence, written so it
+survives a rewrite of either side.
+Describe the relationship in role\-words (\(lqthe doc,\(rq \(lqthe parser,\(rq
+\(lqthe runbook,\(rq \(lqthe migration\(rq) rather than repeating filenames.
+For asymmetric relationships, name which side is normative:
+\(lqthe doc is the source of truth when they disagree.\(rq
+Do not restate the span name, embed incidental implementation details, or
+bundle ownership and review triggers in the why.
+.PP
+.B Re\-anchoring on drift.
+When
+.B git span stale
+reports drift, review the change at each anchor.
+If the relationship still holds, re-anchor with
+.B git span add
+and commit.
+If the relationship has changed, update the why with
+.B git span why
+before re-anchoring.
+.PP
+Each span is an ordinary tracked file under the span root (default
+.IR .span ,
+overridable with
+.BR \-\-span\-dir ,
+the
+.I GIT_SPAN_DIR
+environment variable, or
+.IR "git config git-span.dir" ).
+Spans are versioned, fetched, and pushed exactly like any other
+tracked file \[em] stage and commit edits with
+.B git add .span && git commit
+\&.
+.PP
+Bare invocations:
+.RS 4
+.TP
+.B git span
+List every span in the repository.
+.TP
+.BI git\ span\  <name>
+Show one span (anchors, why, config).
+.RE
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH OPTIONS
+.TP
+\fB\-\-perf\fR
+Emit performance timings for major git\-span operation groups to stderr.
+
+Can also be enabled with `GIT_SPAN_PERF=1`.
+.TP
+\fB\-\-span\-dir\fR \fI<SPAN_DIR>\fR
+Span root directory (default: .span). Overrides GIT_SPAN_DIR and git config git\-span.dir
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH SUBCOMMANDS
+.TP
+git\-span\-show(1)
+Show the named span — its anchors, why, and config. Equivalent to the bare `git span <name>` positional form
+.TP
+git\-span\-list(1)
+List files and anchors currently tracked by a span
+.TP
+git\-span\-stale(1)
+Report anchors whose content has drifted from their anchored state
+.TP
+git\-span\-add(1)
+Add anchors to a span, writing the span file under the span root. Stage and commit the change with `git add .span && git commit`
+.TP
+git\-span\-remove(1)
+Remove anchors from a span, editing the span file under the span root. Stage and commit the change with `git add .span && git commit`
+.TP
+git\-span\-why(1)
+Read or stage the span\*(Aqs why — a one\-sentence definition of the subsystem, flow, or concern the anchors collectively form
+.TP
+git\-span\-delete(1)
+Delete a span
+.TP
+git\-span\-move(1)
+Rename a span
+.TP
+git\-span\-doctor(1)
+Audit the local span setup
+.TP
+git\-span\-tree(1)
+Trace blast radius: render a clique\-grouped impact tree rooted at the files matched by the given paths/globs
+.TP
+git\-span\-merge\-driver(1)
+Resolve `.span/` merge conflicts structurally when invoked by git as a merge driver. Receives three clean blob temp files and the marker length from git. Resolves only what is structurally derivable without trusting the worktree (which may be mid\-merge); defers same\-anchor range/hash divergence by writing minimal conflict markers and exiting non\-zero so `git span stale \-\-fix` can finish authoritatively
+.TP
+git\-span\-history(1)
+Show a chronological timeline of a span file\*(Aqs git history: each commit where the span changed, rendered oldest→newest, with the content of any anchor that was added, modified, or removed, and an optional `current` entry describing how the working tree has drifted from HEAD
+.TP
+git\-span\-help(1)
+Print this message or the help of the given subcommand(s)
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH VERSION
+v1.0.131
+.SH EXAMPLES
+Anchor a new span alongside a code change:
+.PP
+.RS 4
+.nf
+git span add billing/charge-request-contract \e
+    docs/api/charge.md#L40-L88 api/charge.ts#L30-L76
+git span why billing/charge-request-contract \e
+    -m "The doc states the request body shape the parser honors; \e
+the doc is the source of truth when they disagree."
+git add .span
+git commit -m "Wire checkout to charge API"
+.fi
+.RE
+.PP
+Document an existing relationship anchored at HEAD:
+.PP
+.RS 4
+.nf
+git span add auth/token-contract --at HEAD \e
+    packages/auth/token.ts#L88-L104 \e
+    packages/auth/crypto.ts#L12-L40
+git span why auth/token-contract \e
+    -m "Token verification depends on signature verification."
+git add .span && git commit -m "Document token/crypto coupling"
+.fi
+.RE
+.PP
+Check for drift and inspect a span:
+.PP
+.RS 4
+.nf
+git span stale
+git span billing/charge-request-contract
+git span show billing/charge-request-contract
+.fi
+.RE
+.SH SEE ALSO
+.BR git (1),
+.BR gitcli (7)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "git-span",
+  "version": "1.0.131",
+  "bin": "bin/git-span.exe",
+  "man": [
+    "man/git-span.1"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "build:man": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo run --quiet --locked --bin gen-manpage -- man/git-span.1",
+    "build": "yarn build:man && bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo build --release --locked",
+    "build:local": "bash scripts/build-local.sh",
+    "build:clean": "bash scripts/cleanup-stale-target.sh && bash scripts/clean-shared-build.sh && yarn build",
+    "test": "bash scripts/with-target-lock.sh shared env CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo nextest run --build-jobs 1 --locked",
+    "lint": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 RUSTFLAGS=\"-W unused -W dead-code\" CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/check\" cargo clippy --quiet --locked -- -D warnings",
+    "typecheck": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 RUSTFLAGS=\"-W unused -W dead-code\" CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/check\" cargo check --quiet --locked",
+    "bench:check": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo bench --no-run --locked --features bench-corpus",
+    "bench": "bash scripts/with-target-lock.sh shared env CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/build\" cargo bench --locked",
+    "udeps": "bash scripts/with-target-lock.sh shared env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_SPAN_CARGO_TARGET_ROOT:-$HOME/.cache/git-span/cargo-target}/git-span/udeps\" cargo +nightly udeps"
+  },
+  "files": [
+    "bin/git-span.exe",
+    "man/",
+    "scripts/postinstall.js"
+  ],
+  "optionalDependencies": {
+    "git-span-darwin-arm64": "1.0.131",
+    "git-span-darwin-x64": "1.0.131",
+    "git-span-linux-arm64": "1.0.131",
+    "git-span-linux-x64": "1.0.131",
+    "git-span-win32-x64": "1.0.131"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goodfoot-io/git-span.git"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PLATFORM_MAP = {
+  linux: 'linux',
+  darwin: 'darwin',
+  win32: 'win32'
+};
+
+const ARCH_MAP = {
+  x64: 'x64',
+  arm64: 'arm64'
+};
+
+function fail(message, error) {
+  console.error(message);
+  if (error) {
+    console.error(error.message);
+  }
+  process.exit(1);
+}
+
+function buildFromSource(destBinary, binaryName) {
+  const cargoToml = path.join(__dirname, '..', 'Cargo.toml');
+  if (!fs.existsSync(cargoToml)) {
+    fail(`git-span: Binary not found at ${destBinary} and no Cargo.toml available to build from source.`);
+  }
+
+  console.log(`git-span: Prebuilt binary missing; building from source via cargo...`);
+
+  const targetDir = path.join(__dirname, '..', 'target-cache', 'build');
+  const result = spawnSync('cargo', ['build', '--release', '--manifest-path', cargoToml], {
+    stdio: 'inherit',
+    env: { ...process.env, CARGO_BUILD_JOBS: '1', CARGO_TARGET_DIR: targetDir }
+  });
+
+  if (result.error || result.status !== 0) {
+    fail(
+      `git-span: Failed to build binary from source. Install Rust/cargo or publish the platform package.`,
+      result.error
+    );
+  }
+
+  const builtBinary = path.join(targetDir, 'release', binaryName);
+  if (!fs.existsSync(builtBinary)) {
+    fail(`git-span: cargo build succeeded but binary not found at ${builtBinary}.`);
+  }
+
+  fs.mkdirSync(path.dirname(destBinary), { recursive: true });
+  fs.copyFileSync(builtBinary, destBinary);
+  fs.chmodSync(destBinary, 0o755);
+}
+
+function isInsideSourceTree() {
+  // Walk up from this script looking for a `.git` entry. If found, this is
+  // the git-span source repo (developer doing `yarn install`), not
+  // a consumer install under node_modules. Mutating the tracked `bin/git-span`
+  // shim in that case dirties the working tree and — if committed — ships a
+  // dangling symlink in the published tarball (see git-span-v1.0.25 regression).
+  let dir = path.resolve(__dirname, '..');
+  for (let i = 0; i < 16; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    if (path.basename(parent) === 'node_modules') return false;
+    dir = parent;
+  }
+  return false;
+}
+
+function main() {
+  if (isInsideSourceTree()) {
+    console.log('git-span: postinstall skipped (running inside source tree).');
+    return;
+  }
+
+  const platform = PLATFORM_MAP[process.platform];
+  const arch = ARCH_MAP[process.arch];
+
+  if (!platform || !arch) {
+    fail(`git-span: No prebuilt binary available for ${process.platform}-${process.arch}.`);
+  }
+
+  const packageName = `git-span-${platform}-${arch}`;
+  const sourceBinaryName = process.platform === 'win32' ? 'git-span.exe' : 'git-span';
+
+  let packageDir;
+  try {
+    packageDir = path.dirname(require.resolve(`${packageName}/package.json`));
+  } catch (error) {
+    fail(`git-span: Required platform package ${packageName} not found.`, error);
+  }
+
+  const sourceBinary = path.join(packageDir, 'bin', sourceBinaryName);
+  if (!fs.existsSync(sourceBinary)) {
+    buildFromSource(sourceBinary, sourceBinaryName);
+  }
+
+  // Always write to bin/git-span.exe — the package.json `bin` field points
+  // here on every platform. The `.exe` extension plus a no-shebang stub makes
+  // npm's cmd-shim (generated at install time, before this postinstall) emit
+  // a direct exec on Windows; Unix executes by mode bit + ELF/Mach-O header
+  // and ignores the `.exe` suffix entirely. No resident Node process — the
+  // `git-span` command execs the native binary directly. Same pattern as
+  // Bun's and Claude Code's npm packages.
+  const binGitSpan = path.join(__dirname, '..', 'bin', 'git-span.exe');
+
+  // Hardlink first (instant, zero extra disk for the ~16MB binary; src and
+  // dest are both under node_modules so same-filesystem is the common case),
+  // then fall back to copy across devices / on link-permission errors.
+  try {
+    fs.linkSync(sourceBinary, binGitSpan);
+  } catch (linkError) {
+    if (linkError.code === 'EEXIST') {
+      try {
+        fs.unlinkSync(binGitSpan);
+        fs.linkSync(sourceBinary, binGitSpan);
+      } catch {
+        fs.copyFileSync(sourceBinary, binGitSpan);
+      }
+    } else if (linkError.code === 'EXDEV' || linkError.code === 'EPERM') {
+      fs.copyFileSync(sourceBinary, binGitSpan);
+    } else {
+      try {
+        fs.copyFileSync(sourceBinary, binGitSpan);
+      } catch (copyError) {
+        fail(
+          `git-span: Could not install binary from ${sourceBinary} to ${binGitSpan}.`,
+          new Error(`link failed: ${linkError.message}\ncopy failed: ${copyError.message}`)
+        );
+      }
+    }
+  }
+  if (process.platform !== 'win32') {
+    fs.chmodSync(binGitSpan, 0o755);
+  }
+
+  console.log(`git-span: Installed git-span from ${packageName}`);
+}
+
+main();