@oxog/codeguardian 1.0.0

package/dist/types-CQZEdzEa.d.ts

@@ -0,0 +1,487 @@
+import ts from 'typescript';
+
+/** Severity level for findings. */
+type Severity = 'critical' | 'error' | 'warning' | 'info';
+/** Detected role of a source file based on path and content. */
+type FileRole = 'controller' | 'service' | 'repository' | 'util' | 'type' | 'config' | 'test' | 'unknown';
+/**
+ * Information about a single import statement.
+ *
+ * @example
+ * ```typescript
+ * const info: ImportInfo = {
+ *   source: './user.service',
+ *   specifiers: ['UserService'],
+ *   isTypeOnly: false,
+ * };
+ * ```
+ */
+interface ImportInfo {
+    /** Module specifier (e.g., './user.service') */
+    source: string;
+    /** Imported names */
+    specifiers: string[];
+    /** Whether this is a type-only import */
+    isTypeOnly: boolean;
+}
+/**
+ * An edge in the import dependency graph.
+ *
+ * @example
+ * ```typescript
+ * const edge: ImportEdge = {
+ *   from: 'src/controllers/user.controller.ts',
+ *   to: 'src/services/user.service.ts',
+ *   specifiers: ['UserService'],
+ *   isTypeOnly: false,
+ * };
+ * ```
+ */
+interface ImportEdge {
+    /** Importing file path */
+    from: string;
+    /** Imported file path */
+    to: string;
+    /** Imported symbol names */
+    specifiers: string[];
+    /** Whether type-only import */
+    isTypeOnly: boolean;
+}
+/** Parameter information for a function. */
+interface ParamInfo {
+    name: string;
+    type: string;
+    optional: boolean;
+}
+/** An issue detected in a function during graph building. */
+interface Issue {
+    message: string;
+    line: number;
+    column: number;
+}
+/**
+ * A node representing a source file in the codebase graph.
+ *
+ * @example
+ * ```typescript
+ * const file: FileNode = {
+ *   path: 'src/services/user.service.ts',
+ *   role: 'service',
+ *   layer: 'service',
+ *   exports: ['UserService'],
+ *   imports: [],
+ *   complexity: 5,
+ *   loc: 120,
+ *   functions: [],
+ * };
+ * ```
+ */
+interface FileNode {
+    /** Relative file path */
+    path: string;
+    /** Detected role */
+    role: FileRole;
+    /** Architectural layer */
+    layer: string;
+    /** Exported symbol names */
+    exports: string[];
+    /** Import information */
+    imports: ImportInfo[];
+    /** Cyclomatic complexity (sum of all functions) */
+    complexity: number;
+    /** Lines of code */
+    loc: number;
+    /** Functions defined in this file */
+    functions: FunctionNode[];
+}
+/**
+ * A node representing a function in the codebase graph.
+ *
+ * @example
+ * ```typescript
+ * const fn: FunctionNode = {
+ *   name: 'getUser',
+ *   file: 'src/services/user.service.ts',
+ *   startLine: 10,
+ *   endLine: 25,
+ *   params: [{ name: 'id', type: 'string', optional: false }],
+ *   returnType: 'Promise<User>',
+ *   complexity: 3,
+ *   isAsync: true,
+ *   hasSideEffects: true,
+ *   issues: [],
+ * };
+ * ```
+ */
+interface FunctionNode {
+    name: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    params: ParamInfo[];
+    returnType: string;
+    complexity: number;
+    isAsync: boolean;
+    hasSideEffects: boolean;
+    issues: Issue[];
+}
+/**
+ * A node representing an exported symbol.
+ *
+ * @example
+ * ```typescript
+ * const sym: SymbolNode = {
+ *   name: 'UserService',
+ *   kind: 'class',
+ *   file: 'src/services/user.service.ts',
+ *   usedBy: ['src/controllers/user.controller.ts'],
+ *   dependsOn: ['src/repositories/user.repository.ts'],
+ *   isPublicAPI: true,
+ * };
+ * ```
+ */
+interface SymbolNode {
+    name: string;
+    kind: 'function' | 'class' | 'interface' | 'type' | 'variable' | 'enum';
+    file: string;
+    usedBy: string[];
+    dependsOn: string[];
+    isPublicAPI: boolean;
+}
+/** Architectural layer definition. */
+interface LayerDefinition {
+    name: string;
+    order: number;
+    patterns: string[];
+}
+/** A detected pattern in the codebase. */
+interface DetectedPattern {
+    type: string;
+    description: string;
+    files: string[];
+    confidence: number;
+}
+/** Module dependency graph (adjacency list). */
+interface DependencyGraph {
+    /** Map of file path → set of file paths it depends on */
+    adjacency: Map<string, Set<string>>;
+}
+/**
+ * The codebase knowledge graph — core data structure.
+ *
+ * @example
+ * ```typescript
+ * const graph: CodebaseGraph = {
+ *   files: new Map(),
+ *   symbols: new Map(),
+ *   edges: [],
+ *   layers: [],
+ *   patterns: [],
+ *   dependencies: { adjacency: new Map() },
+ * };
+ * ```
+ */
+interface CodebaseGraph {
+    files: Map<string, FileNode>;
+    symbols: Map<string, SymbolNode>;
+    edges: ImportEdge[];
+    layers: LayerDefinition[];
+    patterns: DetectedPattern[];
+    dependencies: DependencyGraph;
+}
+/**
+ * A single finding (issue) detected by a rule.
+ *
+ * @example
+ * ```typescript
+ * const finding: Finding = {
+ *   message: 'console.log should not be in production code',
+ *   file: 'src/services/user.service.ts',
+ *   line: 42,
+ *   column: 5,
+ *   rule: 'quality/no-console',
+ *   severity: 'warning',
+ *   fix: { suggestion: 'Use a logger instead' },
+ * };
+ * ```
+ */
+interface Finding {
+    message: string;
+    file: string;
+    line: number;
+    column: number;
+    rule?: string;
+    severity?: Severity;
+    fix?: {
+        suggestion: string;
+        replacement?: string;
+    };
+}
+/** Category for grouping rules. */
+type RuleCategory = 'architecture' | 'security' | 'performance' | 'quality';
+/** AST visitor function map. */
+type ASTVisitors = {
+    [K in string]?: (node: ts.Node) => void;
+};
+/**
+ * Context provided to rules during analysis.
+ *
+ * @example
+ * ```typescript
+ * const check = (context: RuleContext) => {
+ *   const findings: Finding[] = [];
+ *   context.walk(context.ast, {
+ *     CallExpression(node) {
+ *       if (context.isConsoleCall(node as ts.CallExpression)) {
+ *         findings.push({ message: 'No console', file: context.file.path, line: 1, column: 1 });
+ *       }
+ *     },
+ *   });
+ *   return findings;
+ * };
+ * ```
+ */
+interface RuleContext {
+    file: FileNode;
+    ast: ts.SourceFile;
+    graph: CodebaseGraph;
+    program: ts.Program;
+    checker: ts.TypeChecker;
+    walk: (node: ts.Node, visitors: ASTVisitors) => void;
+    isCallTo: (node: ts.CallExpression, name: string) => boolean;
+    isConsoleCall: (node: ts.CallExpression, method?: string) => boolean;
+    getTypeString: (node: ts.Node) => string;
+    hasStringConcat: (node: ts.Node) => boolean;
+    getImports: () => ImportInfo[];
+    isExternallyUsed: (symbolName: string) => boolean;
+    config: Record<string, unknown>;
+}
+/**
+ * A single analysis rule.
+ *
+ * @example
+ * ```typescript
+ * const rule: Rule = {
+ *   name: 'quality/no-any',
+ *   severity: 'warning',
+ *   description: 'Disallow any type',
+ *   category: 'quality',
+ *   check: (ctx) => [],
+ * };
+ * ```
+ */
+interface Rule {
+    name: string;
+    severity: Severity;
+    description: string;
+    category: RuleCategory;
+    check: (context: RuleContext) => Finding[] | Promise<Finding[]>;
+}
+/**
+ * The kernel interface exposed to plugins during installation.
+ *
+ * @example
+ * ```typescript
+ * const install = (kernel: GuardianKernel) => {
+ *   kernel.registerRule(myRule);
+ * };
+ * ```
+ */
+interface GuardianKernel<TConfig = unknown> {
+    registerRule: (rule: Rule) => void;
+    unregisterRule: (name: string) => void;
+    getRules: () => Rule[];
+    getConfig: () => TConfig;
+}
+/**
+ * Plugin interface for extending codeguardian.
+ *
+ * @typeParam TConfig - Plugin-specific configuration type
+ *
+ * @example
+ * ```typescript
+ * const myPlugin: GuardianPlugin = {
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   install: (kernel) => {
+ *     kernel.registerRule(myRule);
+ *   },
+ * };
+ * ```
+ */
+interface GuardianPlugin<TConfig = unknown> {
+    name: string;
+    version: string;
+    dependencies?: string[];
+    install: (kernel: GuardianKernel<TConfig>) => void;
+    onInit?: (graph: CodebaseGraph) => void | Promise<void>;
+    onDestroy?: () => void | Promise<void>;
+    onError?: (error: Error) => void;
+}
+/** Severity configuration for commit blocking. */
+interface SeverityConfig {
+    blockOn: Severity[];
+    warnOn: Severity[];
+    ignoreBelow?: Severity;
+}
+/** Architecture plugin config. */
+interface ArchitecturePluginConfig {
+    enabled: boolean;
+    layers?: string[];
+    enforceDirection?: boolean;
+    maxFileLines?: number;
+    maxFunctionLines?: number;
+    maxFunctionComplexity?: number;
+}
+/** Security plugin config. */
+interface SecurityPluginConfig {
+    enabled: boolean;
+    checkInjection?: boolean;
+    checkAuth?: boolean;
+    checkSecrets?: boolean;
+    checkXSS?: boolean;
+    checkCSRF?: boolean;
+}
+/** Performance plugin config. */
+interface PerformancePluginConfig {
+    enabled: boolean;
+    checkN1Queries?: boolean;
+    checkMemoryLeaks?: boolean;
+    checkAsyncPatterns?: boolean;
+    checkBundleSize?: boolean;
+}
+/** Quality plugin config. */
+interface QualityPluginConfig {
+    enabled: boolean;
+    checkDeadCode?: boolean;
+    checkNaming?: boolean;
+    checkComplexity?: boolean;
+    maxCyclomaticComplexity?: number;
+}
+/** Optional plugin configs. */
+interface NamingPluginConfig {
+    enabled: boolean;
+}
+interface ApiPluginConfig {
+    enabled: boolean;
+}
+interface TestGuardPluginConfig {
+    enabled: boolean;
+}
+interface DepAuditPluginConfig {
+    enabled: boolean;
+    maxDepth?: number;
+}
+/** All plugin configurations. */
+interface PluginConfigs {
+    architecture?: ArchitecturePluginConfig;
+    security?: SecurityPluginConfig;
+    performance?: PerformancePluginConfig;
+    quality?: QualityPluginConfig;
+    naming?: NamingPluginConfig;
+    api?: ApiPluginConfig;
+    testGuard?: TestGuardPluginConfig;
+    depAudit?: DepAuditPluginConfig;
+}
+/** Ignore configuration. */
+interface IgnoreConfig {
+    rules?: string[];
+    files?: string[];
+    lines?: Record<string, number[]>;
+}
+/**
+ * Full project configuration (shape of .codeguardian.json).
+ *
+ * @example
+ * ```typescript
+ * const config: ProjectConfig = {
+ *   rootDir: '.',
+ *   tsconfig: './tsconfig.json',
+ *   include: ['src/**\/*.ts'],
+ *   exclude: ['**\/*.test.ts'],
+ *   severity: { blockOn: ['critical', 'error'], warnOn: ['warning'] },
+ *   plugins: { architecture: { enabled: true } },
+ *   ignore: { rules: [], files: [] },
+ * };
+ * ```
+ */
+interface ProjectConfig {
+    rootDir: string;
+    tsconfig: string;
+    include: string[];
+    exclude: string[];
+    severity: SeverityConfig;
+    plugins: PluginConfigs;
+    ignore: IgnoreConfig;
+}
+/**
+ * Inline configuration (same shape minus rootDir/tsconfig which come from GuardianConfig).
+ */
+interface InlineConfig {
+    include?: string[];
+    exclude?: string[];
+    severity?: Partial<SeverityConfig>;
+    plugins?: Partial<PluginConfigs>;
+    ignore?: Partial<IgnoreConfig>;
+}
+/**
+ * Options passed to createGuardian().
+ *
+ * @example
+ * ```typescript
+ * const config: GuardianConfig = {
+ *   rootDir: process.cwd(),
+ *   tsconfig: './tsconfig.json',
+ * };
+ * ```
+ */
+interface GuardianConfig {
+    rootDir: string;
+    tsconfig?: string;
+    config?: string | InlineConfig;
+    autoDiscover?: boolean;
+}
+/** Options for running analysis. */
+interface RunOptions {
+    staged?: boolean;
+    verbose?: boolean;
+    plugins?: string[];
+    format?: 'terminal' | 'json' | 'sarif';
+}
+/** Statistics from a run. */
+interface RunStats {
+    filesAnalyzed: number;
+    rulesExecuted: number;
+    duration: number;
+    parseTime: number;
+    analysisTime: number;
+}
+/**
+ * Result of running analysis.
+ *
+ * @example
+ * ```typescript
+ * const result: RunResult = {
+ *   findings: [],
+ *   stats: { filesAnalyzed: 10, rulesExecuted: 29, duration: 150, parseTime: 80, analysisTime: 70 },
+ *   blocked: false,
+ *   bySeverity: { critical: [], error: [], warning: [], info: [] },
+ *   byFile: {},
+ * };
+ * ```
+ */
+interface RunResult {
+    findings: Finding[];
+    stats: RunStats;
+    blocked: boolean;
+    bySeverity: Record<Severity, Finding[]>;
+    byFile: Record<string, Finding[]>;
+}
+/** Result of incremental scan. */
+interface IncrementalResult {
+    changedFiles: string[];
+    affectedFiles: string[];
+    graph: CodebaseGraph;
+}
+
+export type { ASTVisitors as A, CodebaseGraph as C, DetectedPattern as D, FileNode as F, GuardianConfig as G, IncrementalResult as I, NamingPluginConfig as N, ProjectConfig as P, QualityPluginConfig as Q, RunOptions as R, SymbolNode as S, TestGuardPluginConfig as T, RunResult as a, GuardianPlugin as b, Rule as c, Finding as d, FunctionNode as e, GuardianKernel as f, ImportEdge as g, ImportInfo as h, RuleCategory as i, RuleContext as j, RunStats as k, Severity as l, SeverityConfig as m, ArchitecturePluginConfig as n, SecurityPluginConfig as o, PerformancePluginConfig as p, ApiPluginConfig as q, DepAuditPluginConfig as r };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@oxog/codeguardian",
+  "version": "1.0.0",
+  "description": "Zero-dependency TypeScript codebase guardian - pre-commit hook enforcing architecture, security, performance, and quality rules",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "codeguardian": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./plugins": {
+      "import": {
+        "types": "./dist/plugins/index.d.ts",
+        "default": "./dist/plugins/index.js"
+      },
+      "require": {
+        "types": "./dist/plugins/index.d.cts",
+        "default": "./dist/plugins/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test:coverage"
+  },
+  "keywords": [
+    "typescript",
+    "code-quality",
+    "architecture",
+    "security",
+    "pre-commit",
+    "guardian",
+    "static-analysis",
+    "linter",
+    "code-review",
+    "ast",
+    "codebase",
+    "oxog"
+  ],
+  "author": "Ersin Koç",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ersinkoc/codeguardian.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ersinkoc/codeguardian/issues"
+  },
+  "homepage": "https://codeguardian.oxog.dev",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^2.0.0"
+  }
+}