@drip-apex/sdk 0.1.0

package/src/targeting-diagnostics.ts

@@ -0,0 +1,560 @@
+import type {
+  ActivationGateDiagnostic,
+  AttributeRule,
+  ConditionDiagnostic,
+  PageTargetingRule,
+  SegmentCondition,
+  SegmentTargetingRule,
+  Targeting,
+  TargetingDiagnostics,
+  UrlRule,
+} from "./types";
+import {
+  evalUrlRule,
+  evaluateJsTriggerResult,
+  evaluatePageAdvancedConditionResult,
+  matchAttributeRule,
+  matchSegmentConditionValues,
+  matchUrlRules,
+  normalizeRuntimeUrlRules,
+  pageManualTriggerMatches,
+  resolveNamedConditionActual,
+  resolveNamedConditionExpected,
+} from "./targeting";
+
+function urlRuleOperator(rule: UrlRule): string {
+  return rule.matchType ?? rule.match_type ?? rule.type;
+}
+
+function diagnoseUrlRules(
+  url: string,
+  rules: UrlRule[],
+): { matched: boolean; conditions: ConditionDiagnostic[] } {
+  const conditions: ConditionDiagnostic[] = [];
+  if (!rules.length) return { matched: true, conditions };
+
+  let hasInclude = false;
+  let included = false;
+  let stopped = false;
+  for (let index = 0; index < rules.length; index += 1) {
+    const rule = rules[index];
+    if (stopped) {
+      conditions.push({
+        id: `url:${index}`,
+        label: rule.include === false ? "URL exclude rule" : "URL include rule",
+        status: "skipped",
+        reason: "url_exclude_matched",
+        operator: urlRuleOperator(rule),
+        expected: rule.pattern,
+        actual: url,
+        source: rule.pattern,
+        sourceType: "url",
+      });
+      continue;
+    }
+
+    const rawMatched = evalUrlRule(url, rule);
+    const passed = rule.include === false ? !rawMatched : rawMatched;
+    conditions.push({
+      id: `url:${index}`,
+      label: rule.include === false ? "URL exclude rule" : "URL include rule",
+      status: passed ? "passed" : "failed",
+      reason: passed ? "url_matched" : "url_mismatch",
+      operator: urlRuleOperator(rule),
+      expected: rule.pattern,
+      actual: url,
+      source: rule.pattern,
+      sourceType: "url",
+    });
+
+    if (rule.include === false) {
+      if (rawMatched) stopped = true;
+    } else {
+      hasInclude = true;
+      if (rawMatched) included = true;
+    }
+  }
+
+  return { matched: stopped ? false : included || !hasInclude, conditions };
+}
+
+type BooleanDiagnosticResult = {
+  matched: boolean;
+  reason?: string;
+  error?: unknown;
+};
+
+function pageRulePatternSummary(rule: PageTargetingRule): string {
+  const rules = [
+    ...(rule.includeRules ?? []).map((item) => ({
+      // Preserve explicit negatives: the page-audience migration emits
+      // include:false entries INSIDE includeRules (not_contains conditions),
+      // and runtime evaluation honors them — the summary must not flip them.
+      include: item.include !== false,
+      matchType: urlRuleOperator(item),
+      pattern: item.pattern,
+    })),
+    ...(rule.excludeRules ?? []).map((item) => ({
+      include: false,
+      matchType: urlRuleOperator(item),
+      pattern: item.pattern,
+    })),
+  ];
+  return JSON.stringify(rules);
+}
+
+function pageRuleSource(rule: PageTargetingRule): Pick<ConditionDiagnostic, "source" | "sourceType"> {
+  const advancedCode = rule.advancedCondition?.code?.trim();
+  if (advancedCode) return { source: advancedCode, sourceType: "js" };
+  const triggerJs = rule.trigger?.triggerJs?.trim();
+  if (triggerJs) return { source: triggerJs, sourceType: "js" };
+  return { source: pageRulePatternSummary(rule), sourceType: "page_rule" };
+}
+
+function evaluatePageRuleForDiagnostics(
+  rule: PageTargetingRule,
+  ctx: { url: string; attributes: Record<string, unknown> },
+): BooleanDiagnosticResult {
+  if (rule.disabled) return { matched: false, reason: "page_rule_disabled" };
+  if (rule.trigger?.disabled) return { matched: false, reason: "page_trigger_disabled" };
+
+  const includeRules = rule.includeRules ?? [];
+  const excludeRules = (rule.excludeRules ?? []).map((item) => ({ ...item, include: false }));
+  const urlMatched = matchUrlRules(ctx.url, [...includeRules, ...excludeRules]);
+  if (!urlMatched) return { matched: false, reason: "url_mismatch" };
+  if (!pageManualTriggerMatches(rule, ctx)) return { matched: false, reason: "manual_trigger_mismatch" };
+  const advanced = evaluatePageAdvancedConditionResult(rule, ctx);
+  if (!advanced.matched) return advanced;
+  return { matched: true };
+}
+
+function pageRuleCondition(
+  rule: PageTargetingRule,
+  index: number,
+  status: ConditionDiagnostic["status"],
+  reason: string | undefined,
+  actual?: unknown,
+): ConditionDiagnostic {
+  const include = rule.include !== false;
+  const hasPatterns = Boolean(rule.includeRules?.length || rule.excludeRules?.length);
+  const source = pageRuleSource(rule);
+  return {
+    id: `page:${rule.id || index}`,
+    label: rule.name ?? (include ? "Page include rule" : "Page exclude rule"),
+    status,
+    reason,
+    operator: include ? "include" : "exclude",
+    // For plain page rules the pattern summary already lives in source; only
+    // JS-sourced rules need it carried separately so the panel can show both
+    // the patterns and the raw JS. The label already renders the rule name.
+    expected: source.sourceType === "js" && hasPatterns ? pageRulePatternSummary(rule) : undefined,
+    actual,
+    ...source,
+  };
+}
+
+function diagnosePageRules(
+  rules: PageTargetingRule[],
+  ctx: { url: string; attributes: Record<string, unknown> },
+): { matched: boolean; conditions: ConditionDiagnostic[] } {
+  const conditions: ConditionDiagnostic[] = [];
+  if (!rules.length) return { matched: true, conditions };
+
+  let hasInclude = false;
+  let included = false;
+  let stopped = false;
+  for (let index = 0; index < rules.length; index += 1) {
+    const rule = rules[index];
+    if (stopped) {
+      conditions.push(pageRuleCondition(rule, index, "skipped", "page_rule_exclude_matched"));
+      continue;
+    }
+
+    const result = evaluatePageRuleForDiagnostics(rule, ctx);
+    const include = rule.include !== false;
+    const passed = include ? result.matched : !result.matched;
+    conditions.push(pageRuleCondition(
+      rule,
+      index,
+      passed ? "passed" : "failed",
+      passed ? undefined : include ? result.reason ?? "page_rule_mismatch" : "page_rule_exclude_matched",
+      pageRuleSource(rule).sourceType === "page_rule"
+        ? `${ctx.url} — ${passed ? "passed" : "failed"}`
+        : result.matched,
+    ));
+
+    if (rule.include === false) {
+      if (result.matched) stopped = true;
+    } else {
+      hasInclude = true;
+      if (result.matched) included = true;
+    }
+  }
+
+  return { matched: stopped ? false : included || !hasInclude, conditions };
+}
+
+function skippedPageRuleConditions(rules: PageTargetingRule[], reason: string): ConditionDiagnostic[] {
+  return rules.map((rule, index) => pageRuleCondition(rule, index, "skipped", reason));
+}
+
+function resolveSegmentConditionForDiagnostics(
+  condition: SegmentCondition,
+  ctx: { url: string; attributes: Record<string, unknown> },
+): { actual: unknown; expected: SegmentCondition["value"]; jsReason?: string } {
+  if (condition.signal === "cookie.value" || condition.signal === "url.query") {
+    return {
+      actual: resolveNamedConditionActual(condition, ctx),
+      expected: resolveNamedConditionExpected(condition),
+    };
+  }
+  if (condition.js) {
+    const result = evaluateJsTriggerResult(condition, ctx);
+    return {
+      actual: result.actual,
+      expected: resolveNamedConditionExpected(condition),
+      jsReason: result.reason,
+    };
+  }
+  return {
+    actual: resolveNamedConditionActual(condition, ctx),
+    expected: resolveNamedConditionExpected(condition),
+  };
+}
+
+function segmentConditionDiagnostic(
+  rule: SegmentTargetingRule,
+  condition: SegmentCondition,
+  index: number,
+  status: ConditionDiagnostic["status"],
+  reason: string | undefined,
+  actual?: unknown,
+  expected?: unknown,
+): ConditionDiagnostic {
+  const jsCode = condition.js?.code?.trim();
+  return {
+    id: `segment:${rule.id || "rule"}:${index}`,
+    label: rule.name ? `${rule.name}: ${condition.signal}` : `Segment condition: ${condition.signal}`,
+    status,
+    reason,
+    operator: condition.operator,
+    signal: condition.signal,
+    expected,
+    actual,
+    source: jsCode || rule.id,
+    sourceType: jsCode ? "js" : "segment",
+  };
+}
+
+function segmentRuleDiagnosticConditions(rule: SegmentTargetingRule): SegmentCondition[] {
+  const groups = Array.isArray(rule.rules?.groups)
+    ? rule.rules.groups.filter((group) => Array.isArray(group) && group.length > 0)
+    : [];
+  return groups.length ? groups.flat() : rule.rules?.conditions ?? [];
+}
+
+function skippedSegmentRuleConditions(rule: SegmentTargetingRule, reason: string): ConditionDiagnostic[] {
+  const conditions = segmentRuleDiagnosticConditions(rule);
+  return conditions.map((condition, index) =>
+    segmentConditionDiagnostic(
+      rule,
+      condition,
+      index,
+      "skipped",
+      reason,
+      undefined,
+      resolveNamedConditionExpected(condition),
+    ),
+  );
+}
+
+function diagnoseSegmentCondition(
+  rule: SegmentTargetingRule,
+  condition: SegmentCondition,
+  index: number,
+  ctx: { url: string; attributes: Record<string, unknown> },
+): { matched: boolean; diagnostic: ConditionDiagnostic } {
+  const resolved = resolveSegmentConditionForDiagnostics(condition, ctx);
+  const matched = matchSegmentConditionValues(condition, resolved.actual, resolved.expected);
+  return {
+    matched,
+    diagnostic: segmentConditionDiagnostic(
+      rule,
+      condition,
+      index,
+      matched ? "passed" : "failed",
+      matched ? undefined : resolved.jsReason ?? "segment_mismatch",
+      resolved.actual,
+      resolved.expected,
+    ),
+  };
+}
+
+function diagnoseSegmentRule(
+  rule: SegmentTargetingRule,
+  ctx: { url: string; attributes: Record<string, unknown> },
+): { matched: boolean; conditions: ConditionDiagnostic[] } {
+  const diagnostics: ConditionDiagnostic[] = [];
+  const groups = Array.isArray(rule.rules?.groups)
+    ? rule.rules.groups.filter((group) => Array.isArray(group) && group.length > 0)
+    : [];
+
+  if (groups.length) {
+    let flatIndex = 0;
+    for (let groupOffset = 0; groupOffset < groups.length; groupOffset += 1) {
+      const group = groups[groupOffset];
+      let groupMatched = false;
+      for (let groupIndex = 0; groupIndex < group.length; groupIndex += 1) {
+        const condition = group[groupIndex];
+        if (groupMatched) {
+          diagnostics.push(segmentConditionDiagnostic(
+            rule,
+            condition,
+            flatIndex,
+            "skipped",
+            "segment_group_matched",
+            undefined,
+            resolveNamedConditionExpected(condition),
+          ));
+          flatIndex += 1;
+          continue;
+        }
+        const result = diagnoseSegmentCondition(rule, condition, flatIndex, ctx);
+        diagnostics.push(result.diagnostic);
+        groupMatched = result.matched;
+        flatIndex += 1;
+      }
+      if (!groupMatched) {
+        for (const remainingGroup of groups.slice(groupOffset + 1)) {
+          for (const condition of remainingGroup) {
+            diagnostics.push(segmentConditionDiagnostic(
+              rule,
+              condition,
+              flatIndex,
+              "skipped",
+              "segment_group_failed",
+              undefined,
+              resolveNamedConditionExpected(condition),
+            ));
+            flatIndex += 1;
+          }
+        }
+        return { matched: false, conditions: diagnostics };
+      }
+    }
+    return { matched: true, conditions: diagnostics };
+  }
+
+  const conditions = rule.rules?.conditions ?? [];
+  if (!conditions.length) return { matched: true, conditions: diagnostics };
+  if (rule.rules.operator === "or") {
+    let matched = false;
+    for (let index = 0; index < conditions.length; index += 1) {
+      const condition = conditions[index];
+      if (matched) {
+        diagnostics.push(segmentConditionDiagnostic(
+          rule,
+          condition,
+          index,
+          "skipped",
+          "segment_or_matched",
+          undefined,
+          resolveNamedConditionExpected(condition),
+        ));
+        continue;
+      }
+      const result = diagnoseSegmentCondition(rule, condition, index, ctx);
+      diagnostics.push(result.diagnostic);
+      matched = result.matched;
+    }
+    return { matched, conditions: diagnostics };
+  }
+
+  let matched = true;
+  for (let index = 0; index < conditions.length; index += 1) {
+    const condition = conditions[index];
+    if (!matched) {
+      diagnostics.push(segmentConditionDiagnostic(
+        rule,
+        condition,
+        index,
+        "skipped",
+        "segment_and_failed",
+        undefined,
+        resolveNamedConditionExpected(condition),
+      ));
+      continue;
+    }
+    const result = diagnoseSegmentCondition(rule, condition, index, ctx);
+    diagnostics.push(result.diagnostic);
+    matched = result.matched;
+  }
+  return { matched, conditions: diagnostics };
+}
+
+function attributeCondition(
+  rule: AttributeRule,
+  index: number,
+  status: ConditionDiagnostic["status"],
+  reason: string | undefined,
+  actual?: unknown,
+): ConditionDiagnostic {
+  return {
+    id: `attribute:${rule.attribute}:${index}`,
+    label: `Attribute rule: ${rule.attribute}`,
+    status,
+    reason,
+    operator: rule.operator,
+    signal: rule.attribute,
+    expected: rule.value,
+    actual,
+    source: rule.attribute,
+    sourceType: "attribute",
+  };
+}
+
+function diagnoseAttributeRules(
+  rules: AttributeRule[],
+  attrs: Record<string, unknown>,
+): { matched: boolean; conditions: ConditionDiagnostic[] } {
+  const conditions: ConditionDiagnostic[] = [];
+  let matched = true;
+  for (let index = 0; index < rules.length; index += 1) {
+    const rule = rules[index];
+    const actual = attrs[rule.attribute];
+    if (!matched) {
+      conditions.push(attributeCondition(rule, index, "skipped", "attribute_mismatch", actual));
+      continue;
+    }
+    const ruleMatched = matchAttributeRule(attrs, rule);
+    conditions.push(attributeCondition(
+      rule,
+      index,
+      ruleMatched ? "passed" : "failed",
+      ruleMatched ? undefined : "attribute_mismatch",
+      actual,
+    ));
+    matched = ruleMatched;
+  }
+  return { matched, conditions };
+}
+
+function skippedAttributeConditions(rules: AttributeRule[], reason: string): ConditionDiagnostic[] {
+  return rules.map((rule, index) =>
+    attributeCondition(rule, index, "skipped", reason, undefined),
+  );
+}
+
+function diagnoseSegmentRules(
+  rules: SegmentTargetingRule[],
+  ctx: { url: string; attributes: Record<string, unknown> },
+): { matched: boolean; conditions: ConditionDiagnostic[] } {
+  const conditions: ConditionDiagnostic[] = [];
+  if (!rules.length) return { matched: true, conditions };
+
+  let hasInclude = false;
+  let included = false;
+  let stopped = false;
+  for (const rule of rules) {
+    if (stopped) {
+      conditions.push(...skippedSegmentRuleConditions(rule, "segment_exclude_matched"));
+      continue;
+    }
+    const result = diagnoseSegmentRule(rule, ctx);
+    conditions.push(...result.conditions);
+    if (rule.include === false) {
+      if (result.matched) stopped = true;
+    } else {
+      hasInclude = true;
+      if (result.matched) included = true;
+    }
+  }
+
+  return { matched: stopped ? false : included || !hasInclude, conditions };
+}
+
+function skippedSegmentConditions(rules: SegmentTargetingRule[], reason: string): ConditionDiagnostic[] {
+  return rules.flatMap((rule) => skippedSegmentRuleConditions(rule, reason));
+}
+
+export function evaluateTargetingGatesWithConditionDiagnostics(
+  targeting: Targeting | undefined,
+  ctx: { url: string; attributes: Record<string, unknown> },
+): TargetingDiagnostics {
+  const conditions: ConditionDiagnostic[] = [];
+  if (!targeting) {
+    return {
+      matched: true,
+      gates: [
+        { id: "page", label: "Page check", status: "skipped", reason: "no_page_rules" },
+        { id: "audience", label: "Audience check", status: "skipped", reason: "no_audience_rules" },
+      ],
+      conditions,
+    };
+  }
+
+  const gates: ActivationGateDiagnostic[] = [];
+  const urlRules = normalizeRuntimeUrlRules(targeting);
+  const pageRules = targeting.pageRules ?? [];
+  const pageHasRules = urlRules.length > 0 || pageRules.length > 0;
+  const url = diagnoseUrlRules(ctx.url, urlRules);
+  conditions.push(...url.conditions);
+
+  let pageRulesMatched = true;
+  if (url.matched) {
+    const page = diagnosePageRules(pageRules, ctx);
+    pageRulesMatched = page.matched;
+    conditions.push(...page.conditions);
+  } else {
+    pageRulesMatched = false;
+    conditions.push(...skippedPageRuleConditions(pageRules, "url_mismatch"));
+  }
+
+  const pageMatched = pageHasRules ? url.matched && pageRulesMatched : true;
+  gates.push({
+    id: "page",
+    label: "Page check",
+    status: pageHasRules ? (pageMatched ? "passed" : "failed") : "skipped",
+    reason: pageHasRules ? (pageMatched ? "url_matched" : "url_mismatch") : "no_page_rules",
+    detail: pageHasRules ? { url: ctx.url, rules: urlRules.length, pageRules: pageRules.length } : undefined,
+  });
+
+  const attributeRules = targeting.attributes ?? [];
+  const segmentRules = targeting.segmentRules ?? [];
+  if (!pageMatched) {
+    conditions.push(...skippedAttributeConditions(attributeRules, "page_mismatch"));
+    conditions.push(...skippedSegmentConditions(segmentRules, "page_mismatch"));
+    gates.push({
+      id: "audience",
+      label: "Audience check",
+      status: "skipped",
+      reason: "page_mismatch",
+      detail: { skipped: true },
+    });
+    return { matched: false, gates, conditions };
+  }
+
+  const attributes = diagnoseAttributeRules(attributeRules, ctx.attributes);
+  conditions.push(...attributes.conditions);
+
+  const segments = diagnoseSegmentRules(segmentRules, ctx);
+  conditions.push(...segments.conditions);
+
+  const audienceHasRules = attributeRules.length > 0 || segmentRules.length > 0;
+  const audienceMatched = attributes.matched && segments.matched;
+  gates.push({
+    id: "audience",
+    label: "Audience check",
+    status: audienceHasRules ? (audienceMatched ? "passed" : "failed") : "skipped",
+    reason: audienceHasRules
+      ? (audienceMatched ? "audience_matched" : !attributes.matched ? "attribute_mismatch" : "segment_mismatch")
+      : "no_audience_rules",
+    detail: audienceHasRules ? { attributeRules: attributeRules.length, segmentRules: segmentRules.length } : undefined,
+  });
+
+  return {
+    matched: pageMatched && audienceMatched,
+    gates,
+    conditions,
+  };
+}