unitbob 0.1.5 → 0.1.7

package/dist/files/guardrails.js

@@ -3,13 +3,25 @@ import { join } from 'node:path';
 export const GUARDRAILS_DIR = join('.unitbob', 'guardrails');
 export const SUITE_FILE = 'architecture_map_contracts_spec.rb';
 export const HELPER_FILE = 'unitbob_helper.rb';
+// An always-empty custom options file: pointing rspec's --options here keeps
+// the project's own .rspec (stray --require lines, extra stdout formatters)
+// out of guardrail runs, whose JSON output must stay parseable.
+export const OPTIONS_FILE = 'rspec.opts';
+// RSpec writes its JSON report here via `--out`, not to stdout: the app under
+// test can print to stdout during a run (Rails logging, deprecation notices, a
+// stray `puts`), which corrupts a stdout-parsed JSON document. A dedicated file
+// isolates the report from anything else the process emits.
+export const RESULT_FILE = 'rspec_result.json';
 // The boot file the generated suite requires (spec 29). Connector-owned and
 // versioned with it — never scaffolded into the project, never part of the
 // suite digest (that covers `spec_rb` bytes only). Delegates to the project's
 // own RSpec setup when one exists; boots the Rails test environment directly
-// when none does.
+// when none does. Both branches refuse a non-test environment — before boot
+// via ENV (nothing touched yet), after boot via Rails.env (config overrides).
 export const UNITBOB_HELPER_RB = `# frozen_string_literal: true
 # Written by the unitbob connector on every materialization — do not edit.
+ENV['RAILS_ENV'] ||= 'test'
+abort 'unitbob_helper: refusing to run against a non-test environment' unless ENV['RAILS_ENV'] == 'test'
 root = File.expand_path('../..', __dir__)
 if File.exist?(File.join(root, 'spec', 'rails_helper.rb'))
   # The project has its own RSpec setup — respect it (factories, cleaners…).
@@ -17,9 +29,7 @@ if File.exist?(File.join(root, 'spec', 'rails_helper.rb'))
   require 'rails_helper'
 else
   # No RSpec scaffolding — boot the Rails test environment directly.
-  ENV['RAILS_ENV'] ||= 'test'
   require File.join(root, 'config', 'environment')
-  abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
   require 'rspec/rails'
   ActiveRecord::Migration.maintain_test_schema!
   RSpec.configure do |config|
@@ -27,6 +37,7 @@ else
     config.infer_spec_type_from_file_location!
   end
 end
+abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
 `;
 export function materializeGuardrails(projectRoot, suite) {
     const dir = join(projectRoot, GUARDRAILS_DIR);
@@ -37,12 +48,13 @@ export function materializeGuardrails(projectRoot, suite) {
     materializeHelper(projectRoot);
     return { suitePath };
 }
-// Both flows boot the same way: the check flow writes the helper next to the
-// suite here, the suite-build flow writes it right after the precheck.
+// Both flows boot the same way: the check flow writes the boot kit next to
+// the suite here, the suite-build flow writes it right after the precheck.
 export function materializeHelper(projectRoot) {
     const dir = join(projectRoot, GUARDRAILS_DIR);
     mkdirSync(dir, { recursive: true });
     const helperPath = join(dir, HELPER_FILE);
     writeFileSync(helperPath, UNITBOB_HELPER_RB);
+    writeFileSync(join(dir, OPTIONS_FILE), '');
     return helperPath;
 }

package/dist/link.js

@@ -4,7 +4,7 @@
 // server key nobody is expected to know.
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { CONFIG_FILE, readLocalRepoId, writeConfigFile } from "./config.js";
 import { registerRepo, WireError } from "./wire.js";
 // Grill decision #1: hosted deployment is deferred; the local brain is the only
@@ -50,17 +50,32 @@ export function projectName(cwd) {
         if (!pointer)
             return basename(cwd);
         const gitdir = isAbsolute(pointer[1]) ? pointer[1] : resolve(cwd, pointer[1]);
-        const worktrees = dirname(gitdir); // <root>/.git/worktrees
-        const commonGit = dirname(worktrees); // <root>/.git
-        if (basename(worktrees) === 'worktrees' && basename(commonGit) === '.git') {
+        const commonGit = commonGitDir(gitdir);
+        if (commonGit === null)
+            return basename(cwd); // submodule (`.git/modules/…`) or exotic layout
+        if (basename(commonGit) === '.git')
             return basename(dirname(commonGit));
-        }
-        return basename(cwd); // submodule (`.git/modules/…`) or exotic layout
+        return basename(commonGit).replace(/\.git$/, '') || basename(cwd); // bare / separate git dir
     }
     catch {
         return basename(cwd); // no .git at all — git-less project
     }
 }
+// The main checkout's git dir for a worktree: git's own `commondir` pointer
+// inside the worktree admin dir works for every layout (bare main repo,
+// --separate-git-dir); the literal `<root>/.git/worktrees/<slug>` shape is
+// the fallback. null means "not a worktree we understand" — the caller falls
+// back to basename(cwd), so name resolution never fails linking.
+function commonGitDir(gitdir) {
+    const commondir = join(gitdir, 'commondir');
+    if (existsSync(commondir))
+        return resolve(gitdir, readFileSync(commondir, 'utf8').trim());
+    const worktrees = dirname(gitdir);
+    if (basename(worktrees) === 'worktrees' && basename(dirname(worktrees)) === '.git') {
+        return dirname(worktrees);
+    }
+    return null;
+}
 const PROJECT_MARKERS = ['Gemfile', 'gems.rb', 'package.json'];
 // Linking writes a file and creates a server row — only do that at a real
 // project root: never $HOME or the filesystem root, and the folder must be
@@ -68,12 +83,32 @@ const PROJECT_MARKERS = ['Gemfile', 'gems.rb', 'package.json'];
 // version control at all; the marker still keeps junk folders off the brain).
 export function assertProjectRoot(cwd) {
     const isFsRoot = dirname(cwd) === cwd;
-    const anchored = existsSync(join(cwd, '.git')) ||
-        PROJECT_MARKERS.some((marker) => existsSync(join(cwd, marker)));
+    const hasGit = existsSync(join(cwd, '.git'));
+    const anchored = hasGit || PROJECT_MARKERS.some((marker) => existsSync(join(cwd, marker)));
     if (isFsRoot || cwd === homedir() || !anchored) {
         throw new WireError(`${cwd} does not look like a project root (no .git and no project files ` +
             "(Gemfile/package.json) here) — run this from your project's root folder.");
     }
+    // A marker without .git can also mean a folder *inside* a bigger project —
+    // a monorepo sub-package, a Rails app's frontend/, node_modules. Those must
+    // never mint a brain repo: inside a checkout, the root is where .git is.
+    if (!hasGit) {
+        const enclosing = enclosingCheckout(cwd);
+        if (enclosing !== null || cwd.split(sep).includes('node_modules')) {
+            const hint = enclosing === null ? 'a dependency folder' : `the project at ${enclosing}`;
+            throw new WireError(`${cwd} looks like a folder inside ${hint} — run this from your project's root folder.`);
+        }
+    }
+}
+// Nearest ancestor carrying a .git, walking up to (but not including) $HOME —
+// a dotfiles repo in $HOME must not swallow every git-less project under it.
+function enclosingCheckout(cwd) {
+    const home = homedir();
+    for (let dir = dirname(cwd); dir !== home && dirname(dir) !== dir; dir = dirname(dir)) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+    }
+    return null;
 }
 const ARTIFACT_DIR = '.unitbob/';
 const GITIGNORE = '.gitignore';

package/dist/runner/precheck.js

@@ -6,7 +6,9 @@ export function runtimePrecheck(projectRoot) {
     if (!hasGemfileWith(projectRoot, /\brails\b/)) {
         return { ok: false, message: `${SUPPORTED} (no \`rails\` gem found in Gemfile.)` };
     }
-    if (!hasGemfileWith(projectRoot, /\brspec(-rails)?\b/)) {
+    // Specifically rspec-rails: the boot helper requires `rspec/rails`, so a
+    // bare `rspec` gem passes nothing downstream — stop with the honest offer.
+    if (!hasGemfileWith(projectRoot, /\brspec-rails\b/)) {
         return {
             ok: false,
             message: "Unitbob guardrails need the rspec-rails gem, which is not in this project's " +

package/dist/runner/rspec.js

@@ -1,7 +1,7 @@
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.js";
-import { GUARDRAILS_DIR, SUITE_FILE } from "../files/guardrails.js";
+import { GUARDRAILS_DIR, OPTIONS_FILE, RESULT_FILE, SUITE_FILE } from "../files/guardrails.js";
 export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // Spec 26: the Unitbob file runs in a defined order with a fixed seed so a
 // green→red flip can never come from run-order nondeterminism. It does not inherit
@@ -9,9 +9,40 @@ export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 export const RSPEC_SEED = '1';
 // Run the materialised Unitbob guardrail suite (spec 26). Only this file runs —
 // never the project's full suite — under RAILS_ENV=test with a fixed order/seed.
+// --options points at the materialized empty file so the project's own .rspec
+// (a --require of a helper we replaced, an extra stdout formatter) can neither
+// break the boot nor corrupt the JSON output. The JSON report goes to `--out`
+// (a file), not stdout, so the app's own stdout writes during the run can never
+// corrupt it.
 export async function runRspecSuite(projectRoot) {
     const suitePath = join(GUARDRAILS_DIR, SUITE_FILE);
-    return invokeRspec(projectRoot, [suitePath, '--order', 'defined', '--seed', RSPEC_SEED, '--format', 'json']);
+    const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
+    const resultPath = join(GUARDRAILS_DIR, RESULT_FILE);
+    const { result, command, args } = await invokeRspec(projectRoot, [
+        suitePath,
+        '--options',
+        optionsPath,
+        '--order',
+        'defined',
+        '--seed',
+        RSPEC_SEED,
+        '--format',
+        'json',
+        '--out',
+        resultPath,
+    ]);
+    return { ...result, command, args, jsonReport: readReport(join(projectRoot, resultPath)) };
+}
+// Read the `--out` report file back verbatim. A missing or unreadable file is a
+// clean empty string, not a throw: the caller falls back to stdout/stderr and
+// reports a suite error, exactly as it would for unparseable output.
+function readReport(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, 'utf8') : '';
+    }
+    catch {
+        return '';
+    }
 }
 // Prefer the project's own `bin/rspec`; fall back to `bundle exec rspec`. Every
 // run sets RAILS_ENV=test so guardrails execute against the Rails test
@@ -26,7 +57,7 @@ async function invokeRspec(projectRoot, rspecArgs) {
         timeoutMs: RSPEC_TIMEOUT_MS,
         env: { ...process.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
     });
-    return { ...result, command, args };
+    return { result, command, args };
 }
 function executable(path) {
     try {

package/dist/verbs/run.js

@@ -32,6 +32,7 @@ export async function run(config, _args, deps) {
         code: null,
         command: 'rspec',
         args: [],
+        jsonReport: '',
     }));
     const payload = rawRunPayload(suite.suite_digest, result);
     const summary = await d.postRun(payload);
@@ -39,8 +40,11 @@ export async function run(config, _args, deps) {
     if (summary.map_url)
         d.stdout.write(`${summary.map_url}\n`);
 }
+// The RSpec JSON report comes from the `--out` file (`jsonReport`), which the app
+// under test cannot pollute. Stdout is only a fallback for a runner double that
+// emits its report there; anything unparseable is a genuine suite error.
 function rawRunPayload(suiteDigest, result) {
-    const parsed = parseJsonObject(result.stdout);
+    const parsed = parseJsonObject(result.jsonReport) ?? parseJsonObject(result.stdout);
     if (parsed)
         return { suite_digest: suiteDigest, rspec_json: boundFailures(parsed) };
     return {

package/dist/verbs/show.js

@@ -1,5 +1,5 @@
 export function repoUrl(config) {
-    return `${config.server}/repos/${config.repoId}`;
+    return `${config.server}/repos/${config.repoId}#map`;
 }
 export async function show(config) {
     process.stdout.write(`${repoUrl(config)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {