Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

37.2 KB
Raw Blame
import childProcess, { execFileSync, spawnSync } from 'node:child_process';
import {
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  statSync,
  symlinkSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { syncBuiltinESMExports } from 'node:module';
import { tmpdir } from 'node:os';
import { basename, dirname, join } from 'node:path';
import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';
import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
import {
  loadScopeConfig,
  SCOPE_CONFIG_FILENAME,
  ScopeConfigError,
  ScopeConfigMissingError,
  unitsRequiringFiles,
} from './config.mjs';
import {
  diagnoseScope,
  discoverInScopeFiles,
  discoverInScopeFilesWithSkips,
  gitEnvironment,
  globToRegExp,
  isExcluded,
  isInScope,
  SUBJECT_ROOT as REPO_ROOT,
  scopeForRoot,
  subjectScope,
  unitFor,
} from './scope.mjs';
import { configWith, createScratchRoot, removeScratchRoots } from './scratch-root.test-helper.mjs';

const CONFIG = subjectScope().config;

const privateTestPath = (dir, stem) => `${dir}/${stem}.private.test.ts`;

describe('glob compilation', () => {
  const cases = [
    ['packages/**/src/**/*.ts', 'packages/app/src/lib/a.ts', true],
    ['packages/**/src/**/*.ts', 'packages/core/src/a.ts', true],
    ['packages/**/src/**/*.ts', 'packages/app/tests/a.ts', false],
    ['**/*.d.ts', 'docs/next-env.d.ts', true],
    ['**/*.d.ts', 'a.d.ts', true],
    ['**/*.d.mts', 'docs/next-env.d.mts', true],
    ['**/*.d.cts', 'docs/lib/types.d.cts', true],
    ['**/*.d.mts', 'docs/vitest.real-source.config.mts', false],
    ['*.ts', 'oxlint.config.ts', true],
    ['*.ts', 'docs/tailwind.config.ts', false],
    ['*.ts', 'vitest.scripts.config.mts', false],
    ['docs/**/*.mts', 'docs/vitest.real-source.config.mts', true],
    ['**/*.private.*', privateTestPath('packages/core/src', 'a'), true],
  ];

  test.each(cases)('%s vs %s is %s', (glob, path, expected) => {
    expect(globToRegExp(glob).test(path)).toBe(expected);
  });
});

describe('scope membership', () => {
  const inScope = [
    'packages/app/src/components/Foo.tsx',
    'packages/core/src/index.ts',
    'packages/desktop/tests/integration/a.ts',
    'scripts/comment-fidelity.mjs',
    '.github/scripts/bridge-public-pr-to-monorepo.mjs',
    'docs/tailwind.config.ts',
    'docs/vitest.real-source.config.mts',
    'docs/lib/a.cts',
    'oxlint.config.ts',
    'vitest.scripts.config.mts',
    'packages/desktop/scripts/afterPack.mjs',
    'packages/app/src/build/app-version.ts',
    'packages/app/src/build/rejection-loop-guard-script.js',
    'packages/desktop/tests/unit/packaged-report-path.uncached.test.mjs',
    'packages/app/tests/perf/fixtures/cache-regime-rotation/vault.ts',
    'packages/core/src/markdown/fixtures/index.ts',
    'test-support/vitest.base.ts',
    'test-support/strip-comments.test-helper.mjs',
    'plugins/ok/skills/bug-triage/scripts/bundle-forensics.mjs',
    'packages/app/src/lib/a.mjs',
    'packages/app/tests/fidelity/invariant-i17.test.ts',
    'packages/desktop/tests/lume-qa/scenarios/ok-e2e-claude.ts',
    'packages/desktop/tests/lume-qa/lume-qa-happy-path.e2e.ts',
    'scripts/lume-bake/bake.sh',
    'packages/app/scripts/perf-prod.sh',
    'packages/desktop/build/deb-postinst.sh',
    'plugins/ok/skills/linux-vm/scripts/linuxvm.sh',
    '.husky/pre-commit',
    '.husky/pre-push',
  ];
  const outOfScope = [
    'knip.config.ts',
    'packages/md-conformance/md-audit/src/lib/tags.ts',
    privateTestPath('packages/core/src/markdown', 'a'),
    'packages/app/src/locales/en/messages.ts',
    'docs/next-env.d.ts',
    'docs/next-env.d.mts',
    'docs/lib/types.d.cts',
    'types.d.mts',
    'lint-plugins/no-comments/__fixtures__/must-fire.fixture.ts',
    'packages/app/node_modules/x/src/a.ts',
    'tech-probes/r1-preflight-gate/probe.mjs',
    'packages/native-config/index.js',
    'packages/desktop/out/main/index.js',
    'packages/desktop/dist-desktop/linux-unpacked/resources/app/index.js',
    'packages/desktop/playwright-report/trace/assets/index.js',
    'packages/md-conformance/md-audit/src/lib/registry.mjs',
    '.claude/hooks/no-comments-guard.sh',
    'reports/comment-policy-adoption/scripts/measure.sh',
    'specs/2026-09-02-no-comments-substrate-hardening/probe.sh',
    'sandbox-recipes/claude-code/setup.sh',
    'packages/md-conformance/scripts/tournament-orchestrate.sh',
  ];

  test.each(inScope)('%s is in scope', (path) => expect(isInScope(path)).toBe(true));
  test.each(outOfScope)('%s is out of scope', (path) => expect(isInScope(path)).toBe(false));

  test('a windows-style path is normalised before matching', () => {
    expect(isInScope('packages\\app\\src\\a.ts')).toBe(true);
  });

  test('the fixture corpus is excluded so the gate cannot self-trip', () => {
    expect(CONFIG.exclude).toContain('**/__fixtures__/**');
    expect(CONFIG.exclude).toContain('**/*.fixture.ts');
  });

  test('an authored fixtures/ directory is ordinary source, not a carve-out', () => {
    expect(CONFIG.exclude).not.toContain('**/fixtures/**');
    expect(isInScope('packages/app/tests/perf/fixtures/generate-view-count-fixtures.ts')).toBe(
      true,
    );
  });
});

describe('the non-vacuity floor excuses a unit this tree does not carry', () => {
  const unitsFor = (roots) =>
    unitsRequiringFiles(
      loadScopeConfig(
        createScratchRoot({
          prefix: 'no-comments-floor-',
          config: configWith({
            units: [
              { id: 'app', family: 'typescript', roots: ['packages/*/src'] },
              { id: 'absent', family: 'typescript', roots },
            ],
          }),
          files: { 'packages/a/src/a.ts': 'export const a = 1;\n' },
        }),
      ),
    );

  test('a unit whose every declared root is absent is excused', () => {
    expect(unitsFor(['plugins'])).toEqual(['app']);
  });

  test('a unit whose root exists but holds no in-scope file is still required', () => {
    expect(unitsFor(['packages/*/src'])).toEqual(['app', 'absent']);
  });

  test('a unit carrying one present root and one absent root is still required', () => {
    expect(unitsFor(['plugins', 'packages/*/src'])).toEqual(['app', 'absent']);
  });

  test('a config that never stat-ed the tree is refused rather than read as all-present', () => {
    expect(() => unitsRequiringFiles({ units: CONFIG.units, declaredPaths: [] })).toThrow(
      /declaredAbsent/,
    );
  });
});

describe('discovery over the real tree', () => {
  const discovered = discoverInScopeFiles(REPO_ROOT, { readdirSync, statSync, lstatSync });

  test('discovery finds a substantial corpus', () => {
    expect(discovered.length).toBeGreaterThan(1000);
  });

  const required = unitsRequiringFiles(CONFIG);

  test('the non-vacuity floor itself covers units', () => {
    expect(required.length).toBeGreaterThan(0);
  });

  test.each(required)('unit %s is non-vacuous', (id) => {
    expect(discovered.filter((path) => unitFor(path) === id).length).toBeGreaterThan(0);
  });

  test('every discovered file belongs to exactly one declared unit', () => {
    expect(discovered.filter((path) => unitFor(path) === null)).toEqual([]);
  });

  test('every file discovery finds is a file git tracks', () => {
    const tracked = new Set(
      execFileSync('git', ['ls-files', '-z'], {
        cwd: REPO_ROOT,
        encoding: 'utf8',
        maxBuffer: 1 << 28,
      })
        .split('\0')
        .filter(Boolean),
    );
    expect(
      discovered.filter((path) => !tracked.has(path)),
      'track it if it is source, move it outside the declared roots if it is scratch, or add it ' +
        'to exclude if it is generated output',
    ).toEqual([]);
  });

  test('no excluded tree leaks into discovery', () => {
    const leaks = discovered.filter(
      (path) =>
        path.includes('node_modules/') ||
        path.includes('/dist/') ||
        path.includes('.private.') ||
        path.includes('md-conformance/') ||
        /\.d\.[mc]?ts$/.test(path),
    );
    expect(leaks).toEqual([]);
  });
});

describe('gitignored output is outside discovery', () => {
  afterAll(removeScratchRoots);

  let root;
  const expected = [
    'packages/desktop/out/tracked.ts',
    'packages/desktop/src/authoring.ts',
    'packages/desktop/src/tracked.ts',
  ];
  beforeAll(() => {
    root = createScratchRoot({
      prefix: 'no-comments-gitignore-',
      config: configWith({
        units: [{ id: 'desktop', family: 'typescript', roots: ['packages/desktop'] }],
      }),
      files: {
        '.gitignore': 'packages/desktop/out/\n',
        'packages/desktop/src/tracked.ts': 'export const tracked = true;\n',
        'packages/desktop/src/deleted.ts': 'export const deleted = true;\n',
        'packages/desktop/src/authoring.ts': 'export const authoring = true;\n',
        'packages/desktop/out/generated.ts': 'export const generated = true;\n',
        'packages/desktop/out/tracked.ts': 'export const trackedOutput = true;\n',
      },
    });
    symlinkSync('../src/tracked.ts', join(root, 'packages/desktop/out/linked.ts'));
    execFileSync('git', ['init', '-q'], { cwd: root });
    execFileSync(
      'git',
      [
        'add',
        '.gitignore',
        SCOPE_CONFIG_FILENAME,
        'packages/desktop/src/deleted.ts',
        'packages/desktop/src/tracked.ts',
      ],
      { cwd: root },
    );
    execFileSync('git', ['add', '-f', 'packages/desktop/out/tracked.ts'], { cwd: root });
    rmSync(join(root, 'packages/desktop/src/deleted.ts'));
  });

  test('retains tracked and untracked source while excluding ignored desktop output', () => {
    expect(discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toStrictEqual(
      expected,
    );
  });

  test('ignored skips disappear while a visible unreadable entry remains a refusal', () => {
    const unreadable = {
      readdirSync,
      statSync,
      lstatSync: (path) => {
        if (
          String(path).endsWith('/packages/desktop/out/generated.ts') ||
          String(path).endsWith('/packages/desktop/src/tracked.ts')
        ) {
          const error = new Error(`EACCES: simulated failure, lstat '${path}'`);
          error.code = 'EACCES';
          throw error;
        }
        return lstatSync(path);
      },
    };
    const result = discoverInScopeFilesWithSkips(root, unreadable);
    expect(result.skips).toStrictEqual([
      { path: 'packages/desktop/src/tracked.ts', reason: 'EACCES' },
    ]);
    expect(result.files).toStrictEqual([
      'packages/desktop/out/tracked.ts',
      'packages/desktop/src/authoring.ts',
    ]);
    expect(() => discoverInScopeFiles(root, unreadable)).toThrow(
      /packages\/desktop\/src\/tracked\.ts \(EACCES\)/,
    );
  });

  test('retains an unreadable ignored directory when it contains tracked source', () => {
    const root = createScratchRoot({
      config: configWith({}),
      files: {
        '.gitignore': 'packages/app/src/blocked/\n',
        'packages/app/src/blocked/tracked.ts': 'export const tracked = true;\n',
      },
    });
    for (const args of [
      ['init', '-q'],
      ['add', '-f', 'packages/app/src/blocked/tracked.ts'],
    ]) {
      expect(
        spawnSync('git', args, { cwd: root, env: { ...gitCleanEnv(), LC_ALL: 'C' } }).status,
      ).toBe(0);
    }
    expect(() =>
      discoverInScopeFiles(root, {
        lstatSync,
        statSync,
        readdirSync: (path) => {
          if (path === join(root, 'packages/app/src/blocked')) {
            throw Object.assign(new Error('unreadable directory'), { code: 'EACCES' });
          }
          return readdirSync(path);
        },
      }),
    ).toThrow(/packages\/app\/src\/blocked \(EACCES\)/);
  });

  test('keeps tracked source without repeating its index lookup for each ignore query', ({
    onTestFinished,
  }) => {
    const root = createScratchRoot({
      config: configWith({}),
      files: {
        '.gitignore': 'packages/app/src/tracked.ts\npackages/app/src/ignored.ts\n',
        'packages/app/src/tracked.ts': 'export const tracked = true;\n',
        'packages/app/src/authoring.ts': 'export const authoring = true;\n',
        'packages/app/src/ignored.ts': 'export const ignored = true;\n',
      },
    });
    for (const args of [
      ['init', '-q'],
      ['add', '-f', 'packages/app/src/tracked.ts'],
    ]) {
      const run = spawnSync('git', args, {
        cwd: root,
        env: { ...gitCleanEnv(), LC_ALL: 'C' },
        encoding: 'utf8',
      });
      expect({ status: run.status, error: run.error, stderr: run.stderr }).toEqual({
        status: 0,
        error: undefined,
        stderr: '',
      });
    }
    const calls = vi.spyOn(childProcess, 'spawnSync');
    syncBuiltinESMExports();
    onTestFinished(() => {
      calls.mockRestore();
      syncBuiltinESMExports();
    });
    const files = discoverInScopeFiles(root, { readdirSync, statSync, lstatSync });
    expect(files).toEqual(['packages/app/src/authoring.ts', 'packages/app/src/tracked.ts']);
    const queried = calls.mock.calls
      .filter(
        ([command, args, options]) =>
          command === 'git' && args[0] === 'check-ignore' && options.cwd === root,
      )
      .flatMap(([, , options]) => options.input.split('\0').filter(Boolean));
    expect(queried).toContain('packages/app/src/ignored.ts');
    expect(queried).not.toContain('packages/app/src/tracked.ts');
  });

  test('retains the index snapshot when membership changes before ignore matching', ({
    onTestFinished,
  }) => {
    const root = createScratchRoot({
      config: configWith({}),
      files: {
        '.gitignore': '*.ts\n',
        'packages/app/src/before.ts': 'export const before = true;\n',
        'packages/app/src/after.ts': 'export const after = true;\n',
      },
    });
    const options = { cwd: root, env: { ...gitCleanEnv(), LC_ALL: 'C' }, encoding: 'utf8' };
    for (const args of [
      ['init', '-q'],
      ['add', '-f', 'packages/app/src/before.ts'],
    ]) {
      expect(spawnSync('git', args, options).status).toBe(0);
    }
    const original = childProcess.spawnSync;
    let changed = false;
    const calls = vi.spyOn(childProcess, 'spawnSync').mockImplementation((command, args, opts) => {
      const result = original(command, args, opts);
      if (command === 'git' && args[0] === 'ls-files' && opts.cwd === root) {
        expect(
          original('git', ['rm', '--cached', 'packages/app/src/before.ts'], options).status,
        ).toBe(0);
        expect(original('git', ['add', '-f', 'packages/app/src/after.ts'], options).status).toBe(0);
        changed = true;
      }
      return result;
    });
    syncBuiltinESMExports();
    onTestFinished(() => {
      calls.mockRestore();
      syncBuiltinESMExports();
    });
    const files = discoverInScopeFiles(root, { readdirSync, statSync, lstatSync });
    expect(changed).toBe(true);
    expect(files).toEqual(['packages/app/src/before.ts']);
  });

  test('keeps Git refusals for paths inside an indexed submodule', () => {
    const root = createScratchRoot({
      config: configWith({}),
      files: { 'packages/app/src/probe.ts': 'export const probe = true;\n' },
    });
    const options = { cwd: root, env: { ...gitCleanEnv(), LC_ALL: 'C' }, encoding: 'utf8' };
    expect(spawnSync('git', ['init', '-q'], options).status).toBe(0);
    const object = spawnSync('git', ['hash-object', '-w', 'packages/app/src/probe.ts'], options);
    expect(object.status).toBe(0);
    expect(
      spawnSync(
        'git',
        ['update-index', '--add', '--cacheinfo', `160000,${object.stdout.trim()},packages/app`],
        options,
      ).status,
    ).toBe(0);
    expect(() => discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toThrow(
      /is in submodule/,
    );
  });

  test('inherited git redirection cannot retarget the ignore lookup', () => {
    const decoy = createScratchRoot({ prefix: 'no-comments-gitignore-decoy-' });
    execFileSync('git', ['init', '-q'], { cwd: decoy });
    const gitDirKey = 'GIT_DIR';
    const previous = Reflect.get(process.env, gitDirKey);
    Reflect.set(process.env, gitDirKey, join(decoy, '.git'));
    try {
      expect(discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toStrictEqual(
        expected,
      );
    } finally {
      if (previous === undefined) Reflect.deleteProperty(process.env, gitDirKey);
      else Reflect.set(process.env, gitDirKey, previous);
    }
  });

  test('missing Git fails with the spawn error instead of admitting ignored output', () => {
    const pathKey = 'PATH';
    const previous = Reflect.get(process.env, pathKey);
    const emptyPath = join(root, 'empty-path');
    mkdirSync(emptyPath);
    Reflect.set(process.env, pathKey, emptyPath);
    try {
      expect(() => discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toThrow(
        /git check-ignore failed in .*: no exit status \(spawnSync git ENOENT\)$/,
      );
    } finally {
      if (previous === undefined) Reflect.deleteProperty(process.env, pathKey);
      else Reflect.set(process.env, pathKey, previous);
    }
  });

  test('a Git that exits nonzero with nothing to say names the exit alone', () => {
    const pathKey = 'PATH';
    const previous = Reflect.get(process.env, pathKey);
    const shimPath = join(root, 'silent-exit-path');
    mkdirSync(shimPath);
    writeFileSync(join(shimPath, 'git'), '#!/bin/sh\ncat > /dev/null\nexit 3\n', { mode: 0o755 });
    Reflect.set(process.env, pathKey, `${shimPath}:${previous}`);
    try {
      expect(() => discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toThrow(
        /git check-ignore failed in .*: exit 3$/,
      );
    } finally {
      if (previous === undefined) Reflect.deleteProperty(process.env, pathKey);
      else Reflect.set(process.env, pathKey, previous);
    }
  });

  test('a signal-killed Git names the termination instead of echoing a bare token', () => {
    const pathKey = 'PATH';
    const previous = Reflect.get(process.env, pathKey);
    const shimPath = join(root, 'signal-path');
    mkdirSync(shimPath);
    writeFileSync(
      join(shimPath, 'git'),
      '#!/bin/sh\nwhile IFS= read -r _; do :; done\nkill -KILL $$\n',
      { mode: 0o755 },
    );
    Reflect.set(process.env, pathKey, shimPath);
    try {
      expect(() => discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toThrow(
        /git check-ignore failed in .*: killed by SIGKILL$/,
      );
    } finally {
      if (previous === undefined) Reflect.deleteProperty(process.env, pathKey);
      else Reflect.set(process.env, pathKey, previous);
    }
  });

  const walkerBeyondAnyPipeBuffer = () => {
    const padded = new Set();
    for (let bytes = 0; bytes < 1 << 20; ) {
      const name = `pad-${padded.size}.ts`;
      padded.add(name);
      bytes += `packages/desktop/src/${name}`.length + 1;
    }
    return {
      readdirSync: (path) =>
        String(path).endsWith('/packages/desktop/src')
          ? [...readdirSync(path), ...padded]
          : readdirSync(path),
      statSync,
      lstatSync: (path) =>
        padded.has(basename(String(path)))
          ? { isSymbolicLink: () => false, isDirectory: () => false }
          : lstatSync(path),
    };
  };

  test('a signal-killed Git still names the termination when the candidate write breaks', () => {
    const pathKey = 'PATH';
    const previous = Reflect.get(process.env, pathKey);
    const shimPath = join(root, 'broken-write-path');
    mkdirSync(shimPath);
    writeFileSync(join(shimPath, 'git'), '#!/bin/sh\nkill -KILL $$\n', { mode: 0o755 });
    Reflect.set(process.env, pathKey, shimPath);
    try {
      expect(() => discoverInScopeFiles(root, walkerBeyondAnyPipeBuffer())).toThrow(
        /git check-ignore failed.*killed by SIGKILL \(spawnSync git EPIPE\)/,
      );
    } finally {
      if (previous === undefined) Reflect.deleteProperty(process.env, pathKey);
      else Reflect.set(process.env, pathKey, previous);
    }
  });

  test('a Git that both complains and dies mid-write carries each account once', () => {
    const pathKey = 'PATH';
    const previous = Reflect.get(process.env, pathKey);
    const shimPath = join(root, 'loud-broken-write-path');
    mkdirSync(shimPath);
    writeFileSync(
      join(shimPath, 'git'),
      '#!/bin/sh\necho "fatal: bad config line 3" >&2\necho "  run git config to repair it" >&2\nexit 3\n',
      { mode: 0o755 },
    );
    Reflect.set(process.env, pathKey, shimPath);
    try {
      expect(() => discoverInScopeFiles(root, walkerBeyondAnyPipeBuffer())).toThrow(
        /git check-ignore failed in .*: exit 3 \(spawnSync git EPIPE; fatal: bad config line 3\n {2}run git config to repair it\)$/,
      );
    } finally {
      if (previous === undefined) Reflect.deleteProperty(process.env, pathKey);
      else Reflect.set(process.env, pathKey, previous);
    }
  });

  test('the local scrub stays aligned with the canonical Git environment helper', () => {
    const keysReadBy = (helper) => {
      const reads = new Set();
      const base = new Proxy(
        { KEEP: 'yes', LC_ALL: 'caller' },
        {
          get(target, key, receiver) {
            if (typeof key === 'string') reads.add(key);
            return Reflect.get(target, key, receiver);
          },
        },
      );
      helper(base);
      return reads;
    };
    const canonicalReads = keysReadBy(gitCleanEnv);
    const localReads = keysReadBy(gitEnvironment);
    expect(localReads).toStrictEqual(canonicalReads);
    const redirectKeys = [
      ...[...canonicalReads].filter((key) => key.startsWith('GIT_')),
      'GIT_CONFIG_KEY_0',
      'GIT_CONFIG_VALUE_0',
    ];
    const base = {
      KEEP: 'yes',
      LC_ALL: 'caller',
      ...Object.fromEntries(redirectKeys.map((key) => [key, 'redirect'])),
    };
    const local = gitEnvironment(base);
    expect(local).toStrictEqual({ ...gitCleanEnv(base), LC_ALL: 'C' });
    for (const key of redirectKeys) expect(local).not.toHaveProperty(key);
  });
});

describe('discovery from a nested Git worktree root', () => {
  afterAll(removeScratchRoots);

  let root;
  beforeAll(() => {
    root = createScratchRoot({
      prefix: 'no-comments-nested-git-',
      nest: 'public/open-knowledge',
      config: configWith({
        units: [{ id: 'desktop', family: 'typescript', roots: ['packages/desktop'] }],
      }),
      files: {
        'packages/desktop/src/authoring.ts': 'export const authoring = true;\n',
        'packages/desktop/out/generated.ts': 'export const generated = true;\n',
      },
    });
    const outer = dirname(dirname(root));
    writeFileSync(join(outer, '.gitignore'), 'public/open-knowledge/packages/desktop/out/\n');
    execFileSync('git', ['init', '-q'], { cwd: outer });
  });

  const discover = () => discoverInScopeFiles(root, { readdirSync, statSync, lstatSync });

  test('inherits ignore rules from the enclosing repository', () => {
    expect(discover()).toStrictEqual(['packages/desktop/src/authoring.ts']);
  });

  test('a strict-ancestor discovery ceiling cannot hide the enclosing repository', () => {
    const ceilingKey = 'GIT_CEILING_DIRECTORIES';
    const previousCeiling = Reflect.get(process.env, ceilingKey);
    Reflect.set(process.env, ceilingKey, dirname(root));
    try {
      expect(discover()).toStrictEqual(['packages/desktop/src/authoring.ts']);
    } finally {
      if (previousCeiling === undefined) Reflect.deleteProperty(process.env, ceilingKey);
      else Reflect.set(process.env, ceilingKey, previousCeiling);
    }
  });
});

describe('the scope definition is derived, not restated', () => {
  test('include is the flatten of the per-unit globs the matcher itself compiles', () => {
    expect(CONFIG.include).toEqual(CONFIG.units.flatMap((unit) => unit.include));
  });

  test('isInScope admits exactly the paths some unit claims', () => {
    const probes = CONFIG.include
      .map((glob) => glob.replace(/\*\*\//g, 'x/').replace(/\*/g, 'a'))
      .concat(['README.md', 'packages/md-conformance/anything.ts', 'packages/app/src/a.md']);
    expect(probes.filter((path) => isInScope(path) !== (unitFor(path) !== null))).toEqual([]);
  });

  test('the config the predicate reads is the one committed at the repository root', () => {
    expect(loadScopeConfig(REPO_ROOT).include).toEqual(CONFIG.include);
  });

  test('isExcluded reports the exclusion independently of the include set', () => {
    expect(isExcluded('packages/md-conformance/anything.ts')).toBe(true);
    expect(isExcluded('README.md')).toBe(false);
    expect(isInScope('README.md')).toBe(false);
  });
});

describe('a directory-name-shaped exclude prunes that directory during the walk', () => {
  const roots = [];
  afterAll(() => {
    for (const root of roots) rmSync(root, { recursive: true, force: true });
  });

  const syntheticRoot = (excludeGlob) => {
    const root = mkdtempSync(join(tmpdir(), 'no-comments-prune-'));
    roots.push(root);
    for (const rel of [
      'packages/pkg/src/real.ts',
      'packages/pkg/src/vendored/deep/one.ts',
      'packages/pkg/src/vendored/deep/two.ts',
    ]) {
      mkdirSync(dirname(join(root, rel)), { recursive: true });
      writeFileSync(join(root, rel), 'export const a = 1;\n');
    }
    writeFileSync(
      join(root, 'no-comments.config.jsonc'),
      JSON.stringify({
        version: 1,
        families: { ts: { extensions: ['.ts'], extractor: 'c-family' } },
        units: [{ id: 'src', family: 'ts', roots: ['packages/**/src'] }],
        exclude: [excludeGlob],
      }),
    );
    return root;
  };

  const discoverCountingReads = (root) => {
    const read = [];
    const files = discoverInScopeFiles(root, {
      readdirSync: (dir) => {
        read.push(basename(dir));
        return readdirSync(dir);
      },
      statSync,
      lstatSync,
    });
    return { files, read };
  };

  test('the same membership is reachable with and without the prune, so the rule is observable', () => {
    const pruned = discoverCountingReads(syntheticRoot('**/vendored/**'));
    const walked = discoverCountingReads(syntheticRoot('packages/pkg/src/vendored/**'));
    expect(pruned.files).toEqual(['packages/pkg/src/real.ts']);
    expect(walked.files).toEqual(pruned.files);
    expect(pruned.read).not.toContain('vendored');
    expect(walked.read).toContain('vendored');
    expect(walked.read).toContain('deep');
  });

  test('no directory a real-tree exclude names is ever read, and the walk did meet some', () => {
    const read = [];
    const met = [];
    discoverInScopeFiles(REPO_ROOT, {
      readdirSync: (dir) => {
        read.push(basename(dir));
        const entries = readdirSync(dir);
        for (const entry of entries) {
          if (CONFIG.pruneDirectories.includes(entry)) met.push(entry);
        }
        return entries;
      },
      statSync,
      lstatSync,
    });
    expect(read.filter((name) => CONFIG.pruneDirectories.includes(name))).toEqual([]);
    expect(met).toContain('node_modules');
    expect(met.length).toBeGreaterThan(1);
  });
});

describe('a unit can name files no extension would reach', () => {
  const roots = [];
  afterAll(() => {
    for (const root of roots) rmSync(root, { recursive: true, force: true });
  });

  const rootWithHooks = () => {
    const root = mkdtempSync(join(tmpdir(), 'no-comments-files-'));
    roots.push(root);
    writeFileSync(
      join(root, 'no-comments.config.jsonc'),
      JSON.stringify({
        version: 1,
        families: { shell: { extensions: ['.sh'], extractor: 'hash-family' } },
        units: [
          {
            id: 'shell',
            family: 'shell',
            roots: ['scripts'],
            files: ['.husky/pre-commit', '.husky/never-written'],
          },
        ],
        exclude: [],
      }),
    );
    for (const rel of ['scripts/build.sh', '.husky/pre-commit']) {
      mkdirSync(dirname(join(root, rel)), { recursive: true });
      writeFileSync(join(root, rel), '#!/usr/bin/env bash\n');
    }
    return root;
  };

  test('an extensionless member is discovered and attributed to the unit that names it', () => {
    const root = rootWithHooks();
    expect(discoverInScopeFiles(root, { readdirSync, statSync, lstatSync })).toStrictEqual([
      '.husky/pre-commit',
      'scripts/build.sh',
    ]);
    const scope = scopeForRoot(root);
    expect(scope.isInScope('.husky/pre-commit')).toBe(true);
    expect(scope.unitFor('.husky/pre-commit')).toBe('shell');
  });

  test('a named file the tree lacks is recorded as declared-absent, never as an error', () => {
    const root = rootWithHooks();
    const { declaredAbsent } = discoverInScopeFilesWithSkips(root, {
      readdirSync,
      statSync,
      lstatSync,
    });
    expect(declaredAbsent).toStrictEqual([
      { unit: 'shell', kind: 'file', path: '.husky/never-written' },
    ]);
  });
});

describe('a hash family may not declare a dialect no reference measures', () => {
  afterAll(removeScratchRoots);

  const rootDeclaring = (extensions) =>
    createScratchRoot({
      prefix: 'no-comments-unmeasured-dialect-',
      config: configWith({
        families: { probe: { extensions, extractor: 'hash-family' } },
        units: [{ id: 'probe', family: 'probe', roots: ['scripts'] }],
      }),
    });

  test('a .py family is refused at load, naming the dialect and what it lacks', () => {
    let thrown;
    try {
      scopeForRoot(rootDeclaring(['.py']));
    } catch (error) {
      thrown = error;
    }
    expect(thrown).toBeInstanceOf(ScopeConfigError);
    expect(thrown.key).toBe('families.probe.extensions');
    expect(thrown.message).toContain('python');
    expect(thrown.message).toContain('comment-position reference');
  });

  test('the refusal is the missing reference, not the hash family: a .sh family loads', () => {
    expect(scopeForRoot(rootDeclaring(['.sh'])).isInScope('scripts/build.sh')).toBe(true);
  });

  test('it names a move the adopter can make, not only one a contributor to this file can', () => {
    let thrown;
    try {
      scopeForRoot(rootDeclaring(['.sh', '.py']));
    } catch (error) {
      thrown = error;
    }
    expect(thrown).toBeInstanceOf(ScopeConfigError);
    expect(thrown.message).toContain('Drop .py from this family');
    expect(thrown.message).not.toContain('.sh from this family');
    expect(thrown.message).toContain('lint-plugins/no-comments/extract-hash.mjs');
    expect(thrown.message).toContain('DIALECTS');
  });
});

describe('a ./ prefix is a spelling, never a membership decision', () => {
  afterAll(removeScratchRoots);

  const TREE = {
    'packages/pkg/src/a.ts': 'export const a = 1;\n',
    'packages/pkg/src/vendored/deep/b.ts': 'export const b = 2;\n',
    'tools/present.ts': 'export const present = true;\n',
  };

  const rootDeclaring = ({ roots = ['packages/**/src'], files, exclude = [] }) =>
    createScratchRoot({
      prefix: 'no-comments-spelling-',
      config: {
        version: 1,
        families: { ts: { extensions: ['.ts'], extractor: 'c-family' } },
        units: [{ id: 'src', family: 'ts', roots, ...(files === undefined ? {} : { files }) }],
        exclude,
      },
      files: TREE,
    });

  const discover = (root) =>
    discoverInScopeFilesWithSkips(root, { readdirSync, statSync, lstatSync });

  const cells = [
    ['canonical spelling of a file the tree has', 'tools/present.ts', true],
    ['./ spelling of a file the tree has', './tools/present.ts', true],
    ['canonical spelling of a file the tree lacks', 'tools/missing.ts', false],
    ['./ spelling of a file the tree lacks', './tools/missing.ts', false],
  ];

  test.each(cells)('%s', (_label, entry, exists) => {
    const root = rootDeclaring({ files: [entry] });
    const { files, declaredAbsent } = discover(root);
    const canonical = entry.replace(/^\.\//, '');
    expect(scopeForRoot(root).unitFor(canonical)).toBe('src');
    expect(files.includes(canonical)).toBe(exists);
    expect(declaredAbsent).toStrictEqual(
      exists ? [] : [{ unit: 'src', kind: 'file', path: canonical }],
    );
  });

  test('a ./-prefixed exclude excludes exactly what its canonical spelling excludes', () => {
    const canonical = discover(rootDeclaring({ exclude: ['**/vendored/**'] }));
    const dotted = discover(rootDeclaring({ exclude: ['./**/vendored/**'] }));
    expect(canonical.files).toStrictEqual(['packages/pkg/src/a.ts']);
    expect(dotted.files).toStrictEqual(canonical.files);
  });

  test('a trailing-slash root discovers exactly what the bare root discovers', () => {
    const bare = discover(rootDeclaring({ roots: ['packages'] }));
    const slashed = discover(rootDeclaring({ roots: ['packages/'] }));
    expect(bare.files.length).toBeGreaterThan(0);
    expect(slashed.files).toStrictEqual(bare.files);
    expect(slashed.declaredAbsent).toStrictEqual(bare.declaredAbsent);
  });

  test('a root that leaves the tree is refused by name rather than walked', () => {
    const root = rootDeclaring({ roots: ['../outside'] });
    const diagnosis = diagnoseScope(root);
    expect(diagnosis.status).toBe('invalid');
    expect(diagnosis.key).toBe('units[0].roots[0]');
    expect(diagnosis.message).toContain('scope-config: UNREADABLE');
  });
});

describe('every directory-name-shaped exclude is pinned to what it hides', () => {
  const SHAPED = [
    '**/node_modules/**',
    '**/dist/**',
    '**/.next/**',
    '**/.turbo/**',
    '**/.git/**',
    '**/coverage/**',
    '**/__fixtures__/**',
    '**/playwright-report/**',
  ];

  const tracked = execFileSync('git', ['ls-files', '-z'], {
    cwd: REPO_ROOT,
    encoding: 'utf8',
    maxBuffer: 1 << 28,
  })
    .split('\0')
    .filter(Boolean);

  const includeRes = CONFIG.include.map(globToRegExp);
  const hiddenBy = (glob) => {
    const own = globToRegExp(glob);
    const others = CONFIG.exclude.filter((other) => other !== glob).map(globToRegExp);
    return tracked.filter(
      (path) =>
        includeRes.some((re) => re.test(path)) &&
        own.test(path) &&
        !others.some((re) => re.test(path)),
    );
  };

  test('the pinned list is exactly the directory-name-shaped excludes the config declares', () => {
    const shaped = CONFIG.exclude.filter((glob) => /^\*\*\/[^/*]+\/\*\*$/.test(glob));
    expect(shaped.slice().sort()).toEqual(SHAPED.slice().sort());
  });

  test.each(SHAPED)('%s hides no tracked in-scope file', (glob) => {
    expect(hiddenBy(glob)).toEqual([]);
  });

  test('no build-named glob hides tracked source under packages/app/src/build/', () => {
    expect(CONFIG.exclude).not.toContain('**/build/**');
    expect(CONFIG.exclude).not.toContain('packages/app/src/build/**');
    expect(isInScope('packages/app/src/build/rejection-loop-guard-plugin.ts')).toBe(true);
  });
});

test('globToRegExp refuses syntax it does not implement instead of mis-compiling it', () => {
  for (const glob of [
    'packages/**/{src,tests}/**/*.ts',
    'packages/**/*.?s',
    '!packages/foo/**',
    'src/[abc]/*.ts',
  ]) {
    expect(() => globToRegExp(glob), glob).toThrow(/unsupported glob syntax/);
  }
});

describe('a long-lived host reads the config as it is now, not as it was at first compile', () => {
  afterAll(removeScratchRoots);

  const PINNED_EPOCH_SECONDS = 1_700_000_000;

  const configScoping = (unitRoot) =>
    configWith({ units: [{ id: 'app', family: 'typescript', roots: [unitRoot] }] });

  let pinsIssued = 0;
  const pinDistinctMtime = (configPath) => {
    pinsIssued += 1;
    const seconds = PINNED_EPOCH_SECONDS + pinsIssued;
    utimesSync(configPath, seconds, seconds);
    return configPath;
  };

  const rootScoping = (unitRoot) => {
    const root = createScratchRoot({
      prefix: 'no-comments-config-mtime-',
      config: configScoping(unitRoot),
    });
    pinDistinctMtime(join(root, SCOPE_CONFIG_FILENAME));
    return root;
  };

  const writeConfig = (configPath, unitRoot) => {
    writeFileSync(configPath, `${JSON.stringify(configScoping(unitRoot), null, 2)}\n`);
    return configPath;
  };

  const rewrite = (root, unitRoot) =>
    pinDistinctMtime(writeConfig(join(root, SCOPE_CONFIG_FILENAME), unitRoot));

  test('an edit between two calls in one process moves the scope boundary with it', () => {
    const root = rootScoping('packages/*/src');
    expect(scopeForRoot(root).isInScope('packages/app/src/a.ts')).toBe(true);
    expect(scopeForRoot(root).isInScope('tools/a.ts')).toBe(false);

    rewrite(root, 'tools');

    expect(scopeForRoot(root).isInScope('tools/a.ts')).toBe(true);
    expect(scopeForRoot(root).isInScope('packages/app/src/a.ts')).toBe(false);
  });

  test('an unedited config keeps serving the compile it already paid for', () => {
    const root = rootScoping('packages/*/src');
    expect(scopeForRoot(root)).toBe(scopeForRoot(root));
  });

  test('a config deleted after it was compiled raises rather than serving the stale compile', () => {
    const root = rootScoping('packages/*/src');
    expect(scopeForRoot(root).isInScope('packages/app/src/a.ts')).toBe(true);

    rmSync(join(root, SCOPE_CONFIG_FILENAME));

    expect(() => scopeForRoot(root)).toThrow(ScopeConfigMissingError);
  });

  test('an edit that leaves the config mtime unchanged still moves the scope boundary', () => {
    const root = rootScoping('packages/*/src');
    const configPath = join(root, SCOPE_CONFIG_FILENAME);
    const mtimeAtFirstCompile = statSync(configPath).mtimeMs;

    expect(scopeForRoot(root).isInScope('packages/app/src/a.ts')).toBe(true);
    expect(scopeForRoot(root).isInScope('tools/a.ts')).toBe(false);

    writeConfig(configPath, 'tools');
    utimesSync(configPath, mtimeAtFirstCompile / 1000, mtimeAtFirstCompile / 1000);
    expect(statSync(configPath).mtimeMs).toBe(mtimeAtFirstCompile);
    expect(readFileSync(configPath, 'utf8')).toContain('"tools"');

    expect(scopeForRoot(root).isInScope('tools/a.ts')).toBe(true);
    expect(scopeForRoot(root).isInScope('packages/app/src/a.ts')).toBe(false);
  });
});