@nebulord/sickbay-core 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @nebulord/sickbay-core
+
+The analysis engine for Sickbay. Orchestrates all health checks in parallel and returns a structured `SickbayReport`.
+
+## Overview
+
+`@nebulord/sickbay-core` exposes a single `runSickbay()` function that:
+
+1. Detects project metadata (framework, package manager, tooling)
+2. Runs all enabled checks concurrently via `Promise.allSettled`
+3. Calculates weighted scores per category
+4. Returns a `SickbayReport` with issues and fix suggestions
+
+## API
+
+### `runSickbay(options)`
+
+```typescript
+import { runSickbay } from '@nebulord/sickbay-core';
+
+const report = await runSickbay({
+  projectPath: '/path/to/project',
+  checks: ['knip', 'npm-audit'],   // optional — runs all if omitted
+  verbose: false,
+  onCheckStart: (name) => console.log(`Starting ${name}`),
+  onCheckComplete: (result) => console.log(`Done: ${result.id}`),
+});
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `projectPath` | `string` | Absolute path to the project root |
+| `checks` | `string[]` | Subset of check IDs to run (default: all) |
+| `verbose` | `boolean` | Pass through tool output |
+| `onCheckStart` | `(name: string) => void` | Called when a check begins |
+| `onCheckComplete` | `(result: CheckResult) => void` | Called when a check finishes |
+
+### Key Types
+
+```typescript
+interface SickbayReport {
+  timestamp: string;
+  projectPath: string;
+  projectInfo: ProjectInfo;
+  checks: CheckResult[];
+  overallScore: number;
+  summary: { critical: number; warnings: number; info: number };
+}
+
+interface CheckResult {
+  id: string;
+  category: 'dependencies' | 'performance' | 'code-quality' | 'security' | 'git';
+  name: string;
+  score: number;           // 0–100
+  status: 'pass' | 'warning' | 'fail' | 'skipped';
+  issues: Issue[];
+  toolsUsed: string[];
+  duration: number;        // milliseconds
+  metadata?: Record<string, unknown>;
+}
+
+interface Issue {
+  severity: 'critical' | 'warning' | 'info';
+  message: string;
+  file?: string;
+  fix?: { description: string; command: string };
+  reportedBy: string[];
+}
+```
+
+## Checks
+
+Each check lives in `src/integrations/` and extends `BaseRunner`:
+
+| File | Check ID | External tool |
+|------|----------|---------------|
+| `knip.ts` | `knip` | `knip` |
+| `depcheck.ts` | `depcheck` | `depcheck` |
+| `npm-check-updates.ts` | `npm-check-updates` | `ncu` |
+| `npm-audit.ts` | `npm-audit` | `npm` |
+| `license-checker.ts` | `license-checker` | `license-checker` |
+| `madge.ts` | `madge` | `madge` |
+| `jscpd.ts` | `jscpd` | `jscpd` |
+| `coverage.ts` | `coverage` | *(auto-runs vitest/jest)* |
+| `source-map-explorer.ts` | `source-map-explorer` | `source-map-explorer` |
+| `git.ts` | `git` | `git` |
+
+### Adding a new check
+
+1. Create `src/integrations/my-check.ts` extending `BaseRunner`
+2. Implement `async run(projectPath): Promise<CheckResult>`
+3. Optionally implement `async isApplicable(projectPath): Promise<boolean>`
+4. Register it in `src/runner.ts` in the `ALL_RUNNERS` array
+
+```typescript
+export class MyCheckRunner extends BaseRunner {
+  name = 'my-check';
+  category = 'code-quality' as const;
+
+  async run(projectPath: string): Promise<CheckResult> {
+    const elapsed = timer();
+    // ... run tool, parse output, build issues array
+    return {
+      id: 'my-check',
+      category: this.category,
+      name: 'My Check',
+      score: 100,
+      status: 'pass',
+      issues: [],
+      toolsUsed: ['my-tool'],
+      duration: elapsed(),
+    };
+  }
+}
+```
+
+## Scoring Weights
+
+```typescript
+const CATEGORY_WEIGHTS = {
+  security: 0.30,
+  dependencies: 0.25,
+  'code-quality': 0.25,
+  performance: 0.15,
+  git: 0.05,
+};
+```
+
+## Build
+
+```bash
+pnpm build   # tsup → dist/
+pnpm dev     # watch mode
+```

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+interface Quote {
+    text: string;
+    source: string;
+    severity: 'critical' | 'warning' | 'info' | 'allClear';
+}
+interface SickbayReport {
+    timestamp: string;
+    projectPath: string;
+    projectInfo: ProjectInfo;
+    checks: CheckResult[];
+    overallScore: number;
+    summary: {
+        critical: number;
+        warnings: number;
+        info: number;
+    };
+    quote?: Quote;
+}
+interface ProjectInfo {
+    name: string;
+    version: string;
+    hasTypeScript: boolean;
+    hasESLint: boolean;
+    hasPrettier: boolean;
+    framework: 'react' | 'next' | 'vite' | 'cra' | 'express' | 'fastify' | 'koa' | 'hapi' | 'node' | 'hono' | 'unknown';
+    packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun';
+    totalDependencies: number;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    overrides?: Record<string, string>;
+}
+interface CheckResult {
+    id: string;
+    category: 'dependencies' | 'performance' | 'code-quality' | 'security' | 'git' | 'unknown-category';
+    name: string;
+    score: number;
+    status: 'pass' | 'warning' | 'fail' | 'skipped';
+    issues: Issue[];
+    toolsUsed: string[];
+    duration: number;
+    metadata?: Record<string, unknown>;
+}
+interface Issue {
+    severity: 'critical' | 'warning' | 'info';
+    message: string;
+    file?: string;
+    fix?: FixSuggestion;
+    reportedBy: string[];
+}
+interface FixSuggestion {
+    command?: string;
+    description: string;
+    modifiesSource?: boolean;
+    nextSteps?: string;
+    codeChange?: {
+        before: string;
+        after: string;
+    };
+}
+type Framework = 'react' | 'next' | 'angular' | 'vue' | 'svelte' | 'remix';
+type Runtime = 'browser' | 'node' | 'edge' | 'unknown';
+type BuildTool = 'vite' | 'webpack' | 'esbuild' | 'rollup' | 'tsc' | 'unknown';
+type TestFramework = 'vitest' | 'jest' | 'mocha' | null;
+interface ProjectContext {
+    runtime: Runtime;
+    frameworks: Framework[];
+    buildTool: BuildTool;
+    testFramework: TestFramework;
+}
+interface ToolRunner {
+    name: string;
+    category: CheckResult['category'];
+    run(projectPath: string, options?: RunOptions): Promise<CheckResult>;
+    isApplicable(projectPath: string, context: ProjectContext): Promise<boolean>;
+    isApplicableToContext(context: ProjectContext): boolean;
+}
+interface RunOptions {
+    verbose?: boolean;
+    timeout?: number;
+}
+interface ToolResult {
+    tool: string;
+    status: 'success' | 'error' | 'skipped';
+    data: unknown;
+    duration: number;
+    error?: string;
+}
+interface MonorepoInfo {
+    isMonorepo: true;
+    type: 'pnpm' | 'npm' | 'yarn' | 'turbo' | 'nx' | 'lerna';
+    packageManager: ProjectInfo['packageManager'];
+    packagePaths: string[];
+}
+interface PackageReport {
+    name: string;
+    path: string;
+    relativePath: string;
+    framework: ProjectInfo['framework'];
+    runtime: Runtime;
+    checks: CheckResult[];
+    score: number;
+    summary: {
+        critical: number;
+        warnings: number;
+        info: number;
+    };
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+}
+interface MonorepoReport {
+    isMonorepo: true;
+    timestamp: string;
+    rootPath: string;
+    monorepoType: MonorepoInfo['type'];
+    packageManager: ProjectInfo['packageManager'];
+    packages: PackageReport[];
+    overallScore: number;
+    summary: {
+        critical: number;
+        warnings: number;
+        info: number;
+    };
+    quote?: Quote;
+}
+
+interface RunnerOptions {
+    projectPath?: string;
+    checks?: string[];
+    verbose?: boolean;
+    quotes?: boolean;
+    onRunnersReady?: (names: string[]) => void;
+    onCheckStart?: (name: string) => void;
+    onCheckComplete?: (result: CheckResult) => void;
+    onPackageStart?: (name: string) => void;
+    onPackageComplete?: (report: PackageReport) => void;
+}
+declare function runSickbay(options?: RunnerOptions): Promise<SickbayReport>;
+declare function runSickbayMonorepo(options?: RunnerOptions): Promise<MonorepoReport>;
+
+interface DependencyTreeNode {
+    name: string;
+    version: string;
+    dependencies?: Record<string, DependencyTreeNode>;
+}
+interface DependencyTree {
+    name: string;
+    version: string;
+    packageManager: string;
+    dependencies: Record<string, DependencyTreeNode>;
+}
+interface MonorepoDependencyTree {
+    packages: Record<string, DependencyTree>;
+}
+declare function getDependencyTree(projectPath: string, packageManager: ProjectInfo['packageManager']): Promise<DependencyTree>;
+
+declare function calculateOverallScore(checks: CheckResult[]): number;
+declare function buildSummary(checks: CheckResult[]): SickbayReport['summary'];
+declare function getScoreColor(score: number): 'green' | 'yellow' | 'red';
+declare function getScoreEmoji(score: number): string;
+
+/**
+ * detectProject analyzes the given project directory to extract key information about the project setup.
+ * It reads the package.json file to determine the project's name, version, dependencies, and devDependencies.
+ * The function checks for the presence of TypeScript configuration and ESLint/Prettier configurations to infer if those tools are being used.
+ * It also detects the framework used (e.g., Next.js, Vite, Create React App) based on dependencies and configuration files.
+ * Finally, it identifies the package manager in use by checking for lock files (pnpm-lock.yaml, yarn.lock).
+ * This information is crucial for tailoring checks and recommendations specific to the project's technology stack and tooling.
+ */
+declare function detectProject(projectPath: string): Promise<ProjectInfo>;
+declare function detectPackageManager(projectPath: string): ProjectInfo["packageManager"];
+declare function detectContext(projectPath: string): Promise<ProjectContext>;
+
+type NotMonorepo = {
+    isMonorepo: false;
+};
+declare function detectMonorepo(rootPath: string): Promise<MonorepoInfo | NotMonorepo>;
+
+declare const WARN_LINES = 400;
+declare const CRITICAL_LINES = 600;
+declare const SCORE_EXCELLENT = 90;
+declare const SCORE_GOOD = 80;
+declare const SCORE_FAIR = 60;
+
+export { type BuildTool, CRITICAL_LINES, type CheckResult, type DependencyTree, type DependencyTreeNode, type FixSuggestion, type Framework, type Issue, type MonorepoDependencyTree, type MonorepoInfo, type MonorepoReport, type PackageReport, type ProjectContext, type ProjectInfo, type Quote, type RunOptions, type Runtime, SCORE_EXCELLENT, SCORE_FAIR, SCORE_GOOD, type SickbayReport, type TestFramework, type ToolResult, type ToolRunner, WARN_LINES, buildSummary, calculateOverallScore, detectContext, detectMonorepo, detectPackageManager, detectProject, getDependencyTree, getScoreColor, getScoreEmoji, runSickbay, runSickbayMonorepo };