clean-slop 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,225 @@
+/**
+ * Core types for the clean-slop production readiness engine.
+ */
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type Confidence = 'certain' | 'high' | 'medium' | 'low';
+type RuleCategory = 'ai-slop' | 'security' | 'reliability' | 'maintainability' | 'production-readiness';
+interface Location {
+    file: string;
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+interface IssueFix {
+    description: string;
+    code?: string;
+}
+interface Issue {
+    /** Rule identifier that produced this issue, e.g. "security/sql-injection" */
+    ruleId: string;
+    /** Human-readable rule name */
+    ruleName: string;
+    /** Category the rule belongs to */
+    category: RuleCategory;
+    /** Severity of the issue */
+    severity: Severity;
+    /** Confidence that this is a real issue */
+    confidence: Confidence;
+    /** Short summary of what was found */
+    message: string;
+    /** Detailed explanation of the issue */
+    explanation: string;
+    /** Why this matters in production */
+    impact: string;
+    /** Location in source */
+    location: Location;
+    /** Extracted source snippet */
+    snippet?: string;
+    /** Suggested fix */
+    fix?: IssueFix;
+    /** URL to extended documentation */
+    docsUrl?: string;
+    /** Additional metadata from the rule */
+    metadata?: Record<string, unknown>;
+}
+interface CategoryScore {
+    category: RuleCategory;
+    score: number;
+    issueCount: number;
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+}
+interface ScanScore {
+    overall: number;
+    categories: CategoryScore[];
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    productionReady: boolean;
+}
+interface FileResult {
+    file: string;
+    issues: Issue[];
+    parseError?: string;
+    skipped?: boolean;
+    skipReason?: string;
+}
+interface ScanResult {
+    /** Absolute path of the scanned project root */
+    root: string;
+    /** ISO timestamp of the scan */
+    timestamp: string;
+    /** clean-slop version */
+    version: string;
+    /** Files that were scanned */
+    files: FileResult[];
+    /** All issues aggregated */
+    issues: Issue[];
+    /** Scores per category and overall */
+    score: ScanScore;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Configuration used for this scan */
+    config: ResolvedConfig;
+}
+interface RuleMeta {
+    id: string;
+    name: string;
+    category: RuleCategory;
+    severity: Severity;
+    confidence: Confidence;
+    description: string;
+    rationale: string;
+    docsUrl: string;
+    fixable: boolean;
+    frameworks?: string[];
+}
+interface RuleContext {
+    filePath: string;
+    source: string;
+    ast: unknown;
+    config: ResolvedConfig;
+    report(issue: Omit<Issue, 'ruleId' | 'ruleName' | 'category' | 'severity' | 'confidence' | 'docsUrl'>): void;
+}
+interface Rule {
+    meta: RuleMeta;
+    create(context: RuleContext): void;
+}
+type RuleSeverityOverride = Severity | 'off';
+interface RuleConfig {
+    severity?: RuleSeverityOverride;
+    options?: Record<string, unknown>;
+}
+interface UserConfig {
+    /** Glob patterns of files to include (default: all JS/TS files) */
+    include?: string[];
+    /** Glob patterns of files to exclude */
+    exclude?: string[];
+    /** Rule category toggles */
+    categories?: Record<RuleCategory, boolean>;
+    /** Per-rule overrides */
+    rules?: Record<string, RuleSeverityOverride | RuleConfig>;
+    /** Threshold below which the process exits non-zero */
+    failThreshold?: number;
+    /** Maximum issues of each severity before failing */
+    maxIssues?: Partial<Record<Severity, number>>;
+    /** Plugins to load */
+    plugins?: string[];
+    /** Output reporter */
+    reporter?: 'text' | 'json' | 'html' | 'markdown' | 'sarif';
+    /** Output file for reports */
+    output?: string;
+    /** Whether to enable verbose output */
+    verbose?: boolean;
+    /** Ignore patterns (in addition to .gitignore) */
+    ignorePatterns?: string[];
+    /** TypeScript project file */
+    tsConfigPath?: string;
+}
+type ResolvedConfig = Required<Omit<UserConfig, 'output' | 'tsConfigPath'>> & {
+    output: string | null;
+    tsConfigPath: string | null;
+    root: string;
+    version: string;
+};
+interface Plugin {
+    name: string;
+    version: string;
+    rules: Rule[];
+}
+interface Reporter {
+    name: string;
+    generate(result: ScanResult): string;
+}
+type Language = 'javascript' | 'typescript' | 'jsx' | 'tsx';
+interface ParsedFile {
+    filePath: string;
+    source: string;
+    ast: unknown;
+    language: Language;
+}
+
+declare function loadConfig(cwd: string, configPath?: string): Promise<ResolvedConfig>;
+declare function resolveConfig(userConfig: UserConfig, cwd: string): ResolvedConfig;
+declare function generateDefaultConfig(): string;
+
+interface ScanOptions {
+    config: ResolvedConfig;
+    onFile?: (filePath: string, index: number, total: number) => void;
+    onIssue?: (issue: Issue) => void;
+}
+declare function discoverFiles(config: ResolvedConfig): Promise<string[]>;
+declare function scan(options: ScanOptions): Promise<ScanResult>;
+
+declare class RuleEngine {
+    private rules;
+    register(rule: Rule): void;
+    registerAll(rules: Rule[]): void;
+    getRule(id: string): Rule | undefined;
+    getRules(): Rule[];
+    getRulesByCategory(category: RuleCategory): Rule[];
+    runOnFile(parsedFile: ParsedFile, config: ResolvedConfig): Issue[];
+    private resolveSeverityOverride;
+}
+
+declare const BUILT_IN_RULES: Rule[];
+
+type ReporterName = 'text' | 'json' | 'html' | 'markdown' | 'sarif';
+declare function generate(result: ScanResult, reporter?: ReporterName): string;
+declare function writeReport(content: string, outputPath: string): Promise<void>;
+
+declare class ParseError extends Error {
+    readonly filePath: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, filePath: string, cause?: unknown | undefined);
+}
+declare function parseFile(filePath: string): Promise<ParsedFile>;
+declare function parseSource(filePath: string, source: string): ParsedFile;
+declare function extractSnippet(source: string, line: number, contextLines?: number): string;
+
+declare const PACKAGE_VERSION = "1.0.0";
+
+/**
+ * clean-slop - Production Readiness Engine
+ *
+ * Public JavaScript/TypeScript API.
+ *
+ * @example
+ * ```typescript
+ * import { scanDirectory, loadConfig } from 'clean-slop';
+ *
+ * const config = await loadConfig(process.cwd());
+ * const result = await scanDirectory(process.cwd(), config);
+ *
+ * console.log(`Score: ${result.score.overall}/100`);
+ * console.log(`Issues: ${result.issues.length}`);
+ * ```
+ */
+
+/**
+ * Convenience: scan a directory and return the full result.
+ */
+declare function scanDirectory(directory: string, userConfig?: UserConfig): Promise<ScanResult>;
+
+export { BUILT_IN_RULES, type CategoryScore, type Confidence, type FileResult, type Issue, type IssueFix, type Language, type Location, ParseError, type ParsedFile, type Plugin, type Reporter, type ResolvedConfig, type Rule, type RuleCategory, type RuleContext, RuleEngine, type RuleMeta, type ScanResult, type ScanScore, type Severity, type UserConfig, discoverFiles, extractSnippet, generateDefaultConfig, generate as generateReport, loadConfig, parseFile, parseSource, resolveConfig, scan, scanDirectory, PACKAGE_VERSION as version, writeReport };

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Core types for the clean-slop production readiness engine.
+ */
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type Confidence = 'certain' | 'high' | 'medium' | 'low';
+type RuleCategory = 'ai-slop' | 'security' | 'reliability' | 'maintainability' | 'production-readiness';
+interface Location {
+    file: string;
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+interface IssueFix {
+    description: string;
+    code?: string;
+}
+interface Issue {
+    /** Rule identifier that produced this issue, e.g. "security/sql-injection" */
+    ruleId: string;
+    /** Human-readable rule name */
+    ruleName: string;
+    /** Category the rule belongs to */
+    category: RuleCategory;
+    /** Severity of the issue */
+    severity: Severity;
+    /** Confidence that this is a real issue */
+    confidence: Confidence;
+    /** Short summary of what was found */
+    message: string;
+    /** Detailed explanation of the issue */
+    explanation: string;
+    /** Why this matters in production */
+    impact: string;
+    /** Location in source */
+    location: Location;
+    /** Extracted source snippet */
+    snippet?: string;
+    /** Suggested fix */
+    fix?: IssueFix;
+    /** URL to extended documentation */
+    docsUrl?: string;
+    /** Additional metadata from the rule */
+    metadata?: Record<string, unknown>;
+}
+interface CategoryScore {
+    category: RuleCategory;
+    score: number;
+    issueCount: number;
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+}
+interface ScanScore {
+    overall: number;
+    categories: CategoryScore[];
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    productionReady: boolean;
+}
+interface FileResult {
+    file: string;
+    issues: Issue[];
+    parseError?: string;
+    skipped?: boolean;
+    skipReason?: string;
+}
+interface ScanResult {
+    /** Absolute path of the scanned project root */
+    root: string;
+    /** ISO timestamp of the scan */
+    timestamp: string;
+    /** clean-slop version */
+    version: string;
+    /** Files that were scanned */
+    files: FileResult[];
+    /** All issues aggregated */
+    issues: Issue[];
+    /** Scores per category and overall */
+    score: ScanScore;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Configuration used for this scan */
+    config: ResolvedConfig;
+}
+interface RuleMeta {
+    id: string;
+    name: string;
+    category: RuleCategory;
+    severity: Severity;
+    confidence: Confidence;
+    description: string;
+    rationale: string;
+    docsUrl: string;
+    fixable: boolean;
+    frameworks?: string[];
+}
+interface RuleContext {
+    filePath: string;
+    source: string;
+    ast: unknown;
+    config: ResolvedConfig;
+    report(issue: Omit<Issue, 'ruleId' | 'ruleName' | 'category' | 'severity' | 'confidence' | 'docsUrl'>): void;
+}
+interface Rule {
+    meta: RuleMeta;
+    create(context: RuleContext): void;
+}
+type RuleSeverityOverride = Severity | 'off';
+interface RuleConfig {
+    severity?: RuleSeverityOverride;
+    options?: Record<string, unknown>;
+}
+interface UserConfig {
+    /** Glob patterns of files to include (default: all JS/TS files) */
+    include?: string[];
+    /** Glob patterns of files to exclude */
+    exclude?: string[];
+    /** Rule category toggles */
+    categories?: Record<RuleCategory, boolean>;
+    /** Per-rule overrides */
+    rules?: Record<string, RuleSeverityOverride | RuleConfig>;
+    /** Threshold below which the process exits non-zero */
+    failThreshold?: number;
+    /** Maximum issues of each severity before failing */
+    maxIssues?: Partial<Record<Severity, number>>;
+    /** Plugins to load */
+    plugins?: string[];
+    /** Output reporter */
+    reporter?: 'text' | 'json' | 'html' | 'markdown' | 'sarif';
+    /** Output file for reports */
+    output?: string;
+    /** Whether to enable verbose output */
+    verbose?: boolean;
+    /** Ignore patterns (in addition to .gitignore) */
+    ignorePatterns?: string[];
+    /** TypeScript project file */
+    tsConfigPath?: string;
+}
+type ResolvedConfig = Required<Omit<UserConfig, 'output' | 'tsConfigPath'>> & {
+    output: string | null;
+    tsConfigPath: string | null;
+    root: string;
+    version: string;
+};
+interface Plugin {
+    name: string;
+    version: string;
+    rules: Rule[];
+}
+interface Reporter {
+    name: string;
+    generate(result: ScanResult): string;
+}
+type Language = 'javascript' | 'typescript' | 'jsx' | 'tsx';
+interface ParsedFile {
+    filePath: string;
+    source: string;
+    ast: unknown;
+    language: Language;
+}
+
+declare function loadConfig(cwd: string, configPath?: string): Promise<ResolvedConfig>;
+declare function resolveConfig(userConfig: UserConfig, cwd: string): ResolvedConfig;
+declare function generateDefaultConfig(): string;
+
+interface ScanOptions {
+    config: ResolvedConfig;
+    onFile?: (filePath: string, index: number, total: number) => void;
+    onIssue?: (issue: Issue) => void;
+}
+declare function discoverFiles(config: ResolvedConfig): Promise<string[]>;
+declare function scan(options: ScanOptions): Promise<ScanResult>;
+
+declare class RuleEngine {
+    private rules;
+    register(rule: Rule): void;
+    registerAll(rules: Rule[]): void;
+    getRule(id: string): Rule | undefined;
+    getRules(): Rule[];
+    getRulesByCategory(category: RuleCategory): Rule[];
+    runOnFile(parsedFile: ParsedFile, config: ResolvedConfig): Issue[];
+    private resolveSeverityOverride;
+}
+
+declare const BUILT_IN_RULES: Rule[];
+
+type ReporterName = 'text' | 'json' | 'html' | 'markdown' | 'sarif';
+declare function generate(result: ScanResult, reporter?: ReporterName): string;
+declare function writeReport(content: string, outputPath: string): Promise<void>;
+
+declare class ParseError extends Error {
+    readonly filePath: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, filePath: string, cause?: unknown | undefined);
+}
+declare function parseFile(filePath: string): Promise<ParsedFile>;
+declare function parseSource(filePath: string, source: string): ParsedFile;
+declare function extractSnippet(source: string, line: number, contextLines?: number): string;
+
+declare const PACKAGE_VERSION = "1.0.0";
+
+/**
+ * clean-slop - Production Readiness Engine
+ *
+ * Public JavaScript/TypeScript API.
+ *
+ * @example
+ * ```typescript
+ * import { scanDirectory, loadConfig } from 'clean-slop';
+ *
+ * const config = await loadConfig(process.cwd());
+ * const result = await scanDirectory(process.cwd(), config);
+ *
+ * console.log(`Score: ${result.score.overall}/100`);
+ * console.log(`Issues: ${result.issues.length}`);
+ * ```
+ */
+
+/**
+ * Convenience: scan a directory and return the full result.
+ */
+declare function scanDirectory(directory: string, userConfig?: UserConfig): Promise<ScanResult>;
+
+export { BUILT_IN_RULES, type CategoryScore, type Confidence, type FileResult, type Issue, type IssueFix, type Language, type Location, ParseError, type ParsedFile, type Plugin, type Reporter, type ResolvedConfig, type Rule, type RuleCategory, type RuleContext, RuleEngine, type RuleMeta, type ScanResult, type ScanScore, type Severity, type UserConfig, discoverFiles, extractSnippet, generateDefaultConfig, generate as generateReport, loadConfig, parseFile, parseSource, resolveConfig, scan, scanDirectory, PACKAGE_VERSION as version, writeReport };