@ash-technologia/fathom 0.1.0

package/dist/plugins/types.d.ts

@@ -0,0 +1,148 @@
+import type { Category } from '../rules/categories.js';
+import type { Severity } from '../rules/severity.js';
+import type { Finding } from '../core/findings.js';
+import type { FileEntry, GitContext } from '../core/context.js';
+import type { EcosystemDetection } from '../detectors/language.js';
+import type { FrameworkDetection } from '../detectors/framework.js';
+import type { PackageManagerDetection } from '../detectors/package-manager.js';
+import type { ProjectTypeDetection } from '../detectors/project-type.js';
+import type { AnalyzerResult, Metrics } from '../core/result.js';
+import type { RuleDefinition } from '../rules/definitions.js';
+/**
+ * Definition of a rule exposed by a plugin.
+ * Extends the standard Fathom RuleDefinition.
+ */
+export interface PluginRule extends RuleDefinition {
+    /** Optional documentation or explanation specific to the plugin */
+    readonly plugin?: string | undefined;
+    /** Title / display name alias for name */
+    readonly title?: string | undefined;
+    /** Recommended action */
+    readonly recommendation?: string | undefined;
+    /** Confidence score 0-1 */
+    readonly confidence?: number | undefined;
+    /** Whether finding is auto-fixable */
+    readonly autoFixable?: boolean | undefined;
+    /** References / external URLs */
+    readonly references?: readonly string[] | undefined;
+}
+/**
+ * Metadata manifest describing a Fathom plugin.
+ */
+export interface PluginManifest {
+    /** Unique plugin identifier / package name, e.g. "@fathom/plugin-react" */
+    readonly name: string;
+    /** Semantic version string, e.g. "0.1.0" */
+    readonly version: string;
+    /** Human-readable description of what this plugin analyzes */
+    readonly description: string;
+    /** Plugin author or organization */
+    readonly author?: string | undefined;
+    /** Homepage or repository URL */
+    readonly homepage?: string | undefined;
+    /** Minimum compatible Fathom version */
+    readonly minFathomVersion?: string | undefined;
+    /** Rules provided by this plugin */
+    readonly rules: readonly PluginRule[];
+}
+/**
+ * Result returned by a plugin analyzer.
+ */
+export interface PluginAnalyzerResult {
+    /** Findings emitted by this analyzer */
+    findings: Finding[];
+    /** Optional metrics collected during analysis */
+    metrics?: Metrics | undefined;
+    /** Optional non-fatal warnings */
+    warnings?: string[] | undefined;
+}
+/**
+ * Safe, read-only context provided to plugin analyzers.
+ *
+ * Plugins are strictly sandboxed:
+ * - Read-only view of repository metadata
+ * - Traversal-safe file reading (no escaping repositoryRoot)
+ * - Helper methods for structured finding creation
+ * - No network transmission or arbitrary code execution
+ */
+export interface PluginContext {
+    /** Absolute path to repository root */
+    readonly repositoryRoot: string;
+    /** Read-only list of discovered files */
+    readonly files: readonly FileEntry[];
+    /** Detected programming languages */
+    readonly languages: readonly EcosystemDetection[];
+    /** Detected frameworks (e.g. React, Next.js, Express) */
+    readonly frameworks: readonly FrameworkDetection[];
+    /** Detected package managers (e.g. npm, pnpm, yarn) */
+    readonly packageManagers: readonly PackageManagerDetection[];
+    /** High-level project classification */
+    readonly projectType: ProjectTypeDetection;
+    /** Git repository status */
+    readonly git: Readonly<GitContext>;
+    /** Whether online network mode is explicitly enabled */
+    readonly online: boolean;
+    /**
+     * Check if a relative file path exists in the repository.
+     */
+    hasFile(relativePath: string): boolean;
+    /**
+     * Read the text content of a repository file safely.
+     * Disallows path traversal outside repository root.
+     * Bounded by maxBytes (default 1MB) to prevent memory exhaustion.
+     */
+    getFileContent(relativePath: string, maxBytes?: number): Promise<string | null>;
+    /**
+     * Helper to construct a validated finding linked to a plugin rule.
+     */
+    createFinding(ruleId: string, details: {
+        filePath?: string | undefined;
+        lineNumber?: number | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        recommendation?: string | undefined;
+        severity?: Severity | undefined;
+        confidence?: number | undefined;
+        autoFixable?: boolean | undefined;
+    }): Finding;
+}
+/**
+ * Plugin analyzer contract.
+ */
+export interface PluginAnalyzer {
+    /** Unique analyzer identifier within the plugin (e.g. "react") */
+    readonly id: string;
+    /** Display name of the analyzer */
+    readonly name: string;
+    /** Category to which findings and deductions contribute */
+    readonly category: Category;
+    /** Short description of what this analyzer checks */
+    readonly description: string;
+    /**
+     * Analyze the repository and return findings.
+     */
+    analyze(context: PluginContext): Promise<PluginAnalyzerResult | AnalyzerResult>;
+}
+/**
+ * Optional setup context passed to a plugin during initialization.
+ */
+export interface PluginSetupContext {
+    /** Register an analyzer programmatically */
+    registerAnalyzer(analyzer: PluginAnalyzer): void;
+    /** Register a rule programmatically */
+    registerRule(rule: PluginRule): void;
+}
+/**
+ * A Fathom Plugin definition.
+ */
+export interface FathomPlugin {
+    /** Plugin metadata manifest */
+    readonly manifest: PluginManifest;
+    /** Rules provided by this plugin */
+    readonly rules?: readonly PluginRule[] | undefined;
+    /** Analyzers provided by this plugin */
+    readonly analyzers?: readonly PluginAnalyzer[] | undefined;
+    /** Optional lifecycle setup hook */
+    setup?(context: PluginSetupContext): void | Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"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"}

package/dist/plugins/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/plugins/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":""}

package/dist/reporters/html.d.ts

@@ -0,0 +1,11 @@
+import type { AnalysisResult } from '../core/result.js';
+/**
+ * HTML reporter — generates a 100% self-contained developer dashboard.
+ * Zero external CDNs, zero fonts, zero tracking, zero network requests.
+ */
+export declare class HtmlReporter {
+    report(result: AnalysisResult, outputPath: string): Promise<void>;
+}
+export declare function escapeHtml(str: string | number | boolean | null | undefined): string;
+export declare function generateDashboardHtml(result: AnalysisResult): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/reporters/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/reporters/html.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD;;;GAGG;AACH,qBAAa,YAAY;IACjB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIxE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAQpF;AA2BD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA2yCpE"}