kindred-drift 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Malaga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+<div align="center">
+
+# kindred
+
+**Template-less drift detection for a folder of sibling repos.**
+
+You never declared a template, but your repos clearly share one. kindred finds it, and shows you where each repo has wandered off.
+
+[![CI](https://github.com/BenMalaga/kindred/actions/workflows/test.yml/badge.svg)](https://github.com/BenMalaga/kindred/actions/workflows/test.yml)
+[![release](https://img.shields.io/github/v/release/BenMalaga/kindred)](https://github.com/BenMalaga/kindred/releases)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![dependencies](https://img.shields.io/badge/dependencies-0-blue)](package.json)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+</div>
+
+---
+
+If you maintain a handful of small repos, you know the pattern. You copy a LICENSE, a `.gitignore`, a CI workflow from the last project into the new one. Six months later one repo has a fixed workflow, another has a stale `.gitignore`, a third never got `CONTRIBUTING.md` at all. There is a shared template in there somewhere. It just lives in your head.
+
+kindred scans a folder of sibling git repos, clusters the files they share, and prints a drift matrix: which files are identical everywhere, which have drifted (and by how much), and which repos are missing them entirely. No template file, no manifest, no config. The repos themselves are the template.
+
+It is strictly read-only. kindred never writes a single byte inside the repos it scans.
+
+## A real run
+
+This is actual output from running kindred on the folder where kindred itself was built, alongside its sibling projects:
+
+```
+$ kindred scan "/Users/benmalaga/Github Projects"
+4 repos under /Users/benmalaga/Github Projects:
+  claudemd-check, lockbisect, nopus, wastegate
+
+file                        claudemd-check  lockbisect  nopus  wastegate
+--------------------------  --------------  ----------  -----  ---------
+.github/workflows/test.yml  =               =           --     =
+.gitignore                  ~75%            =           =      =
+CONTRIBUTING.md             --              =           ~24%   ~33%
+LICENSE                     =               =           =      =
+README.md                   =               ~30%        ~27%   ~33%
+package.json                =               ~58%        ~56%   ~57%
+src/cli.js                  =               ~26%        ~14%   ~31%
+
+legend: =  identical to reference   ~NN%  drifted (similarity)   --  missing
+7 shared files across 4 repos: 1 identical everywhere, 5 drifted, 2 missing somewhere
+```
+
+One glance tells the whole story: the LICENSE is in sync everywhere, `nopus` never got a CI workflow, `claudemd-check` is missing `CONTRIBUTING.md`, and one repo's `.gitignore` has drifted from the other three. To see exactly how, ask for the diff:
+
+```
+$ kindred diff .gitignore "/Users/benmalaga/Github Projects"
+--- lockbisect/.gitignore
++++ claudemd-check/.gitignore
+@@ -1,4 +1,4 @@
+ node_modules/
+ *.log
+ .DS_Store
+-*.tgz
++.claudemd-baseline.json
+```
+
+## Install
+
+No install needed:
+
+```sh
+npx kindred-drift scan ~/projects
+```
+
+Or install globally:
+
+```sh
+npm install -g kindred-drift
+kindred scan ~/projects
+```
+
+Or run straight from a clone (there are zero dependencies, so there is no `npm install` step):
+
+```sh
+git clone https://github.com/BenMalaga/kindred.git
+node kindred/bin/kindred.js scan ~/projects
+```
+
+> **Why `kindred-drift`?** The npm names `kindred` (a 2012 blogging engine) and `kindred-cli` were both already taken, so the package is published as `kindred-drift`. The binary is still `kindred`.
+
+Requires Node 18 or newer. Zero runtime dependencies, zero dev dependencies.
+
+## Usage
+
+```
+kindred scan [dir] [--json]    scan sibling git repos under dir (default: cwd)
+                               and print the drift matrix
+kindred diff <relpath> [dir]   unified diff between the variants of a shared file
+kindred --help                 show help
+kindred --version              show version
+```
+
+`scan` looks at the immediate subdirectories of `dir`, keeps the ones that are git repos, and compares the files they share. `--json` emits the full result (statuses and similarity scores per repo) for scripting.
+
+`diff` shows a unified diff between the reference variant of a shared file and every other variant. If all copies are identical it says so and exits 0. If the file is not shared, it exits 1.
+
+## How it works
+
+1. **Discover.** Immediate subdirectories of the target folder that contain `.git` are treated as sibling repos. Everything else is ignored, including half-checked-out folders that are not repos yet.
+
+2. **Collect.** Each repo is walked, skipping `node_modules`, `.git`, `dist`, `build`, `coverage`, and friends. Binary files, lockfiles (`package-lock.json`, `yarn.lock`, and other machine-generated files), and files over 1 MiB are excluded.
+
+3. **Cluster.** A file becomes a comparison cluster if its relative path appears in 2 or more repos, or if it is a well-known shareable file (LICENSE, `.gitignore`, anything under `.github/`, `tsconfig.json`, `.eslintrc*`, `CONTRIBUTING.md`, and so on) present in at least one repo. Well-known files are reported even when only one repo has them, because absence is drift too.
+
+4. **Normalize.** Before comparison, content is normalized: CRLF becomes LF, trailing whitespace is stripped, and runs of blank lines collapse to one. Two files that differ only cosmetically count as identical.
+
+5. **Compare.** Within each cluster, identical normalized content is grouped into variants. The variant held by the most repos becomes the reference (ties break toward the alphabetically first repo). Every other variant gets a similarity score against the reference: the normalized diff ratio `2 * LCS(a, b) / (|a| + |b|)` over lines, the same family of metric as Python's `difflib.ratio`. It is order-sensitive on purpose: reordered config is changed config. For very large file pairs, kindred falls back to a linear-time multiset overlap ratio.
+
+6. **Report.** Each repo's cell in the matrix is one of: `=` (holds the reference variant), `~NN%` (drifted, with similarity), or `--` (missing).
+
+## Why not cruft, copier, or repo-file-sync-action?
+
+Those are all excellent tools, and they all share one assumption: a declared template that exists before your repos do. [cruft](https://github.com/cruft/cruft) and [copier](https://github.com/copier-org/copier) check projects against a cookiecutter-style template repo. [repo-file-sync-action](https://github.com/BetaHuhn/repo-file-sync-action) pushes files from a designated source repo to targets you enumerate in a config file.
+
+kindred starts from the opposite end. Most people with five sibling repos never made a template; they made five repos that rhyme. kindred infers the implicit template you already have, by observation, and tells you where reality disagrees with it. There is nothing to set up, nothing to declare, and nothing to keep in sync about the syncing tool itself. Run one command in a folder you already have.
+
+If kindred convinces you that you want a real template, great: graduate to copier. Until then, you do not need one to see your drift.
+
+## Roadmap
+
+v1 is deliberately read-only: scan, matrix, diff. Planned next:
+
+- **`kindred bless <relpath> <repo>`**: mark one repo's variant as the canonical one for that file, recorded outside the scanned repos.
+- **`kindred apply <relpath>`**: copy the blessed (or reference) variant into the repos that drifted or lack the file, with a dry-run by default and per-repo confirmation. This will be the first and only command that writes into scanned repos, and it will be loudly explicit about it.
+- Similarity-based clustering of files whose paths differ but whose content rhymes (the `ci.yml` in one repo that is really the `test.yml` from the others).
+- `--fail-on-drift` exit codes for CI.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: zero dependencies, Node 18+, `node --test` must stay green, and scanning must stay read-only.
+
+## License
+
+[MIT](LICENSE) (c) 2026 Ben Malaga

package/bin/kindred.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+process.exit(main(process.argv.slice(2)));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "kindred-drift",
+  "version": "0.1.0",
+  "description": "Template-less drift detection for a folder of sibling repos",
+  "type": "module",
+  "bin": {
+    "kindred": "bin/kindred.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "drift",
+    "sync",
+    "cli",
+    "devtools",
+    "repos",
+    "template",
+    "diff",
+    "config"
+  ],
+  "author": "Ben Malaga",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BenMalaga/kindred.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BenMalaga/kindred/issues"
+  },
+  "homepage": "https://github.com/BenMalaga/kindred#readme"
+}

package/src/cli.js

@@ -0,0 +1,125 @@
+// CLI entry: argument parsing and command dispatch.
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { unifiedDiff } from './diff.js';
+import { renderMatrix, toJSON } from './render.js';
+import { scan } from './scan.js';
+
+const HELP = `kindred: template-less drift detection for a folder of sibling repos
+
+usage:
+  kindred scan [dir] [--json]    scan sibling git repos under dir (default: cwd)
+                                 and print the drift matrix
+  kindred diff <relpath> [dir]   unified diff between the variants of a shared file
+  kindred --help                 show this help
+  kindred --version              show version
+
+examples:
+  kindred scan ~/projects
+  kindred diff .gitignore ~/projects
+  npx kindred-drift scan .
+`;
+
+function version() {
+  const pkg = JSON.parse(
+    readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')
+  );
+  return pkg.version;
+}
+
+function cmdScan(args) {
+  const json = args.includes('--json');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const root = resolve(positional[0] ?? '.');
+  const result = scan(root);
+  if (json) {
+    process.stdout.write(`${JSON.stringify(toJSON(result), null, 2)}\n`);
+    return 0;
+  }
+  process.stdout.write(`${result.repos.length} repos under ${root}:\n`);
+  process.stdout.write(`  ${result.repos.join(', ')}\n\n`);
+  process.stdout.write(`${renderMatrix(result)}\n`);
+  return 0;
+}
+
+function cmdDiff(args) {
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const relpath = positional[0];
+  if (!relpath) {
+    process.stderr.write('usage: kindred diff <relpath> [dir]\n');
+    return 2;
+  }
+  const root = resolve(positional[1] ?? '.');
+  const result = scan(root);
+  const cluster = result.clusters.find((c) => c.relpath === relpath);
+  if (!cluster) {
+    process.stderr.write(`kindred: ${relpath} is not a shared file under ${root}\n`);
+    process.stderr.write('hint: run "kindred scan" to list shared files\n');
+    return 1;
+  }
+  if (cluster.variantCount === 1) {
+    const holders = [...cluster.statuses.entries()]
+      .filter(([, e]) => e.status !== 'missing')
+      .map(([repo]) => repo);
+    process.stdout.write(
+      `${relpath}: all ${holders.length} copies identical (${holders.join(', ')})\n`
+    );
+    return 0;
+  }
+
+  // Diff the reference variant against one representative of each other variant.
+  const ref = cluster.members.get(cluster.referenceRepo);
+  const seen = new Set([ref.hash]);
+  const chunks = [];
+  for (const [repo, entry] of cluster.members) {
+    if (seen.has(entry.hash)) continue;
+    seen.add(entry.hash);
+    chunks.push(
+      unifiedDiff(
+        ref.lines,
+        entry.lines,
+        `${cluster.referenceRepo}/${relpath}`,
+        `${repo}/${relpath}`
+      )
+    );
+  }
+  process.stdout.write(`${chunks.join('\n\n')}\n`);
+  return 0;
+}
+
+/**
+ * Run the CLI.
+ * @param {string[]} argv process.argv.slice(2)
+ * @returns {number} exit code
+ */
+export function main(argv) {
+  const [command, ...rest] = argv;
+  try {
+    switch (command) {
+      case 'scan':
+        return cmdScan(rest);
+      case 'diff':
+        return cmdDiff(rest);
+      case '--version':
+      case '-v':
+        process.stdout.write(`${version()}\n`);
+        return 0;
+      case undefined:
+      case '--help':
+      case '-h':
+      case 'help':
+        process.stdout.write(HELP);
+        return command === undefined ? 2 : 0;
+      default:
+        process.stderr.write(`kindred: unknown command "${command}"\n\n`);
+        process.stderr.write(HELP);
+        return 2;
+    }
+  } catch (err) {
+    process.stderr.write(`kindred: ${err.message}\n`);
+    return 1;
+  }
+}

package/src/cluster.js

@@ -0,0 +1,149 @@
+// Clustering: decide which files are comparable across sibling repos, and
+// compute a per-repo status for each cluster.
+//
+// A cluster is keyed by relative path. A relative path becomes a cluster if:
+//   - it exists in 2 or more repos (the implicit shared template), or
+//   - it is a well-known shareable file (LICENSE, .gitignore, anything under
+//     .github/, etc.) present in at least one repo. Absence of a well-known
+//     file is drift too, so those clusters are reported even with one member.
+//
+// Within a cluster, identical normalized content is grouped into variants.
+// The variant held by the most repos is the reference (ties break toward the
+// variant containing the alphabetically first repo). Each repo is then:
+//   - identical: holds the reference variant
+//   - drifted:   holds a different variant (with similarity vs the reference)
+//   - missing:   does not have the file
+
+import { similarity } from './similarity.js';
+
+export const WELL_KNOWN_BASENAMES = new Set([
+  'LICENSE',
+  'LICENSE.md',
+  'LICENSE.txt',
+  'LICENCE',
+  'COPYING',
+  'CONTRIBUTING.md',
+  'CODE_OF_CONDUCT.md',
+  'SECURITY.md',
+  '.gitignore',
+  '.gitattributes',
+  '.editorconfig',
+  '.npmrc',
+  '.nvmrc',
+  '.node-version',
+  '.dockerignore',
+  'Dockerfile',
+  'Makefile',
+  'tsconfig.json',
+  'jsconfig.json',
+  'eslint.config.js',
+  'eslint.config.mjs',
+  'eslint.config.cjs',
+  'prettier.config.js',
+  'prettier.config.mjs',
+  'rollup.config.js',
+  'vitest.config.js',
+  'vitest.config.ts',
+  'jest.config.js',
+  'babel.config.js',
+  'renovate.json',
+  '.releaserc'
+]);
+
+const WELL_KNOWN_PATTERNS = [
+  /^\.eslintrc(\..+)?$/u,
+  /^\.prettierrc(\..+)?$/u,
+  /^\.babelrc(\..+)?$/u,
+  /^\.stylelintrc(\..+)?$/u
+];
+
+/**
+ * Is this relative path a well-known shareable file?
+ * @param {string} relpath posix-style relative path within a repo
+ * @returns {boolean}
+ */
+export function isWellKnown(relpath) {
+  if (relpath.startsWith('.github/')) return true;
+  const base = relpath.includes('/') ? relpath.slice(relpath.lastIndexOf('/') + 1) : relpath;
+  if (WELL_KNOWN_BASENAMES.has(base)) return true;
+  return WELL_KNOWN_PATTERNS.some((re) => re.test(base));
+}
+
+/**
+ * Build the list of comparable relative paths.
+ * @param {Map<string, Set<string>>} repoPaths repo name -> set of relpaths
+ * @returns {string[]} sorted cluster keys
+ */
+export function clusterPaths(repoPaths) {
+  const counts = new Map();
+  for (const paths of repoPaths.values()) {
+    for (const relpath of paths) {
+      counts.set(relpath, (counts.get(relpath) ?? 0) + 1);
+    }
+  }
+  const keys = [];
+  for (const [relpath, count] of counts) {
+    if (count >= 2 || isWellKnown(relpath)) keys.push(relpath);
+  }
+  return keys.sort();
+}
+
+/**
+ * Compute variant groups and per-repo status for one cluster.
+ * @param {string} relpath the cluster key
+ * @param {Map<string, {hash: string, lines: string[]}>} members
+ *        repo name -> normalized content for repos that have the file
+ * @param {string[]} allRepos every repo in the scan, sorted
+ * @param {(a: string[], b: string[]) => number} [simFn] similarity function
+ * @returns {{
+ *   relpath: string,
+ *   variantCount: number,
+ *   referenceRepo: string,
+ *   statuses: Map<string, {status: 'identical'|'drifted'|'missing', similarity: number|null}>
+ * }}
+ */
+export function clusterStatus(relpath, members, allRepos, simFn = similarity) {
+  // Group repos by normalized content hash.
+  const variants = new Map(); // hash -> repo names (sorted because allRepos is)
+  for (const repo of allRepos) {
+    const entry = members.get(repo);
+    if (!entry) continue;
+    const list = variants.get(entry.hash);
+    if (list) list.push(repo);
+    else variants.set(entry.hash, [repo]);
+  }
+
+  // Reference variant: most repos; ties break toward the variant whose first
+  // (alphabetically smallest) repo sorts first.
+  let refHash = null;
+  let refRepos = [];
+  for (const [hash, repos] of variants) {
+    if (
+      repos.length > refRepos.length ||
+      (repos.length === refRepos.length && (refRepos.length === 0 || repos[0] < refRepos[0]))
+    ) {
+      refHash = hash;
+      refRepos = repos;
+    }
+  }
+  const refLines = members.get(refRepos[0]).lines;
+
+  const statuses = new Map();
+  for (const repo of allRepos) {
+    const entry = members.get(repo);
+    if (!entry) {
+      statuses.set(repo, { status: 'missing', similarity: null });
+    } else if (entry.hash === refHash) {
+      statuses.set(repo, { status: 'identical', similarity: 1 });
+    } else {
+      statuses.set(repo, { status: 'drifted', similarity: simFn(refLines, entry.lines) });
+    }
+  }
+
+  return {
+    relpath,
+    variantCount: variants.size,
+    referenceRepo: refRepos[0],
+    statuses
+  };
+}

package/src/diff.js

@@ -0,0 +1,111 @@
+// Minimal unified diff between two line arrays. Zero dependencies.
+// Classic LCS backtrack for edit script, then hunk assembly with context.
+
+const DIFF_CELL_LIMIT = 4_000_000;
+
+/**
+ * Edit script between two line arrays.
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {Array<{type: 'eq'|'del'|'add', line: string}>}
+ */
+export function diffOps(a, b) {
+  // Degenerate and oversized cases: whole-file replace.
+  if (a.length * b.length > DIFF_CELL_LIMIT) {
+    return [
+      ...a.map((line) => ({ type: 'del', line })),
+      ...b.map((line) => ({ type: 'add', line }))
+    ];
+  }
+
+  // Full LCS table (Uint32, one row per a-line) for backtracking.
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const table = new Uint32Array(rows * cols);
+  for (let i = 1; i < rows; i++) {
+    const ai = a[i - 1];
+    for (let j = 1; j < cols; j++) {
+      table[i * cols + j] =
+        ai === b[j - 1]
+          ? table[(i - 1) * cols + (j - 1)] + 1
+          : Math.max(table[(i - 1) * cols + j], table[i * cols + (j - 1)]);
+    }
+  }
+
+  const ops = [];
+  let i = a.length;
+  let j = b.length;
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      ops.push({ type: 'eq', line: a[i - 1] });
+      i--;
+      j--;
+    } else if (table[(i - 1) * cols + j] > table[i * cols + (j - 1)]) {
+      ops.push({ type: 'del', line: a[i - 1] });
+      i--;
+    } else {
+      ops.push({ type: 'add', line: b[j - 1] });
+      j--;
+    }
+  }
+  while (i > 0) ops.push({ type: 'del', line: a[--i] });
+  while (j > 0) ops.push({ type: 'add', line: b[--j] });
+  return ops.reverse();
+}
+
+/**
+ * Render a unified diff with @@ hunks.
+ * @param {string[]} a old lines
+ * @param {string[]} b new lines
+ * @param {string} aLabel
+ * @param {string} bLabel
+ * @param {number} [context]
+ * @returns {string} empty string when a and b are identical
+ */
+export function unifiedDiff(a, b, aLabel, bLabel, context = 3) {
+  const ops = diffOps(a, b);
+  if (ops.every((op) => op.type === 'eq')) return '';
+
+  // Annotate ops with line numbers.
+  let aLine = 1;
+  let bLine = 1;
+  const annotated = ops.map((op) => {
+    const entry = { ...op, aLine, bLine };
+    if (op.type !== 'add') aLine++;
+    if (op.type !== 'del') bLine++;
+    return entry;
+  });
+
+  // Group changed op indexes into hunks separated by > 2*context equal lines.
+  const changed = [];
+  annotated.forEach((op, idx) => {
+    if (op.type !== 'eq') changed.push(idx);
+  });
+  const groups = [];
+  let group = [changed[0]];
+  for (let k = 1; k < changed.length; k++) {
+    if (changed[k] - changed[k - 1] > context * 2) {
+      groups.push(group);
+      group = [];
+    }
+    group.push(changed[k]);
+  }
+  groups.push(group);
+
+  const out = [`--- ${aLabel}`, `+++ ${bLabel}`];
+  for (const g of groups) {
+    const start = Math.max(0, g[0] - context);
+    const end = Math.min(annotated.length - 1, g[g.length - 1] + context);
+    const slice = annotated.slice(start, end + 1);
+    const aCount = slice.filter((op) => op.type !== 'add').length;
+    const bCount = slice.filter((op) => op.type !== 'del').length;
+    const aStart = aCount === 0 ? slice[0].aLine - 1 : slice[0].aLine;
+    const bStart = bCount === 0 ? slice[0].bLine - 1 : slice[0].bLine;
+    out.push(`@@ -${aStart},${aCount} +${bStart},${bCount} @@`);
+    for (const op of slice) {
+      const prefix = op.type === 'eq' ? ' ' : op.type === 'del' ? '-' : '+';
+      out.push(prefix + op.line);
+    }
+  }
+  return out.join('\n');
+}

package/src/normalize.js

@@ -0,0 +1,44 @@
+// Content normalization: makes cosmetic differences invisible to comparison.
+// Two files that differ only in trailing whitespace, CRLF vs LF, or the
+// number of consecutive blank lines are treated as identical.
+
+/**
+ * Normalize file content into an array of lines.
+ * - Converts CRLF / CR line endings to LF.
+ * - Strips trailing whitespace from every line.
+ * - Collapses runs of 2+ blank lines into a single blank line.
+ * - Drops leading and trailing blank lines.
+ * @param {string} text raw file content
+ * @returns {string[]} normalized lines
+ */
+export function normalizeLines(text) {
+  const raw = String(text)
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(/[ \t]+$/u, ''));
+
+  const out = [];
+  let prevBlank = false;
+  for (const line of raw) {
+    if (line === '') {
+      if (!prevBlank) out.push('');
+      prevBlank = true;
+    } else {
+      out.push(line);
+      prevBlank = false;
+    }
+  }
+  while (out.length > 0 && out[0] === '') out.shift();
+  while (out.length > 0 && out[out.length - 1] === '') out.pop();
+  return out;
+}
+
+/**
+ * Normalize file content into a single string (lines joined by LF).
+ * @param {string} text raw file content
+ * @returns {string}
+ */
+export function normalizeText(text) {
+  return normalizeLines(text).join('\n');
+}

package/src/render.js

@@ -0,0 +1,91 @@
+// Text rendering of the drift matrix.
+
+/**
+ * Cell text for one repo status.
+ * @param {{status: string, similarity: number|null}} entry
+ * @returns {string}
+ */
+function cellText(entry) {
+  if (entry.status === 'identical') return '=';
+  if (entry.status === 'missing') return '--';
+  return `~${Math.round(entry.similarity * 100)}%`;
+}
+
+/**
+ * Render the drift matrix as a plain-text table.
+ * @param {{root: string, repos: string[], clusters: Array}} result
+ * @returns {string}
+ */
+export function renderMatrix(result) {
+  const { repos, clusters } = result;
+  if (clusters.length === 0) {
+    return `scanned ${repos.length} repos under ${result.root}: no shared files found`;
+  }
+
+  const pathWidth = Math.max(4, ...clusters.map((c) => c.relpath.length));
+  const colWidths = repos.map((r) =>
+    Math.max(
+      r.length,
+      ...clusters.map((c) => cellText(c.statuses.get(r)).length)
+    )
+  );
+
+  const lines = [];
+  lines.push(
+    `${'file'.padEnd(pathWidth)}  ${repos.map((r, i) => r.padEnd(colWidths[i])).join('  ')}`
+  );
+  lines.push(
+    `${'-'.repeat(pathWidth)}  ${colWidths.map((w) => '-'.repeat(w)).join('  ')}`
+  );
+  for (const cluster of clusters) {
+    const cells = repos.map((r, i) => cellText(cluster.statuses.get(r)).padEnd(colWidths[i]));
+    lines.push(`${cluster.relpath.padEnd(pathWidth)}  ${cells.join('  ')}`);
+  }
+
+  // Summary counts.
+  let identical = 0;
+  let drifted = 0;
+  let gaps = 0;
+  for (const cluster of clusters) {
+    const entries = [...cluster.statuses.values()];
+    const missing = entries.filter((e) => e.status === 'missing').length;
+    if (missing > 0) gaps++;
+    if (cluster.variantCount > 1) drifted++;
+    else if (missing === 0) identical++;
+  }
+
+  lines.push('');
+  lines.push('legend: =  identical to reference   ~NN%  drifted (similarity)   --  missing');
+  lines.push(
+    `${clusters.length} shared file${clusters.length === 1 ? '' : 's'} across ${repos.length} repos: ` +
+      `${identical} identical everywhere, ${drifted} drifted, ${gaps} missing somewhere`
+  );
+  return lines.join('\n');
+}
+
+/**
+ * JSON-serializable form of a scan result.
+ * @param {{root: string, repos: string[], clusters: Array}} result
+ * @returns {object}
+ */
+export function toJSON(result) {
+  return {
+    root: result.root,
+    repos: result.repos,
+    clusters: result.clusters.map((c) => ({
+      path: c.relpath,
+      variants: c.variantCount,
+      reference: c.referenceRepo,
+      repos: Object.fromEntries(
+        [...c.statuses.entries()].map(([repo, entry]) => [
+          repo,
+          {
+            status: entry.status,
+            similarity:
+              entry.similarity === null ? null : Math.round(entry.similarity * 1000) / 1000
+          }
+        ])
+      )
+    }))
+  };
+}

package/src/scan.js

@@ -0,0 +1,158 @@
+// Filesystem walking and scan orchestration. Strictly read-only: this module
+// only ever opens files for reading and never writes inside scanned repos.
+
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { clusterPaths, clusterStatus } from './cluster.js';
+import { normalizeLines } from './normalize.js';
+
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'vendor',
+  'target',
+  '.next',
+  '.nuxt',
+  '.turbo',
+  '.cache',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.pytest_cache',
+  '.idea'
+]);
+
+// Lockfiles are machine-generated and expected to differ; comparing them is
+// noise, not drift signal.
+const SKIP_FILES = new Set([
+  '.DS_Store',
+  'Thumbs.db',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lockb',
+  'bun.lock',
+  'Cargo.lock',
+  'poetry.lock',
+  'uv.lock',
+  'Gemfile.lock',
+  'composer.lock',
+  'go.sum'
+]);
+
+const MAX_FILE_BYTES = 1024 * 1024; // 1 MiB
+const MAX_DEPTH = 10;
+
+/**
+ * Immediate subdirectories of root that are git repos (have .git).
+ * @param {string} root
+ * @returns {Array<{name: string, path: string}>} sorted by name
+ */
+export function listRepos(root) {
+  const repos = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const path = join(root, entry.name);
+    if (existsSync(join(path, '.git'))) repos.push({ name: entry.name, path });
+  }
+  return repos.sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+/**
+ * Quick binary sniff: NUL byte in the first 8 KiB.
+ * @param {Buffer} buf
+ * @returns {boolean}
+ */
+function looksBinary(buf) {
+  return buf.subarray(0, 8192).includes(0);
+}
+
+/**
+ * Collect candidate file relpaths in a repo (text files, skip list applied).
+ * @param {string} repoPath
+ * @returns {Set<string>} posix-style relative paths
+ */
+export function collectFiles(repoPath) {
+  const found = new Set();
+  const walk = (dir, rel, depth) => {
+    if (depth > MAX_DEPTH) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const name = entry.name;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(name)) walk(join(dir, name), rel ? `${rel}/${name}` : name, depth + 1);
+      } else if (entry.isFile()) {
+        if (SKIP_FILES.has(name)) continue;
+        const relpath = rel ? `${rel}/${name}` : name;
+        try {
+          if (statSync(join(dir, name)).size > MAX_FILE_BYTES) continue;
+        } catch {
+          continue;
+        }
+        found.add(relpath);
+      }
+    }
+  };
+  walk(repoPath, '', 0);
+  return found;
+}
+
+/**
+ * Scan a folder of sibling repos and compute drift clusters.
+ * @param {string} root
+ * @returns {{
+ *   root: string,
+ *   repos: string[],
+ *   clusters: Array<ReturnType<typeof clusterStatus> & {members: Map<string, {hash: string, lines: string[]}>}>
+ * }}
+ */
+export function scan(root) {
+  const repos = listRepos(root);
+  if (repos.length < 2) {
+    throw new Error(
+      `need at least 2 git repos directly under ${root}, found ${repos.length}`
+    );
+  }
+
+  const repoPaths = new Map();
+  for (const repo of repos) repoPaths.set(repo.name, collectFiles(repo.path));
+
+  const keys = clusterPaths(repoPaths);
+  const repoNames = repos.map((r) => r.name);
+  const byName = new Map(repos.map((r) => [r.name, r.path]));
+
+  const clusters = [];
+  for (const relpath of keys) {
+    // Read and normalize content only for clustered files.
+    const members = new Map();
+    for (const repo of repoNames) {
+      if (!repoPaths.get(repo).has(relpath)) continue;
+      let buf;
+      try {
+        buf = readFileSync(join(byName.get(repo), ...relpath.split('/')));
+      } catch {
+        continue;
+      }
+      if (looksBinary(buf)) continue;
+      const lines = normalizeLines(buf.toString('utf8'));
+      const hash = createHash('sha256').update(lines.join('\n')).digest('hex');
+      members.set(repo, { hash, lines });
+    }
+    if (members.size === 0) continue;
+    clusters.push({ ...clusterStatus(relpath, members, repoNames), members });
+  }
+
+  return { root, repos: repoNames, clusters };
+}

package/src/similarity.js

@@ -0,0 +1,96 @@
+// Line-based similarity between two normalized files.
+//
+// Primary metric: normalized diff ratio, 2 * LCS(a, b) / (|a| + |b|).
+// This is the same family as difflib's ratio: 1.0 means identical line
+// sequences, 0.0 means no line in common. It is order-sensitive, which is
+// what you want for config files where reordering is a real change.
+//
+// For very large pairs (where the O(n*m) LCS table would be expensive) we
+// fall back to a multiset Jaccard-style ratio, which is order-insensitive
+// but linear time. Both return values in [0, 1].
+
+const LCS_CELL_LIMIT = 4_000_000; // ~2000 x 2000 lines
+
+/**
+ * Intern lines into integers so comparisons are cheap.
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {{a: Int32Array, b: Int32Array}}
+ */
+function intern(a, b) {
+  const table = new Map();
+  const enc = (line) => {
+    let id = table.get(line);
+    if (id === undefined) {
+      id = table.size;
+      table.set(line, id);
+    }
+    return id;
+  };
+  return {
+    a: Int32Array.from(a, enc),
+    b: Int32Array.from(b, enc)
+  };
+}
+
+/**
+ * Length of the longest common subsequence of two line arrays.
+ * Dynamic programming with two rolling rows: O(n*m) time, O(min) space.
+ * @param {string[]} aLines
+ * @param {string[]} bLines
+ * @returns {number}
+ */
+export function lcsLength(aLines, bLines) {
+  if (aLines.length === 0 || bLines.length === 0) return 0;
+  const { a, b } = intern(aLines, bLines);
+  let prev = new Int32Array(b.length + 1);
+  let curr = new Int32Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    const ai = a[i - 1];
+    for (let j = 1; j <= b.length; j++) {
+      curr[j] = ai === b[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], curr[j - 1]);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+/**
+ * Multiset Jaccard-style ratio: 2 * sum(min(countA, countB)) / (|a| + |b|).
+ * Order-insensitive, linear time. Used as the fallback for huge files.
+ * @param {string[]} aLines
+ * @param {string[]} bLines
+ * @returns {number} in [0, 1]
+ */
+export function multisetRatio(aLines, bLines) {
+  if (aLines.length === 0 && bLines.length === 0) return 1;
+  if (aLines.length === 0 || bLines.length === 0) return 0;
+  const counts = new Map();
+  for (const line of aLines) counts.set(line, (counts.get(line) ?? 0) + 1);
+  let common = 0;
+  for (const line of bLines) {
+    const c = counts.get(line) ?? 0;
+    if (c > 0) {
+      common++;
+      counts.set(line, c - 1);
+    }
+  }
+  return (2 * common) / (aLines.length + bLines.length);
+}
+
+/**
+ * Similarity between two normalized line arrays, in [0, 1].
+ * Uses the LCS diff ratio when the pair is small enough, otherwise the
+ * multiset ratio.
+ * @param {string[]} aLines
+ * @param {string[]} bLines
+ * @returns {number}
+ */
+export function similarity(aLines, bLines) {
+  if (aLines.length === 0 && bLines.length === 0) return 1;
+  if (aLines.length === 0 || bLines.length === 0) return 0;
+  if (aLines.length * bLines.length > LCS_CELL_LIMIT) {
+    return multisetRatio(aLines, bLines);
+  }
+  return (2 * lcsLength(aLines, bLines)) / (aLines.length + bLines.length);
+}