@littlebearapps/platform-admin-sdk 1.4.2 → 1.5.0

package/templates/standard/workers/lib/mapper/attribution-check.ts

@@ -0,0 +1,339 @@
+/**
+ * Attribution Check Module for Platform Mapper
+ *
+ * Checks whether discovered Cloudflare resources are properly attributed to projects.
+ * Runs every 15 minutes as part of platform-mapper's scheduled handler.
+ *
+ * @module workers/lib/mapper/attribution-check
+ */
+
+import type { Logger } from '@littlebearapps/platform-consumer-sdk';
+
+/**
+ * Environment bindings required for attribution checking.
+ * Uses generic types to work with both raw Env and TrackedEnv.
+ */
+export interface AttributionEnv {
+  PLATFORM_DB: {
+    prepare: (query: string) => {
+      bind: (...args: unknown[]) => {
+        run: () => Promise<unknown>;
+        first: <T>() => Promise<T | null>;
+      };
+      first: <T>() => Promise<T | null>;
+    };
+  };
+  PLATFORM_CACHE: {
+    get: (key: string) => Promise<string | null>;
+    put: (key: string, value: string, options?: { expirationTtl?: number }) => Promise<void>;
+  };
+  SERVICE_REGISTRY: {
+    get: (key: string) => Promise<string | null>;
+  };
+  SLACK_WEBHOOK_URL?: string;
+}
+
+/**
+ * Discovered resource
+ */
+export interface DiscoveredResource {
+  resourceType: string; // worker, d1, kv, r2, queue, do
+  resourceId: string;
+  resourceName: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Attribution result for a single resource
+ */
+export interface ResourceAttribution {
+  resource: DiscoveredResource;
+  project: string | null;
+  matchedPattern: string | null;
+  confidence: 'high' | 'medium' | 'low' | 'none';
+}
+
+/**
+ * Full attribution report
+ */
+export interface AttributionReport {
+  discoveryTime: string;
+  attributed: ResourceAttribution[];
+  unattributed: ResourceAttribution[];
+  totalResources: number;
+  attributedCount: number;
+  unattributedCount: number;
+}
+
+/**
+ * Project patterns for attribution.
+ * Maps resource name patterns to projects.
+ *
+ * TODO: Add your project patterns here. Each key is a project name,
+ * and the value is an array of RegExp patterns that match resource names
+ * belonging to that project.
+ *
+ * Example:
+ *   'my-app': [/^my-app-/i, /my-app-db/i, /my-app-kv/i],
+ *   'api': [/^api-/i, /api-worker/i],
+ */
+const PROJECT_PATTERNS: Record<string, RegExp[]> = {
+  // Add your project patterns here:
+  // 'project-name': [/^project-name-/i, /project-name-db/i],
+};
+
+/**
+ * Resources to exclude from attribution (system/shared resources).
+ *
+ * TODO: Adjust these patterns to match resources you want to skip.
+ */
+const EXCLUDED_PATTERNS: RegExp[] = [
+  /^_/i, // Internal resources
+  /test/i, // Test resources
+  /dev-/i, // Dev resources
+  /staging/i, // Staging resources
+];
+
+/**
+ * Check attribution of discovered resources
+ */
+export function checkAttribution(resources: DiscoveredResource[]): AttributionReport {
+  const report: AttributionReport = {
+    discoveryTime: new Date().toISOString(),
+    attributed: [],
+    unattributed: [],
+    totalResources: 0,
+    attributedCount: 0,
+    unattributedCount: 0,
+  };
+
+  for (const resource of resources) {
+    // Skip excluded resources
+    if (EXCLUDED_PATTERNS.some((pattern) => pattern.test(resource.resourceName))) {
+      continue;
+    }
+
+    report.totalResources++;
+    const attribution = attributeResource(resource);
+
+    if (attribution.project) {
+      report.attributed.push(attribution);
+      report.attributedCount++;
+    } else {
+      report.unattributed.push(attribution);
+      report.unattributedCount++;
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Attribute a single resource to a project
+ */
+function attributeResource(resource: DiscoveredResource): ResourceAttribution {
+  for (const [project, patterns] of Object.entries(PROJECT_PATTERNS)) {
+    for (const pattern of patterns) {
+      if (pattern.test(resource.resourceName)) {
+        return {
+          resource,
+          project,
+          matchedPattern: pattern.source,
+          confidence: 'high',
+        };
+      }
+    }
+  }
+
+  // Try to infer from resource name structure
+  const suggestedProject = suggestProject(resource.resourceName);
+  if (suggestedProject) {
+    return {
+      resource,
+      project: suggestedProject,
+      matchedPattern: 'name_inference',
+      confidence: 'low',
+    };
+  }
+
+  return {
+    resource,
+    project: null,
+    matchedPattern: null,
+    confidence: 'none',
+  };
+}
+
+/**
+ * Suggest a project from resource name using heuristics.
+ *
+ * TODO: Update this function to match your project naming conventions.
+ * The heuristics below look for common substrings in resource names.
+ */
+function suggestProject(resourceName: string): string | null {
+  const lowerName = resourceName.toLowerCase();
+
+  // Check against PROJECT_PATTERNS keys as substring match
+  for (const project of Object.keys(PROJECT_PATTERNS)) {
+    if (lowerName.includes(project.toLowerCase())) {
+      return project;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Store attribution report in D1
+ */
+export async function storeAttributionReport(
+  env: AttributionEnv,
+  report: AttributionReport,
+  log: Logger
+): Promise<void> {
+  try {
+    const id = crypto.randomUUID();
+
+    await env.PLATFORM_DB.prepare(
+      `
+      INSERT INTO attribution_reports (id, discovery_time, total_resources, attributed_count, unattributed_count, report_json)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `
+    )
+      .bind(
+        id,
+        report.discoveryTime,
+        report.totalResources,
+        report.attributedCount,
+        report.unattributedCount,
+        JSON.stringify(report)
+      )
+      .run();
+
+    log.debug('Stored attribution report', {
+      id,
+      total: report.totalResources,
+      unattributed: report.unattributedCount,
+    });
+  } catch (error) {
+    log.error('Failed to store attribution report', error);
+  }
+}
+
+/**
+ * Alert on unattributed resources via Slack
+ */
+export async function alertUnattributedResources(
+  env: AttributionEnv,
+  report: AttributionReport,
+  log: Logger
+): Promise<void> {
+  // Only alert if there are unattributed resources
+  if (report.unattributedCount === 0) {
+    return;
+  }
+
+  // Check rate limit (1 alert per 4 hours)
+  const alertKey = 'attribution:alert';
+  const alreadySent = await env.PLATFORM_CACHE.get(alertKey);
+
+  if (alreadySent) {
+    log.debug('Attribution alert rate limited');
+    return;
+  }
+
+  if (!env.SLACK_WEBHOOK_URL) {
+    log.debug('No SLACK_WEBHOOK_URL configured, skipping attribution alert');
+    return;
+  }
+
+  // Build summary of unattributed resources
+  const summary = report.unattributed
+    .slice(0, 10)
+    .map((a) => `${a.resource.resourceType}: ${a.resource.resourceName}`)
+    .join('\n');
+
+  const message = {
+    text: `[WARNING] ${report.unattributedCount} Cloudflare resources not attributed to projects`,
+    blocks: [
+      {
+        type: 'header',
+        text: {
+          type: 'plain_text',
+          text: 'Unattributed Resources Detected',
+        },
+      },
+      {
+        type: 'section',
+        fields: [
+          { type: 'mrkdwn', text: `*Total Resources:*\n${report.totalResources}` },
+          { type: 'mrkdwn', text: `*Attributed:*\n${report.attributedCount}` },
+          { type: 'mrkdwn', text: `*Unattributed:*\n${report.unattributedCount}` },
+          { type: 'mrkdwn', text: `*Discovery Time:*\n${report.discoveryTime}` },
+        ],
+      },
+      {
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: `*Unattributed Resources (first 10):*\n\`\`\`${summary}\`\`\``,
+        },
+      },
+      {
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: `*Action Required:*\nUpdate PROJECT_PATTERNS in \`workers/lib/mapper/attribution-check.ts\` to include patterns for these resources.`,
+        },
+      },
+    ],
+  };
+
+  try {
+    const response = await fetch(env.SLACK_WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(message),
+    });
+
+    if (response.ok) {
+      // Set rate limit (4 hours)
+      await env.PLATFORM_CACHE.put(alertKey, new Date().toISOString(), {
+        expirationTtl: 14400,
+      });
+      log.info('Sent attribution alert', { unattributed: report.unattributedCount });
+    } else {
+      const text = await response.text();
+      log.error('Failed to send attribution alert', undefined, { status: response.status, error: text });
+    }
+  } catch (error) {
+    log.error('Error sending attribution alert', error);
+  }
+}
+
+/**
+ * Get latest attribution report from D1
+ */
+export async function getLatestAttributionReport(
+  env: AttributionEnv,
+  log: Logger
+): Promise<AttributionReport | null> {
+  try {
+    const result = await env.PLATFORM_DB.prepare(
+      `
+      SELECT report_json
+      FROM attribution_reports
+      ORDER BY discovery_time DESC
+      LIMIT 1
+    `
+    ).first<{ report_json: string }>();
+
+    if (result?.report_json) {
+      return JSON.parse(result.report_json) as AttributionReport;
+    }
+    return null;
+  } catch (error) {
+    log.error('Failed to get latest attribution report', error);
+    return null;
+  }
+}

package/templates/standard/workers/lib/mapper/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Mapper Module Exports
+ *
+ * Barrel export for all mapper modules.
+ */
+
+export * from './attribution-check';