@oxog/codeguardian 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,169 @@
+import { G as GuardianConfig, P as ProjectConfig, C as CodebaseGraph, I as IncrementalResult, R as RunOptions, a as RunResult, b as GuardianPlugin, D as DetectedPattern, F as FileNode, S as SymbolNode, c as Rule } from './types-CQZEdzEa.cjs';
+export { A as ASTVisitors, d as Finding, e as FunctionNode, f as GuardianKernel, g as ImportEdge, h as ImportInfo, i as RuleCategory, j as RuleContext, k as RunStats, l as Severity, m as SeverityConfig } from './types-CQZEdzEa.cjs';
+import 'typescript';
+
+/**
+ * Create a Guardian instance for analyzing a TypeScript project.
+ *
+ * @param config - Guardian configuration
+ * @returns Guardian instance with scan, run, use methods
+ *
+ * @example
+ * ```typescript
+ * const guardian = createGuardian({
+ *   rootDir: process.cwd(),
+ *   tsconfig: './tsconfig.json',
+ * });
+ *
+ * const graph = await guardian.scan();
+ * console.log(`Scanned ${graph.files.size} files`);
+ * ```
+ */
+declare function createGuardian(config: GuardianConfig): {
+    /** The project configuration. */
+    config: ProjectConfig;
+    /** The codebase knowledge graph (available after scan). */
+    readonly graph: CodebaseGraph;
+    /**
+     * Perform a full codebase scan and build the knowledge graph.
+     *
+     * @returns The complete codebase graph
+     *
+     * @example
+     * ```typescript
+     * const graph = await guardian.scan();
+     * console.log(`${graph.files.size} files, ${graph.symbols.size} symbols`);
+     * ```
+     */
+    scan(): Promise<CodebaseGraph>;
+    /**
+     * Perform an incremental scan based on git staged files.
+     *
+     * @returns Incremental result with changed and affected files
+     *
+     * @example
+     * ```typescript
+     * const result = await guardian.scanIncremental();
+     * console.log(`Updated ${result.changedFiles.length} files`);
+     * ```
+     */
+    scanIncremental(): Promise<IncrementalResult>;
+    /**
+     * Run analysis rules on the codebase.
+     *
+     * @param options - Run options (staged, verbose, plugins, format)
+     * @returns Run result with findings, stats, and blocked status
+     *
+     * @example
+     * ```typescript
+     * const result = await guardian.run({ staged: true });
+     * if (result.blocked) {
+     *   console.error('Commit blocked!');
+     *   process.exit(1);
+     * }
+     * ```
+     */
+    run(options?: RunOptions): Promise<RunResult>;
+    /**
+     * Register a plugin with the guardian.
+     *
+     * @param plugin - Plugin to register
+     *
+     * @example
+     * ```typescript
+     * import { definePlugin } from '@oxog/codeguardian';
+     * guardian.use(myPlugin);
+     * ```
+     */
+    use<TConfig>(plugin: GuardianPlugin<TConfig>): void;
+    /**
+     * Auto-discover project conventions.
+     *
+     * @returns Detected patterns
+     *
+     * @example
+     * ```typescript
+     * const conventions = await guardian.discover();
+     * ```
+     */
+    discover(): Promise<DetectedPattern[]>;
+    /**
+     * Format run results for output.
+     *
+     * @param result - Run result
+     * @param format - Output format
+     * @param verbose - Include info-level findings
+     * @returns Formatted string
+     */
+    format(result: RunResult, format?: "terminal" | "json" | "sarif", verbose?: boolean): string;
+    /**
+     * Get graph query helpers.
+     */
+    query: {
+        getFile: (path: string) => FileNode | undefined;
+        getSymbol: (name: string) => SymbolNode | undefined;
+        getDependencies: (path: string) => string[];
+        getDependents: (path: string) => string[];
+        findCircularDeps: () => string[][];
+        getStats: () => {
+            totalFiles: number;
+            totalSymbols: number;
+            totalEdges: number;
+            totalFunctions: number;
+            totalLOC: number;
+            avgComplexity: number;
+            filesByRole: Record<string, number>;
+            filesByLayer: Record<string, number>;
+        } | null;
+    };
+    /**
+     * Get all registered rules.
+     */
+    getRules(): Rule[];
+    /**
+     * Get all installed plugin names.
+     */
+    getPlugins(): string[];
+};
+/**
+ * Define a custom analysis rule.
+ *
+ * @param rule - Rule definition
+ * @returns The same rule (for type-safe chaining)
+ *
+ * @example
+ * ```typescript
+ * const noConsole = defineRule({
+ *   name: 'custom/no-console',
+ *   severity: 'warning',
+ *   description: 'Disallow console.log',
+ *   category: 'quality',
+ *   check: (ctx) => {
+ *     const findings: Finding[] = [];
+ *     // ... analysis
+ *     return findings;
+ *   },
+ * });
+ * ```
+ */
+declare function defineRule(rule: Rule): Rule;
+/**
+ * Define a custom plugin.
+ *
+ * @param plugin - Plugin definition
+ * @returns The same plugin (for type-safe chaining)
+ *
+ * @example
+ * ```typescript
+ * const myPlugin = definePlugin({
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   install: (kernel) => {
+ *     kernel.registerRule(myRule);
+ *   },
+ * });
+ * ```
+ */
+declare function definePlugin<TConfig = unknown>(plugin: GuardianPlugin<TConfig>): GuardianPlugin<TConfig>;
+
+export { CodebaseGraph, FileNode, GuardianConfig, GuardianPlugin, IncrementalResult, ProjectConfig, Rule, RunOptions, RunResult, SymbolNode, createGuardian, definePlugin, defineRule };

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import { G as GuardianConfig, P as ProjectConfig, C as CodebaseGraph, I as IncrementalResult, R as RunOptions, a as RunResult, b as GuardianPlugin, D as DetectedPattern, F as FileNode, S as SymbolNode, c as Rule } from './types-CQZEdzEa.js';
+export { A as ASTVisitors, d as Finding, e as FunctionNode, f as GuardianKernel, g as ImportEdge, h as ImportInfo, i as RuleCategory, j as RuleContext, k as RunStats, l as Severity, m as SeverityConfig } from './types-CQZEdzEa.js';
+import 'typescript';
+
+/**
+ * Create a Guardian instance for analyzing a TypeScript project.
+ *
+ * @param config - Guardian configuration
+ * @returns Guardian instance with scan, run, use methods
+ *
+ * @example
+ * ```typescript
+ * const guardian = createGuardian({
+ *   rootDir: process.cwd(),
+ *   tsconfig: './tsconfig.json',
+ * });
+ *
+ * const graph = await guardian.scan();
+ * console.log(`Scanned ${graph.files.size} files`);
+ * ```
+ */
+declare function createGuardian(config: GuardianConfig): {
+    /** The project configuration. */
+    config: ProjectConfig;
+    /** The codebase knowledge graph (available after scan). */
+    readonly graph: CodebaseGraph;
+    /**
+     * Perform a full codebase scan and build the knowledge graph.
+     *
+     * @returns The complete codebase graph
+     *
+     * @example
+     * ```typescript
+     * const graph = await guardian.scan();
+     * console.log(`${graph.files.size} files, ${graph.symbols.size} symbols`);
+     * ```
+     */
+    scan(): Promise<CodebaseGraph>;
+    /**
+     * Perform an incremental scan based on git staged files.
+     *
+     * @returns Incremental result with changed and affected files
+     *
+     * @example
+     * ```typescript
+     * const result = await guardian.scanIncremental();
+     * console.log(`Updated ${result.changedFiles.length} files`);
+     * ```
+     */
+    scanIncremental(): Promise<IncrementalResult>;
+    /**
+     * Run analysis rules on the codebase.
+     *
+     * @param options - Run options (staged, verbose, plugins, format)
+     * @returns Run result with findings, stats, and blocked status
+     *
+     * @example
+     * ```typescript
+     * const result = await guardian.run({ staged: true });
+     * if (result.blocked) {
+     *   console.error('Commit blocked!');
+     *   process.exit(1);
+     * }
+     * ```
+     */
+    run(options?: RunOptions): Promise<RunResult>;
+    /**
+     * Register a plugin with the guardian.
+     *
+     * @param plugin - Plugin to register
+     *
+     * @example
+     * ```typescript
+     * import { definePlugin } from '@oxog/codeguardian';
+     * guardian.use(myPlugin);
+     * ```
+     */
+    use<TConfig>(plugin: GuardianPlugin<TConfig>): void;
+    /**
+     * Auto-discover project conventions.
+     *
+     * @returns Detected patterns
+     *
+     * @example
+     * ```typescript
+     * const conventions = await guardian.discover();
+     * ```
+     */
+    discover(): Promise<DetectedPattern[]>;
+    /**
+     * Format run results for output.
+     *
+     * @param result - Run result
+     * @param format - Output format
+     * @param verbose - Include info-level findings
+     * @returns Formatted string
+     */
+    format(result: RunResult, format?: "terminal" | "json" | "sarif", verbose?: boolean): string;
+    /**
+     * Get graph query helpers.
+     */
+    query: {
+        getFile: (path: string) => FileNode | undefined;
+        getSymbol: (name: string) => SymbolNode | undefined;
+        getDependencies: (path: string) => string[];
+        getDependents: (path: string) => string[];
+        findCircularDeps: () => string[][];
+        getStats: () => {
+            totalFiles: number;
+            totalSymbols: number;
+            totalEdges: number;
+            totalFunctions: number;
+            totalLOC: number;
+            avgComplexity: number;
+            filesByRole: Record<string, number>;
+            filesByLayer: Record<string, number>;
+        } | null;
+    };
+    /**
+     * Get all registered rules.
+     */
+    getRules(): Rule[];
+    /**
+     * Get all installed plugin names.
+     */
+    getPlugins(): string[];
+};
+/**
+ * Define a custom analysis rule.
+ *
+ * @param rule - Rule definition
+ * @returns The same rule (for type-safe chaining)
+ *
+ * @example
+ * ```typescript
+ * const noConsole = defineRule({
+ *   name: 'custom/no-console',
+ *   severity: 'warning',
+ *   description: 'Disallow console.log',
+ *   category: 'quality',
+ *   check: (ctx) => {
+ *     const findings: Finding[] = [];
+ *     // ... analysis
+ *     return findings;
+ *   },
+ * });
+ * ```
+ */
+declare function defineRule(rule: Rule): Rule;
+/**
+ * Define a custom plugin.
+ *
+ * @param plugin - Plugin definition
+ * @returns The same plugin (for type-safe chaining)
+ *
+ * @example
+ * ```typescript
+ * const myPlugin = definePlugin({
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   install: (kernel) => {
+ *     kernel.registerRule(myRule);
+ *   },
+ * });
+ * ```
+ */
+declare function definePlugin<TConfig = unknown>(plugin: GuardianPlugin<TConfig>): GuardianPlugin<TConfig>;
+
+export { CodebaseGraph, FileNode, GuardianConfig, GuardianPlugin, IncrementalResult, ProjectConfig, Rule, RunOptions, RunResult, SymbolNode, createGuardian, definePlugin, defineRule };