@runhalo/engine 0.3.1 → 0.5.0

package/dist/frameworks/django.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Django Framework Profile
+ *
+ * Django provides built-in protections that overlap with several COPPA rules:
+ * - Template engine auto-escapes all variables by default
+ * - SecurityMiddleware enforces HTTPS when configured
+ * - Built-in password validators enforce complexity requirements
+ * - django-lifecycle and django-reversion can handle data retention externally
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.djangoProfile = void 0;
+exports.djangoProfile = {
+    id: 'django',
+    name: 'Django',
+    ecosystem: 'python',
+    handled_rules: [
+        {
+            rule_id: 'coppa-sec-015',
+            action: 'suppress',
+            reason: 'Django templates auto-escape all variables by default.',
+            documentation_url: 'https://docs.djangoproject.com/en/stable/ref/templates/language/#automatic-html-escaping',
+        },
+        {
+            rule_id: 'coppa-retention-005',
+            action: 'downgrade',
+            downgrade_to: 'low',
+            reason: 'Django models with django-lifecycle or django-reversion may handle retention externally.',
+            documentation_url: 'https://docs.djangoproject.com/en/stable/topics/db/models/',
+        },
+        {
+            rule_id: 'coppa-sec-006',
+            action: 'suppress',
+            reason: 'Django SecurityMiddleware enforces HTTPS when configured.',
+            documentation_url: 'https://docs.djangoproject.com/en/stable/ref/middleware/#module-django.middleware.security',
+        },
+        {
+            rule_id: 'coppa-sec-010',
+            action: 'suppress',
+            reason: 'Django built-in password validators enforce complexity.',
+            documentation_url: 'https://docs.djangoproject.com/en/stable/topics/auth/passwords/#module-django.contrib.auth.password_validation',
+        },
+    ],
+    safe_patterns: [
+        {
+            description: 'Django CSRF middleware for cross-site request forgery protection',
+            patterns: [/CsrfViewMiddleware/, /csrf_token/],
+            applies_to_rules: ['coppa-sec-015'],
+        },
+        {
+            description: 'Django admin interface with built-in auth and access controls',
+            patterns: [/admin\.site\.register/, /class.*Admin\(/, /admin\.py/],
+            applies_to_rules: ['coppa-auth-001', 'coppa-ui-008', 'coppa-default-020'],
+        },
+    ],
+};
+//# sourceMappingURL=django.js.map

package/dist/frameworks/django.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"django.js","sourceRoot":"","sources":["../../src/frameworks/django.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAIU,QAAA,aAAa,GAAqB;IAC7C,EAAE,EAAE,QAAQ;IACZ,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,QAAQ;IACnB,aAAa,EAAE;QACb;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,wDAAwD;YAChE,iBAAiB,EAAE,0FAA0F;SAC9G;QACD;YACE,OAAO,EAAE,qBAAqB;YAC9B,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,0FAA0F;YAClG,iBAAiB,EAAE,4DAA4D;SAChF;QACD;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,2DAA2D;YACnE,iBAAiB,EAAE,4FAA4F;SAChH;QACD;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,yDAAyD;YACjE,iBAAiB,EAAE,gHAAgH;SACpI;KACF;IACD,aAAa,EAAE;QACb;YACE,WAAW,EAAE,kEAAkE;YAC/E,QAAQ,EAAE,CAAC,oBAAoB,EAAE,YAAY,CAAC;YAC9C,gBAAgB,EAAE,CAAC,eAAe,CAAC;SACpC;QACD;YACE,WAAW,EAAE,+DAA+D;YAC5E,QAAQ,EAAE,CAAC,uBAAuB,EAAE,gBAAgB,EAAE,WAAW,CAAC;YAClE,gBAAgB,EAAE,CAAC,gBAAgB,EAAE,cAAc,EAAE,mBAAmB,CAAC;SAC1E;KACF;CACF,CAAC"}

package/dist/frameworks/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Framework Allowlisting System
+ *
+ * Entry point for Halo's framework-aware rule management. When a developer
+ * declares their framework in .halorc.json (e.g. { "framework": "nextjs" }),
+ * Halo loads the corresponding profile and automatically suppresses or
+ * downgrades rules that the framework already handles natively.
+ *
+ * Usage:
+ *   import { applyFrameworkOverrides } from './frameworks';
+ *   const result = applyFrameworkOverrides(violations, 'nextjs');
+ *   // result.violations  — filtered/downgraded violations
+ *   // result.suppressedCount — number of violations removed
+ *   // result.downgradedCount — number of violations with reduced severity
+ */
+export type { FrameworkAction, FrameworkRuleOverride, FrameworkSafePattern, FrameworkProfile } from './types';
+import { FrameworkProfile } from './types';
+/**
+ * Minimal violation shape used by the framework system to avoid circular
+ * imports with the engine's Violation type. Any object with at least ruleId
+ * and severity will work.
+ */
+interface ViolationLike {
+    ruleId: string;
+    severity: string;
+    [key: string]: any;
+}
+/**
+ * Look up a framework profile by its id.
+ *
+ * @param id - Framework identifier (e.g. "nextjs", "django", "rails")
+ * @returns The matching FrameworkProfile, or null if not found
+ */
+export declare function getFrameworkProfile(id: string): FrameworkProfile | null;
+/**
+ * List all registered framework ids.
+ *
+ * @returns Sorted array of framework id strings
+ */
+export declare function listFrameworks(): string[];
+/**
+ * Apply a framework's rule overrides to a set of violations.
+ *
+ * For each violation whose ruleId appears in the framework's handled_rules:
+ * - "suppress" removes the violation from the output entirely
+ * - "downgrade" reduces the violation's severity to the specified level
+ *
+ * Violations whose ruleId is NOT in the framework's profile are passed
+ * through unchanged.
+ *
+ * @param violations - Array of violation objects to filter
+ * @param frameworkId - Framework identifier to look up
+ * @returns Object with the filtered violations array and counts
+ */
+export declare function applyFrameworkOverrides<T extends ViolationLike>(violations: T[], frameworkId: string): {
+    violations: T[];
+    suppressedCount: number;
+    downgradedCount: number;
+};

package/dist/frameworks/index.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Framework Allowlisting System
+ *
+ * Entry point for Halo's framework-aware rule management. When a developer
+ * declares their framework in .halorc.json (e.g. { "framework": "nextjs" }),
+ * Halo loads the corresponding profile and automatically suppresses or
+ * downgrades rules that the framework already handles natively.
+ *
+ * Usage:
+ *   import { applyFrameworkOverrides } from './frameworks';
+ *   const result = applyFrameworkOverrides(violations, 'nextjs');
+ *   // result.violations  — filtered/downgraded violations
+ *   // result.suppressedCount — number of violations removed
+ *   // result.downgradedCount — number of violations with reduced severity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFrameworkProfile = getFrameworkProfile;
+exports.listFrameworks = listFrameworks;
+exports.applyFrameworkOverrides = applyFrameworkOverrides;
+const nextjs_1 = require("./nextjs");
+const django_1 = require("./django");
+const rails_1 = require("./rails");
+/** Registry of all built-in framework profiles keyed by id. */
+const FRAMEWORK_REGISTRY = {
+    nextjs: nextjs_1.nextjsProfile,
+    django: django_1.djangoProfile,
+    rails: rails_1.railsProfile,
+};
+/**
+ * Look up a framework profile by its id.
+ *
+ * @param id - Framework identifier (e.g. "nextjs", "django", "rails")
+ * @returns The matching FrameworkProfile, or null if not found
+ */
+function getFrameworkProfile(id) {
+    return FRAMEWORK_REGISTRY[id] ?? null;
+}
+/**
+ * List all registered framework ids.
+ *
+ * @returns Sorted array of framework id strings
+ */
+function listFrameworks() {
+    return Object.keys(FRAMEWORK_REGISTRY).sort();
+}
+/**
+ * Apply a framework's rule overrides to a set of violations.
+ *
+ * For each violation whose ruleId appears in the framework's handled_rules:
+ * - "suppress" removes the violation from the output entirely
+ * - "downgrade" reduces the violation's severity to the specified level
+ *
+ * Violations whose ruleId is NOT in the framework's profile are passed
+ * through unchanged.
+ *
+ * @param violations - Array of violation objects to filter
+ * @param frameworkId - Framework identifier to look up
+ * @returns Object with the filtered violations array and counts
+ */
+function applyFrameworkOverrides(violations, frameworkId) {
+    const profile = getFrameworkProfile(frameworkId);
+    if (!profile) {
+        return { violations: [...violations], suppressedCount: 0, downgradedCount: 0 };
+    }
+    // Build a lookup map from rule_id to override for O(1) access
+    const overrideMap = new Map(profile.handled_rules.map((override) => [override.rule_id, override]));
+    let suppressedCount = 0;
+    let downgradedCount = 0;
+    const filtered = [];
+    for (const violation of violations) {
+        const override = overrideMap.get(violation.ruleId);
+        if (!override) {
+            filtered.push(violation);
+            continue;
+        }
+        if (override.action === 'suppress') {
+            suppressedCount++;
+            // Violation is removed from output
+            continue;
+        }
+        if (override.action === 'downgrade' && override.downgrade_to) {
+            downgradedCount++;
+            // Create a shallow copy with the new severity to avoid mutating the original
+            filtered.push({ ...violation, severity: override.downgrade_to });
+            continue;
+        }
+        // Fallback: pass through if action is unrecognized
+        filtered.push(violation);
+    }
+    return { violations: filtered, suppressedCount, downgradedCount };
+}
+//# sourceMappingURL=index.js.map

package/dist/frameworks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/frameworks/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAiCH,kDAEC;AAOD,wCAEC;AAgBD,0DA6CC;AApGD,qCAAyC;AACzC,qCAAyC;AACzC,mCAAuC;AAavC,+DAA+D;AAC/D,MAAM,kBAAkB,GAAqC;IAC3D,MAAM,EAAE,sBAAa;IACrB,MAAM,EAAE,sBAAa;IACrB,KAAK,EAAE,oBAAY;CACpB,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,EAAU;IAC5C,OAAO,kBAAkB,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,uBAAuB,CACrC,UAAe,EACf,WAAmB;IAEnB,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEjD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IACjF,CAAC;IAED,8DAA8D;IAC9D,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CACtE,CAAC;IAEF,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,MAAM,QAAQ,GAAQ,EAAE,CAAC;IAEzB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEnD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACnC,eAAe,EAAE,CAAC;YAClB,mCAAmC;YACnC,SAAS;QACX,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC;YAC7D,eAAe,EAAE,CAAC;YAClB,6EAA6E;YAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;YACjE,SAAS;QACX,CAAC;QAED,mDAAmD;QACnD,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC;AACpE,CAAC"}

package/dist/frameworks/nextjs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Next.js Framework Profile
+ *
+ * Next.js provides built-in protections that overlap with several COPPA rules:
+ * - React JSX auto-escaping mitigates most XSS vectors
+ * - HTTPS enforcement in production covers unencrypted PII transmission
+ * - Next.js Link component handles external navigation safely
+ * - Middleware provides centralized cookie management
+ */
+import { FrameworkProfile } from './types';
+export declare const nextjsProfile: FrameworkProfile;

package/dist/frameworks/nextjs.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Next.js Framework Profile
+ *
+ * Next.js provides built-in protections that overlap with several COPPA rules:
+ * - React JSX auto-escaping mitigates most XSS vectors
+ * - HTTPS enforcement in production covers unencrypted PII transmission
+ * - Next.js Link component handles external navigation safely
+ * - Middleware provides centralized cookie management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextjsProfile = void 0;
+exports.nextjsProfile = {
+    id: 'nextjs',
+    name: 'Next.js',
+    ecosystem: 'javascript',
+    handled_rules: [
+        {
+            rule_id: 'coppa-sec-015',
+            action: 'downgrade',
+            downgrade_to: 'low',
+            reason: 'React auto-escapes JSX output by default. dangerouslySetInnerHTML is the only XSS vector and is flagged separately.',
+            documentation_url: 'https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html',
+        },
+        {
+            rule_id: 'coppa-sec-006',
+            action: 'suppress',
+            reason: 'Next.js enforces HTTPS in production. API routes run server-side. Development HTTP is expected.',
+            documentation_url: 'https://nextjs.org/docs/app/api-reference/next-config-js/headers',
+        },
+        {
+            rule_id: 'coppa-ext-017',
+            action: 'downgrade',
+            downgrade_to: 'low',
+            reason: "Next.js Link component handles external navigation. rel='noopener noreferrer' is auto-added.",
+            documentation_url: 'https://nextjs.org/docs/app/api-reference/components/link',
+        },
+        {
+            rule_id: 'coppa-cookies-016',
+            action: 'downgrade',
+            downgrade_to: 'low',
+            reason: 'Next.js middleware can intercept and manage cookies centrally.',
+            documentation_url: 'https://nextjs.org/docs/app/building-your-application/routing/middleware',
+        },
+    ],
+    safe_patterns: [
+        {
+            description: 'Next.js Image component for optimized, safe image handling',
+            patterns: [/next\/image/, /<Image\s/],
+            applies_to_rules: ['coppa-ugc-014'],
+        },
+        {
+            description: 'Next.js middleware for centralized request/response interception',
+            patterns: [/middleware\.(ts|js)/, /NextResponse/],
+            applies_to_rules: ['coppa-sec-015'],
+        },
+    ],
+};
+//# sourceMappingURL=nextjs.js.map

package/dist/frameworks/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../../src/frameworks/nextjs.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAIU,QAAA,aAAa,GAAqB;IAC7C,EAAE,EAAE,QAAQ;IACZ,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,YAAY;IACvB,aAAa,EAAE;QACb;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,qHAAqH;YAC7H,iBAAiB,EAAE,4FAA4F;SAChH;QACD;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,iGAAiG;YACzG,iBAAiB,EAAE,kEAAkE;SACtF;QACD;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,8FAA8F;YACtG,iBAAiB,EAAE,2DAA2D;SAC/E;QACD;YACE,OAAO,EAAE,mBAAmB;YAC5B,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,gEAAgE;YACxE,iBAAiB,EAAE,0EAA0E;SAC9F;KACF;IACD,aAAa,EAAE;QACb;YACE,WAAW,EAAE,4DAA4D;YACzE,QAAQ,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC;YACrC,gBAAgB,EAAE,CAAC,eAAe,CAAC;SACpC;QACD;YACE,WAAW,EAAE,kEAAkE;YAC/E,QAAQ,EAAE,CAAC,qBAAqB,EAAE,cAAc,CAAC;YACjD,gBAAgB,EAAE,CAAC,eAAe,CAAC;SACpC;KACF;CACF,CAAC"}

package/dist/frameworks/rails.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ruby on Rails Framework Profile
+ *
+ * Rails provides built-in protections that overlap with several COPPA rules:
+ * - ERB templates auto-escape all output by default
+ * - Strong parameters filter mass assignment (mitigates PII leaks)
+ * - ActiveRecord supports soft delete via acts_as_paranoid or discard gem
+ * - force_ssl config enforces HTTPS application-wide
+ */
+import { FrameworkProfile } from './types';
+export declare const railsProfile: FrameworkProfile;

package/dist/frameworks/rails.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Ruby on Rails Framework Profile
+ *
+ * Rails provides built-in protections that overlap with several COPPA rules:
+ * - ERB templates auto-escape all output by default
+ * - Strong parameters filter mass assignment (mitigates PII leaks)
+ * - ActiveRecord supports soft delete via acts_as_paranoid or discard gem
+ * - force_ssl config enforces HTTPS application-wide
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.railsProfile = void 0;
+exports.railsProfile = {
+    id: 'rails',
+    name: 'Ruby on Rails',
+    ecosystem: 'ruby',
+    handled_rules: [
+        {
+            rule_id: 'coppa-sec-015',
+            action: 'suppress',
+            reason: 'ERB templates auto-escape all output by default.',
+            documentation_url: 'https://guides.rubyonrails.org/security.html#cross-site-scripting-xss',
+        },
+        {
+            rule_id: 'coppa-data-002',
+            action: 'downgrade',
+            downgrade_to: 'low',
+            reason: 'Rails strong parameters filter mass assignment.',
+            documentation_url: 'https://guides.rubyonrails.org/action_controller_overview.html#strong-parameters',
+        },
+        {
+            rule_id: 'coppa-retention-005',
+            action: 'downgrade',
+            downgrade_to: 'low',
+            reason: 'ActiveRecord supports soft delete via acts_as_paranoid or discard gem.',
+            documentation_url: 'https://github.com/jhawthorn/discard',
+        },
+        {
+            rule_id: 'coppa-sec-006',
+            action: 'suppress',
+            reason: 'Rails force_ssl config enforces HTTPS.',
+            documentation_url: 'https://guides.rubyonrails.org/configuring.html#config-force-ssl',
+        },
+    ],
+    safe_patterns: [
+        {
+            description: 'Rails CSRF protection via protect_from_forgery and authenticity tokens',
+            patterns: [/protect_from_forgery/, /authenticity_token/],
+            applies_to_rules: ['coppa-sec-015'],
+        },
+        {
+            description: 'Rails ActiveRecord encryption for sensitive attributes',
+            patterns: [/encrypts\s+:/, /has_encrypted/],
+            applies_to_rules: ['coppa-sec-006'],
+        },
+    ],
+};
+//# sourceMappingURL=rails.js.map

package/dist/frameworks/rails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails.js","sourceRoot":"","sources":["../../src/frameworks/rails.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAIU,QAAA,YAAY,GAAqB;IAC5C,EAAE,EAAE,OAAO;IACX,IAAI,EAAE,eAAe;IACrB,SAAS,EAAE,MAAM;IACjB,aAAa,EAAE;QACb;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,kDAAkD;YAC1D,iBAAiB,EAAE,uEAAuE;SAC3F;QACD;YACE,OAAO,EAAE,gBAAgB;YACzB,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,iDAAiD;YACzD,iBAAiB,EAAE,kFAAkF;SACtG;QACD;YACE,OAAO,EAAE,qBAAqB;YAC9B,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,MAAM,EAAE,wEAAwE;YAChF,iBAAiB,EAAE,sCAAsC;SAC1D;QACD;YACE,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,wCAAwC;YAChD,iBAAiB,EAAE,kEAAkE;SACtF;KACF;IACD,aAAa,EAAE;QACb;YACE,WAAW,EAAE,wEAAwE;YACrF,QAAQ,EAAE,CAAC,sBAAsB,EAAE,oBAAoB,CAAC;YACxD,gBAAgB,EAAE,CAAC,eAAe,CAAC;SACpC;QACD;YACE,WAAW,EAAE,wDAAwD;YACrE,QAAQ,EAAE,CAAC,cAAc,EAAE,eAAe,CAAC;YAC3C,gBAAgB,EAAE,CAAC,eAAe,CAAC;SACpC;KACF;CACF,CAAC"}

package/dist/frameworks/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Framework Allowlisting Type Definitions
+ *
+ * Defines the type contracts for framework profiles that declare which
+ * COPPA/ethical rules a framework already handles natively. When a developer
+ * declares their framework in .halorc.json, Halo uses these profiles to
+ * suppress or downgrade rules the framework covers automatically.
+ */
+export type FrameworkAction = 'suppress' | 'downgrade';
+export interface FrameworkRuleOverride {
+    rule_id: string;
+    action: FrameworkAction;
+    downgrade_to?: 'critical' | 'high' | 'medium' | 'low';
+    condition?: string;
+    reason: string;
+    documentation_url?: string;
+}
+export interface FrameworkSafePattern {
+    description: string;
+    patterns: RegExp[];
+    applies_to_rules: string[];
+}
+export interface FrameworkProfile {
+    id: string;
+    name: string;
+    ecosystem: 'javascript' | 'python' | 'ruby';
+    handled_rules: FrameworkRuleOverride[];
+    safe_patterns: FrameworkSafePattern[];
+}

package/dist/frameworks/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Framework Allowlisting Type Definitions
+ *
+ * Defines the type contracts for framework profiles that declare which
+ * COPPA/ethical rules a framework already handles natively. When a developer
+ * declares their framework in .halorc.json, Halo uses these profiles to
+ * suppress or downgrade rules the framework covers automatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/frameworks/types.js.map

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

package/dist/index.d.ts

@@ -7,7 +7,10 @@
  * Sprint 1 Fixes: Added tree-sitter for AST analysis, YAML rule loading
  */
 import Parser from 'tree-sitter';
+import { ConfidenceResult, ConfidenceSignals, ConfidenceInterpretation, ViolationInput } from './context-analyzer';
+export type { ConfidenceResult, ConfidenceSignals, ConfidenceInterpretation, ViolationInput };
 export type Severity = 'critical' | 'high' | 'medium' | 'low';
+export type ASTVerdict = 'confirmed' | 'suppressed' | 'regex_only';
 export type Fixability = 'auto' | 'guided' | 'flag-only';
 export interface RemediationSpec {
     fixability: Fixability;
@@ -34,6 +37,20 @@ export interface Violation {
     matchType?: 'regex' | 'ast' | 'hybrid';
     fixability?: Fixability;
     remediation?: RemediationSpec;
+    /** AST analysis verdict: confirmed, suppressed, or regex_only */
+    astVerdict?: ASTVerdict;
+    /** AST analysis confidence: 0.0 to 1.0 */
+    astConfidence?: number;
+    /** Reason for AST verdict */
+    astReason?: string;
+    /** Whether this violation was suppressed by framework profile */
+    frameworkSuppressed?: boolean;
+    /** ContextAnalyzer confidence score (0.0-1.0) */
+    confidence?: number;
+    /** ContextAnalyzer interpretation */
+    confidenceInterpretation?: ConfidenceInterpretation;
+    /** ContextAnalyzer reason string */
+    confidenceReason?: string;
 }
 export interface Rule {
     id: string;
@@ -51,6 +68,43 @@ export interface SuppressionConfig {
     commentPattern: string;
 }
 export declare function loadRulesFromYAML(yamlPath: string): Rule[];
+export interface JSONRuleConfig {
+    version: string;
+    generated_at: string;
+    packs: Record<string, {
+        id: string;
+        name: string;
+        description: string;
+        jurisdiction: string;
+        jurisdiction_level: string;
+        is_free: boolean;
+        effective_date: string | null;
+        source_url: string;
+    }>;
+    rules: JSONRule[];
+}
+export interface JSONRule {
+    id: string;
+    name: string;
+    severity: Severity;
+    category: string;
+    description: string;
+    patterns: Array<{
+        pattern: string;
+        flags: string;
+    }>;
+    fix_suggestion: string;
+    penalty: string;
+    languages: string[];
+    packs: string[];
+    fixability: string;
+    transform_type: string | null;
+    scaffold_id: string | null;
+    guidance_url: string | null;
+}
+export declare function loadRulesFromJSON(jsonPath: string): Rule[];
+export declare function loadRulesFromJSONByPack(jsonPath: string, packIds: string[]): Rule[];
+export declare function compileRawRules(rawRules: JSONRule[]): Rule[];
 export declare class TreeSitterParser {
     private parser;
     constructor();
@@ -124,6 +178,13 @@ export interface EngineConfig {
     ethical?: boolean;
     aiAudit?: boolean;
     sectorAuSbd?: boolean;
+    sectorAuOsa?: boolean;
+    packs?: string[];
+    loadedRules?: Rule[];
+    framework?: string;
+    astAnalysis?: boolean;
+    historicalFPRates?: Record<string, number>;
+    suppressionRates?: Record<string, number>;
 }
 export interface ScanResult {
     filePath: string;
@@ -137,7 +198,20 @@ export declare class HaloEngine {
     private config;
     private rules;
     private treeSitter;
+    private astEngine;
+    private contextAnalyzer;
     constructor(config?: EngineConfig);
+    /**
+     * Load rules from the bundled rules.json file, filtered by pack IDs.
+     * Falls back to empty array if rules.json not found.
+     */
+    private loadBundledRulesByPack;
+    /**
+     * Resolve legacy boolean flags to pack IDs.
+     * Maps ethical/aiAudit/sectorAuSbd booleans to their pack ID equivalents.
+     * Always includes 'coppa' as the base pack.
+     */
+    static resolvePacks(config: EngineConfig): string[];
     /**
      * Get the tree-sitter parser for advanced AST analysis
      */