@runhalo/engine 0.4.0 → 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;
@@ -161,8 +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;
@@ -176,6 +198,8 @@ 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.

package/dist/index.js

@@ -59,6 +59,9 @@ const tree_sitter_1 = __importDefault(require("tree-sitter"));
 const tree_sitter_typescript_1 = __importDefault(require("tree-sitter-typescript"));
 const tree_sitter_javascript_1 = __importDefault(require("tree-sitter-javascript"));
 const yaml = __importStar(require("js-yaml"));
+const ast_engine_1 = require("./ast-engine");
+const frameworks_1 = require("./frameworks");
+const context_analyzer_1 = require("./context-analyzer");
 // Extract category from ruleId (e.g. "coppa-auth-001" → "auth", "ETHICAL-001" → "ethical", "AU-SBD-001" → "au-sbd")
 function extractCategory(ruleId) {
     if (ruleId.startsWith('ETHICAL'))
@@ -67,6 +70,16 @@ function extractCategory(ruleId) {
         return 'ai-audit';
     if (ruleId.startsWith('AU-SBD'))
         return 'au-sbd';
+    if (ruleId.startsWith('AU-OSA'))
+        return 'au-osa';
+    if (ruleId.startsWith('caadca'))
+        return 'caadca';
+    if (ruleId.startsWith('AI-RISK'))
+        return 'ai-risk';
+    if (ruleId.startsWith('AI-TRANSPARENCY'))
+        return 'ai-transparency';
+    if (ruleId.startsWith('CAI-'))
+        return 'constitutional-ai';
     const match = ruleId.match(/^coppa-(\w+)-\d+$/);
     return match ? match[1] : 'unknown';
 }
@@ -1140,6 +1153,12 @@ class HaloEngine {
     constructor(config = {}) {
         this.config = config;
         this.treeSitter = new TreeSitterParser();
+        this.astEngine = new ast_engine_1.ASTRuleEngine();
+        this.contextAnalyzer = new context_analyzer_1.ContextAnalyzer({
+            framework: config.framework,
+            historicalFPRates: config.historicalFPRates,
+            suppressionRates: config.suppressionRates,
+        });
         // Rule loading priority chain:
         // 1. config.loadedRules — pre-compiled rules from CLI API fetch
         // 2. config.rulesPath — YAML file (legacy)
@@ -1207,6 +1226,8 @@ class HaloEngine {
             packs.push('ai-audit');
         if (config.sectorAuSbd)
             packs.push('au-sbd');
+        if (config.sectorAuOsa)
+            packs.push('au-osa');
         return packs;
     }
     /**
@@ -1220,18 +1241,17 @@ class HaloEngine {
      */
     scanFileWithAST(filePath, content, language = 'typescript') {
         // First get regex-based violations
-        const violations = this.scanFile(filePath, content);
-        // Then enhance with AST analysis
+        let violations = this.scanFile(filePath, content);
+        // Sprint 8: Enhanced AST analysis with ASTRuleEngine + framework overrides + ContextAnalyzer
         try {
-            const identifiers = this.treeSitter.extractIdentifiers(content);
+            const tree = this.treeSitter.parse(content, language);
+            // Legacy Sprint 1: AST-based detection for social login (signInWithPopup)
             const functionCalls = this.treeSitter.findFunctionCalls(content, 'signInWithPopup');
-            // Add AST-based detection for social login
             for (const call of functionCalls) {
-                // Check if already detected by regex
                 const exists = violations.some(v => v.ruleId === 'coppa-auth-001' &&
                     v.line === call.line);
                 if (!exists) {
-                    const authRule = exports.COPPA_RULES.find(r => r.id === 'coppa-auth-001');
+                    const authRule = this.rules.find(r => r.id === 'coppa-auth-001') || exports.COPPA_RULES.find(r => r.id === 'coppa-auth-001');
                     if (authRule) {
                         violations.push({
                             ruleId: 'coppa-auth-001',
@@ -1253,10 +1273,65 @@ class HaloEngine {
                     }
                 }
             }
+            // Sprint 8: Run ASTRuleEngine analysis on every violation to classify FPs
+            if (this.config.astAnalysis !== false) {
+                for (const violation of violations) {
+                    try {
+                        const astResult = this.astEngine.analyzeViolationWithPath(violation.ruleId, filePath, content, {
+                            ruleId: violation.ruleId,
+                            line: violation.line,
+                            column: violation.column,
+                            codeSnippet: violation.codeSnippet,
+                        }, tree);
+                        violation.astVerdict = astResult.verdict;
+                        violation.astConfidence = astResult.confidence;
+                        violation.astReason = astResult.reason;
+                        // Update matchType to reflect AST involvement
+                        if (astResult.verdict !== 'regex_only') {
+                            violation.matchType = 'hybrid';
+                        }
+                    }
+                    catch (ruleError) {
+                        violation.astVerdict = 'regex_only';
+                        violation.astConfidence = 0;
+                        violation.astReason = 'AST analysis failed for this violation';
+                    }
+                }
+            }
         }
         catch (error) {
-            // If AST parsing fails, fall back to regex-only
+            // If AST parsing fails entirely, fall back to regex-only
             console.warn('AST parsing failed, using regex-only mode:', error);
+            for (const v of violations) {
+                v.astVerdict = 'regex_only';
+                v.astConfidence = 0;
+            }
+        }
+        // Sprint 8: Apply framework overrides
+        if (this.config.framework) {
+            const result = (0, frameworks_1.applyFrameworkOverrides)(violations, this.config.framework);
+            violations = result.violations;
+        }
+        // Sprint 8: ContextAnalyzer — compute confidence scores
+        const violationInputs = violations.map(v => ({
+            ruleId: v.ruleId,
+            severity: v.severity,
+            line: v.line,
+            column: v.column,
+            codeSnippet: v.codeSnippet,
+            astVerdict: v.astVerdict,
+            astConfidence: v.astConfidence,
+            astReason: v.astReason,
+            frameworkSuppressed: v.frameworkSuppressed,
+        }));
+        const confidenceResults = this.contextAnalyzer.analyzeFile(violationInputs, filePath, content);
+        for (let i = 0; i < violations.length; i++) {
+            const result = confidenceResults.get(i);
+            if (result) {
+                violations[i].confidence = result.confidence;
+                violations[i].confidenceInterpretation = result.interpretation;
+                violations[i].confidenceReason = result.reason;
+            }
         }
         return violations;
     }
@@ -1277,6 +1352,25 @@ class HaloEngine {
         }
         const violations = [];
         const lines = content.split('\n');
+        // Sprint 8: Test file detection for regex scanner (coppa-sec-010 FP fix)
+        const normalizedPath = filePath.replace(/\\/g, '/');
+        const isTestFile = /\.(test|spec)\.(ts|tsx|js|jsx|py|rb|java|go)$/i.test(normalizedPath) ||
+            /(^|\/)__tests__\//.test(normalizedPath) ||
+            /(^|\/)test\//.test(normalizedPath) ||
+            /(^|\/)tests\//.test(normalizedPath) ||
+            /(^|\/)spec\//.test(normalizedPath) ||
+            /(^|\/)fixtures\//.test(normalizedPath) ||
+            /\.(stories|story)\.(ts|tsx|js|jsx)$/i.test(normalizedPath) ||
+            /(^|\/)cypress\//.test(normalizedPath) ||
+            /(^|\/)e2e\//.test(normalizedPath) ||
+            /jest\.config|vitest\.config|playwright\.config/i.test(normalizedPath);
+        // Rules that commonly false-positive in test/fixture files
+        const TEST_FP_RULES = new Set([
+            'coppa-sec-010', // Weak passwords in test fixtures
+            'coppa-tracking-003', // Analytics snippets in test mocks
+            'coppa-auth-001', // Auth patterns in test helpers
+            'coppa-sec-015', // XSS patterns in security test cases
+        ]);
         // Parse suppression comments
         const suppressions = parseSuppressions(content);
         // Track lines with global suppressions (at top of file)
@@ -1287,6 +1381,10 @@ class HaloEngine {
             }
         }
         for (const rule of this.rules) {
+            // Sprint 8: Skip rules that commonly FP in test files
+            if (isTestFile && TEST_FP_RULES.has(rule.id)) {
+                continue;
+            }
             // Special handling for coppa-retention-005: skip if schema has retention fields
             if (rule.id === 'coppa-retention-005') {
                 // Check if the content has retention-related fields