@opensip-tools/fitness 1.0.4

package/src/framework/strip-literals.ts

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview Shared utilities for stripping string literal and comment
+ * content from source code. Used by fitness checks to avoid false positives
+ * from patterns appearing inside string literals or comments.
+ */
+
+/**
+ * Strip string literal contents from a single line.
+ * Replaces content inside '...', "...", and `...` with empty strings.
+ * Used by checks for per-line pattern matching to avoid false positives
+ * from patterns appearing inside string literals.
+ */
+export function stripStringLiterals(line: string): string {
+  return line
+    .replaceAll(/'(?:[^'\\]|\\.)*'/g, "''")
+    .replaceAll(/"(?:[^"\\]|\\.)*"/g, '""')
+    .replaceAll(/`(?:[^`\\]|\\.)*`/gs, '``')
+}
+
+/** Shared regex patterns for string literal replacement */
+const SINGLE_QUOTE_RE = /'(?:[^'\\]|\\.)*'/g
+const DOUBLE_QUOTE_RE = /"(?:[^"\\]|\\.)*"/g
+const BACKTICK_RE = /`(?:[^`\\]|\\.)*`/gs
+
+/**
+ * Strip string literals and single-line comments from full file content.
+ * Used by checks for quick-filter gates to avoid matching keywords
+ * that only appear in documentation strings or comments.
+ */
+/**
+ * Check if a position in a line is inside a string literal.
+ * Scans characters before the match position for unescaped quotes/backticks.
+ * Used by checks to avoid false positives from suggestion/description text.
+ */
+export function isInsideStringLiteral(line: string, matchIndex: number): boolean {
+  let inSingle = false
+  let inDouble = false
+  let inTemplate = false
+  let escaped = false
+
+  for (let i = 0; i < matchIndex; i++) {
+    const ch = line[i]
+
+    if (escaped) {
+      escaped = false
+      continue
+    }
+
+    if (ch === '\\' && (inSingle || inDouble || inTemplate)) {
+      escaped = true
+      continue
+    }
+
+    if (ch === "'" && !inDouble && !inTemplate) inSingle = !inSingle
+    else if (ch === '"' && !inSingle && !inTemplate) inDouble = !inDouble
+    else if (ch === '`' && !inSingle && !inDouble) inTemplate = !inTemplate
+  }
+
+  return inSingle || inDouble || inTemplate
+}
+
+/**
+ * Strip string literals and single-line comments from full file content.
+ * Used by checks for quick-filter gates to avoid matching keywords
+ * that only appear in documentation strings or comments.
+ */
+export function stripStringsAndComments(content: string): string {
+  // Strip string literals first
+  let result = content
+    .replaceAll(SINGLE_QUOTE_RE, "''")
+    .replaceAll(DOUBLE_QUOTE_RE, '""')
+    .replaceAll(BACKTICK_RE, '``')
+  // Strip single-line comments (after string stripping to avoid matching // inside strings)
+  // eslint-disable-next-line sonarjs/slow-regex -- .*$ anchored to line end; linear scan
+  result = result.replaceAll(/\/\/.*$/gm, '')
+  return result
+}
+
+/**
+ * Strip strings, single-line comments, AND block comments while preserving
+ * BOTH character positions and line numbers. Each stripped character is
+ * replaced with a space (non-newline) so the output has identical length
+ * and line offsets to the input. Use this when downstream processing
+ * needs to map a match index back to a line number in the ORIGINAL
+ * source — `stripStringsAndComments` collapses string literals to empty
+ * pairs, which shifts indexes and breaks `getLineNumber(content, idx)`.
+ *
+ * Strips:
+ * - Single-quoted, double-quoted, and template-literal string contents
+ * - Single-line `// ...` comments (to end of line)
+ * - Block `/* ... *\/` comments (including JSDoc `/** ... *\/`)
+ *
+ * Preserves: newlines, total character count, character positions of
+ * code OUTSIDE these regions.
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- token-state-machine: single-pass tokenizer, branches reflect quote/comment state
+export function stripStringsAndCommentsPreservingPositions(content: string): string {
+  const out: string[] = []
+  let i = 0
+  let inSingle = false
+  let inDouble = false
+  let inTemplate = false
+  let inLineComment = false
+  let inBlockComment = false
+  let escaped = false
+
+  while (i < content.length) {
+    const ch = content[i]
+    const next = content[i + 1]
+
+    // Inside any string: blank out chars (preserve newlines) until terminator.
+    if (inSingle || inDouble || inTemplate) {
+      if (escaped) {
+        out.push(ch === '\n' ? '\n' : ' ')
+        escaped = false
+        i++
+        continue
+      }
+      if (ch === '\\') {
+        out.push(' ')
+        escaped = true
+        i++
+        continue
+      }
+      if ((ch === "'" && inSingle) || (ch === '"' && inDouble) || (ch === '`' && inTemplate)) {
+        // Keep terminator for symmetry — replace with space too. The
+        // string itself is gone; outer code doesn't care about the quote.
+        out.push(' ')
+        inSingle = inDouble = inTemplate = false
+        i++
+        continue
+      }
+      out.push(ch === '\n' ? '\n' : ' ')
+      i++
+      continue
+    }
+
+    // Inside line comment: blank to end of line.
+    if (inLineComment) {
+      if (ch === '\n') {
+        inLineComment = false
+        out.push('\n')
+      } else {
+        out.push(' ')
+      }
+      i++
+      continue
+    }
+
+    // Inside block comment: blank until `*/`.
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') {
+        out.push('  ')
+        inBlockComment = false
+        i += 2
+        continue
+      }
+      out.push(ch === '\n' ? '\n' : ' ')
+      i++
+      continue
+    }
+
+    // Outside any region: detect openers.
+    if (ch === '/' && next === '/') {
+      out.push('  ')
+      inLineComment = true
+      i += 2
+      continue
+    }
+    if (ch === '/' && next === '*') {
+      out.push('  ')
+      inBlockComment = true
+      i += 2
+      continue
+    }
+    if (ch === "'") {
+      out.push(' ')
+      inSingle = true
+      i++
+      continue
+    }
+    if (ch === '"') {
+      out.push(' ')
+      inDouble = true
+      i++
+      continue
+    }
+    if (ch === '`') {
+      out.push(' ')
+      inTemplate = true
+      i++
+      continue
+    }
+
+    out.push(ch)
+    i++
+  }
+
+  return out.join('')
+}

package/src/gate.ts

@@ -0,0 +1,337 @@
+/**
+ * Architecture-gate primitive — pre/post-fix regression detection.
+ *
+ * Operations:
+ *   - saveBaseline(output, path)         — persist current SARIF as the baseline
+ *   - compareToBaseline(output, path)    — diff current SARIF against baseline
+ *   - renderGateCompareOutput(result)    — pretty-print the diff for stdout
+ *
+ * Wired into the `fit` command via `--gate-save` and `--gate-compare` flags
+ * (see commands/fit.ts and index.ts).
+ *
+ * The baseline is opensip-tools' own SARIF document (built via buildSarifLog),
+ * persisted as a file. Diffs match by (filePath, ruleId, message) — line
+ * numbers are intentionally NOT in the matching key so unrelated line shifts
+ * don't register as added/resolved violations.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { logger } from '@opensip-tools/core';
+
+import { buildSarifLog } from './sarif.js';
+
+import type { CliOutput } from '@opensip-tools/contracts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single violation as it appears in the gate diff. */
+interface GateViolation {
+  /** sha256(filePath + '\n' + ruleId + '\n' + message) — opaque identity */
+  readonly hash: string;
+  readonly ruleId: string;
+  readonly message: string;
+  readonly filePath: string;
+  /** Line number — informational only, NOT used in identity */
+  readonly line?: number;
+  readonly severity: 'error' | 'warning';
+}
+
+/** Result of comparing current state to a saved baseline. */
+export interface GateCompareResult {
+  readonly baselinePath: string;
+  /** Violations present now but not in baseline. */
+  readonly added: readonly GateViolation[];
+  /** Violations present in baseline but not now. */
+  readonly resolved: readonly GateViolation[];
+  /** Violations present in both. */
+  readonly unchanged: readonly GateViolation[];
+  /** True iff `added` is non-empty — the gate decision. */
+  readonly degraded: boolean;
+}
+
+/** Thrown when --gate-compare is invoked but the baseline file doesn't exist. */
+export class GateBaselineMissingError extends Error {
+  readonly baselinePath: string;
+  constructor(baselinePath: string) {
+    super(
+      `Gate baseline not found at ${baselinePath}. ` +
+        `Run \`opensip-tools fit --gate-save\` first to create one, ` +
+        `or pass --baseline <path> if it lives elsewhere.`,
+    );
+    this.name = 'GateBaselineMissingError';
+    this.baselinePath = baselinePath;
+  }
+}
+
+/** Thrown when the baseline file exists but isn't a parseable SARIF document. */
+export class GateBaselineInvalidError extends Error {
+  readonly baselinePath: string;
+  constructor(baselinePath: string, reason: string) {
+    super(`Gate baseline at ${baselinePath} is invalid: ${reason}`);
+    this.name = 'GateBaselineInvalidError';
+    this.baselinePath = baselinePath;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default baseline path
+// ---------------------------------------------------------------------------
+
+/**
+ * Default location for the baseline file when --baseline is not
+ * specified. Lives under the per-project gitignored runtime dir.
+ */
+export const DEFAULT_BASELINE_PATH = 'opensip-tools/.runtime/baseline.sarif';
+
+// ---------------------------------------------------------------------------
+// saveBaseline
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist the current run's findings as a baseline SARIF document.
+ * Creates parent directories as needed. Overwrites any existing baseline.
+ */
+export function saveBaseline(output: CliOutput, baselinePath: string): void {
+  const sarif = buildSarifLog(output);
+  const dir = dirname(baselinePath);
+  // mkdirSync with recursive: true is idempotent — no need to check existsSync first.
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(baselinePath, JSON.stringify(sarif, null, 2), 'utf8');
+
+  const findingCount = output.checks.reduce((n, c) => n + c.findings.length, 0);
+  logger.info({
+    evt: 'cli.gate.save.complete',
+    module: 'cli:gate',
+    baselinePath,
+    findingCount,
+    checkCount: output.checks.length,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// compareToBaseline
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare current findings against a saved baseline. Returns a structured
+ * diff of added / resolved / unchanged violations.
+ *
+ * @throws {GateBaselineMissingError} when the baseline file doesn't exist
+ * @throws {GateBaselineInvalidError} when the baseline isn't valid SARIF
+ */
+export function compareToBaseline(output: CliOutput, baselinePath: string): GateCompareResult {
+  if (!existsSync(baselinePath)) {
+    throw new GateBaselineMissingError(baselinePath);
+  }
+
+  const baselineRaw = readFileSync(baselinePath, 'utf8');
+  let baselineDoc: unknown;
+  try {
+    baselineDoc = JSON.parse(baselineRaw);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new GateBaselineInvalidError(baselinePath, `not valid JSON (${reason})`);
+  }
+
+  const baselineViolations = extractViolationsFromSarif(baselineDoc, baselinePath);
+  const currentViolations = extractViolationsFromCliOutput(output);
+
+  const baselineByHash = new Map(baselineViolations.map((v) => [v.hash, v]));
+  const currentByHash = new Map(currentViolations.map((v) => [v.hash, v]));
+
+  const added: GateViolation[] = [];
+  const unchanged: GateViolation[] = [];
+  for (const [hash, v] of currentByHash) {
+    if (baselineByHash.has(hash)) {
+      unchanged.push(v);
+    } else {
+      added.push(v);
+    }
+  }
+
+  const resolved: GateViolation[] = [];
+  for (const [hash, v] of baselineByHash) {
+    if (!currentByHash.has(hash)) {
+      resolved.push(v);
+    }
+  }
+
+  const result: GateCompareResult = {
+    baselinePath,
+    added,
+    resolved,
+    unchanged,
+    degraded: added.length > 0,
+  };
+
+  logger.info({
+    evt: 'cli.gate.compare.complete',
+    module: 'cli:gate',
+    baselinePath,
+    addedCount: added.length,
+    resolvedCount: resolved.length,
+    unchangedCount: unchanged.length,
+    degraded: result.degraded,
+  });
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// renderGateCompareOutput
+// ---------------------------------------------------------------------------
+
+/**
+ * Pretty-print a gate compare result for stdout. Caller sets the exit code.
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- multi-section diff renderer: added/removed/changed sections each shape output; flatter form would scatter formatting
+export function renderGateCompareOutput(result: GateCompareResult): string {
+  const lines: string[] = [ 'opensip-tools gate compare', ''];
+
+  if (result.added.length > 0) {
+    lines.push(`Added (${result.added.length}):`);
+    for (const v of sortViolations(result.added)) {
+      lines.push(`  ✗ ${v.ruleId.padEnd(40)} ${formatLocation(v)}`);
+      if (v.message && v.message !== v.ruleId) {
+        lines.push(`      ${truncate(v.message, 120)}`);
+      }
+    }
+    lines.push('');
+  }
+
+  if (result.resolved.length > 0) {
+    lines.push(`Resolved (${result.resolved.length}):`);
+    for (const v of sortViolations(result.resolved)) {
+      lines.push(`  ✓ ${v.ruleId.padEnd(40)} ${formatLocation(v)}`);
+    }
+    lines.push('');
+  }
+
+  if (result.unchanged.length > 0) {
+    lines.push(`Unchanged (${result.unchanged.length}):`);
+    // Truncate unchanged list — usually long and not actionable.
+    const sample = sortViolations(result.unchanged).slice(0, 5);
+    for (const v of sample) {
+      lines.push(`  · ${v.ruleId.padEnd(40)} ${formatLocation(v)}`);
+    }
+    if (result.unchanged.length > sample.length) {
+      lines.push(`  · ... and ${result.unchanged.length - sample.length} more`);
+    }
+    lines.push('');
+  }
+
+  if (result.degraded) {
+    lines.push(`✗ DEGRADED — ${result.added.length} new violation${result.added.length === 1 ? '' : 's'}`);
+  } else if (result.resolved.length > 0) {
+    lines.push(`✓ IMPROVED — ${result.resolved.length} violation${result.resolved.length === 1 ? '' : 's'} resolved, none added`);
+  } else {
+    lines.push(`✓ STABLE — no change`);
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function hashViolation(filePath: string, ruleId: string, message: string): string {
+  return createHash('sha256').update(`${filePath}\n${ruleId}\n${message}`).digest('hex');
+}
+
+function extractViolationsFromCliOutput(output: CliOutput): GateViolation[] {
+  const violations: GateViolation[] = [];
+  for (const check of output.checks) {
+    for (const f of check.findings) {
+      const filePath = f.filePath ?? '';
+      violations.push({
+        hash: hashViolation(filePath, f.ruleId, f.message),
+        ruleId: f.ruleId,
+        message: f.message,
+        filePath,
+        line: f.line,
+        severity: f.severity,
+      });
+    }
+  }
+  return violations;
+}
+
+interface SarifResult {
+  ruleId?: string;
+  level?: string;
+  message?: { text?: string };
+  locations?: readonly {
+    physicalLocation?: {
+      artifactLocation?: { uri?: string };
+      region?: { startLine?: number };
+    };
+  }[];
+}
+
+interface SarifRun {
+  tool?: { driver?: { name?: string } };
+  results?: readonly SarifResult[];
+}
+
+interface SarifDoc {
+  version?: string;
+  runs?: readonly SarifRun[];
+}
+
+function extractViolationsFromSarif(doc: unknown, baselinePath: string): GateViolation[] {
+  if (typeof doc !== 'object' || doc === null) {
+    throw new GateBaselineInvalidError(baselinePath, 'top-level value is not an object');
+  }
+  const sarif = doc as SarifDoc;
+  if (sarif.runs === undefined || !Array.isArray(sarif.runs)) {
+    throw new GateBaselineInvalidError(baselinePath, 'missing or non-array `runs`');
+  }
+
+  const runs: readonly SarifRun[] = sarif.runs;
+  const violations: GateViolation[] = [];
+  for (const run of runs) {
+    const results: readonly SarifResult[] | undefined = run.results;
+    if (results === undefined) continue;
+    for (const result of results) {
+      const ruleId = result.ruleId ?? '';
+      const message = result.message?.text ?? '';
+      const loc = result.locations?.[0]?.physicalLocation;
+      const filePath = loc?.artifactLocation?.uri ?? '';
+      const line = loc?.region?.startLine;
+      const severity = result.level === 'error' ? 'error' : 'warning';
+      violations.push({
+        hash: hashViolation(filePath, ruleId, message),
+        ruleId,
+        message,
+        filePath,
+        line,
+        severity,
+      });
+    }
+  }
+  return violations;
+}
+
+function formatLocation(v: GateViolation): string {
+  if (!v.filePath) return '(no location)';
+  return v.line == null ? v.filePath : `${v.filePath}:${v.line}`;
+}
+
+function sortViolations(vs: readonly GateViolation[]): GateViolation[] {
+  return [...vs].sort((a, b) => {
+    if (a.ruleId !== b.ruleId) return a.ruleId.localeCompare(b.ruleId);
+    if (a.filePath !== b.filePath) return a.filePath.localeCompare(b.filePath);
+    return (a.line ?? 0) - (b.line ?? 0);
+  });
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + '…';
+}

package/src/index.ts

@@ -0,0 +1,110 @@
+// Framework — check definition API
+export { defineCheck } from './framework/define-check.js';
+export { CheckRegistry, defaultRegistry } from './framework/registry.js';
+export { registerChecks } from './framework/register-helpers.js';
+
+// Framework types — the real check API types
+export type { CheckViolation, CheckScope, FileAccessor, CheckConcern, CheckLanguage } from './framework/check-config.js';
+export type { Check, CheckConfig, ResolvedScope } from './framework/check-types.js';
+export { isCheck } from './framework/check-types.js';
+export type { ExecutionContext, RunOptions } from './framework/execution-context.js';
+
+// Framework utilities used by checks
+export { getLineNumber, extractSnippet, isAPIFile } from './framework/result-builder.js';
+export {
+  parseSource, walkNodes,
+  getLineNumber as getASTLineNumber,
+  getIdentifierName, getPropertyChain,
+  isInStringLiteral,
+  isLiteral, isPropertyAccess,
+} from './framework/ast-utilities.js';
+export { execAbortable } from './framework/abortable-exec.js';
+// File cache (used by checks for content access; tests may seed/clear).
+export { fileCache, DEFAULT_PREWARM_PATTERNS } from './framework/file-cache.js';
+export { buildImportGraph, findStronglyConnectedComponents } from './framework/import-graph.js';
+export type { ImportGraph } from './framework/import-graph.js';
+export { isInsideStringLiteral, stripStringLiterals, stripStringsAndComments, stripStringsAndCommentsPreservingPositions } from './framework/strip-literals.js';
+export { filterContent, clearFilterCache } from './framework/content-filter.js';
+export type { FilteredContent } from './framework/content-filter.js';
+// Re-export TypeScript compiler API for AST-based checks. The typescript module
+// uses `export =`, so `export * as ts from 'typescript'` is invalid; the
+// import-then-rename-export form works under esModuleInterop.
+/* eslint-disable unicorn/prefer-export-from -- `export * as ts from 'typescript'` is invalid (the module uses `export =`); the namespace import + named export is the only working shape */
+import * as _ts from 'typescript';
+export { _ts as ts };
+/* eslint-enable unicorn/prefer-export-from */
+
+
+// Types — findings output
+export type { Finding, Severity, FindingSeverity, ToolOutput, CheckResult, CheckInfo, CheckResultMetadata, ItemType } from './types/findings.js';
+export { createResultWithSignals, createErrorResult, createPassingResult, CheckInfoFactory } from './types/findings.js';
+
+// Recipe service
+export { FitnessRecipeService } from './recipes/service.js';
+export type { FitnessRecipeServiceConfig, FitnessRecipeServiceCallbacks, CheckSummary } from './recipes/service-types.js';
+export type { FitnessRecipeResult, RecipeCheckResult, RecipeCheckConfigMap } from './recipes/types.js';
+export { builtInRecipesByName } from './recipes/built-in-recipes.js';
+export { defaultRecipeRegistry, FitnessRecipeRegistry } from './recipes/registry.js';
+export { getCheckConfig, setCurrentRecipeCheckConfig, clearCurrentRecipeCheckConfig } from './recipes/check-config.js';
+
+// Targets and signalers
+export { loadTargetsConfig, resolveTargetFiles } from './targets/index.js';
+export type { TargetsConfig } from './targets/types.js';
+export { TargetRegistry } from './targets/target-registry.js';
+export { buildScopeBasedFileMap } from './framework/scope-resolver.js';
+export { loadSignalersConfig } from './signalers/index.js';
+export type { SignalersConfig } from './signalers/types.js';
+
+// Plugin loader (fitness owns the dispatcher; lang plugins also flow through
+// it because lang adapter loading currently shares the same orchestration).
+export { loadPlugin, loadAllPlugins } from './plugins/loader.js';
+export type { FitPluginExports } from './plugins/types.js';
+
+// Check-package discovery (fitness-specific — scans @opensip-tools/checks-* packages).
+export {
+  discoverCheckPackages,
+  readCheckPackageMetadata,
+  readCheckPackagePreferences,
+} from './plugins/check-package-discovery.js';
+export type {
+  CheckPackageDiscoveryOptions,
+  DiscoveredCheckPackage,
+  CheckPackageMetadata,
+} from './plugins/check-package-discovery.js';
+
+// Tool plugin export — fitness as a Tool.
+export { fitnessTool } from './tool.js';
+
+// CLI command implementations — re-exported for the Phase 2 CLI which
+// still drives commands directly. Phase 4 will collapse these behind
+// the Tool contract.
+export {
+  executeFit,
+  ensureChecksLoaded,
+  getDisplayName,
+  getEnabledCheckCount,
+  getIcon,
+  getPluginLoadErrors,
+  setPreLoadHook,
+  formatDuration,
+  formatValidatedColumn,
+} from './cli/fit.js';
+export type { PreLoadHook } from './cli/fit.js';
+export { openDashboard } from './cli/dashboard.js';
+export { listChecks } from './cli/list-checks.js';
+export { listRecipes } from './cli/list-recipes.js';
+
+// Architecture-gate primitives (baseline save / compare) and SARIF
+// upload — both operate on fitness's CliOutput. Wired into the `fit`
+// subcommand by the tool's register() handler.
+export {
+  saveBaseline,
+  compareToBaseline,
+  renderGateCompareOutput,
+  GateBaselineMissingError,
+  GateBaselineInvalidError,
+  DEFAULT_BASELINE_PATH,
+} from './gate.js';
+export type { GateCompareResult } from './gate.js';
+export { buildSarifLog, chunkSarifRuns, reportToCloud } from './sarif.js';
+export type { ReportResult } from './sarif.js';