@opensip-tools/fitness 1.0.4

package/src/framework/__tests__/define-check.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest';
+
+import { defineCheck } from '../define-check.js';
+
+describe('defineCheck', () => {
+  describe('analyze mode', () => {
+    const noFooCheck = defineCheck({
+      id: '11111111-1111-4111-8111-111111111111',
+      slug: 'no-foo',
+      description: 'flag any line containing FOO',
+      tags: ['quality'],
+      analyze: (content, filePath) => {
+        const out: { line: number; message: string; severity: 'error' | 'warning'; filePath: string }[] = [];
+        const lines = content.split('\n');
+        for (const [i, line] of lines.entries()) {
+          if (line?.includes('FOO')) {
+            out.push({ line: i + 1, message: 'FOO not allowed', severity: 'error', filePath });
+          }
+        }
+        return out;
+      },
+    });
+
+    it('returns a Check with the configured slug and id', () => {
+      expect(noFooCheck.config.slug).toBe('no-foo');
+      expect(noFooCheck.config.id).toBe('11111111-1111-4111-8111-111111111111');
+    });
+
+    it('defaults itemType to "files"', () => {
+      expect(noFooCheck.config.itemType).toBe('files');
+    });
+
+    it('marks scansFiles=true for analyze mode', () => {
+      expect(noFooCheck.config.scansFiles).toBe(true);
+    });
+
+    it('records analysisMode "analyze"', () => {
+      expect(noFooCheck.config.analysisMode).toBe('analyze');
+    });
+
+    it('preserves user-supplied tags', () => {
+      expect(noFooCheck.config.tags).toEqual(['quality']);
+    });
+
+    it('exposes a getScope() and getMatcher() pair', () => {
+      const scope = noFooCheck.getScope();
+      expect(scope.include).toEqual([]);
+      expect(noFooCheck.getMatcher('/tmp')).toBeDefined();
+    });
+  });
+
+  describe('analyzeAll mode', () => {
+    const allCheck = defineCheck({
+      id: '22222222-2222-4222-8222-222222222222',
+      slug: 'all-mode-check',
+      description: 'returns no violations',
+      tags: ['demo'],
+      // eslint-disable-next-line @typescript-eslint/require-await -- stub for shape verification
+      analyzeAll: async () => [],
+    });
+
+    it('records analysisMode "analyzeAll"', () => {
+      expect(allCheck.config.analysisMode).toBe('analyzeAll');
+    });
+
+    it('marks scansFiles=true for analyzeAll mode', () => {
+      expect(allCheck.config.scansFiles).toBe(true);
+    });
+  });
+
+  describe('command mode', () => {
+    const cmd = defineCheck({
+      id: '33333333-3333-4333-8333-333333333333',
+      slug: 'cmd-check',
+      description: 'shells out',
+      tags: ['demo'],
+      command: { bin: 'echo', args: ['hello'], parseOutput: () => [] },
+    });
+
+    it('records analysisMode "command"', () => {
+      expect(cmd.config.analysisMode).toBe('command');
+    });
+
+    it('marks scansFiles=false for command mode', () => {
+      expect(cmd.config.scansFiles).toBe(false);
+    });
+  });
+
+  describe('scope handling', () => {
+    it('passes through scope.languages and scope.concerns', () => {
+      const c = defineCheck({
+        id: '44444444-4444-4444-8444-444444444444',
+        slug: 'scoped',
+        description: 's',
+        tags: ['demo'],
+        scope: { languages: ['typescript', 'rust'], concerns: ['backend'] },
+        analyze: () => [],
+      });
+      expect(c.config.checkScope?.languages).toEqual(['typescript', 'rust']);
+      expect(c.config.checkScope?.concerns).toEqual(['backend']);
+    });
+
+    it('leaves checkScope undefined when scope is omitted', () => {
+      const c = defineCheck({
+        id: '55555555-5555-4555-8555-555555555555',
+        slug: 'unscoped',
+        description: 's',
+        tags: ['demo'],
+        analyze: () => [],
+      });
+      expect(c.config.checkScope).toBeUndefined();
+    });
+  });
+
+  describe('runtime metadata passthrough', () => {
+    it('preserves docs, disabled, confidence, and timeout', () => {
+      const c = defineCheck({
+        id: '66666666-6666-4666-8666-666666666666',
+        slug: 'with-meta',
+        description: 'meta',
+        tags: ['demo'],
+        docs: 'https://example.com/x',
+        disabled: true,
+        confidence: 'high',
+        timeout: 1234,
+        analyze: () => [],
+      });
+      expect(c.config.docs).toBe('https://example.com/x');
+      expect(c.config.disabled).toBe(true);
+      expect(c.config.confidence).toBe('high');
+      expect(c.config.timeout).toBe(1234);
+    });
+
+    it('copies fileTypes when provided', () => {
+      const c = defineCheck({
+        id: '77777777-7777-4777-8777-777777777777',
+        slug: 'typed',
+        description: 'd',
+        tags: ['demo'],
+        fileTypes: ['ts', 'tsx'],
+        analyze: () => [],
+      });
+      expect(c.config.fileTypes).toEqual(['ts', 'tsx']);
+    });
+  });
+
+  describe('validation', () => {
+    it('throws when id is missing', () => {
+      expect(() =>
+        // @ts-expect-error — testing the runtime guard
+        defineCheck({ slug: 'no-id', description: 'd', tags: [], analyze: () => [] }),
+      ).toThrow();
+    });
+
+    it('throws when id is not a UUID', () => {
+      expect(() =>
+        defineCheck({
+          id: 'not-a-uuid',
+          slug: 'bad-id',
+          description: 'd',
+          tags: ['demo'],
+          analyze: () => [],
+        }),
+      ).toThrow();
+    });
+
+    it('throws when slug is missing', () => {
+      expect(() =>
+        defineCheck({
+          id: '88888888-8888-4888-8888-888888888888',
+          // @ts-expect-error — testing the runtime guard
+          slug: undefined,
+          description: 'd',
+          tags: ['demo'],
+          analyze: () => [],
+        }),
+      ).toThrow();
+    });
+  });
+});

package/src/framework/__tests__/directive-inventory.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+
+import { parseDirectiveLine } from '../directive-inventory.js'
+
+describe('parseDirectiveLine', () => {
+  describe('line comments (// form)', () => {
+    it('parses @fitness-ignore-file with reason', () => {
+      const result = parseDirectiveLine('// @fitness-ignore-file no-console-log -- debug scaffold for this module')
+      expect(result).toEqual({ type: 'file', checkId: 'no-console-log', reason: 'debug scaffold for this module' })
+    })
+
+    it('parses @fitness-ignore-next-line without reason', () => {
+      const result = parseDirectiveLine('// @fitness-ignore-next-line no-any-types')
+      expect(result).toEqual({ type: 'next-line', checkId: 'no-any-types', reason: null })
+    })
+
+    it('rejects lines without the directive prefix', () => {
+      expect(parseDirectiveLine('// just a comment')).toBeNull()
+      expect(parseDirectiveLine('const x = 1;')).toBeNull()
+    })
+  })
+
+  describe('block comments (/* form) — parity with suppression parser', () => {
+    it('parses single-line block directive with reason', () => {
+      const result = parseDirectiveLine('/* @fitness-ignore-file no-console-log -- legacy file */')
+      expect(result).toEqual({ type: 'file', checkId: 'no-console-log', reason: 'legacy file' })
+    })
+
+    it('parses single-line block directive without reason', () => {
+      const result = parseDirectiveLine('/* @fitness-ignore-next-line no-any-types */')
+      expect(result).toEqual({ type: 'next-line', checkId: 'no-any-types', reason: null })
+    })
+
+    it('strips trailing whitespace before */', () => {
+      const result = parseDirectiveLine('/* @fitness-ignore-file some-check   */')
+      expect(result).toEqual({ type: 'file', checkId: 'some-check', reason: null })
+    })
+  })
+
+  describe('rejection cases', () => {
+    it('rejects directive without comment marker', () => {
+      expect(parseDirectiveLine('@fitness-ignore-file foo')).toBeNull()
+    })
+
+    it('rejects checkId with spaces', () => {
+      expect(parseDirectiveLine('// @fitness-ignore-file foo bar baz')).toBeNull()
+    })
+
+    it('rejects empty checkId', () => {
+      expect(parseDirectiveLine('// @fitness-ignore-file ')).toBeNull()
+    })
+  })
+})

package/src/framework/__tests__/execution-context.test.ts

@@ -0,0 +1,80 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { createExecutionContext } from '../execution-context.js'
+import { fileCache } from '../file-cache.js'
+import { PathMatcher } from '../path-matcher.js'
+
+let testDir: string
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'opensip-exec-ctx-'))
+})
+
+afterEach(() => {
+  fileCache.clear()
+  rmSync(testDir, { recursive: true, force: true })
+})
+
+describe('createExecutionContext > matchFiles fileCache fallback', () => {
+  // Regression test for the scope-resolver bug surfaced during the
+  // checks-builtin split: scope-empty checks (e.g. file-length-limit)
+  // were scanning every prewarmed file, including paths the user had
+  // explicitly listed in `globalExcludes`. The fix threads the run's
+  // globalExcludes through RunOptions into the matchFiles fallback.
+
+  // eslint-disable-next-line unicorn/consistent-function-scoping -- closes over describe-scoped `testDir`
+  function setupCachedFiles(): void {
+    mkdirSync(join(testDir, 'src'), { recursive: true })
+    mkdirSync(join(testDir, 'docs'), { recursive: true })
+    mkdirSync(join(testDir, 'tests', 'fixtures'), { recursive: true })
+
+    writeFileSync(join(testDir, 'src', 'a.ts'), 'export const a = 1')
+    writeFileSync(join(testDir, 'docs', 'design.md'), '# Design')
+    writeFileSync(join(testDir, 'tests', 'fixtures', 'sample.json'), '{}')
+  }
+
+  async function runMatchFiles(globalExcludes?: readonly string[]): Promise<readonly string[]> {
+    setupCachedFiles()
+    await fileCache.prewarm(testDir, ['**/*.ts', '**/*.md', '**/*.json'])
+
+    const matcher = PathMatcher.create({ cwd: testDir, include: [], exclude: [] })
+    const ctx = createExecutionContext(
+      { id: 'test-id', slug: 'test-slug', itemType: 'files' },
+      testDir,
+      matcher,
+      globalExcludes ? { globalExcludes } : undefined,
+    )
+    return ctx.matchFiles()
+  }
+
+  it('returns every cached path when no globalExcludes are provided', async () => {
+    const files = await runMatchFiles()
+    expect(files.length).toBe(3)
+    // Sanity: includes the docs and fixtures files that we'll exclude below
+    expect(files.some((f) => f.endsWith('docs/design.md'))).toBe(true)
+    expect(files.some((f) => f.endsWith('tests/fixtures/sample.json'))).toBe(true)
+  })
+
+  it('filters paths matching globalExcludes patterns out of the fallback', async () => {
+    const files = await runMatchFiles(['docs/**', 'tests/fixtures/**'])
+    expect(files.length).toBe(1)
+    expect(files[0]).toMatch(/src\/a\.ts$/)
+  })
+
+  it('honors extension-style globalExcludes (*.md, *.json)', async () => {
+    const files = await runMatchFiles(['**/*.md', '**/*.json'])
+    expect(files.length).toBe(1)
+    expect(files[0]).toMatch(/src\/a\.ts$/)
+  })
+
+  it('returns the unfiltered list when globalExcludes is an empty array', async () => {
+    // Empty array must not engage the matcher at all — otherwise we
+    // pay relative-path computation per file for no reason.
+    const files = await runMatchFiles([])
+    expect(files.length).toBe(3)
+  })
+})

package/src/framework/__tests__/file-accessor.test.ts

@@ -0,0 +1,121 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ValidationError } from '@opensip-tools/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { createFileAccessor } from '../file-accessor.js';
+import { fileCache } from '../file-cache.js';
+
+let testDir: string;
+
+beforeEach(() => {
+   
+  testDir = mkdtempSync(join(tmpdir(), 'opensip-fa-'));
+  fileCache.clear();
+});
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  fileCache.clear();
+});
+
+describe('createFileAccessor', () => {
+  it('exposes the configured paths via the readonly paths property', () => {
+    const acc = createFileAccessor(['/a.ts', '/b.ts']);
+    expect(acc.paths).toEqual(['/a.ts', '/b.ts']);
+  });
+
+  it('reads file content from disk via fileCache when not preloaded', async () => {
+    const path = join(testDir, 'x.ts');
+    writeFileSync(path, 'hi');
+    const acc = createFileAccessor([path]);
+    expect(await acc.read(path)).toBe('hi');
+  });
+
+  it('rejects reads of paths not in the configured set', async () => {
+    const acc = createFileAccessor(['/allowed.ts']);
+    await expect(acc.read('/disallowed.ts')).rejects.toThrow(ValidationError);
+  });
+
+  it('caches reads — second call returns the same content even if disk changed', async () => {
+    const path = join(testDir, 'cache.ts');
+    writeFileSync(path, 'first');
+    const acc = createFileAccessor([path]);
+    expect(await acc.read(path)).toBe('first');
+    writeFileSync(path, 'second');
+    // Cached
+    expect(await acc.read(path)).toBe('first');
+  });
+
+  it('throws ValidationError when a file exceeds 10 MB', async () => {
+    const path = join(testDir, 'big.txt');
+    // Use Buffer-write to avoid loading 11 MB of string into memory unnecessarily
+    writeFileSync(path, Buffer.alloc(11 * 1024 * 1024, 'a'));
+    const acc = createFileAccessor([path]);
+    await expect(acc.read(path)).rejects.toThrow(/File too large/);
+  });
+
+  it('readMany reads multiple files and returns a Map', async () => {
+    const a = join(testDir, 'a.ts');
+    const b = join(testDir, 'b.ts');
+    writeFileSync(a, 'A');
+    writeFileSync(b, 'B');
+    const acc = createFileAccessor([a, b]);
+    const map = await acc.readMany([a, b]);
+    expect(map.get(a)).toBe('A');
+    expect(map.get(b)).toBe('B');
+  });
+
+  it('readAll returns every configured path', async () => {
+    const a = join(testDir, 'a.ts');
+    writeFileSync(a, 'AA');
+    const acc = createFileAccessor([a]);
+    const map = await acc.readAll();
+    expect(map.size).toBe(1);
+    expect(map.get(a)).toBe('AA');
+  });
+
+  it('throws when an aborted signal is passed', async () => {
+    const ac = new AbortController();
+    ac.abort();
+    const path = join(testDir, 'z.ts');
+    writeFileSync(path, 'z');
+    const acc = createFileAccessor([path], { signal: ac.signal });
+    await expect(acc.read(path)).rejects.toThrow();
+  });
+
+  it('cachedCount reflects internal LRU size', async () => {
+    const path = join(testDir, 'cnt.ts');
+    writeFileSync(path, 'cnt');
+    const acc = createFileAccessor([path]) as unknown as { cachedCount: number; clearCache: () => void; read: (p: string) => Promise<string> };
+    expect(acc.cachedCount).toBe(0);
+    await acc.read(path);
+    expect(acc.cachedCount).toBe(1);
+    acc.clearCache();
+    expect(acc.cachedCount).toBe(0);
+  });
+
+  it('preferentially returns content from the global fileCache when prewarmed', async () => {
+    const path = join(testDir, 'p.ts');
+    writeFileSync(path, 'on-disk');
+    await fileCache.prewarm(testDir, ['p.ts']);
+    // Mutate disk; accessor should still return prewarmed content
+    writeFileSync(path, 'changed');
+    const acc = createFileAccessor([path]);
+    expect(await acc.read(path)).toBe('on-disk');
+  });
+
+  it('LRU eviction kicks in beyond the configured capacity', async () => {
+    const paths: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      const p = join(testDir, `${i}.ts`);
+      writeFileSync(p, String(i));
+      paths.push(p);
+    }
+    const acc = createFileAccessor(paths, { cacheCapacity: 2 }) as unknown as { cachedCount: number; read: (p: string) => Promise<string> };
+    for (const p of paths) await acc.read(p);
+    expect(acc.cachedCount).toBe(2);
+  });
+});

package/src/framework/__tests__/file-cache.test.ts

@@ -0,0 +1,142 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ValidationError } from '@opensip-tools/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { DEFAULT_PREWARM_PATTERNS, fileCache } from '../file-cache.js';
+
+let testDir: string;
+
+beforeEach(() => {
+   
+  testDir = mkdtempSync(join(tmpdir(), 'opensip-fc-'));
+  fileCache.clear();
+});
+
+afterEach(() => {
+  fileCache.clear();
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe('fileCache.prewarm', () => {
+  it('loads matching files into the cache', async () => {
+    writeFileSync(join(testDir, 'a.ts'), 'export const a = 1;');
+    writeFileSync(join(testDir, 'b.ts'), 'export const b = 2;');
+    const stats = await fileCache.prewarm(testDir, ['*.ts']);
+    expect(stats.filesLoaded).toBe(2);
+    expect(stats.totalBytes).toBeGreaterThan(0);
+    expect(stats.durationMs).toBeGreaterThanOrEqual(0);
+    expect(fileCache.stats.prewarmed).toBe(true);
+  });
+
+  it('respects default ignore patterns (skips node_modules)', async () => {
+    mkdirSync(join(testDir, 'node_modules', 'foo'), { recursive: true });
+    writeFileSync(join(testDir, 'node_modules', 'foo', 'x.ts'), 'export {};');
+    writeFileSync(join(testDir, 'app.ts'), 'export const app = 1;');
+    await fileCache.prewarm(testDir, ['**/*.ts']);
+    expect(fileCache.paths().some((p) => p.includes('node_modules'))).toBe(false);
+    expect(fileCache.paths().some((p) => p.endsWith('app.ts'))).toBe(true);
+  });
+
+  it('handles multiple patterns and deduplicates', async () => {
+    writeFileSync(join(testDir, 'x.ts'), '1');
+    const stats = await fileCache.prewarm(testDir, ['*.ts', '**/*.ts']);
+    expect(stats.filesLoaded).toBe(1);
+  });
+});
+
+describe('fileCache.get', () => {
+  it('returns content from disk on cache miss and caches it', async () => {
+    const path = join(testDir, 'fresh.ts');
+    writeFileSync(path, 'fresh content');
+    const content = await fileCache.get(path);
+    expect(content).toBe('fresh content');
+    expect(fileCache.getCached(path)).toBe('fresh content');
+  });
+
+  it('returns cached content on hit', async () => {
+    const path = join(testDir, 'a.ts');
+    writeFileSync(path, 'first');
+    await fileCache.prewarm(testDir, ['*.ts']);
+    // Mutate the file on disk; cached read still returns first
+    writeFileSync(path, 'second');
+    expect(await fileCache.get(path)).toBe('first');
+  });
+
+  it('throws ValidationError when path is a directory', async () => {
+    const dirPath = join(testDir, 'dir');
+    mkdirSync(dirPath);
+    await expect(fileCache.get(dirPath)).rejects.toThrow(ValidationError);
+  });
+
+  it('resolves relative paths against cwd', async () => {
+    const abs = join(testDir, 'foo.ts');
+    writeFileSync(abs, 'rel');
+    process.chdir(testDir);
+    const content = await fileCache.get('foo.ts');
+    expect(content).toBe('rel');
+  });
+});
+
+describe('fileCache.getCached', () => {
+  it('returns undefined when file is not in cache', () => {
+    expect(fileCache.getCached('/nope/nope.ts')).toBeUndefined();
+  });
+
+  it('returns cached content after prewarm', async () => {
+    writeFileSync(join(testDir, 'q.ts'), 'q');
+    await fileCache.prewarm(testDir, ['*.ts']);
+    expect(fileCache.getCached(join(testDir, 'q.ts'))).toBe('q');
+  });
+});
+
+describe('fileCache.exists', () => {
+  it('returns true for cached files', async () => {
+    writeFileSync(join(testDir, 'e.ts'), 'e');
+    await fileCache.prewarm(testDir, ['*.ts']);
+    expect(await fileCache.exists(join(testDir, 'e.ts'))).toBe(true);
+  });
+
+  it('returns true for files on disk but not yet cached', async () => {
+    writeFileSync(join(testDir, 'd.ts'), 'd');
+    expect(await fileCache.exists(join(testDir, 'd.ts'))).toBe(true);
+  });
+
+  it('returns false when file does not exist', async () => {
+    expect(await fileCache.exists(join(testDir, 'missing.ts'))).toBe(false);
+  });
+});
+
+describe('fileCache.clear', () => {
+  it('empties the cache and resets prewarmed flag', async () => {
+    writeFileSync(join(testDir, 'x.ts'), 'x');
+    await fileCache.prewarm(testDir, ['*.ts']);
+    expect(fileCache.stats.size).toBeGreaterThan(0);
+    fileCache.clear();
+    expect(fileCache.stats.size).toBe(0);
+    expect(fileCache.stats.prewarmed).toBe(false);
+    expect(fileCache.stats.cleared).toBe(true);
+  });
+});
+
+describe('fileCache.paths', () => {
+  it('returns sorted absolute paths', async () => {
+    writeFileSync(join(testDir, 'b.ts'), '');
+    writeFileSync(join(testDir, 'a.ts'), '');
+    await fileCache.prewarm(testDir, ['*.ts']);
+    const paths = fileCache.paths();
+    expect(paths.length).toBe(2);
+    expect([...paths].sort()).toEqual(paths);
+  });
+});
+
+describe('DEFAULT_PREWARM_PATTERNS', () => {
+  it('includes the major source extensions', () => {
+    expect(DEFAULT_PREWARM_PATTERNS).toContain('**/*.ts');
+    expect(DEFAULT_PREWARM_PATTERNS).toContain('**/*.tsx');
+    expect(DEFAULT_PREWARM_PATTERNS).toContain('**/*.js');
+    expect(DEFAULT_PREWARM_PATTERNS).toContain('**/*.json');
+  });
+});