@opensip-tools/fitness 1.0.4

package/src/targets/target-registry.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Target Registry
+ *
+ * Registry for target definitions. Provides lookup by name and tags.
+ * Standalone implementation without platform GenericRegistry dependency.
+ *
+ * The entire targets module uses a synchronous API because target definitions
+ * are loaded once at startup from a small YAML config file (via loader.ts) and
+ * then held in-memory for fast, repeated lookups throughout the process lifetime.
+ * The resolver (resolver.ts) similarly uses synchronous glob expansion. Since the
+ * data set is small and bounded by project configuration, async I/O offers no
+ * practical benefit and would complicate every call site that queries targets.
+ */
+
+import type { Target } from './types.js'
+
+/** Registry for target definitions with lookup by name and tags. */
+export class TargetRegistry {
+  private readonly targets = new Map<string, Target>()
+
+  /**
+   * Register a target. Silently skips if a target with the same name already exists.
+   * @param target - Target definition to register
+   * @returns This registry instance for chaining
+   */
+  register(target: Target): this {
+    const name = target.config.name
+
+    if (this.targets.has(name)) {
+      return this
+    }
+
+    this.targets.set(name, target)
+    return this
+  }
+
+  /**
+   * Look up a target by its config name.
+   * @param name - Target name to find
+   * @returns The matching target, or undefined if not found
+   */
+  getByName(name: string): Target | undefined {
+    return this.targets.get(name)
+  }
+
+  /** Return all registered targets. */
+  getAll(): readonly Target[] {
+    return [...this.targets.values()]
+  }
+
+  /**
+   * Return all targets that include the given tag.
+   * @param tag - Tag string to filter by
+   * @returns Targets whose config.tags contain the tag
+   */
+  getByTag(tag: string): readonly Target[] {
+    return this.getAll().filter((t) => t.config.tags?.includes(tag))
+  }
+
+  /**
+   * Check whether a target with the given name is registered.
+   * @param name - Target name to check
+   * @returns True if the target exists in the registry
+   */
+  has(name: string): boolean {
+    return this.targets.has(name)
+  }
+
+  /**
+   * Find targets whose languages and concerns intersect with the given scope.
+   *
+   * Both dimensions must match (AND logic):
+   * - A target matches languages if the intersection is non-empty (or either side is empty/undefined)
+   * - A target matches concerns if the intersection is non-empty (or either side is empty/undefined)
+   *
+   * @param languages - Languages the check is designed for
+   * @param concerns - Semantic concerns the check targets
+   * @returns Targets that match both dimensions
+   */
+  findByScope(languages: readonly string[], concerns: readonly string[]): readonly Target[] {
+    return this.getAll().filter((target) => {
+      const targetLangs = target.config.languages
+      const targetConcerns = target.config.concerns
+
+      // Language matching: if either side has no languages, treat as "matches any"
+      const languageMatch =
+        languages.length === 0 ||
+        !targetLangs || targetLangs.length === 0 ||
+        languages.some((lang) => targetLangs.includes(lang))
+
+      // Concern matching: if either side has no concerns, treat as "matches any"
+      const concernMatch =
+        concerns.length === 0 ||
+        !targetConcerns || targetConcerns.length === 0 ||
+        concerns.some((concern) => targetConcerns.includes(concern))
+
+      return languageMatch && concernMatch
+    })
+  }
+
+  /** Number of registered targets. */
+  get size(): number {
+    return this.targets.size
+  }
+
+  /** Remove all targets from the registry. */
+  clear(): void {
+    this.targets.clear()
+  }
+}
+

package/src/targets/types.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Target type definitions for shared targeting
+ */
+
+/** Configuration for a named target (file set with include/exclude globs). */
+export interface TargetConfig {
+  /** Kebab-case identifier, e.g. 'backend', 'module-foundation' */
+  readonly name: string
+  /** Human-readable description */
+  readonly description: string
+  /** Glob patterns to include */
+  readonly include: readonly string[]
+  /** Glob patterns to exclude */
+  readonly exclude: readonly string[]
+  /** Context doc paths for assessments */
+  readonly context?: readonly string[]
+  /** Tags for filtering/grouping */
+  readonly tags?: readonly string[]
+  /** Languages this target contains (e.g. 'typescript', 'tsx', 'json') */
+  readonly languages?: readonly string[]
+  /** Semantic concerns this target represents (e.g. 'backend', 'server', 'api') */
+  readonly concerns?: readonly string[]
+}
+
+/** A resolved target wrapping its configuration. */
+export interface Target {
+  readonly config: TargetConfig
+}
+
+/**
+ * Per-check target overrides.
+ * Maps check slug → target name(s) to restrict which files a check runs against.
+ */
+type CheckTargetMap = Readonly<Record<string, string | readonly string[]>>
+
+/**
+ * Project-local plugin declarations — one list per plugin domain.
+ *
+ * When present in the config file, these override the default user-level
+ * plugin directory (`~/.opensip-tools/<domain>/`). Plugins get installed
+ * into `<project-root>/.opensip-tools/<domain>/` and are version-pinned
+ * by the project rather than by each developer's machine.
+ *
+ * Each entry is any npm install spec: `@scope/pkg`, `@scope/pkg@^1.2.3`,
+ * `./local-path`, `/abs/path/to/pkg.tgz`, `git+https://...`, etc.
+ */
+interface PluginsConfig {
+  readonly fit?: readonly string[]
+  readonly sim?: readonly string[]
+  readonly asm?: readonly string[]
+  readonly lang?: readonly string[]
+  /**
+   * Explicit list of npm package names to load as check providers
+   * (e.g. ['@opensip-tools/checks-python', '@my-org/checks-internal']).
+   *
+   * When present, ONLY these packages are loaded. Auto-discovery is
+   * disabled for the run. No package is privileged: if you want the
+   * default check pack you must list `@opensip-tools/checks-builtin`
+   * (or its successors) here explicitly. An empty list disables all
+   * check loading and triggers a no-checks-loaded warning.
+   */
+  readonly checkPackages?: readonly string[]
+  /**
+   * When false, the CLI does NOT scan node_modules for
+   * @opensip-tools/checks-* packages. Default: true.
+   * Ignored when `checkPackages` is set (explicit list always wins).
+   */
+  readonly autoDiscoverChecks?: boolean
+}
+
+/**
+ * Result of loading targets config, including both the target registry
+ * and per-check target overrides.
+ */
+export interface TargetsConfig {
+  /** Global file exclusion patterns (replaces .fitnessignore). */
+  readonly globalExcludes: readonly string[]
+  /** Per-check target overrides for third-party/marketplace checks. */
+  readonly checkOverrides: CheckTargetMap
+  /**
+   * Project-local plugin declarations, keyed by domain. When any domain
+   * has entries here, plugin discovery for that domain reads from
+   * `<project>/.opensip-tools/<domain>/` instead of `~/.opensip-tools/<domain>/`.
+   * Absent (or undefined per-domain) = fall back to the user-level dir
+   * for that domain.
+   */
+  readonly plugins?: PluginsConfig
+}
+

package/src/tool.ts

@@ -0,0 +1,302 @@
+/**
+ * fitnessTool — fitness as a Tool plugin.
+ *
+ * Owns its full Commander wiring for the `fit`, `dashboard`, `fit-list`,
+ * and `fit-recipes` subcommands. The CLI calls register() once at
+ * startup and the rest is local: every option-parsing rule, gate-mode
+ * dispatch, JSON-vs-Ink rendering decision, and dashboard auto-open
+ * lives here, in the package that owns the fitness command surface.
+ *
+ * The CLI no longer imports `executeFit`, `openDashboard`, etc.
+ * directly — it just calls `fitnessTool.register(cli)`. Adding a new
+ * subcommand to fitness is a local change; no CLI edit required.
+ */
+
+
+import { EXIT_CODES } from '@opensip-tools/contracts';
+import { type Command } from 'commander';
+
+import { openDashboard } from './cli/dashboard.js';
+import { executeFit } from './cli/fit.js';
+import { listChecks } from './cli/list-checks.js';
+import { listRecipes } from './cli/list-recipes.js';
+import {
+  saveBaseline,
+  compareToBaseline,
+  renderGateCompareOutput,
+  GateBaselineMissingError,
+  GateBaselineInvalidError,
+  DEFAULT_BASELINE_PATH,
+} from './gate.js';
+
+import type { CliArgs, FitOptions, ToolOptions } from '@opensip-tools/contracts';
+import type { Tool, ToolCliContext, ToolCommandDescriptor } from '@opensip-tools/core';
+
+// =============================================================================
+// COMMAND DESCRIPTORS — used by --help listings and conflict detection.
+// =============================================================================
+
+const FIT: ToolCommandDescriptor = {
+  name: 'fit',
+  description: 'Run fitness checks',
+};
+
+const DASHBOARD: ToolCommandDescriptor = {
+  name: 'dashboard',
+  description: 'Generate the HTML dashboard and open it in your browser',
+};
+
+const FIT_LIST: ToolCommandDescriptor = {
+  name: 'fit-list',
+  description: 'List available fitness checks',
+  aliases: ['list-checks'],
+};
+
+const FIT_RECIPES: ToolCommandDescriptor = {
+  name: 'fit-recipes',
+  description: 'List available fitness recipes',
+  aliases: ['list-recipes'],
+};
+
+// =============================================================================
+// REGISTER — wires Commander subcommands onto the CLI's program.
+// =============================================================================
+
+function fitOptsToCliArgs(opts: FitOptions & { quiet?: boolean; open?: boolean }): CliArgs {
+  return {
+    command: 'fit',
+    json: opts.json,
+    check: opts.check,
+    recipe: opts.recipe,
+    cwd: opts.cwd,
+    help: false,
+    list: opts.list,
+    listRecipes: opts.recipes,
+    verbose: opts.verbose,
+    reportTo: opts.reportTo,
+    apiKey: opts.apiKey,
+    exclude: opts.exclude,
+    findings: opts.findings,
+    tags: opts.tags,
+    quiet: opts.quiet === true,
+    open: opts.open === true,
+    config: opts.config,
+    gateSave: opts.gateSave === true,
+    gateCompare: opts.gateCompare === true,
+    baseline: opts.baseline,
+  };
+}
+
+function register(cli: ToolCliContext): void {
+  // Cast once — the contract intentionally types `program` loosely so
+  // tools aren't pinned to a specific Commander major.
+  const program = cli.program as Command;
+
+  // -- fit ------------------------------------------------------------------
+  program
+    .command(FIT.name)
+    .description(FIT.description)
+    .option('--recipe <name>', 'Use a named recipe (default, quick-smoke, backend, etc.)')
+    .option('--check <slug>', 'Run a single check by slug')
+    .option('--tags <tags>', 'Filter checks by tags (comma-separated)')
+    .option('--list', 'List available checks', false)
+    .option('--recipes', 'List available recipes', false)
+    .option('--json', 'Output structured JSON', false)
+    .option('-v, --verbose', 'Show finding details inline + findings summary', false)
+    .option('--findings', 'Show all findings grouped by check after the run', false)
+    .option('--report-to <url>', 'POST findings to a URL (OpenSIP Cloud or compatible)')
+    .option('--api-key <key>', 'API key for --report-to authentication')
+    .option('--exclude <slug>', 'Exclude check (repeatable)', (val: string, prev: string[]) => [...prev, val], [] as string[])
+    .option('--cwd <path>', 'Target directory', process.cwd())
+    .option('--config <path>', 'Path to opensip-tools.config.yml (overrides package.json pointer and default)')
+    .option('-q, --quiet', 'Suppress banner / boxes; print only the pass-fail summary', false)
+    .option('--open', 'Launch the HTML dashboard in your browser after the run completes', false)
+    .option('--debug', 'Enable debug mode for structured log output', false)
+    .option('--gate-save', 'Architecture-gate: save current findings as baseline (mutually exclusive with --gate-compare)', false)
+    .option('--gate-compare', 'Architecture-gate: compare current findings against baseline; exit 1 on regression', false)
+    .option('--baseline <path>', 'Path to baseline file for --gate-save / --gate-compare (default: opensip-tools/.runtime/baseline.sarif)')
+    .action(async (opts: FitOptions & { quiet?: boolean; open?: boolean }) => {
+      const args = fitOptsToCliArgs(opts);
+
+      // Architecture gate: --gate-save / --gate-compare. Headless,
+      // stdout-only, exit code is the gate decision.
+      if (args.gateSave === true || args.gateCompare === true) {
+        await runGateMode(args, cli);
+        return;
+      }
+
+      // --list
+      if (args.list) {
+        const result = await listChecks(args.cwd);
+        if (args.json) { process.stdout.write(JSON.stringify(result, null, 2) + '\n'); return; }
+        await cli.render(result);
+        return;
+      }
+
+      // --recipes
+      if (args.listRecipes) {
+        const result = await listRecipes(args.cwd);
+        if (args.json) { process.stdout.write(JSON.stringify(result, null, 2) + '\n'); return; }
+        await cli.render(result);
+        return;
+      }
+
+      // Main fit execution.
+      if (args.json) {
+        const fitResult = await executeFit(args);
+        if (fitResult.result.type === 'error') {
+          cli.setExitCode(fitResult.result.exitCode);
+          process.stdout.write(JSON.stringify({ error: fitResult.result.message }, null, 2) + '\n');
+        } else {
+          if (fitResult.result.type === 'fit-done' && fitResult.result.shouldFail) {
+            cli.setExitCode(EXIT_CODES.RUNTIME_ERROR);
+          }
+          process.stdout.write(JSON.stringify(fitResult.output, null, 2) + '\n');
+        }
+        return;
+      }
+
+      // Visual mode — Ink-rendered live results. The CLI supplies the
+      // renderer via cli.renderLive() so this file doesn't depend on
+      // the CLI package directly.
+      await cli.renderLive('fit', args);
+
+      // --open: launch dashboard after the run when conditions allow.
+      await cli.maybeOpenDashboard({
+        openRequested: Boolean(opts.open),
+        jsonOutput: Boolean(args.json),
+        cwd: args.cwd,
+      });
+    });
+
+  // -- dashboard ------------------------------------------------------------
+  program
+    .command(DASHBOARD.name)
+    .description(DASHBOARD.description)
+    .option('--cwd <path>', 'Target directory', process.cwd())
+    .option('--json', 'Output structured JSON', false)
+    .option('--debug', 'Enable debug mode for structured log output', false)
+    .action(async (opts: ToolOptions) => {
+      const result = await openDashboard(opts.cwd);
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+      await cli.render(result);
+    });
+
+  // -- fit-list (alias: list-checks) ----------------------------------------
+  const fitListCmd = program
+    .command(FIT_LIST.name)
+    .description(FIT_LIST.description);
+  for (const alias of FIT_LIST.aliases ?? []) fitListCmd.alias(alias);
+  fitListCmd
+    .option('--cwd <path>', 'Target directory', process.cwd())
+    .option('--json', 'Output structured JSON', false)
+    .action(async (opts: ToolOptions) => {
+      const result = await listChecks(opts.cwd);
+      if (opts.json) { process.stdout.write(JSON.stringify(result, null, 2) + '\n'); return; }
+      await cli.render(result);
+    });
+
+  // -- fit-recipes (alias: list-recipes) ------------------------------------
+  const fitRecipesCmd = program
+    .command(FIT_RECIPES.name)
+    .description(FIT_RECIPES.description);
+  for (const alias of FIT_RECIPES.aliases ?? []) fitRecipesCmd.alias(alias);
+  fitRecipesCmd
+    .option('--cwd <path>', 'Target directory', process.cwd())
+    .option('--json', 'Output structured JSON', false)
+    .action(async (opts: ToolOptions) => {
+      const result = await listRecipes(opts.cwd);
+      if (opts.json) { process.stdout.write(JSON.stringify(result, null, 2) + '\n'); return; }
+      await cli.render(result);
+    });
+}
+
+// =============================================================================
+// GATE MODE — extracted helper used by `fit --gate-save` / `--gate-compare`.
+// =============================================================================
+
+async function runGateMode(args: CliArgs, cli: ToolCliContext): Promise<void> {
+  if (args.gateSave === true && args.gateCompare === true) {
+    cli.logger.warn({
+      evt: 'cli.gate.config_error',
+      module: 'cli:gate',
+      reason: 'mutually-exclusive flags',
+      msg: '--gate-save and --gate-compare specified together',
+    });
+    cli.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+    process.stderr.write('Error: --gate-save and --gate-compare are mutually exclusive.\n');
+    return;
+  }
+  const baselinePath = args.baseline ?? DEFAULT_BASELINE_PATH;
+  const fitResult = await executeFit(args);
+  if (fitResult.result.type !== 'fit-done') {
+    cli.logger.warn({
+      evt: 'cli.gate.fit_failed',
+      module: 'cli:gate',
+      mode: args.gateSave === true ? 'save' : 'compare',
+      baselinePath,
+      reason: fitResult.result.message,
+    });
+    cli.setExitCode(fitResult.result.exitCode);
+    process.stderr.write(`Error: ${fitResult.result.message}\n`);
+    return;
+  }
+  const output = fitResult.output!;
+  try {
+    if (args.gateSave === true) {
+      saveBaseline(output, baselinePath);
+      const findingCount = output.checks.reduce((n, c) => n + c.findings.length, 0);
+      process.stdout.write(`Baseline saved to ${baselinePath}\n`);
+      process.stdout.write(`  ${output.checks.length} check(s), ${findingCount} finding(s)\n`);
+      return;
+    }
+    const result = compareToBaseline(output, baselinePath);
+    process.stdout.write(renderGateCompareOutput(result) + '\n');
+    cli.setExitCode(result.degraded ? 1 : 0);
+    return;
+  } catch (error) {
+    if (error instanceof GateBaselineMissingError || error instanceof GateBaselineInvalidError) {
+      cli.logger.warn({
+        evt: 'cli.gate.baseline_error',
+        module: 'cli:gate',
+        mode: args.gateSave === true ? 'save' : 'compare',
+        baselinePath,
+        errorType: error.name,
+        reason: error.message,
+      });
+      cli.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+      process.stderr.write(`Error: ${error.message}\n`);
+      return;
+    }
+    throw error;
+  }
+}
+
+// =============================================================================
+// EXPORT
+// =============================================================================
+
+export const fitnessTool: Tool = {
+  metadata: {
+    id: 'fitness',
+    version: '1.0.0',
+    description: 'Run fitness checks against a codebase',
+  },
+  commands: [FIT, DASHBOARD, FIT_LIST, FIT_RECIPES],
+  register,
+  initialize: async (): Promise<void> => {
+    // ensureChecksLoaded() is called inside the executeFit / listChecks
+    // / listRecipes paths, so a separate initialize() pass is not
+    // strictly needed today. Left as a no-op so fitness has somewhere
+    // to hang future tool-startup work (eager check-pack discovery,
+    // catalog warming, etc.) without requiring a contract change.
+  },
+};
+
+// Pre-load hook setter — used by the CLI to wire project-plugin
+// auto-sync into ensureChecksLoaded's startup path. Re-exported here
+// so the CLI's bootstrap doesn't need to deep-import.
+export { setPreLoadHook } from './cli/fit.js';