feat: add data-driven rule engine for field detection and claim scanning (F030)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kahboom

PRD.json

@@ -165,7 +165,8 @@
       "id": "F030",
       "phase": 1,
       "name": "Rule Engine v1",
-      "description": "Data-driven JSON rules"
+      "description": "Data-driven JSON rules",
+      "status": "passes"
     },
     {
       "id": "F040",

src/rules/engine.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect } from "vitest";
+import type { PageSnapshot } from "../content/snapshot.js";
+import {
+  detectField,
+  evaluateFields,
+  detectClaims,
+  runRules,
+} from "./engine.js";
+
+function makeSnapshot(overrides: Partial<PageSnapshot> = {}): PageSnapshot {
+  return {
+    url: "https://example.com/product",
+    title: "Test Product",
+    timestamp: new Date().toISOString(),
+    meta: {},
+    textContent: "",
+    skuHints: [],
+    ...overrides,
+  };
+}
+
+describe("detectField", () => {
+  it("finds a field via meta tag", () => {
+    const result = detectField("product_name", "", { "og:title": "Widget X" });
+    expect(result.status).toBe("found");
+    expect(result.value).toBe("Widget X");
+    expect(result.confidence).toBe(0.9);
+  });
+
+  it("finds a field via text pattern", () => {
+    const result = detectField(
+      "country_of_origin",
+      "This product is Made in USA with care",
+      {},
+    );
+    expect(result.status).toBe("found");
+    expect(result.value).toBeDefined();
+    expect(result.confidence).toBe(0.7);
+  });
+
+  it("returns missing when field not found", () => {
+    const result = detectField("manufacturer_address", "Nothing here", {});
+    expect(result.status).toBe("missing");
+    expect(result.confidence).toBe(1.0);
+    expect(result.value).toBeUndefined();
+  });
+
+  it("prefers meta over text when both present", () => {
+    const result = detectField("brand", "Brand: TextBrand", {
+      "og:brand": "MetaBrand",
+    });
+    expect(result.value).toBe("MetaBrand");
+    expect(result.confidence).toBe(0.9);
+  });
+
+  it("detects email in contact field", () => {
+    const result = detectField(
+      "contact_email_or_url",
+      "Reach us at help@example.com for support",
+      {},
+    );
+    expect(result.status).toBe("found");
+  });
+
+  it("detects warnings", () => {
+    const result = detectField(
+      "warnings",
+      "WARNING: This product contains chemicals known to cause harm",
+      {},
+    );
+    expect(result.status).toBe("found");
+  });
+
+  it("detects materials", () => {
+    const result = detectField(
+      "materials",
+      "Materials: 100% organic cotton",
+      {},
+    );
+    expect(result.status).toBe("found");
+    expect(result.value).toContain("cotton");
+  });
+
+  it("detects care instructions", () => {
+    const result = detectField(
+      "care_instructions",
+      "Care instructions: Machine wash cold, tumble dry low",
+      {},
+    );
+    expect(result.status).toBe("found");
+  });
+
+  it("detects certifications", () => {
+    const result = detectField(
+      "certifications",
+      "Certified by OEKO-TEX Standard 100",
+      {},
+    );
+    expect(result.status).toBe("found");
+  });
+});
+
+describe("evaluateFields", () => {
+  it("returns results for all 12 defined fields", () => {
+    const snapshot = makeSnapshot();
+    const results = evaluateFields(snapshot, "general");
+    expect(results).toHaveLength(12);
+  });
+
+  it("marks fields as found when text matches", () => {
+    const snapshot = makeSnapshot({
+      textContent:
+        "Brand: Acme Corp. Materials: 100% cotton. Made in Portugal. Warning: Keep away from fire.",
+      meta: { "og:title": "Acme T-Shirt" },
+    });
+    const results = evaluateFields(snapshot, "textiles");
+    const found = results.filter((r) => r.status === "found");
+    expect(found.length).toBeGreaterThanOrEqual(4);
+
+    const productName = results.find((r) => r.key === "product_name");
+    expect(productName?.status).toBe("found");
+
+    const brand = results.find((r) => r.key === "brand");
+    expect(brand?.status).toBe("found");
+  });
+
+  it("marks all fields missing for empty snapshot", () => {
+    const snapshot = makeSnapshot();
+    const results = evaluateFields(snapshot, "general");
+    const missing = results.filter((r) => r.status === "missing");
+    expect(missing).toHaveLength(12);
+  });
+
+  it("preserves group and required from field definitions", () => {
+    const snapshot = makeSnapshot();
+    const results = evaluateFields(snapshot, "general");
+
+    const productName = results.find((r) => r.key === "product_name");
+    expect(productName?.group).toBe("Identity & Contacts");
+    expect(productName?.required).toBe(true);
+
+    const materials = results.find((r) => r.key === "materials");
+    expect(materials?.group).toBe("Composition & Origin");
+    expect(materials?.required).toBe(false);
+  });
+});
+
+describe("detectClaims", () => {
+  it("flags eco-friendly as high risk", () => {
+    const snapshot = makeSnapshot({
+      textContent: "Our eco-friendly product is made with care",
+    });
+    const claims = detectClaims(snapshot);
+    expect(claims).toHaveLength(1);
+    expect(claims[0].claim).toBe("eco-friendly");
+    expect(claims[0].riskLevel).toBe("high");
+    expect(claims[0].source).toBeTruthy();
+  });
+
+  it("flags multiple claims", () => {
+    const snapshot = makeSnapshot({
+      textContent:
+        "This sustainable, biodegradable, and organic product is vegan",
+    });
+    const claims = detectClaims(snapshot);
+    expect(claims.length).toBeGreaterThanOrEqual(4);
+    const claimNames = claims.map((c) => c.claim);
+    expect(claimNames).toContain("sustainable");
+    expect(claimNames).toContain("biodegradable");
+    expect(claimNames).toContain("organic");
+    expect(claimNames).toContain("vegan");
+  });
+
+  it("returns empty for text without risky claims", () => {
+    const snapshot = makeSnapshot({
+      textContent: "A regular product description with no special claims",
+    });
+    expect(detectClaims(snapshot)).toEqual([]);
+  });
+
+  it("is case-insensitive", () => {
+    const snapshot = makeSnapshot({
+      textContent: "ECO-FRIENDLY and SUSTAINABLE materials",
+    });
+    const claims = detectClaims(snapshot);
+    expect(claims.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("includes surrounding context as source", () => {
+    const snapshot = makeSnapshot({
+      textContent: "We are proud to offer a non-toxic cleaning solution",
+    });
+    const claims = detectClaims(snapshot);
+    const nonToxic = claims.find((c) => c.claim === "non-toxic");
+    expect(nonToxic?.source).toContain("non-toxic");
+    expect(nonToxic?.source?.length).toBeGreaterThan(10);
+  });
+});
+
+describe("runRules", () => {
+  it("returns both fields and claims", () => {
+    const snapshot = makeSnapshot({
+      textContent:
+        "Brand: TestCo. Materials: recycled plastic. This eco-friendly product is non-toxic.",
+      meta: { "og:title": "TestCo Green Widget" },
+    });
+    const result = runRules(snapshot, "general");
+
+    expect(result.fields).toHaveLength(12);
+    expect(result.claims.length).toBeGreaterThanOrEqual(2);
+
+    const brand = result.fields.find((f) => f.key === "brand");
+    expect(brand?.status).toBe("found");
+  });
+
+  it("works with empty snapshot", () => {
+    const snapshot = makeSnapshot();
+    const result = runRules(snapshot, "general");
+    expect(result.fields).toHaveLength(12);
+    expect(result.claims).toHaveLength(0);
+  });
+});

src/rules/engine.ts

@@ -0,0 +1,149 @@
+import type { PageSnapshot } from "../content/snapshot.js";
+import type {
+  ProductCategory,
+  FieldResult,
+  FieldStatus,
+  ClaimFlag,
+} from "../types/scan.js";
+import { FIELD_GROUPS } from "./field-groups.js";
+import { CLAIM_KEYWORDS } from "./claim-keywords.js";
+
+const FIELD_SEARCH_PATTERNS: Record<string, RegExp[]> = {
+  product_name: [
+    /(?:product\s*name|item\s*name)[:\s]+(.+?)(?:\n|$)/i,
+    /(?:og:title|twitter:title)/i,
+  ],
+  brand: [
+    /(?:brand|manufacturer)[:\s]+(.+?)(?:\n|$)/i,
+    /(?:og:brand|product:brand)/i,
+  ],
+  manufacturer_name: [
+    /(?:manufacturer|made\s*by|produced\s*by)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  manufacturer_address: [
+    /(?:manufacturer\s*address|company\s*address|business\s*address)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  contact_email_or_url: [
+    /(?:contact\s*us|customer\s*service|support|email)[:\s]+(.+?)(?:\n|$)/i,
+    /[\w.-]+@[\w.-]+\.\w{2,}/i,
+  ],
+  materials: [
+    /(?:materials?|composition|made\s*(?:from|of|with)|fabric|ingredients?)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  country_of_origin: [
+    /(?:country\s*of\s*origin|made\s*in|manufactured\s*in|origin|product\s*of)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  warnings: [
+    /(?:warning|caution|danger|hazard|prop\s*65|⚠)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  instructions: [
+    /(?:instructions?|directions?|how\s*to\s*use|usage)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  care_instructions: [
+    /(?:care\s*instructions?|wash|cleaning|maintenance)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+  marketing_claims: [/(?:features?|benefits?|highlights?)[:\s]+(.+?)(?:\n|$)/i],
+  certifications: [
+    /(?:certif(?:ied|ication)|certified\s*by|compliant|approved\s*by|tested\s*by)[:\s]+(.+?)(?:\n|$)/i,
+  ],
+};
+
+const META_KEY_MAP: Record<string, string[]> = {
+  product_name: ["og:title", "twitter:title", "product:name", "name"],
+  brand: ["og:brand", "product:brand", "brand"],
+  materials: ["product:material"],
+  country_of_origin: ["product:origin", "og:country-name"],
+};
+
+export function detectField(
+  key: string,
+  text: string,
+  meta: Record<string, string>,
+): { status: FieldStatus; value?: string; confidence: number } {
+  // Check meta tags first
+  const metaKeys = META_KEY_MAP[key] || [];
+  for (const mk of metaKeys) {
+    if (meta[mk]) {
+      return { status: "found", value: meta[mk], confidence: 0.9 };
+    }
+  }
+
+  // Check text content with patterns
+  const patterns = FIELD_SEARCH_PATTERNS[key] || [];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match) {
+      const value = match[1]?.trim() || match[0].trim();
+      return { status: "found", value, confidence: 0.7 };
+    }
+  }
+
+  return { status: "missing", confidence: 1.0 };
+}
+
+export function evaluateFields(
+  snapshot: PageSnapshot,
+  _category: ProductCategory,
+): FieldResult[] {
+  const results: FieldResult[] = [];
+
+  for (const group of FIELD_GROUPS) {
+    for (const field of group.fields) {
+      const detection = detectField(
+        field.key,
+        snapshot.textContent,
+        snapshot.meta,
+      );
+      results.push({
+        key: field.key,
+        group: group.group,
+        required: field.required,
+        status: detection.status,
+        value: detection.value,
+        confidence: detection.confidence,
+      });
+    }
+  }
+
+  return results;
+}
+
+export function detectClaims(snapshot: PageSnapshot): ClaimFlag[] {
+  const flags: ClaimFlag[] = [];
+  const lowerText = snapshot.textContent.toLowerCase();
+
+  for (const kw of CLAIM_KEYWORDS) {
+    const pattern = new RegExp(`\\b${escapeRegex(kw.pattern)}\\b`, "gi");
+    const match = lowerText.match(pattern);
+    if (match) {
+      // Extract surrounding context as source
+      const idx = lowerText.indexOf(kw.pattern.toLowerCase());
+      const start = Math.max(0, idx - 40);
+      const end = Math.min(lowerText.length, idx + kw.pattern.length + 40);
+      const source = snapshot.textContent.slice(start, end).trim();
+
+      flags.push({
+        claim: kw.pattern,
+        riskLevel: kw.riskLevel,
+        evidenceRequired: kw.evidenceRequired,
+        source,
+      });
+    }
+  }
+
+  return flags;
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function runRules(
+  snapshot: PageSnapshot,
+  category: ProductCategory,
+): { fields: FieldResult[]; claims: ClaimFlag[] } {
+  return {
+    fields: evaluateFields(snapshot, category),
+    claims: detectClaims(snapshot),
+  };
+}