@opensip-tools/fitness 1.0.4

package/src/types/findings.ts

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Core finding and result types for fitness checks
+ *
+ * CheckResult carries Signal[]. Factory functions
+ * (createResultWithSignals, createErrorResult, createPassingResult) provide
+ * the standard way to construct check results.
+ */
+
+import { countErrors, countWarnings } from './severity.js'
+
+import type { DirectiveEntry } from '../framework/directive-inventory.js'
+import type { Signal } from '@opensip-tools/core'
+
+
+// =============================================================================
+// SEVERITY
+// =============================================================================
+
+/**
+ * Severity level for findings and violations.
+ */
+export type FindingSeverity = 'error' | 'warning'
+
+/**
+ * Alias for FindingSeverity — used by simplified check.ts types.
+ */
+// eslint-disable-next-line sonarjs/redundant-type-aliases -- public re-export under a shorter name for ergonomics
+export type Severity = FindingSeverity
+
+/**
+ * A single finding from a fitness check (output format).
+ */
+export interface Finding {
+  readonly message: string
+  readonly severity: Severity
+  readonly filePath?: string
+  readonly line?: number
+  readonly column?: number
+  readonly suggestion?: string
+  readonly metadata?: Record<string, unknown>
+}
+
+/**
+ * Output from a tool-based check.
+ */
+export interface ToolOutput {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+// =============================================================================
+// CHECK RESULT
+// =============================================================================
+
+/**
+ * Check info for display.
+ */
+export interface CheckInfo {
+  /** Summary label (e.g., "142/150 files compliant") */
+  readonly label: string
+}
+
+/**
+ * Metadata about a check run.
+ */
+export interface CheckResultMetadata {
+  /** Total items scanned */
+  readonly totalItems: number
+  /** Signals (same reference as top-level) */
+  readonly signals: readonly Signal[]
+  /** Duration in milliseconds */
+  readonly durationMs?: number
+  /** Number of files scanned from filesystem */
+  readonly filesScanned?: number
+  /** Item type (e.g., 'files', 'modules') */
+  readonly itemType?: string
+  /** Extra metadata */
+  readonly extra?: Record<string, unknown>
+}
+
+/**
+ * Result of running a fitness check.
+ * Now carries universal Signal[] instead of domain-specific violations.
+ */
+export interface CheckResult {
+  /** Whether the check passed (no errors) */
+  readonly passed: boolean
+  /** Number of error-level signals */
+  readonly errors: number
+  /** Number of warning-level signals */
+  readonly warnings: number
+  /** All signals */
+  readonly signals: readonly Signal[]
+  /** Display info */
+  readonly info: CheckInfo
+  /** Run metadata */
+  readonly metadata: CheckResultMetadata
+  /** Count of violations ignored via directives */
+  readonly ignoredCount?: number
+  /** Directives that actually suppressed signals during this check's execution */
+  readonly appliedDirectives?: readonly DirectiveEntry[]
+}
+
+// =============================================================================
+// ITEM TYPES
+// =============================================================================
+
+/**
+ * Item types for check info display.
+ */
+export type ItemType =
+  | 'files'
+  | 'modules'
+  | 'packages'
+  | 'functions'
+  | 'classes'
+  | 'components'
+  | 'tests'
+  | 'endpoints'
+  | 'dependencies'
+  | 'issues'
+  | 'violations'
+  | 'rules'
+  | 'recipes'
+  | 'checks'
+
+const ITEM_TYPE_SINGULAR: Record<ItemType, string> = {
+  files: 'file',
+  modules: 'module',
+  packages: 'package',
+  functions: 'function',
+  classes: 'class',
+  components: 'component',
+  tests: 'test',
+  endpoints: 'endpoint',
+  dependencies: 'dependency',
+  issues: 'issue',
+  violations: 'violation',
+  rules: 'rule',
+  recipes: 'recipe',
+  checks: 'check',
+}
+
+/**
+ * Get a human-readable label for an item type.
+ */
+export function getItemTypeLabel(type: ItemType, count: number): string {
+  return count === 1 ? ITEM_TYPE_SINGULAR[type] : type
+}
+
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+
+/**
+ * Factory for creating CheckInfo objects.
+ */
+export const CheckInfoFactory = Object.freeze({
+  compliance(compliantItems: number, totalItems: number, unit: string): CheckInfo {
+    return { label: `${compliantItems}/${totalItems} ${unit} compliant` }
+  },
+  violations(count: number, unit: string): CheckInfo {
+    return { label: count === 0 ? `No ${unit}` : `${count} ${unit}` }
+  },
+})
+
+/**
+ * Create a result with signals.
+ */
+export function createResultWithSignals(
+  info: CheckInfo,
+  signals: readonly Signal[],
+  totalItems: number,
+  options?: {
+    ignoredCount?: number
+    durationMs?: number
+    filesScanned?: number
+    itemType?: string
+    extra?: Record<string, unknown>
+  },
+): CheckResult {
+  const errors = countErrors(signals)
+  const warnings = countWarnings(signals)
+
+  return {
+    passed: errors === 0,
+    errors,
+    warnings,
+    signals,
+    info,
+    metadata: {
+      totalItems,
+      signals,
+      durationMs: options?.durationMs,
+      filesScanned: options?.filesScanned,
+      itemType: options?.itemType,
+      extra: options?.extra,
+    },
+    ...(options?.ignoredCount !== undefined && options.ignoredCount > 0
+      ? { ignoredCount: options.ignoredCount }
+      : {}),
+  }
+}
+
+/**
+ * Create an error result (for check failures).
+ */
+export function createErrorResult(
+  message: string,
+  error?: Error,
+): CheckResult {
+  return {
+    passed: false,
+    errors: 1,
+    warnings: 0,
+    signals: [],
+    info: { label: `Error: ${message}` },
+    metadata: {
+      totalItems: 0,
+      signals: [],
+      extra: error ? { originalError: error.message, ...(error.stack ? { stack: error.stack } : {}) } : undefined,
+    },
+  }
+}
+
+/**
+ * Create a passing result with no signals.
+ */
+export function createPassingResult(
+  totalItems: number,
+  unit: string,
+): CheckResult {
+  return createResultWithSignals(
+    CheckInfoFactory.compliance(totalItems, totalItems, unit),
+    [],
+    totalItems,
+  )
+}

package/src/types/severity.ts

@@ -0,0 +1,39 @@
+// @fitness-ignore-file batch-operation-limits -- iterates bounded collections (config entries, registry items, or small analysis results)
+// @fitness-ignore-file clean-code-naming-quality -- short names used in severity mapping utilities
+// @fitness-ignore-file project-readme-existence -- internal module, not a package root
+/**
+ * @fileoverview Shared severity classification helpers
+ *
+ * Centralizes severity-based signal filtering and counting logic
+ * used across types, framework, and recipes modules.
+ */
+
+import type { SignalSeverity } from '@opensip-tools/core'
+
+/** Returns true for 'high' or 'critical' severity signals (error-level) */
+function isErrorSeverity(severity: SignalSeverity): boolean {
+  return severity === 'high' || severity === 'critical'
+}
+
+/** Returns true for 'medium' severity signals (warning-level) */
+function isWarningSeverity(severity: SignalSeverity): boolean {
+  return severity === 'medium'
+}
+
+/** Count error-level signals in an array */
+export function countErrors(signals: readonly { severity: string }[]): number {
+  let count = 0
+  for (const s of signals) {
+    if (isErrorSeverity(s.severity as SignalSeverity)) count++
+  }
+  return count
+}
+
+/** Count warning-level signals in an array */
+export function countWarnings(signals: readonly { severity: string }[]): number {
+  let count = 0
+  for (const s of signals) {
+    if (isWarningSeverity(s.severity as SignalSeverity)) count++
+  }
+  return count
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    // Loader tests dynamic-import .mjs fixtures that themselves import
+    // @opensip-tools/fitness — a chain that resolves quickly on a warm
+    // cache (~1s) but can hit 5s+ on cold CI runners. 30s is generous
+    // enough to absorb cold-cache import overhead without masking
+    // genuinely hung tests (a real hang at 30s is the same CI problem
+    // as one at 5s).
+    testTimeout: 30_000,
+    coverage: {
+      include: ['src/**'],
+      exclude: [
+        'src/**/*.test.ts',
+        'src/**/__tests__/**',
+        'src/**/index.ts',
+        // Pure type modules
+        'src/types/**/*.ts',
+        'src/framework/check-types.ts',
+        'src/recipes/types.ts',
+        'src/recipes/service-types.ts',
+        'src/plugins/types.ts',
+        'src/signalers/types.ts',
+        'src/targets/types.ts',
+        // CLI handlers — integration-tested via the e2e suite, not
+        // independently unit-testable without re-creating the orchestrator.
+        'src/cli/**',
+        'src/tool.ts',
+      ],
+    },
+  },
+});