@opensip-tools/fitness 1.0.4

package/src/sarif.ts

@@ -0,0 +1,232 @@
+import { withRetry, logger } from '@opensip-tools/core';
+
+import type { CliOutput } from '@opensip-tools/contracts';
+
+const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
+const MAX_FINDINGS_PER_CHUNK = 500;
+
+/** Logger module tag used by every event emitted from SARIF upload. */
+const MODULE_TAG = 'cli:report';
+
+/** Result of a cloud report upload */
+export interface ReportResult {
+  readonly url: string;
+  readonly findingCount: number;
+  readonly runCount: number;
+  readonly success: boolean;
+  readonly error?: string;
+  readonly chunksTotal?: number;
+  readonly chunksSucceeded?: number;
+}
+
+interface SarifRun {
+  tool: { driver: { name: string; version: string; rules: { id: string }[] } };
+  results: Record<string, unknown>[];
+}
+
+/** Build a SARIF 2.1.0 log from CLI output — one run per check slug */
+export function buildSarifLog(output: CliOutput): Record<string, unknown> {
+  return wrapSarifLog(buildSarifRuns(output));
+}
+
+// eslint-disable-next-line sonarjs/cognitive-complexity -- SARIF builder: assembles rules + results per check; flatter shape would scatter the per-check loop
+function buildSarifRuns(output: CliOutput): SarifRun[] {
+  const runs: SarifRun[] = [];
+
+  for (const ch of output.checks) {
+    if (ch.findings.length === 0) continue;
+
+    const ruleIds = new Set<string>();
+    const results: Record<string, unknown>[] = [];
+
+    for (const f of ch.findings) {
+      ruleIds.add(f.ruleId);
+
+      const result: Record<string, unknown> = {
+        ruleId: f.ruleId,
+        message: { text: f.message },
+        level: f.severity === 'error' ? 'error' : 'warning',
+      };
+
+      if (f.filePath) {
+        // SARIF startLine/startColumn are 1-based (per spec § 3.30.6). Values
+        // of 0 are invalid, and fitness signals without a line often carry
+        // line=0 as a sentinel — skip those fields rather than emit invalid SARIF.
+        const region: Record<string, number> = {};
+        if (f.line != null && f.line > 0) region.startLine = f.line;
+        if (f.column != null && f.column > 0) region.startColumn = f.column;
+        result.locations = [{
+          physicalLocation: {
+            artifactLocation: { uri: f.filePath },
+            ...(Object.keys(region).length > 0 ? { region } : {}),
+          },
+        }];
+      }
+
+      if (f.suggestion) {
+        result.fixes = [{ description: { text: f.suggestion } }];
+      }
+
+      results.push(result);
+    }
+
+    runs.push({
+      tool: {
+        driver: {
+          name: ch.checkSlug,
+          version: '1.0.0',
+          rules: [...ruleIds].map((id) => ({ id })),
+        },
+      },
+      results,
+    });
+  }
+
+  return runs;
+}
+
+function wrapSarifLog(runs: SarifRun[]): Record<string, unknown> {
+  return { version: '2.1.0' as const, $schema: SARIF_SCHEMA, runs };
+}
+
+/**
+ * Split SARIF runs into chunks of at most `maxFindings` findings each.
+ * Keeps whole runs together when possible; splits a single run across
+ * chunks only when it exceeds the limit on its own.
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- chunk packer: flush-current vs split-large branches reflect the two shapes the loop must handle
+export function chunkSarifRuns(runs: SarifRun[], maxFindings = MAX_FINDINGS_PER_CHUNK): SarifRun[][] {
+  if (runs.length === 0) return [];
+
+  const chunks: SarifRun[][] = [];
+  let currentChunk: SarifRun[] = [];
+  let currentCount = 0;
+
+  for (const run of runs) {
+    if (run.results.length <= maxFindings && currentCount + run.results.length <= maxFindings) {
+      // Whole run fits in current chunk
+      currentChunk.push(run);
+      currentCount += run.results.length;
+    } else if (run.results.length <= maxFindings) {
+      // Whole run fits, but not in current chunk — start a new one
+      if (currentChunk.length > 0) chunks.push(currentChunk);
+      currentChunk = [run];
+      currentCount = run.results.length;
+    } else {
+      // Run exceeds max — flush current chunk, then split this run
+      if (currentChunk.length > 0) chunks.push(currentChunk);
+      currentChunk = [];
+      currentCount = 0;
+
+      for (let i = 0; i < run.results.length; i += maxFindings) {
+        const slice = run.results.slice(i, i + maxFindings);
+        const ruleIds = new Set(slice.map((r) => r.ruleId as string));
+        chunks.push([{
+          tool: {
+            driver: {
+              ...run.tool.driver,
+              rules: [...ruleIds].map((id) => ({ id })),
+            },
+          },
+          results: slice,
+        }]);
+      }
+    }
+  }
+
+  if (currentChunk.length > 0) chunks.push(currentChunk);
+  return chunks;
+}
+
+/** True for errors where retrying later or with a different chunk may succeed */
+function isTransientError(status: number): boolean {
+  return status >= 500 || status === 429;
+}
+
+// eslint-disable-next-line sonarjs/cognitive-complexity -- network reporter: chunked uploads with per-chunk retries and aggregated error summary; phases read better inline
+export async function reportToCloud(output: CliOutput, url: string, apiKey?: string): Promise<ReportResult> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (apiKey) headers['X-API-Key'] = apiKey;
+
+  const allRuns = buildSarifRuns(output);
+  if (allRuns.length === 0) {
+    return { url, findingCount: 0, runCount: 0, success: true };
+  }
+
+  const sarifUrl = url.endsWith('/sarif') ? url : `${url}/sarif`;
+  const cwd = process.cwd();
+  const target = cwd ? `${sarifUrl}?cwd=${encodeURIComponent(cwd)}` : sarifUrl;
+  const totalFindings = allRuns.reduce((n, r) => n + r.results.length, 0);
+
+  const chunks = chunkSarifRuns(allRuns);
+  const errors: string[] = [];
+  let succeeded = 0;
+
+  for (let ci = 0; ci < chunks.length; ci++) {
+    const chunk = chunks[ci];
+    const chunkFindings = chunk.reduce((n, r) => n + r.results.length, 0);
+    // 60s base + 100ms per finding — receiver does per-finding work (dedup, persistence, traces)
+    const timeoutMs = Math.min(300_000, 60_000 + chunkFindings * 100);
+    const sarifLog = wrapSarifLog(chunk);
+
+    logger.info({ evt: 'cli.report.chunk.start', module: MODULE_TAG, chunk: `${ci + 1}/${chunks.length}`, findings: chunkFindings, timeoutMs });
+
+    try {
+      const res = await withRetry(
+        () => fetch(target, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(sarifLog),
+          signal: AbortSignal.timeout(timeoutMs),
+        }),
+        {
+          maxAttempts: 3,
+          initialDelayMs: 500,
+          maxDelayMs: 5000,
+          onRetry: (attempt, error, delayMs) => {
+            logger.info({
+              evt: 'cli.report.retry',
+              module: MODULE_TAG,
+              attempt,
+              error: error.message,
+              delayMs,
+              url: sarifUrl,
+              chunk: `${ci + 1}/${chunks.length}`,
+            });
+          },
+        },
+      );
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        const msg = `${res.status} ${res.statusText} ${body}`.trim();
+        errors.push(msg);
+
+        if (!isTransientError(res.status)) {
+          // Non-transient (4xx) — no point sending remaining chunks
+          logger.info({ evt: 'cli.report.abort', module: MODULE_TAG, reason: msg, remaining: chunks.length - ci - 1 });
+          break;
+        }
+        continue;
+      }
+
+      succeeded++;
+      logger.info({ evt: 'cli.report.chunk.done', module: MODULE_TAG, chunk: `${ci + 1}/${chunks.length}`, findings: chunkFindings });
+    } catch (error) {
+      // Network errors and timeouts are transient — continue with next chunk
+      const errMsg = error instanceof Error ? error.message : String(error);
+      errors.push(errMsg);
+      logger.info({ evt: 'cli.report.chunk.error', module: MODULE_TAG, chunk: `${ci + 1}/${chunks.length}`, error: errMsg });
+    }
+  }
+
+  return {
+    url: sarifUrl,
+    findingCount: totalFindings,
+    runCount: allRuns.length,
+    success: errors.length === 0,
+    error: errors.length > 0 ? errors.join('; ') : undefined,
+    chunksTotal: chunks.length,
+    chunksSucceeded: succeeded,
+  };
+}

package/src/signalers/__tests__/loader.test.ts

@@ -0,0 +1,99 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ValidationError, SystemError } from '@opensip-tools/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { loadSignalersConfig } from '../loader.js';
+
+let testDir: string;
+
+beforeEach(() => {
+   
+  testDir = mkdtempSync(join(tmpdir(), 'opensip-signalers-loader-'));
+});
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe('loadSignalersConfig', () => {
+  it('loads a minimal valid config', () => {
+    writeFileSync(
+      join(testDir, 'opensip-tools.config.yml'),
+      'targets: {}\n',
+    );
+    const cfg = loadSignalersConfig(testDir);
+    expect(cfg.targets).toEqual({});
+    expect(cfg.fitness.failOnErrors).toBe(1);
+    expect(cfg.fitness.failOnWarnings).toBe(0);
+  });
+
+  it('parses targets with description, include, exclude', () => {
+    writeFileSync(
+      join(testDir, 'opensip-tools.config.yml'),
+      `targets:
+  src:
+    description: TS source
+    include:
+      - "src/**/*.ts"
+    exclude:
+      - "**/*.test.ts"
+    languages: [typescript]
+    concerns: [backend]
+`,
+    );
+    const cfg = loadSignalersConfig(testDir);
+    expect(cfg.targets.src?.description).toBe('TS source');
+    expect(cfg.targets.src?.include).toEqual(['src/**/*.ts']);
+  });
+
+  it('caches by resolved file path within the TTL', () => {
+    const path = join(testDir, 'opensip-tools.config.yml');
+    writeFileSync(path, 'targets: {}\n');
+    const a = loadSignalersConfig(testDir);
+    // Re-write the file content; cached load should not re-read.
+    writeFileSync(path, 'targets: {alt: {description: x, include: ["y"]}}\n');
+    const b = loadSignalersConfig(testDir);
+    expect(b).toBe(a); // same frozen reference
+  });
+
+  it('throws ValidationError when target name violates kebab-case', () => {
+    writeFileSync(
+      join(testDir, 'opensip-tools.config.yml'),
+      `targets:
+  Invalid_Name:
+    description: x
+    include: ["y"]
+`,
+    );
+    expect(() => loadSignalersConfig(testDir)).toThrow(ValidationError);
+  });
+
+  it('throws ValidationError when YAML is malformed', () => {
+    writeFileSync(join(testDir, 'opensip-tools.config.yml'), 'targets: [unbalanced\n');
+    expect(() => loadSignalersConfig(testDir)).toThrow(ValidationError);
+  });
+
+  it('throws SystemError when the file is too large', () => {
+    const huge = 'x'.repeat(11 * 1024 * 1024); // 11 MB > 10 MB limit
+    writeFileSync(join(testDir, 'opensip-tools.config.yml'), huge);
+    expect(() => loadSignalersConfig(testDir)).toThrow(SystemError);
+  });
+
+  it('respects an explicit --config path', () => {
+    writeFileSync(
+      join(testDir, 'custom.yml'),
+      'targets: {}\n',
+    );
+    const cfg = loadSignalersConfig(testDir, join(testDir, 'custom.yml'));
+    expect(cfg.targets).toEqual({});
+  });
+
+  it('treats null YAML as an empty object', () => {
+    writeFileSync(join(testDir, 'opensip-tools.config.yml'), '');
+    const cfg = loadSignalersConfig(testDir);
+    expect(cfg.targets).toEqual({});
+  });
+});

package/src/signalers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Signalers config barrel export
+ *
+ * Public API for opensip-tools.config.yml:
+ * - loadSignalersConfig() — Load and validate signalers config
+ */
+
+// Loader
+export { loadSignalersConfig } from './loader.js'

package/src/signalers/loader.ts

@@ -0,0 +1,141 @@
+// @fitness-ignore-file toctou-race-condition -- cache check + populate is synchronous (sync file I/O + Map.set); no async gap, safe in single-threaded Node.js
+/**
+ * @fileoverview Load and cache opensip-tools.config.yml
+ *
+ * Reads the signalers config file (path resolved via config-resolution),
+ * validates with Zod, and returns a frozen SignalersConfig. Throws when
+ * the config file is missing — silent no-op would mask a broken scan.
+ */
+
+import { readFileSync, statSync } from 'node:fs'
+
+import {  resolveProjectConfigPath , ValidationError, SystemError , logger } from '@opensip-tools/core'
+import yaml from 'js-yaml'
+
+const deepFreeze = <T>(obj: T): T => structuredClone(obj)
+
+import { SignalersConfigSchema } from './schema.js'
+
+import type { SignalersConfig } from './types.js'
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024 // 10 MB
+
+/** TTL for cached signalers config entries in milliseconds (30 seconds) */
+const SIGNALERS_CACHE_TTL_MS = 30_000
+
+interface CacheEntry {
+  config: SignalersConfig
+  cachedAt: number
+  filePath: string
+}
+
+/** Cache keyed by resolved absolute file path, not rootDir — avoids
+ *  stale hits when the same rootDir resolves to different files over
+ *  time (e.g. --config flag changes between invocations in tests). */
+const cache = new Map<string, CacheEntry>()
+
+/**
+ * Read the raw config file from disk.
+ * @throws {SystemError} When the config file exceeds the maximum allowed size
+ * @throws {ValidationError} When the config file cannot be read
+ */
+function readConfigFile(filePath: string): string {
+  try {
+    const stats = statSync(filePath)
+    if (stats.size > MAX_FILE_SIZE) {
+      throw new SystemError(
+        `Config file too large (${stats.size} bytes, max ${MAX_FILE_SIZE}): ${filePath}`,
+        { code: 'SYSTEM.FILE.TOO_LARGE' },
+      )
+    }
+    return readFileSync(filePath, 'utf8')
+  } catch (error) {
+    if (error instanceof ValidationError || error instanceof SystemError) throw error
+    const message = error instanceof Error ? error.message : String(error)
+    throw new ValidationError(
+      `Failed to read config file ${filePath}: ${message}`,
+      {
+        operation: 'load',
+        loader: 'signalers',
+        filePath,
+        cause: error instanceof Error ? error : undefined,
+      },
+    )
+  }
+}
+
+/** @throws {ValidationError} When the YAML content is invalid */
+function parseYaml(raw: string, filePath: string): unknown {
+  try {
+    return yaml.load(raw) ?? {}
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new ValidationError(`${filePath} contains invalid YAML: ${message}`, {
+      operation: 'load',
+      loader: 'signalers',
+      cause: error instanceof Error ? error : undefined,
+    })
+  }
+}
+
+/**
+ * Load and validate opensip-tools.config.yml from the given root directory.
+ *
+ * Resolution: --config (explicit) → package.json#opensip-tools.configPath
+ * → <rootDir>/opensip-tools.config.yml. See resolveProjectConfigPath().
+ *
+ * Results are cached per resolved file path.
+ *
+ * @param rootDir - Absolute path to the project root directory
+ * @param explicitPath - Optional config path from --config CLI flag
+ * @throws {ValidationError} When no config is found, YAML is invalid, or
+ *   schema validation fails. Intentionally loud: a missing config means
+ *   the scan would otherwise silently produce zero findings.
+ */
+export function loadSignalersConfig(
+  rootDir: string,
+  explicitPath?: string,
+): SignalersConfig {
+  const filePath = resolveProjectConfigPath(rootDir, explicitPath)
+
+  const cached = cache.get(filePath)
+  if (cached && (Date.now() - cached.cachedAt) < SIGNALERS_CACHE_TTL_MS) {
+    return cached.config
+  }
+
+  const raw = readConfigFile(filePath)
+  const parsed = parseYaml(raw, filePath)
+
+  const result = SignalersConfigSchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  ${i.path.join('.')}: ${i.message} (expected: ${i.code})`)
+      .join('\n')
+    throw new ValidationError(
+      `${filePath} validation failed:\n${issues}`,
+      {
+        operation: 'load',
+        loader: 'signalers',
+        filePath,
+        code: 'ERRORS.SIGNALERS.VALIDATION_FAILED',
+      },
+    )
+  }
+
+  const data = result.data
+  const targetCount = Object.keys(data.targets).length
+
+  logger.info({
+    evt: 'core.signalers.config.loaded',
+    module: 'core:signalers',
+    file: filePath,
+    hasFitness: data.fitness !== undefined,
+    hasSimulation: data.simulation !== undefined,
+    targetCount,
+  })
+
+  const frozen = deepFreeze(data as unknown as Record<string, unknown>) as unknown as SignalersConfig
+  cache.set(filePath, { config: frozen, cachedAt: Date.now(), filePath })
+  return frozen
+}
+

package/src/signalers/schema.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Zod validation schema for opensip-tools.config.yml
+ *
+ * Defines the schema for signal producer configuration (fitness, simulation,
+ * assess) and file targeting. These settings live alongside the target
+ * definitions in opensip-tools.config.yml.
+ */
+
+import { z } from 'zod'
+
+// Inline defaults
+const DEFAULTS = {
+  signals: {
+    fitness: { failOnErrors: 1, failOnWarnings: 0 },
+  },
+} as const;
+
+// =============================================================================
+// Target Definition Schema
+// =============================================================================
+
+const TargetDefinitionSchema = z.object({
+  description: z.string().min(1, 'description is required'),
+  include: z.array(z.string()).min(1, 'at least one include pattern is required'),
+  exclude: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  languages: z.array(z.string()).optional(),
+  concerns: z.array(z.string()).optional(),
+})
+
+// =============================================================================
+// Signaler Schedule Schema
+// =============================================================================
+
+const SignalerScheduleSchema = z.object({
+  name: z.string().min(1).max(128),
+  recipe: z.string().min(1).max(128).optional(),
+  scenario: z.string().min(1).max(128).optional(),
+  interval: z.enum(['hourly', 'daily', 'weekdays', 'weekly']),
+  time: z.string().regex(/^\d{2}:\d{2}$/).default('00:00'),
+  day: z.enum(['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']).optional(),
+}).refine(s => s.interval !== 'weekly' || s.day != null, {
+  message: 'Weekly schedules must specify a day',
+})
+
+// =============================================================================
+// Producer Schemas (copied from config/schema.ts — removed from there in Phase 2)
+// =============================================================================
+
+/** Schema for fitness check configuration */
+const FitnessSchema = z.object({
+  defaultTarget: z.string().min(1).max(255).optional(),
+  maxParallel: z.number().int().min(1).optional(),
+  timeout: z.number().int().min(1000).optional(),
+  failOnErrors: z.number().int().min(0).default(DEFAULTS.signals.fitness.failOnErrors),
+  failOnWarnings: z.number().int().min(0).default(DEFAULTS.signals.fitness.failOnWarnings),
+  disabledChecks: z.array(z.string().min(1).max(255)).optional().default([]),
+  schedules: z.array(SignalerScheduleSchema).default([]),
+})
+
+/** Schema for simulation engine configuration */
+const SimulationSchema = z.object({
+  schedules: z.array(SignalerScheduleSchema).default([]),
+})
+
+// =============================================================================
+// Check Overrides
+// =============================================================================
+
+const CheckTargetValueSchema = z.union([
+  z.string(),
+  z.array(z.string()).min(1),
+])
+
+// =============================================================================
+// CLI Defaults
+// =============================================================================
+
+/**
+ * Defaults applied to every `opensip-tools` CLI invocation in the project.
+ * Equivalent to flags on the command line (`--recipe`, `--exclude`, …) but
+ * declared once in the project config so every contributor and CI run agrees.
+ *
+ * Lives alongside targets so a project can ship a single config file.
+ */
+const CliDefaultsSchema = z.object({
+  recipe:    z.string().min(1).max(128).optional(),
+  exclude:   z.array(z.string()).optional(),
+  verbose:   z.boolean().optional(),
+  json:      z.boolean().optional(),
+  reportTo:  z.string().url().optional(),
+  apiKey:    z.string().min(1).optional(),
+  fileTypes: z.array(z.string()).optional(),
+  ignore:    z.array(z.string()).optional(),
+})
+
+// =============================================================================
+// Root Schema
+// =============================================================================
+
+/** Wrap a section schema so YAML `null` is treated as `{}` (all defaults). */
+function section<T extends z.ZodTypeAny>(schema: T) {
+  return z.preprocess((v) => v ?? {}, schema).default({})
+}
+
+/** Root schema for opensip-tools.config.yml validation */
+export const SignalersConfigSchema = z.object({
+  globalExcludes: z.array(z.string()).default([]),
+  targets: z.record(
+    z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'target name must be kebab-case'),
+    TargetDefinitionSchema,
+  ).default({}),
+  checkOverrides: z.record(z.string(), CheckTargetValueSchema).optional(),
+  fitness:    section(FitnessSchema),
+  simulation: section(SimulationSchema),
+  cli:        section(CliDefaultsSchema),
+})

package/src/signalers/types.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Signalers configuration types — derived from Zod schemas
+ */
+
+import type { SignalersConfigSchema } from './schema.js'
+import type { z } from 'zod'
+
+
+/** Recursively marks all properties as readonly. */
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K]
+}
+
+/** Top-level signalers configuration. */
+export type SignalersConfig = DeepReadonly<z.infer<typeof SignalersConfigSchema>>