@euconform/core 1.0.1 → 1.3.0

package/src/legal-checks/gpai-classifier.ts

@@ -0,0 +1,281 @@
+/**
+ * GPAI / Foundation Model Compliance Classifier
+ * Based on EU AI Act (Regulation EU 2024/1689) – Art. 53–55 + Art. 51 + Art. 71
+ *
+ * Obligations enforceable since August 2, 2025 (Phase 2, Art. 113(2)).
+ *
+ * IMPORTANT: This module provides technical orientation, not legal advice.
+ */
+
+import type { QuizAnswer, QuizQuestion } from "../types";
+
+/** The specific obligations checked under Art. 53–55 */
+export type GPAIObligationType =
+  | "technical-docs"
+  | "downstream-info"
+  | "copyright-policy"
+  | "eu-database"
+  | "open-source"
+  | "systemic-risk"
+  | "red-teaming"
+  | "incident-reporting"
+  | "cybersecurity";
+
+/** Overall compliance determination */
+export type GPAIComplianceLevel = "compliant" | "partial" | "non-compliant";
+
+/** A specific obligation that is missing or only partially met */
+export interface GPAIComplianceFlag {
+  obligation: GPAIObligationType;
+  status: "missing" | "partial";
+  articleRef: string;
+}
+
+/** Full result of GPAI compliance classification */
+export interface GPAIComplianceResult {
+  level: GPAIComplianceLevel;
+  isSystemicRisk: boolean;
+  flags: GPAIComplianceFlag[];
+  legalBasis: string[];
+  notes: string[];
+}
+
+/**
+ * The 9 GPAI compliance questions (Art. 53–55).
+ * Order matters: q1–q9 map to i18n keys gpai_q1–gpai_q9.
+ */
+export const GPAI_QUESTIONS: QuizQuestion[] = [
+  {
+    id: "gpai-technical-docs",
+    question: "Art. 53(1)(a): Technical documentation (Annex XI/XII)?",
+    description:
+      "Have you prepared and maintain up-to-date technical documentation for the GPAI model per Annex XI/XII (general-purpose) or the systemic-risk extension?",
+    options: [
+      { value: "yes", label: "Yes, implemented" },
+      { value: "no", label: "No, missing" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+  {
+    id: "gpai-downstream-info",
+    question: "Art. 53(1)(b): Downstream provider information?",
+    description:
+      "Do you provide downstream providers / deployers with the information they need to comply with their own EU AI Act obligations (capabilities, limitations, intended use)?",
+    options: [
+      { value: "yes", label: "Yes, implemented" },
+      { value: "no", label: "No, missing" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+  {
+    id: "gpai-copyright-policy",
+    question: "Art. 53(1)(c–d): Copyright policy + training data summary?",
+    description:
+      "Have you established a copyright compliance policy (Art. 53(1)(c)) and published a sufficiently detailed training data summary for copyright purposes (Art. 53(1)(d))?",
+    options: [
+      { value: "yes", label: "Yes, implemented" },
+      { value: "no", label: "No, missing" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+  {
+    id: "gpai-eu-database",
+    question: "Art. 71: EU AI Database registration?",
+    description:
+      "Is the GPAI model registered in the EU AI Database as required under Art. 71 (providers of GPAI models must register before placing the model on the EU market)?",
+    options: [
+      { value: "yes", label: "Yes, registered" },
+      { value: "no", label: "No, not registered" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+  {
+    id: "gpai-open-source",
+    question: "Art. 53(2): Open-source model release?",
+    description:
+      "Is the model released as open source with weights publicly available? Open-source GPAI models are exempt from Art. 53(1)(a–c) obligations (technical docs, downstream info, copyright policy) but not from Art. 53(1)(d) (training data summary) or Art. 55 systemic-risk obligations.",
+    options: [
+      { value: "yes", label: "Yes, open source" },
+      { value: "no", label: "No, proprietary" },
+      { value: "unsure", label: "Unsure / partially open" },
+    ],
+  },
+  {
+    id: "gpai-systemic-risk",
+    question: "Art. 51 + Annex XIII: Trained with ≥ 10²⁵ FLOP?",
+    description:
+      "Was the model trained using compute exceeding 10²⁵ floating-point operations (FLOP)? Models at or above this threshold are designated as GPAI models with systemic risk (Art. 51) and are subject to the additional Art. 55 obligations below.",
+    options: [
+      { value: "yes", label: "Yes (systemic risk)" },
+      { value: "no", label: "No (below threshold)" },
+      { value: "unsure", label: "Unknown / unsure" },
+    ],
+  },
+  {
+    id: "gpai-red-teaming",
+    question: "Art. 55(1)(a): Adversarial testing / red-teaming?",
+    description:
+      "Have you conducted model evaluations, adversarial testing, and red-teaming to identify and mitigate systemic risks (required only for Art. 51 systemic-risk models)?",
+    options: [
+      { value: "yes", label: "Yes, conducted" },
+      { value: "no", label: "No, not done" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+  {
+    id: "gpai-incident-reporting",
+    question: "Art. 55(1)(b): Serious incident reporting mechanisms?",
+    description:
+      "Do you have mechanisms to track, document, and report serious incidents caused by the GPAI model to the AI Office and affected national authorities (required only for Art. 51 systemic-risk models)?",
+    options: [
+      { value: "yes", label: "Yes, in place" },
+      { value: "no", label: "No, missing" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+  {
+    id: "gpai-cybersecurity",
+    question: "Art. 55(1)(c): Cybersecurity measures?",
+    description:
+      "Have you implemented adequate cybersecurity protections for the GPAI model and its infrastructure, including adversarial robustness measures (required only for Art. 51 systemic-risk models)?",
+    options: [
+      { value: "yes", label: "Yes, implemented" },
+      { value: "no", label: "No, missing" },
+      { value: "unsure", label: "In progress / unsure" },
+    ],
+  },
+];
+
+/** Returns the full ordered list of GPAI compliance questions */
+export function getGPAIQuestions(): QuizQuestion[] {
+  return GPAI_QUESTIONS;
+}
+
+/** Returns true if the model meets the systemic risk threshold (Art. 51) */
+export function isSystemicRiskModel(answers: QuizAnswer[]): boolean {
+  const systemicAnswer = answers.find((a) => a.questionId === "gpai-systemic-risk");
+  return systemicAnswer?.value === "yes";
+}
+
+/** Push a flag if the answer value is "no" or "unsure" */
+function checkObligation(
+  value: string | undefined,
+  obligation: GPAIObligationType,
+  articleRef: string,
+  flags: GPAIComplianceFlag[]
+): void {
+  if (value === "no") {
+    flags.push({ obligation, status: "missing", articleRef });
+  } else if (value === "unsure") {
+    flags.push({ obligation, status: "partial", articleRef });
+  }
+}
+
+/** Evaluate Art. 53 obligations and populate flags / notes */
+function evaluateArt53Obligations(
+  byId: Map<string, string>,
+  isOpenSource: boolean,
+  flags: GPAIComplianceFlag[],
+  legalBasis: string[],
+  notes: string[]
+): void {
+  if (!isOpenSource) {
+    checkObligation(byId.get("gpai-technical-docs"), "technical-docs", "Art. 53(1)(a)", flags);
+    checkObligation(byId.get("gpai-downstream-info"), "downstream-info", "Art. 53(1)(b)", flags);
+    checkObligation(
+      byId.get("gpai-copyright-policy"),
+      "copyright-policy",
+      "Art. 53(1)(c–d)",
+      flags
+    );
+  } else {
+    // Open-source: Art. 53(1)(a–c) exempt, but training data summary (Art. 53(1)(d)) still applies
+    const copyrightVal = byId.get("gpai-copyright-policy");
+    checkObligation(copyrightVal, "copyright-policy", "Art. 53(1)(d)", flags);
+    if (copyrightVal === "no" || copyrightVal === "unsure") {
+      notes.push(
+        "Open-source models are exempt from Art. 53(1)(c) copyright policy obligations, but Art. 53(1)(d) training data summary still applies."
+      );
+    }
+  }
+
+  const euDatabase = byId.get("gpai-eu-database");
+  checkObligation(euDatabase, "eu-database", "Art. 71", flags);
+  if (euDatabase === "no") {
+    legalBasis.push("Verordnung (EU) 2024/1689 – Art. 71 (EU AI Database)");
+  }
+}
+
+/** Evaluate Art. 55 systemic risk obligations and populate flags */
+function evaluateArt55Obligations(
+  byId: Map<string, string>,
+  flags: GPAIComplianceFlag[],
+  legalBasis: string[]
+): void {
+  legalBasis.push("Verordnung (EU) 2024/1689 – Art. 51 + Art. 55 (Systemic Risk)");
+  legalBasis.push("Verordnung (EU) 2024/1689 – Annex XIII (Systemic Risk Indicators)");
+  checkObligation(byId.get("gpai-red-teaming"), "red-teaming", "Art. 55(1)(a)", flags);
+  checkObligation(
+    byId.get("gpai-incident-reporting"),
+    "incident-reporting",
+    "Art. 55(1)(b)",
+    flags
+  );
+  checkObligation(byId.get("gpai-cybersecurity"), "cybersecurity", "Art. 55(1)(c)", flags);
+}
+
+/** Determine overall compliance level from accumulated flags */
+function determineLevel(flags: GPAIComplianceFlag[], isOpenSource: boolean): GPAIComplianceLevel {
+  const criticalObligations: GPAIObligationType[] = isOpenSource
+    ? ["eu-database"]
+    : ["technical-docs", "downstream-info", "copyright-policy", "eu-database"];
+
+  const allCriticalMissing =
+    !isOpenSource &&
+    criticalObligations.every((obl) =>
+      flags.some((f) => f.obligation === obl && f.status === "missing")
+    );
+
+  if (allCriticalMissing) return "non-compliant";
+  if (flags.length > 0) return "partial";
+  return "compliant";
+}
+
+/**
+ * Classify GPAI compliance based on answers to the 9 questions.
+ * Returns a GPAIComplianceResult with level, flags, and legal basis.
+ *
+ * Classification logic:
+ * - Open-source (Art. 53(2)): exempt from docs/downstream/copyright obligations
+ * - Systemic risk (Art. 51): Art. 55 obligations apply
+ * - Critical Art. 53 all missing → "non-compliant"
+ * - Any "unsure" or partial → "partial"
+ * - All applicable "yes" → "compliant"
+ */
+export function classifyGPAICompliance(answers: QuizAnswer[]): GPAIComplianceResult {
+  const byId = new Map(answers.map((a) => [a.questionId, a.value] as const));
+  const isOpenSource = byId.get("gpai-open-source") === "yes";
+  const hasSystemicRisk = byId.get("gpai-systemic-risk") === "yes";
+
+  const flags: GPAIComplianceFlag[] = [];
+  const legalBasis: string[] = ["Verordnung (EU) 2024/1689 – Art. 53 (GPAI obligations)"];
+  const notes: string[] = [];
+
+  evaluateArt53Obligations(byId, isOpenSource, flags, legalBasis, notes);
+
+  if (hasSystemicRisk) {
+    evaluateArt55Obligations(byId, flags, legalBasis);
+  } else {
+    notes.push(
+      "Art. 55 systemic risk obligations (red-teaming, incident reporting, cybersecurity) are not applicable as the model does not meet the Art. 51 threshold (≥ 10²⁵ FLOP)."
+    );
+  }
+
+  return {
+    level: determineLevel(flags, isOpenSource),
+    isSystemicRisk: hasSystemicRisk,
+    flags,
+    legalBasis,
+    notes,
+  };
+}

package/src/legal-checks/index.ts

@@ -53,3 +53,36 @@ export { getHumanOversightAndLoggingTemplate } from "./human-oversight-logging";
 
 export type { AnnexIVStructuredReportV1 } from "./annex-iv-report";
 export { buildAnnexIVReportV1 } from "./annex-iv-report";
+
+export type {
+  DeadlineStatus,
+  AffectedAudience,
+  DeadlineObligation,
+  DeadlinePhase,
+} from "./deadline-timeline";
+export {
+  EU_AI_ACT_TIMELINE,
+  DIGITAL_OMNIBUS_PROPOSALS,
+  getDeadlineStatus,
+  getDaysUntilDeadline,
+  getAudiencesForRiskLevel,
+  getNextDeadline,
+  getTimelineForRiskLevel,
+  getTimelineForAudiences,
+} from "./deadline-timeline";
+
+export type {
+  GPAIObligationType,
+  GPAIComplianceLevel,
+  GPAIComplianceFlag,
+  GPAIComplianceResult,
+} from "./gpai-classifier";
+export {
+  GPAI_QUESTIONS,
+  classifyGPAICompliance,
+  getGPAIQuestions,
+  isSystemicRiskModel,
+} from "./gpai-classifier";
+
+export type { GapPriority, GapAction, GapAnalysisResult } from "./gap-analysis";
+export { generateAnnexIIIGapAnalysis, generateGPAIGapAnalysis } from "./gap-analysis";

package/src/scanner/aggregator.ts

@@ -0,0 +1,258 @@
+/**
+ * Scanner aggregator — orchestrates file discovery and signal detection,
+ * deduplicates signals, and assembles the ScanResult.
+ */
+
+import { basename } from "node:path";
+import { hasImplementationSignals } from "../evidence/compliance-evaluation";
+import type {
+  AppType,
+  ConfidenceLevel,
+  DetectedSignal,
+  FileProvenance,
+  OpenQuestion,
+  RepoProfile,
+  ScanFile,
+  ScanOptions,
+  ScanResult,
+  SignalCategory,
+} from "../evidence/types";
+import { runAllDetectors } from "./detectors";
+import { CONFIDENCE_RANK } from "./detectors/shared";
+import { discoverFiles } from "./discovery";
+
+const TOOL_VERSION = "0.1.0";
+
+function parseRootPackageJson(files: ScanFile[]): Record<string, unknown> | undefined {
+  const pkgFile = files.find((f) => f.relativePath === "package.json");
+  if (!pkgFile) return undefined;
+  try {
+    return JSON.parse(pkgFile.content) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function buildRepoProfile(
+  targetPath: string,
+  pkg: Record<string, unknown> | undefined,
+  files: ScanFile[]
+): RepoProfile {
+  const hasTs = files.some((f) => f.extension === ".ts" || f.extension === ".tsx");
+  const hasJs = files.some((f) => f.extension === ".js" || f.extension === ".jsx");
+  const languages: string[] = [];
+  if (hasTs) languages.push("typescript");
+  if (hasJs) languages.push("javascript");
+
+  let packageManager: RepoProfile["packageManager"];
+  if (files.some((f) => f.relativePath === "pnpm-lock.yaml")) packageManager = "pnpm";
+  else if (files.some((f) => f.relativePath === "yarn.lock")) packageManager = "yarn";
+  else if (files.some((f) => f.relativePath === "package-lock.json")) packageManager = "npm";
+
+  const isMonorepo = Boolean(
+    pkg?.workspaces || files.some((f) => f.relativePath === "pnpm-workspace.yaml")
+  );
+
+  return {
+    name: (pkg?.name as string) ?? basename(targetPath),
+    version: pkg?.version as string | undefined,
+    description: pkg?.description as string | undefined,
+    license: pkg?.license as string | undefined,
+    isMonorepo,
+    packageManager,
+    languages,
+  };
+}
+
+function inferAppTypes(signals: DetectedSignal[]): AppType[] {
+  const types = new Set<AppType>();
+
+  const has = (id: string) => signals.some((s) => s.id === id);
+  const hasCategory = (cat: SignalCategory) => signals.some((s) => s.category === cat);
+
+  if (has("framework-nextjs") || has("framework-react")) types.add("web-app");
+  if (
+    has("framework-express") ||
+    has("framework-fastify") ||
+    has("framework-nestjs") ||
+    has("framework-hono") ||
+    has("framework-elysia")
+  )
+    types.add("api-server");
+  if (hasCategory("local-inference") || hasCategory("ai-provider"))
+    if (signals.some((s) => s.name.toLowerCase().includes("chat"))) types.add("chatbot");
+  if (hasCategory("training")) types.add("ml-pipeline");
+
+  if (types.size === 0) types.add("unknown");
+  return [...types];
+}
+
+/** Merge signals with the same ID: keep highest confidence, combine evidence */
+function deduplicateSignals(signals: DetectedSignal[]): DetectedSignal[] {
+  const map = new Map<string, DetectedSignal>();
+
+  for (const signal of signals) {
+    const existing = map.get(signal.id);
+    if (!existing) {
+      map.set(signal.id, { ...signal, evidence: [...signal.evidence] });
+      continue;
+    }
+
+    // Merge evidence (use Set for O(1) dedup instead of O(n) .some())
+    const seen = new Set(existing.evidence.map((e) => `${e.file}:${e.line ?? ""}`));
+    for (const ev of signal.evidence) {
+      const key = `${ev.file}:${ev.line ?? ""}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        existing.evidence.push(ev);
+      }
+    }
+
+    // Upgrade confidence
+    if (CONFIDENCE_RANK[signal.confidence] > CONFIDENCE_RANK[existing.confidence]) {
+      existing.confidence = signal.confidence;
+    }
+  }
+
+  return [...map.values()];
+}
+
+function annotateEvidenceProvenance(
+  signals: DetectedSignal[],
+  files: ScanFile[]
+): DetectedSignal[] {
+  const provenanceByPath = new Map<string, FileProvenance>();
+  for (const file of files) {
+    provenanceByPath.set(file.relativePath, file.provenance);
+  }
+
+  return signals.map((signal) => ({
+    ...signal,
+    evidence: signal.evidence.map((evidence) => ({
+      ...evidence,
+      provenance: evidence.provenance ?? provenanceByPath.get(evidence.file) ?? "runtime",
+    })),
+  }));
+}
+
+function generateOpenQuestions(signals: DetectedSignal[]): OpenQuestion[] {
+  const questions: OpenQuestion[] = [];
+  const hasAI = signals.some(
+    (s) =>
+      s.category === "ai-provider" ||
+      s.category === "ai-framework" ||
+      s.category === "local-inference"
+  );
+
+  if (hasAI) {
+    questions.push({
+      id: "oq-market-placement",
+      question: "Is this AI system placed on the EU market or used within the EU?",
+      context:
+        "The EU AI Act applies to AI systems placed on or put into service in the EU market.",
+      relatedSignalIds: signals.filter((s) => s.category.startsWith("ai-")).map((s) => s.id),
+      suggestedAction: "Determine your system's geographic scope and market placement.",
+    });
+
+    questions.push({
+      id: "oq-intended-purpose",
+      question: "What is the intended purpose of this AI system?",
+      context:
+        "Risk classification under the EU AI Act depends on the system's intended purpose and deployment context, which cannot be determined from code alone.",
+      relatedSignalIds: [],
+      suggestedAction:
+        "Use the EuConform wizard to complete your risk assessment with human-provided context.",
+    });
+
+    questions.push({
+      id: "oq-provider-role",
+      question: "Are you a provider, deployer, or importer of this AI system?",
+      context:
+        "Different roles under Art. 3 carry different obligations. A scanner cannot determine your organizational role.",
+      relatedSignalIds: [],
+      suggestedAction:
+        "Clarify your role in the AI value chain to determine applicable obligations.",
+    });
+  }
+
+  const hasGpaiSignals = signals.some(
+    (s) => s.category === "ai-provider" || s.id.includes("langchain") || s.id.includes("llamaindex")
+  );
+  if (hasGpaiSignals) {
+    questions.push({
+      id: "oq-gpai-downstream",
+      question:
+        "Are you using a general-purpose AI model? Do you provide downstream access to others?",
+      context:
+        "GPAI obligations (Art. 53-55) apply to providers of general-purpose AI models. Using an API does not automatically make you a GPAI provider.",
+      relatedSignalIds: signals.filter((s) => s.category === "ai-provider").map((s) => s.id),
+      suggestedAction: "Determine whether you are a GPAI provider or deployer.",
+    });
+  }
+
+  const hasNoDisclosure = !hasImplementationSignals(signals, ["compliance-disclosure"]);
+  if (hasAI && hasNoDisclosure) {
+    questions.push({
+      id: "oq-disclosure-missing",
+      question: "Does your system inform users that they are interacting with AI?",
+      context:
+        "No AI disclosure signals were found in the codebase. Art. 50 requires transparency for AI systems interacting with natural persons.",
+      relatedSignalIds: [],
+      suggestedAction: "Add explicit AI disclosure in user-facing entry points.",
+    });
+  }
+
+  return questions;
+}
+
+function buildSignalSummary(signals: DetectedSignal[]): ScanResult["signalSummary"] {
+  const byCategory: Partial<Record<SignalCategory, number>> = {};
+  const byConfidence: Record<ConfidenceLevel, number> = {
+    high: 0,
+    medium: 0,
+    low: 0,
+  };
+
+  for (const s of signals) {
+    byCategory[s.category] = (byCategory[s.category] ?? 0) + 1;
+    byConfidence[s.confidence]++;
+  }
+
+  return { total: signals.length, byCategory, byConfidence };
+}
+
+export async function scanRepository(options: ScanOptions): Promise<ScanResult> {
+  const startTime = Date.now();
+  const scope = options.scope ?? "production";
+
+  const discovery = await discoverFiles(options);
+  const allFiles = discovery.files;
+  const rootPkg = parseRootPackageJson(allFiles);
+
+  // Run detectors on all files
+  const rawSignals: DetectedSignal[] = [];
+  for (const file of allFiles) {
+    const ctx = { file, lines: file.content.split("\n"), allFiles, rootPackageJson: rootPkg };
+    rawSignals.push(...runAllDetectors(ctx));
+  }
+
+  const signals = annotateEvidenceProvenance(deduplicateSignals(rawSignals), allFiles);
+  const openQuestions = generateOpenQuestions(signals);
+
+  return {
+    meta: {
+      scannedAt: new Date().toISOString(),
+      scanDurationMs: Date.now() - startTime,
+      toolVersion: TOOL_VERSION,
+      targetPath: options.targetPath,
+      scanScope: scope,
+      filesScanned: allFiles.length,
+      filesSkipped: discovery.skippedCount,
+    },
+    repo: buildRepoProfile(options.targetPath, rootPkg, allFiles),
+    appTypes: inferAppTypes(signals),
+    signals,
+    openQuestions,
+    signalSummary: buildSignalSummary(signals),
+  };
+}

package/src/scanner/detectors/ai-framework-detector.ts

@@ -0,0 +1,94 @@
+import type { DetectedSignal, DetectorContext } from "../../evidence/types";
+import { SOURCE_EXTENSIONS } from "./shared";
+
+// ---------------------------------------------------------------------------
+// Framework patterns
+// ---------------------------------------------------------------------------
+
+interface FrameworkPattern {
+  id: string;
+  name: string;
+  importPattern: RegExp;
+}
+
+const FRAMEWORK_IMPORTS: FrameworkPattern[] = [
+  {
+    id: "ai-framework-langchain",
+    name: "LangChain",
+    importPattern: /(?:from\s+['"]langchain[/'"]|require\s*\(\s*['"]langchain[/'"])/,
+  },
+  {
+    id: "ai-framework-langchain-core",
+    name: "LangChain Core",
+    importPattern:
+      /(?:from\s+['"]@langchain\/[^'"]+['"]|require\s*\(\s*['"]@langchain\/[^'"]+['"])/,
+  },
+  {
+    id: "ai-framework-llamaindex",
+    name: "LlamaIndex",
+    importPattern: /(?:from\s+['"]llamaindex[/'"]|require\s*\(\s*['"]llamaindex[/'"])/,
+  },
+  {
+    id: "ai-framework-transformers",
+    name: "Transformers.js",
+    importPattern:
+      /(?:from\s+['"]@xenova\/transformers['"]|require\s*\(\s*['"]@xenova\/transformers['"])/,
+  },
+  {
+    id: "ai-framework-vercel-ai",
+    name: "Vercel AI SDK",
+    // Only match Vercel AI SDK subpath imports (ai/react, ai/rsc) to avoid false positives
+    // on generic "ai" package name. Bare "ai" import matched only with package.json cross-check.
+    importPattern:
+      /(?:from\s+['"]ai\/(?:react|rsc|svelte|vue|solid|core)['"']|require\s*\(\s*['"]ai\/(?:react|rsc|svelte|vue|solid|core)['"])/,
+  },
+  {
+    id: "ai-framework-huggingface",
+    name: "HuggingFace",
+    importPattern:
+      /(?:from\s+['"]@huggingface\/[^'"]+['"]|require\s*\(\s*['"]@huggingface\/[^'"]+['"])/,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+
+export function detectAiFrameworkSignals(ctx: DetectorContext): DetectedSignal[] {
+  const { file } = ctx;
+  if (!SOURCE_EXTENSIONS.has(file.extension)) return [];
+
+  const lines = ctx.lines;
+  const signalMap = new Map<string, DetectedSignal>();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const lineNum = i + 1;
+
+    for (const framework of FRAMEWORK_IMPORTS) {
+      if (framework.importPattern.test(line)) {
+        const existing = signalMap.get(framework.id);
+        const evidence = {
+          file: file.relativePath,
+          line: lineNum,
+          snippet: line.trim().slice(0, 200),
+        };
+
+        if (existing) {
+          existing.evidence.push(evidence);
+        } else {
+          signalMap.set(framework.id, {
+            id: framework.id,
+            name: framework.name,
+            category: "ai-framework",
+            confidence: "medium",
+            evidence: [evidence],
+          });
+        }
+      }
+    }
+  }
+
+  return Array.from(signalMap.values());
+}