Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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);
});
});