@opensip-tools/fitness 1.0.4

package/src/framework/registry.ts

@@ -0,0 +1,125 @@
+/**
+ * Check registry — central registration and discovery.
+ *
+ * Supports namespaced slugs: checks are stored as `namespace:slug` when
+ * a namespace is provided. Bare slug lookups resolve via a reverse index,
+ * with a warning logged on ambiguity.
+ */
+
+import { NotFoundError , logger } from '@opensip-tools/core';
+
+import type { Check } from './check-types.js';
+
+
+
+export class CheckRegistry {
+  /** Primary store: key is `namespace:slug` or bare `slug` */
+  private readonly checks = new Map<string, Check>();
+  /** Reverse index: bare slug → list of namespaced keys */
+  private readonly bareSlugIndex = new Map<string, string[]>();
+
+  register(check: Check, namespace?: string): void {
+    const bareSlug = check.config.slug;
+    const key = namespace ? `${namespace}:${bareSlug}` : bareSlug;
+
+    if (this.checks.has(key)) {
+      // Silently skip duplicate — same check imported multiple times
+      return;
+    }
+
+    this.checks.set(key, check);
+
+    // Update bare slug index
+    const existing = this.bareSlugIndex.get(bareSlug) ?? [];
+    existing.push(key);
+    this.bareSlugIndex.set(bareSlug, existing);
+  }
+
+  /** Get a check by slug. Supports both namespaced and bare slugs. */
+  get(slug: string): Check {
+    const check = this.resolve(slug);
+    if (!check) throw new NotFoundError(`Check not found: ${slug}`);
+    return check;
+  }
+
+  /** Check whether a slug is registered (namespaced or bare). */
+  has(slug: string): boolean {
+    return this.resolve(slug) !== undefined;
+  }
+
+  list(): Check[] {
+    return [...this.checks.values()];
+  }
+
+  /** Get the namespace a check was registered under. Returns undefined for bare slugs. */
+  getNamespace(bareSlug: string): string | undefined {
+    const keys = this.bareSlugIndex.get(bareSlug);
+    if (!keys || keys.length === 0) return undefined;
+    const key = keys[0];
+    const colonIdx = key.indexOf(':');
+    return colonIdx === -1 ? undefined : key.slice(0, colonIdx);
+  }
+
+  listEnabled(): Check[] {
+    return this.list().filter(c => !c.config.disabled);
+  }
+
+  byTag(tag: string): Check[] {
+    return this.listEnabled().filter(c => c.config.tags?.includes(tag));
+  }
+
+  /** Get a check by slug, returning undefined if not found. */
+  getBySlug(slug: string): Check | undefined {
+    return this.resolve(slug);
+  }
+
+  /** Return all registered keys (namespaced where applicable). */
+  listSlugs(): string[] {
+    return [...this.checks.keys()];
+  }
+
+  /** Return all checks with a given bare slug across all namespaces. */
+  listByBareSlug(bareSlug: string): Check[] {
+    const keys = this.bareSlugIndex.get(bareSlug) ?? [];
+    return keys.map(k => this.checks.get(k)).filter((c): c is Check => c !== undefined);
+  }
+
+  get size(): number {
+    return this.checks.size;
+  }
+
+  /**
+   * Resolve a slug to a Check.
+   * - If slug contains ':', exact lookup.
+   * - If bare slug, use reverse index. Single match → return. Multiple → warn + return first.
+   */
+  private resolve(slug: string): Check | undefined {
+    // Exact match (namespaced or bare)
+    const exact = this.checks.get(slug);
+    if (exact) return exact;
+
+    // If it contains ':', it was a namespaced lookup that didn't match
+    if (slug.includes(':')) return undefined;
+
+    // Bare slug → reverse index
+    const candidates = this.bareSlugIndex.get(slug);
+    if (!candidates || candidates.length === 0) return undefined;
+
+    if (candidates.length > 1) {
+      logger.warn({
+        evt: 'plugin.registry.collision',
+        module: 'core:registry',
+        bareSlug: slug,
+        candidates,
+        msg: `Ambiguous slug '${slug}' matches ${candidates.length} checks — using first registered`,
+      });
+    }
+
+    return this.checks.get(candidates[0]);
+  }
+}
+
+/** Default global registry — checks auto-register here on import */
+export const defaultRegistry = new CheckRegistry();
+
+export {type Check} from './check-types.js';

package/src/framework/result-builder.ts

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview ResultBuilder - Builder pattern for check results
+ *
+ * Provides a fluent API for constructing check results with signals,
+ * metadata, and display information.
+ */
+
+
+import {
+  CheckInfoFactory,
+  createResultWithSignals,
+  createErrorResult,
+  getItemTypeLabel,
+} from '../types/findings.js'
+import { countErrors, countWarnings } from '../types/severity.js'
+
+import type {
+  CheckResult,
+  CheckInfo,
+  ItemType,
+} from '../types/findings.js'
+import type { Signal } from '@opensip-tools/core'
+
+/**
+ * Options for building results.
+ */
+export interface ResultBuilderOptions {
+  /** Check ID */
+  readonly checkId: string
+  /** Item type for display (files, modules, etc.) */
+  readonly itemType: ItemType
+  /** Custom unit label (overrides itemType) */
+  readonly unit?: string | undefined
+}
+
+/**
+ * Builder for constructing check results.
+ *
+ * @example
+ * ```typescript
+ * const result = ResultBuilder.create({ checkId: 'my-check', itemType: 'files' })
+ *   .totalItems(100)
+ *   .addSignal(signal1)
+ *   .build();
+ * ```
+ */
+export class ResultBuilder {
+  private _totalItems = 0
+  private readonly _signals: Signal[] = []
+  private _ignoredCount = 0
+  private _durationMs?: number
+  private _filesScanned?: number
+  private _extra?: Record<string, unknown>
+
+  private constructor(private readonly options: ResultBuilderOptions) {}
+
+  static create(
+    options: ResultBuilderOptions,
+  ): ResultBuilder {
+    return new ResultBuilder(options)
+  }
+
+  totalItems(count: number): this {
+    this._totalItems = count
+    return this
+  }
+
+  filesScanned(count: number): this {
+    this._filesScanned = count
+    return this
+  }
+
+  addSignal(signal: Signal): this {
+    this._signals.push(signal)
+    return this
+  }
+
+  addSignals(signals: readonly Signal[]): this {
+    if (signals.length === 0) {
+      return this
+    }
+    this._signals.push(...signals)
+    return this
+  }
+
+  ignoredCount(count: number): this {
+    this._ignoredCount = count
+    return this
+  }
+
+  incrementIgnored(by = 1): this {
+    this._ignoredCount += by
+    return this
+  }
+
+  duration(ms: number): this {
+    this._durationMs = ms
+    return this
+  }
+
+  extra(data: Record<string, unknown>): this {
+    this._extra = { ...this._extra, ...data }
+    return this
+  }
+
+  build(): CheckResult {
+    const unit = this.options.unit ?? this.options.itemType
+    const errors = countErrors(this._signals)
+    const warnings = countWarnings(this._signals)
+
+    const info = this.buildInfo(errors, warnings, unit)
+
+    const buildOptions: {
+      ignoredCount?: number
+      durationMs?: number
+      filesScanned?: number
+      itemType?: string
+      extra?: Record<string, unknown>
+    } = {}
+
+    if (this._ignoredCount > 0) {
+      buildOptions.ignoredCount = this._ignoredCount
+    }
+    if (this._durationMs !== undefined) {
+      buildOptions.durationMs = this._durationMs
+    }
+    if (this._filesScanned !== undefined) {
+      buildOptions.filesScanned = this._filesScanned
+    }
+    buildOptions.itemType = this.options.itemType
+    if (this._extra !== undefined) {
+      buildOptions.extra = this._extra
+    }
+
+    return createResultWithSignals(
+      info,
+      this._signals,
+      this._totalItems,
+      Object.keys(buildOptions).length > 0 ? buildOptions : undefined,
+    )
+  }
+
+  buildError(message: string, error?: Error): CheckResult {
+    return createErrorResult(message, error)
+  }
+
+  private buildInfo(errors: number, warnings: number, unit: string): CheckInfo {
+    if (this._totalItems > 0) {
+      // Clamp to 0: analyzeAll-mode checks can surface violations against
+      // files outside the scanned set, which would otherwise produce a
+      // negative "-N/M compliant" label.
+      const compliantItems = Math.max(0, this._totalItems - this.getUniqueFileCount())
+      return CheckInfoFactory.compliance(compliantItems, this._totalItems, unit)
+    }
+
+    const total = errors + warnings
+    return CheckInfoFactory.violations(total, getItemTypeLabel('violations', total))
+  }
+
+  private getUniqueFileCount(): number {
+    const files = new Set(this._signals.map((s) => s.code?.file).filter(Boolean))
+    return files.size
+  }
+
+  get signalCount(): number {
+    return this._signals.length
+  }
+
+  get errorCount(): number {
+    return countErrors(this._signals)
+  }
+
+  get warningCount(): number {
+    return countWarnings(this._signals)
+  }
+
+  get hasSignals(): boolean {
+    return this._signals.length > 0
+  }
+
+  get willPass(): boolean {
+    return this.errorCount === 0
+  }
+}
+
+// =============================================================================
+// SNIPPET UTILITIES
+// =============================================================================
+
+/**
+ * Extract a code snippet with context lines around a target line.
+ */
+export function extractSnippet(
+  content: string,
+  line: number,
+  contextLines = 2,
+): { snippet: string; contextLines: number } {
+  const lines = content.split('\n')
+  const startLine = Math.max(0, line - 1 - contextLines)
+  const endLine = Math.min(lines.length, line + contextLines)
+  const snippetLines = lines.slice(startLine, endLine)
+  const snippet = snippetLines.map((l, i) => `${startLine + i + 1} | ${l}`).join('\n')
+  return { snippet, contextLines }
+}
+
+/**
+ * Get line number from content string and character index.
+ */
+export function getLineNumber(content: string, index: number): number {
+  return content.slice(0, Math.max(0, index)).split('\n').length
+}
+
+/**
+ * Default patterns for identifying API-related files.
+ */
+const DEFAULT_API_FILE_PATTERNS = ['/api/', '/routes/', '-handler.ts', '.handler.ts'] as const
+
+/**
+ * Check if a file path matches API file patterns.
+ */
+export function isAPIFile(filePath: string): boolean {
+  return DEFAULT_API_FILE_PATTERNS.some((pattern) =>
+    pattern.startsWith('/') ? filePath.includes(pattern) : filePath.endsWith(pattern),
+  )
+}

package/src/framework/scope-resolver.ts

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview Scope-based file resolution for fitness checks
+ *
+ * Checks declare intent (languages + concerns), targets declare reality
+ * (languages + concerns + globs), and this module resolves the match.
+ *
+ * Performance: all targets are globbed once upfront in buildScopeBasedFileMap.
+ * Per-check resolution is a pure in-memory lookup — no redundant I/O.
+ */
+
+import { relative, resolve } from 'node:path'
+
+import { globSync } from 'glob'
+import { minimatch, Minimatch } from 'minimatch'
+
+import type { CheckScope } from './check-config.js'
+import type { TargetRegistry } from '../targets/target-registry.js'
+import type { Target, TargetsConfig } from '../targets/types.js'
+
+// =============================================================================
+// Pre-resolved target file cache
+// =============================================================================
+
+/** Assemble a single target's file list from pre-resolved pattern results, applying excludes. */
+function assembleTargetFiles(
+  targetConfig: { include: readonly string[]; exclude: readonly string[]; name: string },
+  patternResults: Map<string, readonly string[]>,
+  compiledGlobalExcludes: Minimatch[],
+  rootDir: string,
+): readonly string[] {
+  const files = new Set<string>()
+  for (const pattern of targetConfig.include) {
+    const matches = patternResults.get(pattern) ?? []
+    for (const match of matches) {
+      files.add(match)
+    }
+  }
+
+  if (targetConfig.exclude.length > 0 || compiledGlobalExcludes.length > 0) {
+    const compiledTargetExcludes = targetConfig.exclude.map((ex) => new Minimatch(ex, { dot: true }))
+    const allExcludes = [...compiledTargetExcludes, ...compiledGlobalExcludes]
+    for (const filePath of files) {
+      const rel = relative(rootDir, filePath)
+      if (allExcludes.some((m) => m.match(rel))) {
+        files.delete(filePath)
+      }
+    }
+  }
+
+  return [...files].sort()
+}
+
+/**
+ * Collect all unique glob patterns and ignore patterns from all targets,
+ * run a single deduplicated glob pass, then partition results per target.
+ *
+ * This avoids redundant filesystem traversals when targets share common
+ * patterns (e.g. multiple targets including "packages/star/src/starstar/star.ts").
+ */
+function preResolveAllTargets(
+  registry: TargetRegistry,
+  config: TargetsConfig,
+  rootDir: string,
+): Map<string, readonly string[]> {
+  const targets = registry.getAll()
+  if (targets.length === 0) return new Map()
+
+  // Collect all unique include patterns across targets
+  const allPatterns = new Set<string>()
+  for (const target of targets) {
+    for (const pattern of target.config.include) {
+      allPatterns.add(pattern)
+    }
+  }
+
+  // Single glob pass for each unique pattern — deduplicated across targets.
+  // Common infrastructure dirs are always ignored to prevent expensive traversals.
+  const COMMON_IGNORE = ['**/node_modules/**', '**/dist/**', '**/.git/**']
+  const patternResults = new Map<string, readonly string[]>()
+  for (const pattern of allPatterns) {
+    const matches = globSync(pattern, {
+      cwd: rootDir,
+      absolute: true,
+      nodir: true,
+      ignore: COMMON_IGNORE,
+    })
+    patternResults.set(pattern, matches.map((m) => resolve(m)))
+  }
+
+  // Pre-compile globalExcludes matchers for reuse across all targets
+  const { globalExcludes } = config
+  const compiledExcludes = globalExcludes.map((pattern) => new Minimatch(pattern, { dot: true }))
+
+  // Assemble per-target file lists by combining pattern results and filtering excludes.
+  // Both target-specific excludes AND globalExcludes are applied here so that
+  // per-check resolution is a pure in-memory lookup with no minimatch calls.
+  const result = new Map<string, readonly string[]>()
+  for (const target of targets) {
+    const files = assembleTargetFiles(
+      { include: target.config.include, exclude: target.config.exclude, name: target.config.name },
+      patternResults, compiledExcludes, rootDir,
+    )
+    result.set(target.config.name, files)
+  }
+
+  return result
+}
+
+/**
+ * Resolve a single target's include/exclude globs to absolute file paths.
+ * Used by the resolveFilesForCheck fallback path (single-check mode).
+ */
+function resolveTargetGlobs(target: Target, rootDir: string): string[] {
+  const files = new Set<string>()
+  const { include, exclude } = target.config
+
+  for (const pattern of include) {
+    const matches = globSync(pattern, {
+      cwd: rootDir,
+      ignore: [...exclude],
+      absolute: true,
+    })
+    for (const match of matches) {
+      files.add(resolve(match))
+    }
+  }
+
+  return [...files].sort()
+}
+
+/**
+ * Look up pre-resolved files for a set of target names, union and deduplicate.
+ */
+function unionTargetFiles(
+  targetNames: readonly string[],
+  resolvedTargets: Map<string, readonly string[]>,
+): string[] {
+  if (targetNames.length === 1) {
+    return [...(resolvedTargets.get(targetNames[0]) ?? [])]
+  }
+  const files = new Set<string>()
+  for (const name of targetNames) {
+    const targetFiles = resolvedTargets.get(name)
+    if (targetFiles) {
+      for (const f of targetFiles) files.add(f)
+    }
+  }
+  return [...files].sort()
+}
+
+// =============================================================================
+// Global excludes
+// =============================================================================
+
+function applyGlobalExcludes(
+  files: readonly string[],
+  rootDir: string,
+  globalExcludes: readonly string[],
+): readonly string[] {
+  if (globalExcludes.length === 0) return files
+
+  return files.filter((filePath) => {
+    const relativePath = relative(rootDir, filePath)
+    return !globalExcludes.some((pattern) => minimatch(relativePath, pattern, { dot: true }))
+  })
+}
+
+// =============================================================================
+// Per-check resolution (pure in-memory, no I/O)
+// =============================================================================
+
+/**
+ * Resolve file paths for a single check using pre-resolved target files.
+ *
+ * Resolution order:
+ * 1. If checkOverrides has an entry for this slug, use those target(s) directly
+ * 2. If scope is declared, match against all targets by languages + concerns
+ * 3. If no scope and no override, return undefined (check uses file cache fallback)
+ *
+ * When pre-resolved targets are provided (from buildScopeBasedFileMap), globalExcludes
+ * have already been applied during pre-resolution and are skipped here.
+ * When called without pre-resolved targets (single-check fallback), globalExcludes
+ * are applied after direct globbing.
+ */
+function resolveFilesForCheck(
+  slug: string,
+  scope: CheckScope | undefined,
+  registry: TargetRegistry,
+  config: TargetsConfig,
+  rootDir: string,
+  resolvedTargets?: Map<string, readonly string[]>,
+): readonly string[] | undefined {
+  const { globalExcludes, checkOverrides } = config
+
+  // When resolvedTargets is provided, globalExcludes are pre-applied — skip re-filtering
+  const maybeApplyExcludes = (files: readonly string[]): readonly string[] =>
+    resolvedTargets ? files : applyGlobalExcludes(files, rootDir, globalExcludes)
+
+  // Use pre-resolved cache when available, otherwise fall back to direct glob
+  const lookupFiles = (targetRef: string | readonly string[]): string[] => {
+    const names = typeof targetRef === 'string' ? [targetRef] : targetRef
+    if (resolvedTargets) {
+      return unionTargetFiles(names, resolvedTargets)
+    }
+    // Fallback: resolve directly (single-check mode without precomputed cache)
+    const targets = names
+      .map((name) => registry.getByName(name))
+      .filter((t): t is NonNullable<typeof t> => t !== undefined)
+    const files = new Set<string>()
+    for (const target of targets) {
+      for (const f of resolveTargetGlobs(target, rootDir)) files.add(f)
+    }
+    return [...files].sort()
+  }
+
+  // 1. Check overrides take priority (for marketplace/third-party checks)
+  const override = checkOverrides[slug]
+  if (override) {
+    return maybeApplyExcludes(lookupFiles(override))
+  }
+
+  // 2. Scope-based matching
+  if (scope && (scope.languages.length > 0 || scope.concerns.length > 0)) {
+    const matchedTargets = registry.findByScope(scope.languages, scope.concerns)
+    if (matchedTargets.length === 0) {
+      return []
+    }
+    const names = matchedTargets.map((t) => t.config.name)
+    return maybeApplyExcludes(lookupFiles(names))
+  }
+
+  // 3. No scope, no override — undefined signals "use file cache fallback"
+  return undefined
+}
+
+/**
+ * Build the complete check-to-files map for all checks with scopes or overrides.
+ *
+ * All targets are globbed once upfront. Per-check resolution is a pure
+ * in-memory lookup against the pre-resolved file lists.
+ */
+export function buildScopeBasedFileMap(
+  checks: readonly { slug: string; scope?: CheckScope }[],
+  registry: TargetRegistry,
+  config: TargetsConfig,
+  rootDir: string,
+): Map<string, readonly string[]> {
+  // Pre-resolve all targets once — deduplicated glob pass across all targets.
+  // GlobalExcludes are applied during pre-resolution so per-check lookups are pure in-memory.
+  const resolvedTargets = preResolveAllTargets(registry, config, rootDir)
+
+  const result = new Map<string, readonly string[]>()
+
+  for (const check of checks) {
+    const files = resolveFilesForCheck(check.slug, check.scope, registry, config, rootDir, resolvedTargets)
+    if (files !== undefined) {
+      result.set(check.slug, files)
+    }
+  }
+
+  return result
+}

package/src/framework/severity-mapping.ts

@@ -0,0 +1,56 @@
+// @fitness-ignore-file project-readme-existence -- internal module, not a package root
+/**
+ * @fileoverview Shared severity and category mapping for fitness checks
+ *
+ * Maps FindingSeverity to SignalSeverity and check category strings
+ * to SignalCategory. Used by defineCheck and PatternDetector.
+ */
+
+import type { FindingSeverity } from '../types/findings.js'
+import type { SignalSeverity, SignalCategory } from '@opensip-tools/core'
+
+
+/** Map FindingSeverity to SignalSeverity */
+export function mapFindingSeverity(severity: FindingSeverity): SignalSeverity {
+  switch (severity) {
+    case 'error': {
+      return 'high'
+    }
+    case 'warning': {
+      return 'medium'
+    }
+    default: {
+      return 'medium'
+    }
+  }
+}
+
+/** Map check tags to SignalCategory (first matching tag wins) */
+export function mapTagsToSignalCategory(tags: readonly string[]): SignalCategory {
+  for (const tag of tags) {
+    switch (tag) {
+      case 'security': {
+        return 'security'
+      }
+      case 'performance': {
+        return 'performance'
+      }
+      case 'architecture': {
+        return 'architecture'
+      }
+      case 'quality': {
+        return 'warning'
+      }
+      case 'resilience': {
+        return 'resilience'
+      }
+      case 'testing': {
+        return 'testing'
+      }
+      case 'documentation': {
+        return 'documentation'
+      }
+    }
+  }
+  return 'warning'
+}