@runhalo/engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Halo COPPA Rule Engine
+ * Core scanning logic for child safety compliance detection
+ *
+ * Sprint 2: Added rules 6-20 (coppa-sec-006 through coppa-default-020)
+ * Sprint 2: Added suppression system for // halo-ignore comments
+ * Sprint 1 Fixes: Added tree-sitter for AST analysis, YAML rule loading
+ */
+import Parser from 'tree-sitter';
+export type Severity = 'critical' | 'high' | 'medium' | 'low';
+export interface Violation {
+    ruleId: string;
+    ruleName: string;
+    severity: Severity;
+    filePath: string;
+    line: number;
+    column: number;
+    message: string;
+    codeSnippet: string;
+    fixSuggestion: string;
+    penalty?: string;
+    suppressed?: boolean;
+    suppressionComment?: string;
+}
+export interface Rule {
+    id: string;
+    name: string;
+    severity: Severity;
+    description: string;
+    patterns: RegExp[];
+    fixSuggestion: string;
+    penalty: string;
+    languages: string[];
+}
+export interface SuppressionConfig {
+    enabled: boolean;
+    commentPattern: string;
+}
+export declare function loadRulesFromYAML(yamlPath: string): Rule[];
+export declare class TreeSitterParser {
+    private parser;
+    constructor();
+    /**
+     * Initialize parser with language
+     */
+    initialize(language: 'typescript' | 'javascript'): void;
+    /**
+     * Parse code and return AST
+     */
+    parse(code: string, language?: 'typescript' | 'javascript'): Parser.Tree;
+    /**
+     * Find all function calls matching a name pattern
+     */
+    findFunctionCalls(code: string, functionName: string): Array<{
+        line: number;
+        column: number;
+    }>;
+    /**
+     * Extract all identifiers from code (for pattern matching)
+     */
+    extractIdentifiers(code: string): string[];
+}
+export declare const treeSitterParser: TreeSitterParser;
+export declare const COPPA_RULES: Rule[];
+export declare const ETHICAL_RULES: Rule[];
+export interface IgnoreConfig {
+    /** File glob patterns to ignore entirely */
+    ignoredFiles: string[];
+    /** Global rule suppressions (rule ID → true) */
+    globalRuleSuppressions: Set<string>;
+    /** Per-file rule suppressions (filePath → Set of rule IDs) */
+    fileRuleSuppressions: Map<string, Set<string>>;
+}
+/**
+ * Parse a .haloignore file content
+ *
+ * Format:
+ *   # comment
+ *   path/to/file.ts          — ignore entire file
+ *   **\/*.test.ts              — glob pattern to ignore files
+ *   rule:coppa-auth-001       — globally suppress a rule
+ *   src/auth.ts:coppa-auth-001 — suppress rule in specific file
+ */
+export declare function parseHaloignore(content: string): IgnoreConfig;
+/**
+ * Check if a file should be ignored based on .haloignore config
+ */
+export declare function shouldIgnoreFile(filePath: string, config: IgnoreConfig): boolean;
+/**
+ * Check if a violation should be ignored based on .haloignore config
+ */
+export declare function shouldIgnoreViolation(violation: Violation, config: IgnoreConfig): boolean;
+export interface EngineConfig {
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    rules?: string[];
+    severityFilter?: Severity[];
+    suppressions?: {
+        enabled: boolean;
+        commentPattern?: string;
+    };
+    includeSuppressed?: boolean;
+    rulesPath?: string;
+    ignoreConfig?: IgnoreConfig;
+    projectDomains?: string[];
+    ethical?: boolean;
+}
+export interface ScanResult {
+    filePath: string;
+    violations: Violation[];
+    suppressedViolations?: Violation[];
+    scannedAt: string;
+    totalViolations: number;
+    suppressedCount: number;
+}
+export declare class HaloEngine {
+    private config;
+    private rules;
+    private treeSitter;
+    constructor(config?: EngineConfig);
+    /**
+     * Get the tree-sitter parser for advanced AST analysis
+     */
+    getParser(): TreeSitterParser;
+    /**
+     * Scan using tree-sitter AST analysis (advanced mode)
+     */
+    scanFileWithAST(filePath: string, content: string, language?: 'typescript' | 'javascript'): Violation[];
+    /**
+     * Get the ignore config (if any)
+     */
+    getIgnoreConfig(): IgnoreConfig | undefined;
+    /**
+     * Scan a single file for violations
+     */
+    scanFile(filePath: string, content: string): Violation[];
+    /**
+     * Get all rules
+     */
+    getRules(): Rule[];
+    /**
+     * Get rule by ID
+     */
+    getRule(ruleId: string): Rule | undefined;
+    /**
+     * Explain a rule (for MCP)
+     */
+    explainRule(ruleId: string): string;
+    /**
+     * Get fix suggestion for a rule (for MCP)
+     */
+    getFixSuggestion(ruleId: string): string;
+}
+export default HaloEngine;