unitbob 0.5.1 → 0.6.0

package/README.md

@@ -95,3 +95,40 @@ self-contained — that is what they are designed for.
 - **Red lamp** — something the structure relied on broke. Copy its `id` and run
   step 3.
 - The project links itself by folder name — nothing to set up by hand.
+
+---
+
+## If your tests only run inside Docker
+
+Some projects keep the code on this machine and everything that runs it — the
+interpreter, the packages, the database — inside a container. Name that
+container in `.unitbob.json` and Unitbob starts the project's own commands in
+there:
+
+```json
+{ "server": "…", "repo_id": 3, "token": "…",
+  "exec": { "docker": { "container": "myapp-web-1" } } }
+```
+
+Nothing else changes. Files are still read and written here, and the path inside
+the container is worked out from the container's own mounts, so there is nothing
+else to configure. Leave the field out and everything runs on this machine,
+exactly as before.
+
+The project folder has to be **mounted** into the container rather than copied
+into the image — which it already is in any setup where you can edit a file and
+see the change. If it is not, Unitbob says so and stops before writing anything.
+
+Known limits of running in a container, all of them deliberate for now:
+
+- **A run that times out can leave a process alive inside the container.** The
+  timeout stops the `docker exec`, not necessarily what it started. A report
+  such a process writes afterwards is never counted as a later run's result.
+- **On a Linux host, files the container writes belong to `root`.** Unitbob does
+  not map users: guessing there breaks images that installed their packages as a
+  user of their own.
+- **Only a container that is already running.** A project whose tests go through
+  `docker compose run --rm` is not supported yet.
+- **Review at a fixed revision is not supported with a container.** It works in
+  a git worktree under the system's temporary directory, which is outside the
+  mount. Ordinary review works in the project itself and is unaffected.

package/dist/cli.js

@@ -11,6 +11,8 @@
 import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ensureLinked } from "./link.js";
+import { placeAdvice } from "./runner/placeAdvice.js";
+import { ToolchainUnavailableError } from "./runner/toolchain.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
 import { run, runOnly } from "./verbs/run.js";
@@ -147,7 +149,13 @@ export async function main(argv, deps = { ensureLinked }) {
         }
     }
     catch (err) {
-        process.stderr.write(`${err.message}\n`);
+        // Spec 36, §7.1. One `catch` already stands over every verb, and every hard
+        // stop reaches it — but it also catches "the server did not answer" and
+        // "your token was refused", and advising somebody with a dead Heroku to
+        // configure a container is a new kind of useless message. So the advice is
+        // attached to one named stop and to nothing else.
+        const advice = err instanceof ToolchainUnavailableError ? placeAdvice(err.projectRoot) : null;
+        process.stderr.write(`${err.message}\n${advice ? `\n${advice}\n` : ''}`);
         return 1;
     }
 }

package/dist/config.js

@@ -37,6 +37,23 @@ export function readLocalToken(cwd) {
     const token = readConfigField(cwd, 'token');
     return typeof token === 'string' && token.length > 0 ? token : null;
 }
+// The container this project's own processes run in, or null when they run on
+// this machine (spec 36). One field, one word: the path inside the container is
+// never asked for — it is read off the container's own mounts.
+//
+//     "exec": { "docker": { "container": "source_code-web-1" } }
+//
+// Absent means local, and local means byte-for-byte the behaviour this connector
+// has always had: no docker call, no new question, no new line of output.
+export function readLocalExecContainer(cwd) {
+    const exec = readConfigField(cwd, 'exec');
+    const docker = record(exec)?.['docker'];
+    const container = record(docker)?.['container'];
+    return typeof container === 'string' && container.trim().length > 0 ? container.trim() : null;
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
 function readConfigField(cwd, field) {
     const path = join(cwd, CONFIG_FILE);
     if (!existsSync(path))
@@ -73,6 +90,25 @@ export function locateLinkedRoot(cwd) {
             return null;
     }
 }
+// Write the link, and leave everything else in the file alone.
+//
+// It used to write exactly these three keys and nothing else, which quietly made
+// every other key disposable — and this function runs on ordinary events, a
+// re-link among them. Somebody who had written `exec` by hand would lose it
+// while fixing something unrelated, and the loss says nothing about itself: the
+// next run simply goes back to running on this machine.
 export function writeConfigFile(cwd, config) {
-    writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`);
+    const path = join(cwd, CONFIG_FILE);
+    let existing = {};
+    try {
+        const parsed = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch {
+        // Unparseable, so there is nothing to keep. Writing the link is still the
+        // right thing to do — it is what the caller came here for, and the file was
+        // no use to anybody in the state it was in.
+    }
+    writeFileSync(path, `${JSON.stringify({ ...existing, ...config }, null, 2)}\n`);
 }

package/dist/files/behavioral.js

@@ -10,6 +10,13 @@ import { BDD_RUN_ARTIFACTS } from "../runner/bdd.js";
 // blob only so `check` can execute it locally.
 export const BEHAVIORAL_DIR = '.unitbob/behavioral';
 export const BEHAVIORAL_WORLD_PATH = `${BEHAVIORAL_DIR}/step_definitions/00_unitbob_world.rb`;
+const BEHAVIORAL_WORLD_JS_PATH = `${BEHAVIORAL_DIR}/step_definitions/00_unitbob_world.js`;
+// A level above "step_definitions/", and deliberately. pytest loads every
+// conftest.py from the rootdir down to the directory it collects, so this one is
+// loaded — and the host's own "step_definitions/conftest.py", which the step
+// loading rules already promise them as the home for shared fixtures, stays
+// theirs. Claiming that filename here would take it away.
+const BEHAVIORAL_WORLD_PY_PATH = `${BEHAVIORAL_DIR}/conftest.py`;
 // The Ruby/Cucumber harness is connector-owned. Host agents own business steps;
 // this file owns only the stable Rails integration seam they build on.
 export const BEHAVIORAL_WORLD = `# Generated by Unitbob. DO NOT EDIT: suite materialization restores this file.
@@ -57,6 +64,46 @@ end
 
 World(UnitbobWorld)
 
+# Cucumber loads neither spec/rails_helper.rb nor spec/support/**, so every
+# switch this project's RSpec setup throws is still off here. Nothing said so:
+# the behavioral branch just behaved differently from the structural one, and
+# outgoing HTTP went to the real network while the structural branch had it
+# blocked (spec 35-1).
+#
+# Only what is the same in every Rails application belongs below. Anything that
+# depends on *this* application — signing in, factories, reading props, stubbing
+# a payment provider — stays in host-owned shared steps, where it always was.
+#
+# And not one step definition, here or anywhere in this file. That is a rule with
+# a mechanical reason: Cucumber loads every step file in the bundle into a single
+# flat namespace, so a step defined here would not merely risk colliding with a
+# worker's step — it would collide, and the run would stop on an ambiguous match
+# rather than fail with something a reader can act on.
+begin
+  require 'webmock/cucumber'
+  # Localhost stays reachable on purpose: a suite that talks to a local search or
+  # storage service is not the leak this closes, and blocking it would break runs
+  # that were never going out of the machine.
+  WebMock.disable_net_connect!(allow_localhost: true)
+rescue LoadError
+  warn '[unitbob] webmock could not be loaded: outgoing HTTP from this suite reaches the real network.'
+end
+
+if defined?(Sidekiq)
+  begin
+    require 'sidekiq/testing'
+    Sidekiq::Testing.fake!
+  rescue LoadError
+    warn '[unitbob] sidekiq/testing could not be loaded: Sidekiq jobs in this suite are not in fake mode.'
+  end
+end
+
+ActiveJob::Base.queue_adapter = :test if defined?(ActiveJob::Base)
+
+# The host the integration session already uses, so URL helpers agree with the
+# requests the steps make instead of raising for a missing default.
+Rails.application.routes.default_url_options[:host] ||= 'www.example.com'
+
 Before do
   @unitbob_time_zone = Time.zone
   @unitbob_locale = I18n.locale
@@ -84,10 +131,159 @@ After do
   raise mock_error if mock_error
 end
 `;
-export function materializeBehavioralWorld(projectRoot) {
-    const worldPath = join(projectRoot, BEHAVIORAL_WORLD_PATH);
+// The JS/TS peer of the file above. cucumber-js reads no test bootstrap of its
+// own either — and the connector's explicit `--require` switches off even its
+// own `features/support/` loading — so the branch had the same silence Ruby did.
+//
+// There is no cross-project equivalent of "Sidekiq in fake mode": a JavaScript
+// project has no one job runner. What is the same everywhere is the network, and
+// that is what this file settles.
+const BEHAVIORAL_WORLD_JS = `// Generated by Unitbob. DO NOT EDIT: suite materialization restores this file.
+'use strict';
+
+// cucumber-js loads none of this project's own test bootstrap — not its Vitest
+// setup files, and not \`features/support/\`, which the connector's explicit
+// \`--require\` switches off. Whatever your test setup switches on is still off
+// here, and on one Rails run the same silence sent live HTTP to the real network
+// while the structural peer had it blocked (spec 35-1).
+//
+// Only what is the same in every JavaScript project belongs below. Anything that
+// depends on *this* application — signing in, fixtures, seeding — stays in
+// host-owned shared steps, where it always was.
+//
+// And not one step definition, here or anywhere in this file. That is a rule with
+// a mechanical reason: cucumber-js registers every step in the bundle into a
+// single flat namespace, so a step defined here would not merely risk colliding
+// with a worker's step — it would collide, and the run would stop on an ambiguous
+// match rather than fail with something a reader can act on.
+const net = require('node:net');
+
+// Localhost stays reachable on purpose: a suite that talks to a local database,
+// search or storage service is not the leak this closes, and blocking it would
+// break runs that were never leaving the machine.
+function unitbobLeavesThisMachine(host) {
+  const name = String(host).replace(/^\\[|\\]$/g, '');
+  return !(name === 'localhost' || name === '::1' || name === '0.0.0.0' || name.startsWith('127.'));
+}
+
+// Guarded at the socket, not at \`http.request\`: Node's own \`fetch\` opens its
+// connections below that layer, so a guard one level up would have let the most
+// modern way to call out be the one way that still worked. Mocking libraries
+// (nock, msw) intercept above this and are unaffected.
+// \`Socket.prototype.connect\` is called in more shapes than its documentation
+// shows: \`(options)\`, \`(path)\`, \`(port, host)\`, and — from \`net.connect()\` and
+// therefore from Node's own \`fetch\` — an already normalized \`[options, callback]\`
+// array. Missing that last shape is not a narrower guard, it is no guard at all:
+// the options land where a callback was expected, the host reads as undefined,
+// and every outbound call is waved through.
+function unitbobTarget(args) {
+  const first = Array.isArray(args[0]) ? args[0][0] : args[0];
+  // A unix socket path is not a network address at all.
+  if (typeof first === 'string') return { path: first };
+  if (first !== null && typeof first === 'object') return { path: first.path, host: first.host };
+  return { host: typeof args[1] === 'string' ? args[1] : undefined };
+}
+
+const unitbobConnect = net.Socket.prototype.connect;
+net.Socket.prototype.connect = function unitbobGuardedConnect(...args) {
+  const { path, host } = unitbobTarget(args);
+
+  if (!path && unitbobLeavesThisMachine(host === undefined ? 'localhost' : host)) {
+    throw new Error(
+      '[unitbob] Refused a connection to ' + host + ': this suite must not reach the network. ' +
+      'Stub the boundary in your step definitions instead.',
+    );
+  }
+  return unitbobConnect.apply(this, args);
+};
+`;
+// The Python peer. pytest reads the connector's own ini through \`-c\`, so the
+// project's pytest settings do not apply, and only the conftest.py files on the
+// path from the repository root down to the collected directory are loaded —
+// which is to say a project's \`tests/conftest.py\` fixtures are not here either.
+const BEHAVIORAL_WORLD_PY = `# Generated by Unitbob. DO NOT EDIT: suite materialization restores this file.
+"""Connector-owned harness for the Unitbob behavioral suite.
+
+pytest runs here against the connector's own config ("-c"), so this project's
+pytest settings do not apply, and the only conftest.py files loaded are those on
+the path from the repository root down to "step_definitions/" — a
+"tests/conftest.py" is not one of them. Whatever your own test setup switches
+on is therefore still off, and on one Rails run that same silence sent live HTTP
+to the real network while the structural peer had it blocked (spec 35-1).
+
+Only what is the same in every Python project belongs here. Anything that depends
+on *this* application — signing in, factories, seeding — stays in host-owned
+shared steps and in your own "step_definitions/conftest.py", which this file
+deliberately does not claim.
+
+No step definitions live here, on purpose: step definitions belong to the workers
+that own their capability, and a shared one would collide with theirs.
+"""
+import socket
+
+_UNITBOB_LOCAL = ("localhost", "::1", "0.0.0.0", "")
+
+
+def _unitbob_leaves_this_machine(address):
+    # A unix socket path is a string, not an address tuple, and is not a network
+    # address at all.
+    if not isinstance(address, tuple) or not address:
+        return False
+    host = str(address[0]).strip("[]")
+    # Localhost stays reachable on purpose: a suite that talks to a local
+    # database, search or storage service is not the leak this closes, and
+    # blocking it would break runs that were never leaving the machine.
+    return not (host in _UNITBOB_LOCAL or host.startswith("127."))
+
+
+def _unitbob_refuse(address):
+    return OSError(
+        "[unitbob] Refused a connection to %s: this suite must not reach the "
+        "network. Stub the boundary in your step definitions instead." % (address,)
+    )
+
+
+# Guarded at the socket, so it holds for requests, urllib3, httpx, aiohttp and
+# anything else, rather than for the one HTTP client this file happened to know
+# about. Mocking libraries (responses, respx) intercept above this and are
+# unaffected.
+_unitbob_connect = socket.socket.connect
+_unitbob_connect_ex = socket.socket.connect_ex
+
+
+def _unitbob_guarded_connect(self, address):
+    if _unitbob_leaves_this_machine(address):
+        raise _unitbob_refuse(address)
+    return _unitbob_connect(self, address)
+
+
+def _unitbob_guarded_connect_ex(self, address):
+    if _unitbob_leaves_this_machine(address):
+        raise _unitbob_refuse(address)
+    return _unitbob_connect_ex(self, address)
+
+
+socket.socket.connect = _unitbob_guarded_connect
+socket.socket.connect_ex = _unitbob_guarded_connect_ex
+`;
+// One connector-owned harness per BDD runner, or nothing for a runner that has
+// none. Kept as one table so a fourth runner cannot be added with a step-loading
+// rule and no harness — the two halves of "what this branch runs inside".
+const BEHAVIORAL_WORLDS = {
+    cucumber: { path: BEHAVIORAL_WORLD_PATH, content: BEHAVIORAL_WORLD },
+    'cucumber-js': { path: BEHAVIORAL_WORLD_JS_PATH, content: BEHAVIORAL_WORLD_JS },
+    'pytest-bdd': { path: BEHAVIORAL_WORLD_PY_PATH, content: BEHAVIORAL_WORLD_PY },
+};
+export function behavioralWorldFor(runner) {
+    return BEHAVIORAL_WORLDS[runner];
+}
+export function materializeBehavioralWorld(projectRoot, runner = 'cucumber') {
+    const world = behavioralWorldFor(runner);
+    if (!world)
+        return null;
+    const worldPath = join(projectRoot, world.path);
     mkdirSync(dirname(worldPath), { recursive: true });
-    writeFileSync(worldPath, BEHAVIORAL_WORLD);
+    writeFileSync(worldPath, world.content);
     return worldPath;
 }
 // Write a behavioral artifact envelope (main file + support files) under the
@@ -98,8 +294,9 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     const files = [artifact, ...(artifact.support_files ?? [])];
     for (const file of files)
         assertUnitbobPath(file.path, BEHAVIORAL_DIR);
-    if (files.some((file) => file.path === BEHAVIORAL_WORLD_PATH)) {
-        throw new Error(`${BEHAVIORAL_WORLD_PATH} is the connector-owned World and cannot be supplied by the host artifact.`);
+    const world = behavioralWorldFor(runner);
+    if (world && files.some((file) => file.path === world.path)) {
+        throw new Error(`${world.path} is the connector-owned World and cannot be supplied by the host artifact.`);
     }
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
@@ -117,9 +314,7 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
         if (file === artifact)
             mainPath = dest;
     }
-    if (runner === 'cucumber') {
-        materializeBehavioralWorld(projectRoot);
-    }
+    materializeBehavioralWorld(projectRoot, runner);
     return { mainPath };
 }
 // Everything under the behavioral root that the next materialization will
@@ -136,10 +331,11 @@ export function filesLostOnMaterialize(projectRoot, artifact, runner) {
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     if (!existsSync(behavioralRoot))
         return [];
+    const connectorWorld = behavioralWorldFor(runner);
     const listed = new Set([
         artifact.path,
         ...(artifact.support_files ?? []).map((file) => file.path),
-        ...(runner === 'cucumber' ? [BEHAVIORAL_WORLD_PATH] : []),
+        ...(connectorWorld ? [connectorWorld.path] : []),
     ]);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     return readdirSync(behavioralRoot)
@@ -178,7 +374,11 @@ export function copyBehavioralRunnerEnvironment(sourceRoot, targetRoot, runner)
 // look like noise. Taken from the runner that writes them, never re-typed here.
 const CONNECTOR_RUN_ARTIFACTS = new Set(BDD_RUN_ARTIFACTS);
 const EMPTY_ENTRIES = new Set();
-const RUNNER_ENVIRONMENT_ENTRIES = {
+// What under the behavioral root is an *installed environment* rather than
+// generated text. Exported since spec 36: when the place a run happens in
+// changes, exactly these entries are thrown away so they can be installed again,
+// and the generated suite sitting beside them is left untouched.
+export const RUNNER_ENVIRONMENT_ENTRIES = {
     cucumber: new Set(['.bundle', 'Gemfile', 'Gemfile.lock']),
     'cucumber-js': new Set(['node_modules', 'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']),
     'pytest-bdd': new Set(['.venv']),

package/dist/files/guardrails.js

@@ -67,7 +67,7 @@ abort 'unitbob_helper: refusing to run against a non-test environment' unless Ra
 // runs need no connector-written support files here (the runtime pytest.ini
 // lives outside this directory and is written by the pytest runner).
 //
-// Every file, not just the main one (spec 42, §6.4). The directory is wiped
+// Every file, not just the main one (spec 43, §6.4). The directory is wiped
 // first and only the main file was written back, so a published suite of four
 // files came back as one and the run that followed it silently protected a
 // quarter of what the map claimed.

package/dist/files/suiteBuild.js

@@ -83,7 +83,7 @@ export function branchRunner(output) {
     return runner;
 }
 // What the reviewer actually read: the suite files, and the manifest that runs
-// them. Nothing else (spec 42, §4).
+// them. Nothing else (spec 43, §4).
 //
 // `test_metadata` used to be in here, and the server's copy of this formula
 // stripped the review's own keys back out to match — two lists that had to stay

package/dist/files/suiteBuildUpload.js

@@ -2,7 +2,7 @@ import { readBehavioralReview } from "./suiteBuild.js";
 // What travels to the server, and what "published" means when it answers. One
 // module, because two commands ask those questions: `put-suite-build` sends the
 // batch, and `validate-build` sends the same batch as a dry run so the server's
-// verdict is about the exact bytes the publish will carry (spec 42, §3).
+// verdict is about the exact bytes the publish will carry (spec 43, §3).
 //
 // A second assembly would be a second answer to "what are we uploading", and the
 // dry run would then be checking something the publish does not send — which is

package/dist/proc.js

@@ -2,7 +2,7 @@
 // captures stdout/stderr/exit code and hands them back untouched — shaping or
 // interpreting that output is the caller's (and ultimately Rails') job.
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 // Can this path actually be spawned? A binstub that exists but has lost its
 // executable bit is a real state — checkouts over a filesystem with no
@@ -19,6 +19,15 @@ export function executable(path) {
     }
 }
 export const GRAPHIFY_TIMEOUT_MS = 10 * 60 * 1000;
+// The raw spawn, and it stays raw: this is how the connector starts the tools it
+// brought with it. `graphify` is installed on the vibecoder's own machine and
+// only ever reads files, so it has no business travelling anywhere.
+//
+// A command that needs the *project's* dependencies goes through
+// `runInProject` (`runner/place.ts`) instead — those may have to start where the
+// project's toolchain lives, which is not always this machine (spec 36). The
+// boundary is deliberately visible at each call site rather than hidden in a
+// mode: which function is called is the whole rule.
 export function runProcess(command, args = [], options = {}) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd: options.cwd, env: options.env });
@@ -93,7 +102,14 @@ export const GRAPH_NOISE_PATTERNS = [
     // apps dumped libraries — on the measured app that folder was moment.js,
     // datatables.js and jquery.inputmask, against a single node of own code. A
     // modern Rails app keeps its own JS in `app/javascript/`, which stays.
-    'vendor/',
+    //
+    // Anchored to the repository root, and this is the whole difference between a
+    // pattern and a blind spot: a gitignore pattern whose only separator is the
+    // trailing one is *not* relative to the root, so a bare `vendor/` matched a
+    // `vendor` directory at any depth. On one real Rails app (2026-08-16) that
+    // took `app/controllers/vendor/` with it — the project's own contractor
+    // console, gone from the map for a whole run, with nothing said about it.
+    '/vendor/',
     'app/assets/javascripts/',
     'app/assets/builds/',
     'app/assets/config/',
@@ -135,8 +151,25 @@ export function ensureUnitbobIgnored(projectRoot) {
     // `.graphifyignore` is unitbob's own bookkeeping, like the other two entries —
     // the user never edits it, so it stays out of their commits.
     ensureLines(join(projectRoot, '.gitignore'), ['.unitbob/', 'graphify-out/', '.graphifyignore']);
+    // Before `ensureLines`, never after. `ensureLines` appends whatever the
+    // template is missing, so on an already-installed project the anchored form
+    // would land in the file *next to* the old unanchored one, and the old one
+    // would go on eating `app/**/vendor/` exactly as before.
+    replaceLine(join(projectRoot, '.graphifyignore'), 'vendor/', '/vendor/');
     ensureLines(join(projectRoot, '.graphifyignore'), GRAPH_NOISE_PATTERNS);
 }
+// Rewrite one line this connector wrote in an earlier release, and nothing else.
+// The comparison is exact on the trimmed line, so a line the user wrote —
+// `vendor/bundle/`, `# vendor`, anything else — is left byte for byte as they
+// wrote it. Idempotent: a second run finds nothing to replace.
+function replaceLine(path, from, to) {
+    if (!existsSync(path))
+        return;
+    const lines = readFileSync(path, 'utf8').split('\n');
+    if (!lines.some((line) => line.trim() === from))
+        return;
+    writeFileSync(path, lines.map((line) => (line.trim() === from ? to : line)).join('\n'));
+}
 // Appends whichever lines are missing, in one write, leaving the user's own
 // entries (and their order) untouched. Idempotent: a second run adds nothing.
 function ensureLines(path, lines) {
@@ -150,6 +183,93 @@ function ensureLines(path, lines) {
     const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
     writeFileSync(path, `${current}${prefix}${missing.join('\n')}\n`);
 }
+// What the ignore file actually costs, counted in files, pattern by pattern.
+//
+// This is the general cure and the reason it is worth more than the particular
+// one above: an ignore pattern is a silent instrument. Everything it matches
+// simply never reaches the graph, and the subsystem it swallowed leaves no trace
+// of having existed — which is how one over-broad line hid a whole console and
+// the run looked complete. Anchoring `/vendor/` fixes the blind spot we found;
+// this makes the next one visible, whichever pattern causes it.
+//
+// The whole file is read, not just this connector's own template: a line the
+// user wrote can hide a subsystem exactly as well as a line we wrote.
+export function ignoreExclusions(projectRoot) {
+    const path = join(projectRoot, '.graphifyignore');
+    if (!existsSync(path))
+        return [];
+    const counted = readFileSync(path, 'utf8')
+        .split('\n')
+        .flatMap((line) => {
+        const matcher = compileIgnorePattern(line);
+        return matcher ? [{ pattern: line.trim(), matcher, files: 0 }] : [];
+    });
+    if (counted.length === 0)
+        return [];
+    for (const file of filesUnder(projectRoot)) {
+        // Every pattern that matches is credited, not just the first: two patterns
+        // covering the same directory are each costing you those files, and picking
+        // a winner would report one of them as harmless.
+        for (const entry of counted) {
+            if (matchesIgnorePattern(file, entry.matcher))
+                entry.files += 1;
+        }
+    }
+    return counted.filter((entry) => entry.files > 0).map(({ pattern, files }) => ({ pattern, files }));
+}
+// The working subset of gitignore syntax — the part the patterns in this file
+// actually use. The rule that matters is the anchoring one: a pattern with a
+// separator anywhere but the end is relative to the repository root, and one
+// without is not. That single rule is the entire distance between `/vendor/`
+// and `vendor/`, so it is spelled out here rather than assumed.
+//
+// Negations (`!`) are not supported and are skipped rather than half-honoured:
+// counting a re-include as an exclusion would report a loss that never happened.
+function compileIgnorePattern(line) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('!'))
+        return null;
+    const dirOnly = trimmed.endsWith('/');
+    const path = dirOnly ? trimmed.slice(0, -1) : trimmed;
+    const anchored = path.includes('/');
+    const source = path.replace(/^\//, '').split('/').map(globSegment).join('/');
+    return { dirOnly, regex: new RegExp(anchored ? `^${source}$` : `^(?:.*/)?${source}$`) };
+}
+function globSegment(segment) {
+    return segment
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]');
+}
+function matchesIgnorePattern(relativePath, matcher) {
+    const parts = relativePath.split('/');
+    // A pattern ending in `/` matches directories only, so for a file it is the
+    // ancestors that have to match and never the file itself. Excluding a
+    // directory excludes everything under it, which is why every prefix is tried.
+    const deepest = matcher.dirOnly ? parts.length - 1 : parts.length;
+    for (let depth = 1; depth <= deepest; depth += 1) {
+        if (matcher.regex.test(parts.slice(0, depth).join('/')))
+            return true;
+    }
+    return false;
+}
+// Directories graphify drops on its own (see the note above
+// `GRAPH_NOISE_PATTERNS`), plus `.git`. Counting inside them would charge our
+// patterns for files that were never going to reach the graph anyway, and the
+// number the reader is weighing is "what did this line cost me".
+const ALREADY_OFF_THE_GRAPH = new Set([
+    '.git', 'node_modules', 'venv', '.venv', 'dist', 'build', 'target', 'out', '__pycache__',
+]);
+// Symlinks are neither followed nor counted: a link is not a file the graph
+// would have gained, and following one can walk forever.
+function filesUnder(root, relative = '') {
+    return readdirSync(join(root, relative), { withFileTypes: true }).flatMap((entry) => {
+        const path = relative ? `${relative}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            return ALREADY_OFF_THE_GRAPH.has(entry.name) ? [] : filesUnder(root, path);
+        return entry.isFile() ? [path] : [];
+    });
+}
 export async function runGraphifyExtractKeyless(projectRoot) {
     // Deterministic AST-only graph; no LLM, no API key. `update --force` re-extracts
     // the code and refreshes <root>/graphify-out/graph.json in place, replacing