deepflow 0.1.89 → 0.1.91

package/bin/ratchet.test.js

@@ -0,0 +1,869 @@
+/**
+ * Tests for bin/ratchet.js — mechanical ratchet health-check script.
+ *
+ * Tests cover:
+ *   1. Project type detection from indicator files
+ *   2. Config override loading from .deepflow/config.yaml
+ *   3. Snapshot file loading and path absolutization
+ *   4. Command parsing (tokenizer)
+ *   5. Command building per project type
+ *   6. Health check stage ordering
+ *   7. JSON output format and exit codes
+ *   8. Source-level structural assertions
+ *
+ * Uses Node.js built-in node:test to avoid adding dependencies.
+ */
+
+'use strict';
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const RATCHET_PATH = path.resolve(__dirname, 'ratchet.js');
+const RATCHET_SRC = fs.readFileSync(RATCHET_PATH, 'utf8');
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'df-ratchet-test-'));
+}
+
+function rmrf(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Extract pure functions from ratchet.js source for unit testing.
+// We eval the module source with main() replaced by a no-op, then capture exports.
+// ---------------------------------------------------------------------------
+
+const extractedFns = (() => {
+  // Replace the main() call at the end with exports
+  const modifiedSrc = RATCHET_SRC
+    .replace(/^main\(\);?\s*$/m, '')  // Remove the main() call
+    .replace(/^#!.*$/m, '');           // Remove shebang
+
+  // Wrap in a function that returns the internal functions
+  const wrapped = `
+    ${modifiedSrc}
+    return {
+      detectProjectType,
+      loadConfig,
+      loadSnapshotFiles,
+      parseCommand,
+      hasNpmScript,
+      buildCommands,
+    };
+  `;
+
+  const factory = new Function('require', 'process', '__dirname', '__filename', 'module', 'exports', wrapped);
+  return factory(require, process, __dirname, __filename, module, exports);
+})();
+
+const {
+  detectProjectType,
+  loadConfig,
+  loadSnapshotFiles,
+  parseCommand,
+  hasNpmScript,
+  buildCommands,
+} = extractedFns;
+
+// ---------------------------------------------------------------------------
+// 1. Project type detection
+// ---------------------------------------------------------------------------
+
+describe('detectProjectType — detects from indicator files', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmrf(tmpDir); });
+
+  test('detects node project from package.json', () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+    assert.equal(detectProjectType(tmpDir), 'node');
+  });
+
+  test('detects python project from pyproject.toml', () => {
+    fs.writeFileSync(path.join(tmpDir, 'pyproject.toml'), '[project]');
+    assert.equal(detectProjectType(tmpDir), 'python');
+  });
+
+  test('detects rust project from Cargo.toml', () => {
+    fs.writeFileSync(path.join(tmpDir, 'Cargo.toml'), '[package]');
+    assert.equal(detectProjectType(tmpDir), 'rust');
+  });
+
+  test('detects go project from go.mod', () => {
+    fs.writeFileSync(path.join(tmpDir, 'go.mod'), 'module example');
+    assert.equal(detectProjectType(tmpDir), 'go');
+  });
+
+  test('returns unknown when no indicator files present', () => {
+    assert.equal(detectProjectType(tmpDir), 'unknown');
+  });
+
+  test('prefers node over python when both exist (package.json checked first)', () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+    fs.writeFileSync(path.join(tmpDir, 'pyproject.toml'), '[project]');
+    assert.equal(detectProjectType(tmpDir), 'node');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Config override loading
+// ---------------------------------------------------------------------------
+
+describe('loadConfig — reads .deepflow/config.yaml ratchet section', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmrf(tmpDir); });
+
+  test('returns empty object when config file does not exist', () => {
+    const cfg = loadConfig(tmpDir);
+    assert.deepEqual(cfg, {});
+  });
+
+  test('returns empty object when config has no matching keys', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'some_other_key: value\nmax_retries: 3\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.deepEqual(cfg, {});
+  });
+
+  test('parses build_command', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'build_command: make build\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.build_command, 'make build');
+  });
+
+  test('parses test_command', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'test_command: pytest -v\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.test_command, 'pytest -v');
+  });
+
+  test('parses typecheck_command', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'typecheck_command: mypy src/\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.typecheck_command, 'mypy src/');
+  });
+
+  test('parses lint_command', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'lint_command: eslint .\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.lint_command, 'eslint .');
+  });
+
+  test('parses all four commands from a single config', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      [
+        'build_command: npm run build',
+        'test_command: npm test',
+        'typecheck_command: tsc --noEmit',
+        'lint_command: eslint src/',
+      ].join('\n') + '\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.build_command, 'npm run build');
+    assert.equal(cfg.test_command, 'npm test');
+    assert.equal(cfg.typecheck_command, 'tsc --noEmit');
+    assert.equal(cfg.lint_command, 'eslint src/');
+  });
+
+  test('handles quoted values', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      "build_command: 'make all'\n"
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.build_command, 'make all');
+  });
+
+  test('handles double-quoted values', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'build_command: "cargo build --release"\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.build_command, 'cargo build --release');
+  });
+
+  test('ignores keys embedded in other lines (not at start of line)', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      '# build_command: should not match\nfoo_build_command: nope\n'
+    );
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.build_command, undefined);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Snapshot file loading and path absolutization
+// ---------------------------------------------------------------------------
+
+describe('loadSnapshotFiles — reads auto-snapshot.txt and absolutizes paths', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmrf(tmpDir); });
+
+  test('returns empty array when snapshot file does not exist', () => {
+    const files = loadSnapshotFiles(tmpDir);
+    assert.deepEqual(files, []);
+  });
+
+  test('returns empty array when snapshot file is empty', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(path.join(deepflowDir, 'auto-snapshot.txt'), '');
+    const files = loadSnapshotFiles(tmpDir);
+    assert.deepEqual(files, []);
+  });
+
+  test('absolutizes relative paths using repo root', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'bin/install.test.js\ntest/integration.test.js\n'
+    );
+    const files = loadSnapshotFiles(tmpDir);
+    assert.equal(files.length, 2);
+    assert.equal(files[0], path.join(tmpDir, 'bin/install.test.js'));
+    assert.equal(files[1], path.join(tmpDir, 'test/integration.test.js'));
+  });
+
+  test('trims whitespace from entries', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      '  test/a.js  \n  test/b.js  \n'
+    );
+    const files = loadSnapshotFiles(tmpDir);
+    assert.equal(files.length, 2);
+    assert.equal(files[0], path.join(tmpDir, 'test/a.js'));
+    assert.equal(files[1], path.join(tmpDir, 'test/b.js'));
+  });
+
+  test('ignores blank lines', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'a.js\n\n\nb.js\n\n'
+    );
+    const files = loadSnapshotFiles(tmpDir);
+    assert.equal(files.length, 2);
+  });
+
+  test('handles single entry', () => {
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'auto-snapshot.txt'),
+      'only-one.test.js\n'
+    );
+    const files = loadSnapshotFiles(tmpDir);
+    assert.equal(files.length, 1);
+    assert.equal(files[0], path.join(tmpDir, 'only-one.test.js'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Command parsing (tokenizer)
+// ---------------------------------------------------------------------------
+
+describe('parseCommand — tokenizes command strings', () => {
+  test('splits simple command into tokens', () => {
+    assert.deepEqual(parseCommand('npm run build'), ['npm', 'run', 'build']);
+  });
+
+  test('handles single command with no args', () => {
+    assert.deepEqual(parseCommand('pytest'), ['pytest']);
+  });
+
+  test('handles double-quoted arguments', () => {
+    assert.deepEqual(
+      parseCommand('echo "hello world" foo'),
+      ['echo', 'hello world', 'foo']
+    );
+  });
+
+  test('handles single-quoted arguments', () => {
+    assert.deepEqual(
+      parseCommand("echo 'hello world' bar"),
+      ['echo', 'hello world', 'bar']
+    );
+  });
+
+  test('handles multiple spaces between tokens', () => {
+    assert.deepEqual(
+      parseCommand('npm   run   test'),
+      ['npm', 'run', 'test']
+    );
+  });
+
+  test('handles empty string', () => {
+    assert.deepEqual(parseCommand(''), []);
+  });
+
+  test('handles command with flags', () => {
+    assert.deepEqual(
+      parseCommand('npx tsc --noEmit'),
+      ['npx', 'tsc', '--noEmit']
+    );
+  });
+
+  test('handles complex command with paths', () => {
+    assert.deepEqual(
+      parseCommand('node --test /path/to/file.js'),
+      ['node', '--test', '/path/to/file.js']
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. hasNpmScript
+// ---------------------------------------------------------------------------
+
+describe('hasNpmScript — checks package.json for scripts', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmrf(tmpDir); });
+
+  test('returns true when script exists', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ scripts: { build: 'tsc', test: 'jest' } })
+    );
+    assert.equal(hasNpmScript(tmpDir, 'build'), true);
+    assert.equal(hasNpmScript(tmpDir, 'test'), true);
+  });
+
+  test('returns false when script does not exist', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ scripts: { build: 'tsc' } })
+    );
+    assert.equal(hasNpmScript(tmpDir, 'lint'), false);
+  });
+
+  test('returns false when no scripts section', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ name: 'test' })
+    );
+    assert.equal(hasNpmScript(tmpDir, 'build'), false);
+  });
+
+  test('returns false when package.json does not exist', () => {
+    assert.equal(hasNpmScript(tmpDir, 'build'), false);
+  });
+
+  test('returns false when package.json is invalid JSON', () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), 'not json{{{');
+    assert.equal(hasNpmScript(tmpDir, 'build'), false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. buildCommands — per project type
+// ---------------------------------------------------------------------------
+
+describe('buildCommands — node project', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmrf(tmpDir); });
+
+  test('uses npm run build when package.json has build script', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ scripts: { build: 'tsc' } })
+    );
+    const cmds = buildCommands(tmpDir, 'node', [], {});
+    assert.equal(cmds.build, 'npm run build');
+  });
+
+  test('does not set build when no build script in package.json', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ scripts: {} })
+    );
+    const cmds = buildCommands(tmpDir, 'node', [], {});
+    assert.equal(cmds.build, undefined);
+  });
+
+  test('uses snapshot files for test command when available', () => {
+    const snapshotFiles = ['/abs/path/to/test1.js', '/abs/path/to/test2.js'];
+    const cmds = buildCommands(tmpDir, 'node', snapshotFiles, {});
+    assert.ok(Array.isArray(cmds.test));
+    assert.deepEqual(cmds.test, ['node', '--test', ...snapshotFiles]);
+  });
+
+  test('does not set test when no snapshot files and no config', () => {
+    const cmds = buildCommands(tmpDir, 'node', [], {});
+    assert.equal(cmds.test, undefined);
+  });
+
+  test('sets typecheck to npx tsc --noEmit by default', () => {
+    const cmds = buildCommands(tmpDir, 'node', [], {});
+    assert.equal(cmds.typecheck, 'npx tsc --noEmit');
+  });
+
+  test('uses npm run lint when package.json has lint script', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ scripts: { lint: 'eslint .' } })
+    );
+    const cmds = buildCommands(tmpDir, 'node', [], {});
+    assert.equal(cmds.lint, 'npm run lint');
+  });
+
+  test('config overrides take precedence over auto-detection', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({ scripts: { build: 'tsc', lint: 'eslint .' } })
+    );
+    const cfg = {
+      build_command: 'custom-build',
+      test_command: 'custom-test',
+      typecheck_command: 'custom-typecheck',
+      lint_command: 'custom-lint',
+    };
+    const cmds = buildCommands(tmpDir, 'node', ['/a.js'], cfg);
+    assert.equal(cmds.build, 'custom-build');
+    assert.equal(cmds.test, 'custom-test');
+    assert.equal(cmds.typecheck, 'custom-typecheck');
+    assert.equal(cmds.lint, 'custom-lint');
+  });
+});
+
+describe('buildCommands — python project', () => {
+  test('uses pytest with snapshot files when available', () => {
+    const snapshotFiles = ['/tests/test_a.py', '/tests/test_b.py'];
+    const cmds = buildCommands('/tmp', 'python', snapshotFiles, {});
+    assert.ok(Array.isArray(cmds.test));
+    assert.deepEqual(cmds.test, ['pytest', ...snapshotFiles]);
+  });
+
+  test('falls back to bare pytest when no snapshot files', () => {
+    const cmds = buildCommands('/tmp', 'python', [], {});
+    assert.equal(cmds.test, 'pytest');
+  });
+
+  test('sets mypy as default typecheck', () => {
+    const cmds = buildCommands('/tmp', 'python', [], {});
+    assert.equal(cmds.typecheck, 'mypy .');
+  });
+
+  test('sets ruff as default lint', () => {
+    const cmds = buildCommands('/tmp', 'python', [], {});
+    assert.equal(cmds.lint, 'ruff check .');
+  });
+
+  test('no build command by default', () => {
+    const cmds = buildCommands('/tmp', 'python', [], {});
+    assert.equal(cmds.build, undefined);
+  });
+});
+
+describe('buildCommands — rust project', () => {
+  test('sets cargo defaults', () => {
+    const cmds = buildCommands('/tmp', 'rust', [], {});
+    assert.equal(cmds.build, 'cargo build');
+    assert.equal(cmds.test, 'cargo test');
+    assert.equal(cmds.lint, 'cargo clippy');
+  });
+
+  test('no typecheck by default (cargo build covers it)', () => {
+    const cmds = buildCommands('/tmp', 'rust', [], {});
+    assert.equal(cmds.typecheck, undefined);
+  });
+});
+
+describe('buildCommands — go project', () => {
+  test('sets go defaults', () => {
+    const cmds = buildCommands('/tmp', 'go', [], {});
+    assert.equal(cmds.build, 'go build ./...');
+    assert.equal(cmds.test, 'go test ./...');
+    assert.equal(cmds.lint, 'go vet ./...');
+  });
+
+  test('no typecheck by default', () => {
+    const cmds = buildCommands('/tmp', 'go', [], {});
+    assert.equal(cmds.typecheck, undefined);
+  });
+});
+
+describe('buildCommands — unknown project type', () => {
+  test('returns empty commands with no config', () => {
+    const cmds = buildCommands('/tmp', 'unknown', [], {});
+    assert.equal(cmds.build, undefined);
+    assert.equal(cmds.test, undefined);
+    assert.equal(cmds.typecheck, undefined);
+    assert.equal(cmds.lint, undefined);
+  });
+
+  test('uses config overrides when provided', () => {
+    const cfg = {
+      build_command: 'make',
+      test_command: 'make test',
+      lint_command: 'make lint',
+    };
+    const cmds = buildCommands('/tmp', 'unknown', [], cfg);
+    assert.equal(cmds.build, 'make');
+    assert.equal(cmds.test, 'make test');
+    assert.equal(cmds.lint, 'make lint');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Health check stage ordering — source assertions
+// ---------------------------------------------------------------------------
+
+describe('STAGE_ORDER — build, test, typecheck, lint', () => {
+  test('source defines stages in correct order', () => {
+    const match = RATCHET_SRC.match(/STAGE_ORDER\s*=\s*\[([^\]]+)\]/);
+    assert.ok(match, 'STAGE_ORDER constant should exist in source');
+    const stages = match[1].replace(/['"]/g, '').split(',').map(s => s.trim());
+    assert.deepEqual(stages, ['build', 'test', 'typecheck', 'lint']);
+  });
+
+  test('only lint is SALVAGEABLE', () => {
+    const match = RATCHET_SRC.match(/SALVAGEABLE_STAGES\s*=\s*new Set\(\[([^\]]+)\]\)/);
+    assert.ok(match, 'SALVAGEABLE_STAGES constant should exist in source');
+    const stages = match[1].replace(/['"]/g, '').split(',').map(s => s.trim());
+    assert.deepEqual(stages, ['lint']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. JSON output format — source assertions
+// ---------------------------------------------------------------------------
+
+describe('JSON output — exactly one line with correct structure', () => {
+  test('PASS output is {"result":"PASS"}', () => {
+    assert.ok(
+      RATCHET_SRC.includes("JSON.stringify({ result: 'PASS' })"),
+      'Source should output {"result":"PASS"} for success'
+    );
+  });
+
+  test('FAIL output includes result, stage, and log', () => {
+    assert.ok(
+      RATCHET_SRC.includes("JSON.stringify({ result: 'FAIL', stage, log })"),
+      'Source should output {"result":"FAIL","stage":"...","log":"..."} for failures'
+    );
+  });
+
+  test('SALVAGEABLE output includes result, stage, and log', () => {
+    assert.ok(
+      RATCHET_SRC.includes("JSON.stringify({ result: 'SALVAGEABLE', stage, log })"),
+      'Source should output {"result":"SALVAGEABLE","stage":"...","log":"..."} for salvageable'
+    );
+  });
+
+  test('all outputs end with newline', () => {
+    const outputLines = RATCHET_SRC.match(/process\.stdout\.write\(JSON\.stringify\([^)]+\)\s*\+\s*'\\n'\)/g);
+    assert.ok(outputLines, 'Should have stdout.write calls with JSON');
+    assert.equal(outputLines.length, 3, 'Should have exactly 3 JSON output lines (PASS, FAIL, SALVAGEABLE)');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. Exit codes — 0=PASS, 1=FAIL, 2=SALVAGEABLE
+// ---------------------------------------------------------------------------
+
+describe('Exit codes — source assertions', () => {
+  test('PASS exits with 0', () => {
+    // Find the PASS block — it should call process.exit(0)
+    const passSection = RATCHET_SRC.match(/result:\s*'PASS'[\s\S]{0,100}process\.exit\((\d+)\)/);
+    assert.ok(passSection, 'PASS section should have process.exit');
+    assert.equal(passSection[1], '0');
+  });
+
+  test('FAIL exits with 1', () => {
+    const failSection = RATCHET_SRC.match(/result:\s*'FAIL'[\s\S]{0,100}process\.exit\((\d+)\)/);
+    assert.ok(failSection, 'FAIL section should have process.exit');
+    assert.equal(failSection[1], '1');
+  });
+
+  test('SALVAGEABLE exits with 2', () => {
+    const salvSection = RATCHET_SRC.match(/result:\s*'SALVAGEABLE'[\s\S]{0,100}process\.exit\((\d+)\)/);
+    assert.ok(salvSection, 'SALVAGEABLE section should have process.exit');
+    assert.equal(salvSection[1], '2');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 10. Auto-revert on FAIL — source assertions
+// ---------------------------------------------------------------------------
+
+describe('Auto-revert — source assertions', () => {
+  test('autoRevert function runs git revert HEAD --no-edit', () => {
+    assert.ok(
+      RATCHET_SRC.includes("'revert', 'HEAD', '--no-edit'"),
+      'autoRevert should call git revert HEAD --no-edit'
+    );
+  });
+
+  test('autoRevert is called before FAIL output (not for SALVAGEABLE)', () => {
+    // FAIL path: autoRevert(cwd) then stdout.write FAIL then exit(1)
+    const failBlock = RATCHET_SRC.match(/autoRevert\(cwd\)[\s\S]*?result:\s*'FAIL'/);
+    assert.ok(failBlock, 'autoRevert should be called before FAIL output');
+
+    // SALVAGEABLE path should NOT call autoRevert
+    // Extract text between SALVAGEABLE_STAGES.has(stage)) { and the closing else {
+    const salvIdx = RATCHET_SRC.indexOf('SALVAGEABLE_STAGES.has(stage)');
+    assert.ok(salvIdx !== -1, 'SALVAGEABLE_STAGES.has(stage) should exist in source');
+    const elseIdx = RATCHET_SRC.indexOf('} else {', salvIdx);
+    assert.ok(elseIdx !== -1, 'else block after SALVAGEABLE check should exist');
+    const salvBlock = RATCHET_SRC.slice(salvIdx, elseIdx);
+    assert.ok(
+      !salvBlock.includes('autoRevert'),
+      'SALVAGEABLE path should NOT call autoRevert'
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 11. Skip behavior — ENOENT handling
+// ---------------------------------------------------------------------------
+
+describe('Skip behavior — source assertions', () => {
+  test('runCommand returns ok:null on spawn error (ENOENT)', () => {
+    // Verify source handles result.error with ok: null
+    assert.ok(
+      RATCHET_SRC.includes('ok: null'),
+      'runCommand should return ok: null on spawn error'
+    );
+  });
+
+  test('main loop skips stage when ok is null', () => {
+    assert.ok(
+      RATCHET_SRC.includes('ok === null'),
+      'Main loop should check for ok === null to skip stages'
+    );
+  });
+
+  test('commandExists check runs before command execution for string commands', () => {
+    assert.ok(
+      RATCHET_SRC.includes('commandExists'),
+      'Source should use commandExists to check executables'
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 12. Subprocess integration tests — run ratchet.js in controlled environments
+// ---------------------------------------------------------------------------
+
+describe('Subprocess integration — controlled execution', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    // Initialize a minimal git repo so the script can find repo root
+    execFileSync('git', ['init'], { cwd: tmpDir, stdio: 'ignore' });
+    execFileSync('git', ['config', 'user.email', 'test@test.com'], { cwd: tmpDir, stdio: 'ignore' });
+    execFileSync('git', ['config', 'user.name', 'Test'], { cwd: tmpDir, stdio: 'ignore' });
+  });
+
+  afterEach(() => { rmrf(tmpDir); });
+
+  test('outputs valid JSON for unknown project type (PASS when no commands)', () => {
+    // No indicator files -> unknown project type -> no commands -> PASS
+    // Need at least one commit for git to work
+    fs.writeFileSync(path.join(tmpDir, 'dummy.txt'), 'hello');
+    execFileSync('git', ['add', '.'], { cwd: tmpDir, stdio: 'ignore' });
+    execFileSync('git', ['commit', '-m', 'init'], { cwd: tmpDir, stdio: 'ignore' });
+
+    const result = execFileSync(process.execPath, [RATCHET_PATH], {
+      cwd: tmpDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const parsed = JSON.parse(result.trim());
+    assert.equal(parsed.result, 'PASS');
+  });
+
+  test('exit code is 0 for PASS', () => {
+    fs.writeFileSync(path.join(tmpDir, 'dummy.txt'), 'hello');
+    execFileSync('git', ['add', '.'], { cwd: tmpDir, stdio: 'ignore' });
+    execFileSync('git', ['commit', '-m', 'init'], { cwd: tmpDir, stdio: 'ignore' });
+
+    try {
+      execFileSync(process.execPath, [RATCHET_PATH], {
+        cwd: tmpDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      // If we get here, exit code was 0
+      assert.ok(true);
+    } catch (err) {
+      assert.fail(`Expected exit code 0 but got ${err.status}`);
+    }
+  });
+
+  test('JSON output is exactly one line', () => {
+    fs.writeFileSync(path.join(tmpDir, 'dummy.txt'), 'hello');
+    execFileSync('git', ['add', '.'], { cwd: tmpDir, stdio: 'ignore' });
+    execFileSync('git', ['commit', '-m', 'init'], { cwd: tmpDir, stdio: 'ignore' });
+
+    const result = execFileSync(process.execPath, [RATCHET_PATH], {
+      cwd: tmpDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const lines = result.trim().split('\n');
+    assert.equal(lines.length, 1, 'Output should be exactly one line');
+    // Verify it parses as valid JSON
+    assert.doesNotThrow(() => JSON.parse(lines[0]));
+  });
+
+  test('FAIL exit code and JSON verified via extracted runCommand + buildCommands', () => {
+    // Instead of running the full script (which depends on mainRepoRoot git resolution),
+    // we test the failure path by directly exercising the extracted functions:
+    // buildCommands produces the commands, and we verify the source handles FAIL correctly.
+
+    // Verify that config override produces the expected build command
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'build_command: false\n'
+    );
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.build_command, 'false', 'Config should parse build_command');
+
+    const cmds = buildCommands(tmpDir, 'node', [], cfg);
+    assert.equal(cmds.build, 'false', 'buildCommands should use config override for build');
+
+    // Verify the source code path: when build fails -> autoRevert -> FAIL -> exit(1)
+    // Already covered by source assertions, but confirm the stage ordering
+    const stageMatch = RATCHET_SRC.match(/STAGE_ORDER\s*=\s*\[([^\]]+)\]/);
+    const stages = stageMatch[1].replace(/['"]/g, '').split(',').map(s => s.trim());
+    assert.equal(stages[0], 'build', 'build should be first stage');
+
+    // Verify build is not in SALVAGEABLE_STAGES (so it results in FAIL, not SALVAGEABLE)
+    const salvMatch = RATCHET_SRC.match(/SALVAGEABLE_STAGES\s*=\s*new Set\(\[([^\]]+)\]\)/);
+    const salvStages = salvMatch[1].replace(/['"]/g, '').split(',').map(s => s.trim());
+    assert.ok(!salvStages.includes('build'), 'build should not be SALVAGEABLE');
+  });
+
+  test('SALVAGEABLE path verified via extracted functions for lint failure', () => {
+    // Same approach: verify the lint failure path produces SALVAGEABLE
+
+    const deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(deepflowDir, 'config.yaml'),
+      'lint_command: false\n'
+    );
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+
+    const cfg = loadConfig(tmpDir);
+    assert.equal(cfg.lint_command, 'false', 'Config should parse lint_command');
+
+    const cmds = buildCommands(tmpDir, 'node', [], cfg);
+    assert.equal(cmds.lint, 'false', 'buildCommands should use config override for lint');
+
+    // Verify lint IS in SALVAGEABLE_STAGES
+    const salvMatch = RATCHET_SRC.match(/SALVAGEABLE_STAGES\s*=\s*new Set\(\[([^\]]+)\]\)/);
+    const salvStages = salvMatch[1].replace(/['"]/g, '').split(',').map(s => s.trim());
+    assert.ok(salvStages.includes('lint'), 'lint should be in SALVAGEABLE_STAGES');
+
+    // Verify SALVAGEABLE path does NOT auto-revert (already tested in source assertions)
+    const salvIdx = RATCHET_SRC.indexOf('SALVAGEABLE_STAGES.has(stage)');
+    const elseIdx = RATCHET_SRC.indexOf('} else {', salvIdx);
+    const salvBlock = RATCHET_SRC.slice(salvIdx, elseIdx);
+    assert.ok(!salvBlock.includes('autoRevert'), 'SALVAGEABLE should not auto-revert');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 13. Structural invariants
+// ---------------------------------------------------------------------------
+
+describe('Structural invariants — source assertions', () => {
+  test('script is pure Node.js (no require of external packages)', () => {
+    const requires = RATCHET_SRC.match(/require\(['"]([^'"]+)['"]\)/g) || [];
+    for (const req of requires) {
+      const mod = req.match(/require\(['"]([^'"]+)['"]\)/)[1];
+      assert.ok(
+        mod.startsWith('node:') || ['fs', 'path', 'child_process'].includes(mod),
+        `Unexpected dependency: ${mod} — ratchet.js must be pure Node.js`
+      );
+    }
+  });
+
+  test('script has shebang line', () => {
+    assert.ok(
+      RATCHET_SRC.startsWith('#!/usr/bin/env node'),
+      'Script should start with #!/usr/bin/env node'
+    );
+  });
+
+  test('script uses strict mode', () => {
+    assert.ok(
+      RATCHET_SRC.includes("'use strict'"),
+      'Script should use strict mode'
+    );
+  });
+
+  test('main() is called at the end', () => {
+    const lastNonEmpty = RATCHET_SRC.trim().split('\n').filter(l => l.trim()).pop();
+    assert.equal(lastNonEmpty.trim(), 'main();');
+  });
+});