@runhalo/engine 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,58 @@
+# @runhalo/engine
+
+**Halo rule engine** — COPPA 2.0 risk detection via tree-sitter AST analysis.
+
+[![npm](https://img.shields.io/npm/v/@runhalo/engine.svg)](https://www.npmjs.com/package/@runhalo/engine)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+## What it does
+
+The engine scans source files for code patterns that may indicate COPPA 2.0 privacy risks in children's apps. It ships with **20 COPPA rules** and **5 ethical design rules**, powered by tree-sitter AST analysis and regex pattern matching.
+
+## Install
+
+```bash
+npm install @runhalo/engine
+```
+
+## Usage
+
+```typescript
+import { HaloEngine } from '@runhalo/engine';
+
+const engine = new HaloEngine();
+
+// Scan a single file
+const results = engine.scanFile('src/auth/login.ts', sourceCode);
+
+// Each result includes:
+// - ruleId: 'coppa-auth-001'
+// - severity: 'critical' | 'high' | 'medium' | 'low'
+// - message: human-readable description
+// - line / column / codeSnippet
+// - fixSuggestion: recommended remediation
+```
+
+## Rules
+
+20 COPPA rules covering authentication, data collection, tracking, encryption, and consent — plus 5 ethical design rules for dark patterns like infinite scroll, streak pressure, and loot boxes.
+
+Full rule reference: [github.com/runhalo/halo#rules](https://github.com/runhalo/halo#rules)
+
+## Supported Languages
+
+TypeScript, JavaScript, TSX, JSX, Python, Swift, Java, Kotlin, HTML, Vue, Svelte, PHP, C++, C#, SQL
+
+## CLI
+
+Most users should install the CLI instead:
+
+```bash
+npx @runhalo/cli scan .
+```
+
+See [@runhalo/cli](https://www.npmjs.com/package/@runhalo/cli) for the command-line scanner.
+
+## License
+
+Apache 2.0 — [Mindful Media](https://mindfulmedia.org)

package/dist/fixer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Halo Fix Engine
+ * Tier 1 auto-fix transforms for COPPA violations
+ *
+ * Sprint 5: 4 auto-fixable rules (line-targeted string transforms, no ts-morph)
+ * coppa-sec-006:    HTTP → HTTPS (url-upgrade)
+ * coppa-sec-010:    Remove weak passwords (remove-default)
+ * coppa-sec-015:    innerHTML → textContent (sanitize-input) ⚠️ behavior change
+ * coppa-default-020: Public → private (set-default)
+ */
+import type { Violation } from './index';
+/** Result of attempting to fix a single violation */
+export interface FixResult {
+    ruleId: string;
+    filePath: string;
+    line: number;
+    status: 'applied' | 'skipped' | 'failed' | 'reverted';
+    original: string;
+    fixed: string;
+    reason?: string;
+    /** True if this fix changes rendering behavior (e.g. innerHTML → textContent) */
+    warning?: string;
+}
+/** Result of fixing an entire file */
+export interface FileFixResult {
+    filePath: string;
+    originalContent: string;
+    fixedContent: string;
+    fixes: FixResult[];
+    /** False until caller re-scans to verify violations are gone */
+    verified: boolean;
+}
+/** Options for the fix operation */
+export interface FixOptions {
+    dryRun?: boolean;
+    rules?: string[];
+    verbose?: boolean;
+}
+/**
+ * Transform: url-upgrade (coppa-sec-006)
+ * Replaces http:// with https:// on the violation line.
+ */
+export declare function transformUrlUpgrade(line: string, _violation: Violation): string;
+/**
+ * Transform: remove-default (coppa-sec-010)
+ * Replaces weak hardcoded password string literals with a secure alternative.
+ *
+ * Guards against false positives:
+ * - Enum definitions: PASSWORD = 'password' (discriminant, not a real password)
+ * - Input type declarations: type: 'password' (HTML type attribute)
+ * - Switch case labels: case 'password': (discriminant)
+ */
+export declare function transformRemoveDefault(line: string, _violation: Violation): string;
+/**
+ * Transform: sanitize-input (coppa-sec-015)
+ * Replaces .innerHTML assignments with .textContent.
+ * ⚠️ WARNING: This changes rendering behavior. If the developer needs HTML rendering,
+ * this fix will break their UI. Flagged with a warning in dry-run output.
+ *
+ * Guards against false positives:
+ * - Already-sanitized dangerouslySetInnerHTML (content already wrapped in DOMPurify.sanitize)
+ */
+export declare function transformSanitizeInput(line: string, _violation: Violation): string;
+/**
+ * Transform: set-default (coppa-default-020)
+ * Changes public profile defaults to private.
+ *
+ * Guards against false positives:
+ * - TypeScript type unions: visibility: 'public' | 'private' (type definition, not runtime value)
+ */
+export declare function transformSetDefault(line: string, _violation: Violation): string;
+export declare class FixEngine {
+    /**
+     * Check if a violation is auto-fixable (Tier 1).
+     * Uses the fixability field already populated on the violation.
+     */
+    isAutoFixable(violation: Violation): boolean;
+    /**
+     * Check if a rule ID is auto-fixable by looking at a violation's remediation metadata.
+     * For use when you have a ruleId but no violation object — checks against known auto-fix transforms.
+     */
+    isRuleAutoFixable(ruleId: string): boolean;
+    /**
+     * Get all auto-fixable rule IDs.
+     */
+    getAutoFixableRules(): string[];
+    /**
+     * Apply fixes to file content for a set of violations.
+     * Violations must all belong to the same file.
+     * Processes bottom-to-top to preserve line numbers.
+     * Returns the fixed content (does NOT write to disk).
+     */
+    applyFixes(content: string, violations: Violation[], options?: FixOptions): FileFixResult;
+    /**
+     * Generate a simple unified diff between original and fixed content.
+     * Used for --dry-run output.
+     */
+    generateDiff(filePath: string, original: string, fixed: string): string;
+}

package/dist/fixer.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * Halo Fix Engine
+ * Tier 1 auto-fix transforms for COPPA violations
+ *
+ * Sprint 5: 4 auto-fixable rules (line-targeted string transforms, no ts-morph)
+ * coppa-sec-006:    HTTP → HTTPS (url-upgrade)
+ * coppa-sec-010:    Remove weak passwords (remove-default)
+ * coppa-sec-015:    innerHTML → textContent (sanitize-input) ⚠️ behavior change
+ * coppa-default-020: Public → private (set-default)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixEngine = void 0;
+exports.transformUrlUpgrade = transformUrlUpgrade;
+exports.transformRemoveDefault = transformRemoveDefault;
+exports.transformSanitizeInput = transformSanitizeInput;
+exports.transformSetDefault = transformSetDefault;
+// ==================== Transform Functions ====================
+/**
+ * Transform: url-upgrade (coppa-sec-006)
+ * Replaces http:// with https:// on the violation line.
+ */
+function transformUrlUpgrade(line, _violation) {
+    return line.replace(/http:\/\//g, 'https://');
+}
+/**
+ * Transform: remove-default (coppa-sec-010)
+ * Replaces weak hardcoded password string literals with a secure alternative.
+ *
+ * Guards against false positives:
+ * - Enum definitions: PASSWORD = 'password' (discriminant, not a real password)
+ * - Input type declarations: type: 'password' (HTML type attribute)
+ * - Switch case labels: case 'password': (discriminant)
+ */
+function transformRemoveDefault(line, _violation) {
+    // Skip enum/const member definitions (SCREAMING_CASE = 'value') — case-sensitive for identifier
+    if (/^\s*[A-Z][A-Z0-9_]+\s*=\s*(['"])(123456|password|changeme|student|welcome|student123|child123|default|admin)\1/.test(line)) {
+        return line;
+    }
+    // Skip HTML input type declarations (type: 'password', type="password", type = "password")
+    if (/\btype\s*[:=]\s*(['"])password\1/i.test(line)) {
+        return line;
+    }
+    // Skip switch/case discriminants (case 'password':)
+    if (/\bcase\s+(['"])(password|admin|default)\1\s*:/i.test(line)) {
+        return line;
+    }
+    return line.replace(/(['"])(123456|password|changeme|student|welcome|student123|child123|default|admin)\1/gi, 'require("crypto").randomBytes(16).toString("hex")');
+}
+/**
+ * Transform: sanitize-input (coppa-sec-015)
+ * Replaces .innerHTML assignments with .textContent.
+ * ⚠️ WARNING: This changes rendering behavior. If the developer needs HTML rendering,
+ * this fix will break their UI. Flagged with a warning in dry-run output.
+ *
+ * Guards against false positives:
+ * - Already-sanitized dangerouslySetInnerHTML (content already wrapped in DOMPurify.sanitize)
+ */
+function transformSanitizeInput(line, _violation) {
+    // Handle .innerHTML = ... → .textContent = ...
+    if (/\.innerHTML\s*=/.test(line)) {
+        return line.replace(/\.innerHTML\s*=/, '.textContent =');
+    }
+    // Handle dangerouslySetInnerHTML → wrap in DOMPurify.sanitize()
+    if (/dangerouslySetInnerHTML\s*=\s*\{\s*\{\s*__html\s*:\s*([^}]+)\}\s*\}/.test(line)) {
+        // Skip if the __html value is already wrapped in DOMPurify.sanitize()
+        const match = line.match(/dangerouslySetInnerHTML\s*=\s*\{\s*\{\s*__html\s*:\s*([^}]+)\}\s*\}/);
+        if (match && /DOMPurify\.sanitize\s*\(/.test(match[1])) {
+            return line; // Already sanitized — don't double-wrap
+        }
+        return line.replace(/dangerouslySetInnerHTML\s*=\s*\{\s*\{\s*__html\s*:\s*([^}]+)\}\s*\}/, 'dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize($1) }}');
+    }
+    return line;
+}
+/**
+ * Transform: set-default (coppa-default-020)
+ * Changes public profile defaults to private.
+ *
+ * Guards against false positives:
+ * - TypeScript type unions: visibility: 'public' | 'private' (type definition, not runtime value)
+ */
+function transformSetDefault(line, _violation) {
+    let result = line;
+    // Detect TypeScript type union patterns involving 'public' (e.g., 'public' | 'private')
+    const isTypeUnion = /['"]public['"]\s*\|/.test(line) || /\|\s*['"]public['"]/.test(line);
+    result = result.replace(/isProfileVisible:\s*true/gi, 'isProfileVisible: false');
+    // Only replace string literal 'public' values if NOT in a type union context
+    if (!isTypeUnion) {
+        result = result.replace(/visibility:\s*['"]public['"]/gi, "visibility: 'private'");
+        result = result.replace(/defaultPrivacy:\s*['"]public['"]/gi, "defaultPrivacy: 'private'");
+    }
+    result = result.replace(/isPublic:\s*true/gi, 'isPublic: false');
+    result = result.replace(/profileVisibility\s*=\s*['"]?public['"]?/gi, "profileVisibility = 'private'");
+    return result;
+}
+/** Maps transformType → transform function */
+const TRANSFORM_REGISTRY = {
+    'url-upgrade': transformUrlUpgrade,
+    'remove-default': transformRemoveDefault,
+    'sanitize-input': transformSanitizeInput,
+    'set-default': transformSetDefault,
+};
+/** Rules where the fix changes rendering behavior and needs explicit warning */
+const BEHAVIOR_CHANGING_RULES = new Set(['coppa-sec-015']);
+// ==================== FixEngine Class ====================
+class FixEngine {
+    /**
+     * Check if a violation is auto-fixable (Tier 1).
+     * Uses the fixability field already populated on the violation.
+     */
+    isAutoFixable(violation) {
+        return violation.fixability === 'auto' && violation.remediation?.transformType !== undefined;
+    }
+    /**
+     * Check if a rule ID is auto-fixable by looking at a violation's remediation metadata.
+     * For use when you have a ruleId but no violation object — checks against known auto-fix transforms.
+     */
+    isRuleAutoFixable(ruleId) {
+        // The 4 Tier 1 auto-fix rules with known transforms
+        return ['coppa-sec-006', 'coppa-sec-010', 'coppa-sec-015', 'coppa-default-020'].includes(ruleId);
+    }
+    /**
+     * Get all auto-fixable rule IDs.
+     */
+    getAutoFixableRules() {
+        return ['coppa-sec-006', 'coppa-sec-010', 'coppa-sec-015', 'coppa-default-020'];
+    }
+    /**
+     * Apply fixes to file content for a set of violations.
+     * Violations must all belong to the same file.
+     * Processes bottom-to-top to preserve line numbers.
+     * Returns the fixed content (does NOT write to disk).
+     */
+    applyFixes(content, violations, options) {
+        const fixes = [];
+        const lines = content.split('\n');
+        const filePath = violations[0]?.filePath || '';
+        // Filter to auto-fixable violations with known transforms
+        let fixable = violations.filter(v => this.isAutoFixable(v));
+        // Further filter by --rules if specified
+        if (options?.rules?.length) {
+            fixable = fixable.filter(v => options.rules.includes(v.ruleId));
+        }
+        // Sort by line number descending so edits don't shift subsequent lines
+        const sorted = [...fixable].sort((a, b) => b.line - a.line);
+        for (const violation of sorted) {
+            const transformType = violation.remediation?.transformType;
+            if (!transformType) {
+                fixes.push({
+                    ruleId: violation.ruleId,
+                    filePath,
+                    line: violation.line,
+                    status: 'skipped',
+                    original: '',
+                    fixed: '',
+                    reason: 'No transform type defined',
+                });
+                continue;
+            }
+            const transform = TRANSFORM_REGISTRY[transformType];
+            if (!transform) {
+                fixes.push({
+                    ruleId: violation.ruleId,
+                    filePath,
+                    line: violation.line,
+                    status: 'skipped',
+                    original: '',
+                    fixed: '',
+                    reason: `Unknown transform type: ${transformType}`,
+                });
+                continue;
+            }
+            const lineIdx = violation.line - 1;
+            if (lineIdx < 0 || lineIdx >= lines.length) {
+                fixes.push({
+                    ruleId: violation.ruleId,
+                    filePath,
+                    line: violation.line,
+                    status: 'failed',
+                    original: '',
+                    fixed: '',
+                    reason: `Line ${violation.line} out of range`,
+                });
+                continue;
+            }
+            const originalLine = lines[lineIdx];
+            const fixedLine = transform(originalLine, violation);
+            if (fixedLine === originalLine) {
+                fixes.push({
+                    ruleId: violation.ruleId,
+                    filePath,
+                    line: violation.line,
+                    status: 'skipped',
+                    original: originalLine,
+                    fixed: fixedLine,
+                    reason: 'Transform produced no change',
+                });
+                continue;
+            }
+            // Apply the transform
+            const fixedLines = fixedLine.split('\n');
+            lines.splice(lineIdx, 1, ...fixedLines);
+            const fix = {
+                ruleId: violation.ruleId,
+                filePath,
+                line: violation.line,
+                status: 'applied',
+                original: originalLine,
+                fixed: fixedLine,
+            };
+            // Add warning for behavior-changing transforms
+            if (BEHAVIOR_CHANGING_RULES.has(violation.ruleId)) {
+                fix.warning = 'This fix changes rendering behavior. Review before accepting.';
+            }
+            fixes.push(fix);
+        }
+        return {
+            filePath,
+            originalContent: content,
+            fixedContent: lines.join('\n'),
+            fixes,
+            verified: false,
+        };
+    }
+    /**
+     * Generate a simple unified diff between original and fixed content.
+     * Used for --dry-run output.
+     */
+    generateDiff(filePath, original, fixed) {
+        const origLines = original.split('\n');
+        const fixedLines = fixed.split('\n');
+        const output = [];
+        output.push(`--- a/${filePath}`);
+        output.push(`+++ b/${filePath}`);
+        let i = 0;
+        let j = 0;
+        while (i < origLines.length || j < fixedLines.length) {
+            if (i < origLines.length && j < fixedLines.length && origLines[i] === fixedLines[j]) {
+                i++;
+                j++;
+                continue;
+            }
+            // Found a difference — emit a hunk
+            const contextStart = Math.max(0, i - 1);
+            // Collect removed lines
+            const removed = [];
+            const added = [];
+            while (i < origLines.length && (j >= fixedLines.length || origLines[i] !== fixedLines[j])) {
+                removed.push(origLines[i]);
+                i++;
+                // Check if we've found alignment again
+                if (j < fixedLines.length && i < origLines.length && origLines[i] === fixedLines[j + added.length + 1]) {
+                    break;
+                }
+            }
+            while (j < fixedLines.length && (i >= origLines.length || origLines[i] !== fixedLines[j])) {
+                added.push(fixedLines[j]);
+                j++;
+            }
+            if (removed.length > 0 || added.length > 0) {
+                output.push(`@@ -${contextStart + 1} +${contextStart + 1} @@`);
+                for (const line of removed) {
+                    output.push(`-${line}`);
+                }
+                for (const line of added) {
+                    output.push(`+${line}`);
+                }
+            }
+        }
+        return output.join('\n');
+    }
+}
+exports.FixEngine = FixEngine;
+//# sourceMappingURL=fixer.js.map

package/dist/fixer.js.map

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

package/dist/framework-detect.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Framework Detection — detects project framework from package.json
+ * Used by ScaffoldEngine to generate framework-specific code scaffolds
+ */
+export type Framework = 'react' | 'nextjs' | 'vue' | 'svelte' | 'plain-js';
+export interface FrameworkDetectionResult {
+    framework: Framework;
+    typescript: boolean;
+    confidence: number;
+}
+/**
+ * Detect the project framework by reading package.json
+ * Priority: next > react > vue > svelte > plain-js
+ */
+export declare function detectFramework(projectPath: string): FrameworkDetectionResult;

package/dist/framework-detect.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Framework Detection — detects project framework from package.json
+ * Used by ScaffoldEngine to generate framework-specific code scaffolds
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFramework = detectFramework;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Detect the project framework by reading package.json
+ * Priority: next > react > vue > svelte > plain-js
+ */
+function detectFramework(projectPath) {
+    const result = {
+        framework: 'plain-js',
+        typescript: false,
+        confidence: 0.3,
+    };
+    // Try to read package.json
+    const pkgPath = path.join(projectPath, 'package.json');
+    let pkg = null;
+    try {
+        if (fs.existsSync(pkgPath)) {
+            pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        }
+    }
+    catch {
+        // Malformed package.json — fall through to defaults
+    }
+    if (!pkg) {
+        // Check for tsconfig.json even without package.json
+        const tsconfigPath = path.join(projectPath, 'tsconfig.json');
+        if (fs.existsSync(tsconfigPath)) {
+            result.typescript = true;
+        }
+        return result;
+    }
+    const deps = pkg.dependencies || {};
+    const devDeps = pkg.devDependencies || {};
+    const allDeps = { ...deps, ...devDeps };
+    // Detect TypeScript
+    if (allDeps['typescript']) {
+        result.typescript = true;
+    }
+    else {
+        const tsconfigPath = path.join(projectPath, 'tsconfig.json');
+        if (fs.existsSync(tsconfigPath)) {
+            result.typescript = true;
+        }
+    }
+    // Detect framework (priority order — Next.js includes React, so check first)
+    if (deps['next'] || devDeps['next']) {
+        result.framework = 'nextjs';
+        result.confidence = 0.95;
+    }
+    else if (deps['react'] || devDeps['react']) {
+        result.framework = 'react';
+        result.confidence = 0.9;
+    }
+    else if (deps['vue'] || devDeps['vue']) {
+        result.framework = 'vue';
+        result.confidence = 0.9;
+    }
+    else if (deps['svelte'] || devDeps['svelte']) {
+        result.framework = 'svelte';
+        result.confidence = 0.9;
+    }
+    else {
+        result.framework = 'plain-js';
+        result.confidence = 0.5;
+    }
+    return result;
+}
+//# sourceMappingURL=framework-detect.js.map

package/dist/framework-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-detect.js","sourceRoot":"","sources":["../src/framework-detect.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBH,0CA6DC;AA5ED,uCAAyB;AACzB,2CAA6B;AAU7B;;;GAGG;AACH,SAAgB,eAAe,CAAC,WAAmB;IACjD,MAAM,MAAM,GAA6B;QACvC,SAAS,EAAE,UAAU;QACrB,UAAU,EAAE,KAAK;QACjB,UAAU,EAAE,GAAG;KAChB,CAAC;IAEF,2BAA2B;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI,GAAG,GAAQ,IAAI,CAAC;IAEpB,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,oDAAoD;QACpD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;QAC7D,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;IAExC,oBAAoB;IACpB,IAAI,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;QAC7D,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC5B,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;IAC3B,CAAC;SAAM,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC;QAC3B,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC;IAC1B,CAAC;SAAM,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC;QACzB,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC;IAC1B,CAAC;SAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC5B,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,SAAS,GAAG,UAAU,CAAC;QAC9B,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC;IAC1B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -8,6 +8,14 @@
  */
 import Parser from 'tree-sitter';
 export type Severity = 'critical' | 'high' | 'medium' | 'low';
+export type Fixability = 'auto' | 'guided' | 'flag-only';
+export interface RemediationSpec {
+    fixability: Fixability;
+    transformType?: string;
+    scaffoldId?: string;
+    guidanceUrl?: string;
+    estimatedCost?: '$0' | '$0.01' | '$0.05';
+}
 export interface Violation {
     ruleId: string;
     ruleName: string;
@@ -21,6 +29,11 @@ export interface Violation {
     penalty?: string;
     suppressed?: boolean;
     suppressionComment?: string;
+    category?: string;
+    language?: string;
+    matchType?: 'regex' | 'ast' | 'hybrid';
+    fixability?: Fixability;
+    remediation?: RemediationSpec;
 }
 export interface Rule {
     id: string;
@@ -31,6 +44,7 @@ export interface Rule {
     fixSuggestion: string;
     penalty: string;
     languages: string[];
+    remediation?: RemediationSpec;
 }
 export interface SuppressionConfig {
     enabled: boolean;
@@ -61,6 +75,8 @@ export declare class TreeSitterParser {
     extractIdentifiers(code: string): string[];
 }
 export declare const treeSitterParser: TreeSitterParser;
+declare const REMEDIATION_MAP: Record<string, RemediationSpec>;
+declare function getRemediation(ruleId: string): RemediationSpec;
 export declare const COPPA_RULES: Rule[];
 export declare const ETHICAL_RULES: Rule[];
 export interface IgnoreConfig {
@@ -151,4 +167,16 @@ export declare class HaloEngine {
      */
     getFixSuggestion(ruleId: string): string;
 }
+export { REMEDIATION_MAP, getRemediation };
+export { FixEngine } from './fixer';
+export type { FixResult, FileFixResult, FixOptions } from './fixer';
+export { transformUrlUpgrade, transformRemoveDefault, transformSanitizeInput, transformSetDefault, } from './fixer';
+export { ComplianceScoreEngine } from './scoring';
+export type { ComplianceScoreResult, LetterGrade } from './scoring';
+export { ScaffoldEngine } from './scaffold-engine';
+export type { GuidedFixResult, GuidedFixSummary } from './scaffold-engine';
+export { detectFramework } from './framework-detect';
+export type { Framework, FrameworkDetectionResult } from './framework-detect';
+export { SCAFFOLD_REGISTRY } from './scaffolds/index';
+export type { ScaffoldTemplate, ScaffoldFile } from './scaffolds/index';
 export default HaloEngine;