@bfra.me/workspace-analyzer 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,146 @@
+import { Result } from '@bfra.me/es/result';
+export { Err, Ok, Result, err, flatMap, fromPromise, fromThrowable, isErr, isOk, map, mapErr, ok, unwrap, unwrapOr } from '@bfra.me/es/result';
+
+/**
+ * Core type definitions for workspace analysis.
+ *
+ * These types define the structure of analysis results, issues, severity levels,
+ * and configuration options used throughout the analyzer.
+ */
+
+/**
+ * Severity levels for analysis issues, from informational to critical errors.
+ */
+type Severity = 'info' | 'warning' | 'error' | 'critical';
+/**
+ * Categories of analysis issues for grouping and filtering.
+ */
+type IssueCategory = 'configuration' | 'dependency' | 'architecture' | 'performance' | 'circular-import' | 'unused-export' | 'type-safety';
+/**
+ * Location information for precise issue reporting.
+ */
+interface IssueLocation {
+    /** Absolute file path where the issue was detected */
+    readonly filePath: string;
+    /** Starting line number (1-indexed) */
+    readonly line?: number;
+    /** Starting column number (1-indexed) */
+    readonly column?: number;
+    /** Ending line number (1-indexed) */
+    readonly endLine?: number;
+    /** Ending column number (1-indexed) */
+    readonly endColumn?: number;
+}
+/**
+ * Represents a single issue detected during analysis.
+ */
+interface Issue {
+    /** Unique identifier for the issue type (e.g., 'circular-import', 'unused-dep') */
+    readonly id: string;
+    /** Human-readable title summarizing the issue */
+    readonly title: string;
+    /** Detailed description explaining the problem and potential impact */
+    readonly description: string;
+    /** Severity level determining how critical this issue is */
+    readonly severity: Severity;
+    /** Category for grouping related issues */
+    readonly category: IssueCategory;
+    /** Location where the issue was detected */
+    readonly location: IssueLocation;
+    /** Additional locations related to this issue (e.g., cycle participants) */
+    readonly relatedLocations?: readonly IssueLocation[];
+    /** Suggested fix or action to resolve the issue */
+    readonly suggestion?: string;
+    /** Additional metadata for machine processing */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Summary statistics for an analysis run.
+ */
+interface AnalysisSummary {
+    /** Total number of issues found */
+    readonly totalIssues: number;
+    /** Issues grouped by severity */
+    readonly bySeverity: Readonly<Record<Severity, number>>;
+    /** Issues grouped by category */
+    readonly byCategory: Readonly<Record<IssueCategory, number>>;
+    /** Number of packages analyzed */
+    readonly packagesAnalyzed: number;
+    /** Number of source files analyzed */
+    readonly filesAnalyzed: number;
+    /** Analysis duration in milliseconds */
+    readonly durationMs: number;
+}
+/**
+ * Complete result of a workspace analysis run.
+ */
+interface AnalysisResult {
+    /** All issues detected during analysis */
+    readonly issues: readonly Issue[];
+    /** Summary statistics */
+    readonly summary: AnalysisSummary;
+    /** Workspace root path that was analyzed */
+    readonly workspacePath: string;
+    /** Timestamp when analysis started */
+    readonly startedAt: Date;
+    /** Timestamp when analysis completed */
+    readonly completedAt: Date;
+}
+/**
+ * Configuration for controlling analyzer behavior.
+ */
+interface AnalyzerConfig {
+    /** Glob patterns for files to include in analysis */
+    readonly include?: readonly string[];
+    /** Glob patterns for files to exclude from analysis */
+    readonly exclude?: readonly string[];
+    /** Minimum severity level to report */
+    readonly minSeverity?: Severity;
+    /** Categories of issues to check */
+    readonly categories?: readonly IssueCategory[];
+    /** Whether to enable caching for incremental analysis */
+    readonly cache?: boolean;
+    /** Custom rules configuration */
+    readonly rules?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Options for the analyzeWorkspace function.
+ */
+interface AnalyzeWorkspaceOptions extends AnalyzerConfig {
+    /** Path to workspace-analyzer.config.ts file */
+    readonly configPath?: string;
+    /** Callback for progress reporting */
+    readonly onProgress?: (progress: AnalysisProgress) => void;
+}
+/**
+ * Progress information during analysis.
+ */
+interface AnalysisProgress {
+    /** Current phase of analysis */
+    readonly phase: 'scanning' | 'parsing' | 'analyzing' | 'reporting';
+    /** Current item being processed */
+    readonly current?: string;
+    /** Number of items processed so far */
+    readonly processed: number;
+    /** Total number of items to process (if known) */
+    readonly total?: number;
+}
+/**
+ * Represents an error that occurred during analysis.
+ */
+interface AnalysisError {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Stack trace if available */
+    readonly stack?: string;
+    /** Additional context about the error */
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Type alias for analysis operations that may fail.
+ */
+type AnalysisResultType<T> = Result<T, AnalysisError>;
+
+export type { AnalysisError, AnalysisProgress, AnalysisResult, AnalysisResultType, AnalysisSummary, AnalyzeWorkspaceOptions, AnalyzerConfig, Issue, IssueCategory, IssueLocation, Severity };

package/lib/types/index.js

@@ -0,0 +1,28 @@
+import "../chunk-4LSFAAZW.js";
+import {
+  err,
+  flatMap,
+  fromPromise,
+  fromThrowable,
+  isErr,
+  isOk,
+  map,
+  mapErr,
+  ok,
+  unwrap,
+  unwrapOr
+} from "../chunk-JDF7DQ4V.js";
+export {
+  err,
+  flatMap,
+  fromPromise,
+  fromThrowable,
+  isErr,
+  isOk,
+  map,
+  mapErr,
+  ok,
+  unwrap,
+  unwrapOr
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@bfra.me/workspace-analyzer",
+  "version": "0.1.0",
+  "description": "Comprehensive monorepo static analysis for workspace configuration, dependencies, and architecture",
+  "keywords": [
+    "analyzer",
+    "architecture",
+    "ast",
+    "bfra.me",
+    "circular-dependencies",
+    "dependency-analysis",
+    "monorepo",
+    "static-analysis",
+    "typescript",
+    "works"
+  ],
+  "homepage": "https://github.com/bfra-me/works/tree/main/packages/workspace-analyzer#readme",
+  "bugs": "https://github.com/bfra-me/works/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bfra-me/works.git",
+    "directory": "packages/workspace-analyzer"
+  },
+  "license": "MIT",
+  "author": "Marcus R. Brown <contact@bfra.me>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/index.d.ts",
+      "source": "./src/types/index.ts",
+      "import": "./lib/types/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "workspace-analyzer": "./lib/cli.js"
+  },
+  "files": [
+    "!**/*.map",
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@clack/prompts": "0.11.0",
+    "cac": "6.7.14",
+    "consola": "3.4.2",
+    "zod": "4.1.13",
+    "@bfra.me/doc-sync": "0.1.1",
+    "@bfra.me/es": "0.1.0"
+  },
+  "devDependencies": {
+    "memfs": "4.51.1",
+    "ts-morph": "27.0.2",
+    "typescript": "5.9.3",
+    "@bfra.me/works": "0.0.0-development"
+  },
+  "peerDependencies": {
+    "ts-morph": ">=27.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ts-morph": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint",
+    "start": "node lib/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/analyzers/analyzer.ts

@@ -0,0 +1,201 @@
+/**
+ * Core analyzer interface and types for workspace analysis.
+ *
+ * Defines the plugin architecture contract that all analyzers must implement,
+ * enabling extensible and composable analysis pipelines.
+ */
+
+import type {WorkspacePackage} from '../scanner/workspace-scanner'
+import type {Issue, IssueCategory, Severity} from '../types/index'
+import type {Result} from '../types/result'
+
+/**
+ * Context provided to analyzers during analysis runs.
+ * Contains all information needed to perform analysis without side effects.
+ */
+export interface AnalysisContext {
+  /** Root path of the workspace being analyzed */
+  readonly workspacePath: string
+  /** All packages discovered in the workspace */
+  readonly packages: readonly WorkspacePackage[]
+  /** Analyzer-specific configuration options */
+  readonly config: AnalyzerOptions
+  /** Report progress during long-running analysis */
+  readonly reportProgress?: (message: string) => void
+}
+
+/**
+ * Options for configuring analyzer behavior.
+ */
+export interface AnalyzerOptions {
+  /** Glob patterns for files to include */
+  readonly include?: readonly string[]
+  /** Glob patterns for files to exclude */
+  readonly exclude?: readonly string[]
+  /** Minimum severity level to report */
+  readonly minSeverity?: Severity
+  /** Categories to analyze (empty means all) */
+  readonly categories?: readonly IssueCategory[]
+  /** Analyzer-specific rule configurations */
+  readonly rules?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Error that can occur during analysis.
+ */
+export interface AnalyzerError {
+  /** Error code for programmatic handling */
+  readonly code: string
+  /** Human-readable error message */
+  readonly message: string
+  /** Additional context about the error */
+  readonly context?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Metadata describing an analyzer implementation.
+ */
+export interface AnalyzerMetadata {
+  /** Unique identifier for this analyzer */
+  readonly id: string
+  /** Human-readable name */
+  readonly name: string
+  /** Description of what this analyzer checks */
+  readonly description: string
+  /** Categories of issues this analyzer can detect */
+  readonly categories: readonly IssueCategory[]
+  /** Default severity for issues from this analyzer */
+  readonly defaultSeverity: Severity
+}
+
+/**
+ * Core interface that all analyzers must implement.
+ *
+ * @example
+ * ```ts
+ * const myAnalyzer: Analyzer = {
+ *   metadata: {
+ *     id: 'my-analyzer',
+ *     name: 'My Custom Analyzer',
+ *     description: 'Checks for custom patterns',
+ *     categories: ['architecture'],
+ *     defaultSeverity: 'warning',
+ *   },
+ *   async analyze(context) {
+ *     const issues: Issue[] = []
+ *     // Perform analysis...
+ *     return ok(issues)
+ *   },
+ * }
+ * ```
+ */
+export interface Analyzer {
+  /** Metadata describing this analyzer */
+  readonly metadata: AnalyzerMetadata
+  /**
+   * Perform analysis and return discovered issues.
+   *
+   * @param context - Analysis context with workspace information
+   * @returns Result containing issues found or an error
+   */
+  readonly analyze: (context: AnalysisContext) => Promise<Result<readonly Issue[], AnalyzerError>>
+}
+
+/**
+ * Factory function signature for creating analyzers.
+ */
+export type AnalyzerFactory = (options?: AnalyzerOptions) => Analyzer
+
+/**
+ * Configuration for a single analyzer in the registry.
+ */
+export interface AnalyzerRegistration {
+  /** The analyzer instance or factory */
+  readonly analyzer: Analyzer | AnalyzerFactory
+  /** Whether this analyzer is enabled by default */
+  readonly enabled: boolean
+  /** Priority for execution order (lower runs first) */
+  readonly priority: number
+}
+
+/**
+ * Creates an issue with consistent defaults.
+ *
+ * @example
+ * ```ts
+ * const issue = createIssue({
+ *   id: 'missing-types',
+ *   title: 'Missing types field',
+ *   description: 'package.json should declare a types entry point',
+ *   severity: 'warning',
+ *   category: 'configuration',
+ *   location: {filePath: '/path/to/package.json'},
+ * })
+ * ```
+ */
+export function createIssue(
+  params: Omit<Issue, 'relatedLocations' | 'suggestion' | 'metadata'> & {
+    relatedLocations?: Issue['relatedLocations']
+    suggestion?: Issue['suggestion']
+    metadata?: Issue['metadata']
+  },
+): Issue {
+  return {
+    id: params.id,
+    title: params.title,
+    description: params.description,
+    severity: params.severity,
+    category: params.category,
+    location: params.location,
+    relatedLocations: params.relatedLocations,
+    suggestion: params.suggestion,
+    metadata: params.metadata,
+  }
+}
+
+/**
+ * Helper to check if an analyzer should skip a category based on configuration.
+ */
+export function shouldAnalyzeCategory(
+  category: IssueCategory,
+  options: AnalyzerOptions | undefined,
+): boolean {
+  const categories = options?.categories
+  if (categories === undefined || categories.length === 0) {
+    return true
+  }
+  return categories.includes(category)
+}
+
+/**
+ * Helper to check if an issue meets minimum severity threshold.
+ */
+export function meetsMinSeverity(severity: Severity, minSeverity: Severity | undefined): boolean {
+  if (minSeverity === undefined) {
+    return true
+  }
+
+  const severityOrder: Record<Severity, number> = {
+    info: 0,
+    warning: 1,
+    error: 2,
+    critical: 3,
+  }
+
+  return severityOrder[severity] >= severityOrder[minSeverity]
+}
+
+/**
+ * Filters issues based on configuration options.
+ */
+export function filterIssues(issues: readonly Issue[], options: AnalyzerOptions): readonly Issue[] {
+  return issues.filter(issue => {
+    if (!meetsMinSeverity(issue.severity, options.minSeverity)) {
+      return false
+    }
+    if (!shouldAnalyzeCategory(issue.category, options)) {
+      return false
+    }
+    return true
+  })
+}