@grafema/types 0.2.5-beta → 0.2.7

package/src/infrastructure.ts

@@ -0,0 +1,262 @@
+/**
+ * Infrastructure Types — abstract resource taxonomy and cross-layer mapping.
+ *
+ * USG (Universal System Graph) extends Grafema from code-only to multi-layer:
+ * Code → Abstract Resources → Concrete Infrastructure
+ *
+ * This module defines:
+ * - Abstract resource types (tool-agnostic: compute:service, storage:database:sql)
+ * - InfraResourceMap interface (like RoutingMap but for infra identity resolution)
+ * - Supporting types for analyzers and cross-layer linking
+ */
+
+import type { Resource } from './resources.js';
+import type { EdgeType } from './edges.js';
+
+// ============================================================
+// ABSTRACT RESOURCE TYPE TAXONOMY
+// ============================================================
+
+/**
+ * Known abstract resource types, organized by category.
+ * These are tool-agnostic — K8s Deployment, Docker service, EC2 all map
+ * to the same abstract type (compute:service).
+ *
+ * Convention: category:subcategory[:detail]
+ */
+type KnownResourceType =
+  // --- Compute ---
+  | 'compute:service'                    // Long-running process (K8s Deployment, ECS Service, Docker service)
+  | 'compute:serverless'                 // FaaS (AWS Lambda, GCP Cloud Function, Azure Function)
+  | 'compute:container'                  // Container instance (ECS, Cloud Run, Container Instances)
+  | 'compute:container:orchestration'    // K8s cluster (EKS, GKE, AKS)
+  | 'compute:job'                        // Batch/scheduled (K8s CronJob, AWS Batch, Cloud Scheduler)
+  | 'compute:vm'                         // Virtual machine (EC2, Compute Engine, Azure VM)
+  // --- Networking ---
+  | 'networking:ingress'                 // Load balancer / entry point (ALB, Cloud LB, App Gateway)
+  | 'networking:service'                 // Internal service (K8s Service, ELB, internal LB)
+  | 'networking:gateway'                 // API Gateway (API GW, Apigee, Azure API Management)
+  | 'networking:vpc'                     // Virtual network (VPC, VNet)
+  | 'networking:dns'                     // DNS (Route53, Cloud DNS, Azure DNS)
+  | 'networking:cdn'                     // CDN (CloudFront, Cloud CDN, Azure CDN)
+  | 'networking:firewall'               // Firewall / security group (SG, Cloud Armor, NSG)
+  | 'networking:vpn'                     // VPN (VPN Gateway, Cloud VPN)
+  // --- Storage ---
+  | 'storage:object'                     // Object/blob (S3, GCS, Blob Storage)
+  | 'storage:volume'                     // Block storage (EBS, Persistent Disk, Managed Disks)
+  | 'storage:file'                       // File system (EFS, Filestore, Azure Files)
+  | 'storage:cache'                      // Cache (ElastiCache, Memorystore, Azure Cache)
+  | 'storage:database:sql'              // Relational DB (RDS, Cloud SQL, Azure SQL)
+  | 'storage:database:nosql'            // NoSQL (DynamoDB, Firestore, Cosmos DB)
+  | 'storage:database:graph'            // Graph DB (Neptune, Cosmos DB Gremlin)
+  | 'storage:database:timeseries'       // Time-series (Timestream, Azure Data Explorer)
+  | 'storage:database:warehouse'        // Data warehouse (Redshift, BigQuery, Synapse)
+  // --- Messaging ---
+  | 'messaging:queue'                    // Message queue (SQS, Cloud Tasks, Service Bus)
+  | 'messaging:stream'                   // Event stream (Kinesis, Pub/Sub streaming, Event Hubs)
+  | 'messaging:topic'                    // Pub/sub topic (SNS, Pub/Sub, Service Bus Topics)
+  | 'messaging:event_bus'               // Event bus (EventBridge, Eventarc, Event Grid)
+  | 'messaging:workflow'                 // Workflow orchestration (Step Functions, Workflows, Logic Apps)
+  // --- Config ---
+  | 'config:map'                         // Configuration (K8s ConfigMap, Parameter Store, App Config)
+  | 'config:secret'                      // Secrets (K8s Secret, Secrets Manager, Key Vault)
+  // --- Security ---
+  | 'security:iam'                       // Identity management (IAM, Cloud IAM, Entra ID)
+  | 'security:certificate'              // TLS certificates (ACM, Certificate Manager)
+  | 'security:dlp'                       // Data loss prevention (Macie, DLP, Purview)
+  | 'security:threat_detection'          // Threat detection (GuardDuty, SCC, Defender)
+  // --- Observability ---
+  | 'observability:alert'               // Alert rules (CloudWatch Alarm, Prometheus, Monitor Alerts)
+  | 'observability:dashboard'           // Dashboards (Grafana, CloudWatch Dashboard)
+  | 'observability:slo'                  // SLO definitions
+  | 'observability:log_target'          // Log destination (CloudWatch Logs, Cloud Logging)
+  | 'observability:tracing'             // Distributed tracing (X-Ray, Cloud Trace, App Insights)
+  | 'observability:apm'                  // APM (CloudWatch App Insights, Cloud Profiler)
+  // --- DevOps ---
+  | 'devops:pipeline'                    // CI/CD pipeline (CodePipeline, Cloud Build, Azure Pipelines)
+  | 'devops:registry:container'         // Container registry (ECR, Artifact Registry, ACR)
+  | 'devops:iac'                         // IaC templates (CloudFormation, Deployment Manager, Bicep)
+  // --- AI ---
+  | 'ai:platform'                        // ML platform (SageMaker, Vertex AI, Azure ML)
+  | 'ai:vision'                          // Computer vision (Rekognition, Vision AI, Computer Vision)
+  | 'ai:nlp'                             // NLP (Comprehend, Natural Language AI, Text Analytics)
+  | 'ai:speech'                          // Speech (Polly/Transcribe, Speech-to-Text, Azure Speech)
+  // --- Communication ---
+  | 'communication:email'               // Email service (SES, SendGrid)
+  | 'communication:sms'                  // SMS (SNS SMS, Communication Services)
+  | 'communication:push'                 // Push notifications (SNS Mobile, FCM, Notification Hubs)
+  // --- IoT ---
+  | 'iot:platform'                       // IoT platform (IoT Core, IoT Hub)
+  | 'iot:edge';                          // Edge computing (Greengrass, IoT Edge)
+
+/**
+ * Abstract resource type — known types for autocomplete + extensible via string.
+ * Any 'category:subcategory' string is valid.
+ */
+export type AbstractResourceType = KnownResourceType | `${string}:${string}`;
+
+// ============================================================
+// INFRA RESOURCE MAP
+// ============================================================
+
+/** Well-known Resource ID for InfraResourceMap */
+export const INFRA_RESOURCE_MAP_ID = 'infra:resource:map' as const;
+
+/**
+ * Parsed infrastructure resource from a concrete analyzer.
+ * Generic representation before graph node creation.
+ */
+export interface InfraResource {
+  /** Unique resource ID (e.g., 'infra:k8s:deployment:user-api') */
+  id: string;
+  /** Concrete tool-specific type (e.g., 'infra:k8s:deployment') */
+  type: string;
+  /** Human-readable name */
+  name: string;
+  /** Source file where resource is defined */
+  file: string;
+  /** Line number in file (if available) */
+  line?: number;
+  /** Environment(s) this resource belongs to (undefined = all) */
+  env?: string | string[];
+  /** Tool that created this resource (e.g., 'kubernetes', 'terraform') */
+  tool: string;
+  /** Raw resource data */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Mapping from concrete resource to abstract type.
+ * Created by InfraAnalyzer.mapToAbstract(), stored in InfraResourceMap.
+ */
+export interface ResourceMapping {
+  /** Concrete graph node ID */
+  concreteId: string;
+  /** Concrete type (e.g., 'infra:k8s:deployment') */
+  concreteType: string;
+  /** Abstract type this maps to */
+  abstractType: AbstractResourceType;
+  /** Abstract resource ID (e.g., 'compute:service:user-api') */
+  abstractId: string;
+  /** Human-readable name */
+  name: string;
+  /** Normalized tool-agnostic metadata */
+  metadata: Record<string, unknown>;
+  /** Environment */
+  env?: string | string[];
+  /** Source file */
+  sourceFile: string;
+  /** Tool name */
+  sourceTool: string;
+}
+
+/**
+ * Cross-layer link between code and infrastructure.
+ */
+export interface CrossLayerLink {
+  type: EdgeType;
+  src: string;
+  dst: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Abstract resource — tool-agnostic representation.
+ * Created from one or more concrete resources via InfraResourceMap.
+ */
+export interface AbstractResource {
+  /** Abstract ID (e.g., 'compute:service:user-api') */
+  id: string;
+  /** Abstract type */
+  type: AbstractResourceType;
+  /** Human-readable name */
+  name: string;
+  /** Environment */
+  env?: string | string[];
+  /** Normalized metadata */
+  metadata: Record<string, unknown>;
+  /** Concrete resources that provide this abstract resource */
+  providers: ConcreteResourceRef[];
+}
+
+/**
+ * Reference to a concrete resource that provides an abstract resource.
+ */
+export interface ConcreteResourceRef {
+  /** Concrete graph node ID */
+  id: string;
+  /** Tool-specific type */
+  type: string;
+  /** Tool name */
+  tool: string;
+  /** Source file */
+  file: string;
+}
+
+/**
+ * InfraResourceMap — maps concrete infrastructure to abstract types.
+ * Like RoutingMap but for infrastructure identity resolution.
+ *
+ * Resource ID: 'infra:resource:map'
+ *
+ * Lifecycle:
+ * 1. Concrete analyzers (K8s, Terraform) call register() during ANALYSIS
+ * 2. Enrichers call find*() during ENRICHMENT to create abstract nodes + edges
+ */
+export interface InfraResourceMap extends Resource {
+  readonly id: typeof INFRA_RESOURCE_MAP_ID;
+
+  /** Register a concrete->abstract mapping. Called by analyzers. */
+  register(mapping: ResourceMapping): void;
+
+  /** Find abstract resource by name and type. Returns null if not registered. */
+  findAbstract(name: string, type: AbstractResourceType): AbstractResource | null;
+
+  /** Find all concrete resources for an abstract resource ID. */
+  findConcrete(abstractId: string): ConcreteResourceRef[];
+
+  /** Get all abstract resources of a given type. */
+  findByType(type: AbstractResourceType): AbstractResource[];
+
+  /** Filter abstract resources by environment. */
+  findByEnv(env: string): AbstractResource[];
+
+  /** Get all registered abstract resources. */
+  getAll(): AbstractResource[];
+
+  /** Get count of abstract resources (for metrics). */
+  get resourceCount(): number;
+}
+
+// ============================================================
+// CONFIGURATION SCHEMA
+// ============================================================
+
+/**
+ * Infrastructure configuration section in grafema.config.yaml.
+ *
+ * ```yaml
+ * infrastructure:
+ *   enabled: true
+ *   kubernetes:
+ *     enabled: true
+ *     paths: ['k8s/**.yaml']
+ * ```
+ */
+export interface InfrastructureConfig {
+  enabled: boolean;
+  kubernetes?: InfraToolConfig;
+  terraform?: InfraToolConfig;
+  dockerCompose?: InfraToolConfig;
+  custom?: CustomAnalyzerConfig;
+}
+
+export interface InfraToolConfig {
+  enabled: boolean;
+  paths: string[];
+  mappings?: Record<string, string>;
+}
+
+export interface CustomAnalyzerConfig {
+  analyzerPath: string;
+}

package/src/nodes.ts

@@ -77,6 +77,12 @@ export const NAMESPACED_TYPE = {
   // Network
   NET_REQUEST: 'net:request',
   NET_STDIO: 'net:stdio',
+  NET_TCP_CONNECTION: 'net:tcp-connection',
+  NET_TCP_SERVER: 'net:tcp-server',
+
+  // OS-level IPC (Unix domain sockets)
+  OS_UNIX_SOCKET: 'os:unix-socket',
+  OS_UNIX_SERVER: 'os:unix-server',
 
   // Events
   EVENT_LISTENER: 'event:listener',
@@ -146,6 +152,8 @@ export interface ModuleNodeRecord extends BaseNodeRecord {
   relativePath: string;
   contentHash: string;
   language?: string;
+  /** REG-297: true if module uses top-level await */
+  hasTopLevelAwait?: boolean;
 }
 
 // Import node
@@ -308,6 +316,40 @@ export interface PluginNodeRecord extends BaseNodeRecord {
   dependencies: string[];
 }
 
+// Unix domain socket client (OS IPC)
+export interface OsUnixSocketNodeRecord extends BaseNodeRecord {
+  type: 'os:unix-socket';
+  protocol: 'unix';
+  path: string;
+  library: string;
+}
+
+// Unix domain socket server (OS IPC listener)
+export interface OsUnixServerNodeRecord extends BaseNodeRecord {
+  type: 'os:unix-server';
+  protocol: 'unix';
+  path: string;
+  backlog?: number;
+}
+
+// TCP socket connection (network client)
+export interface NetTcpConnectionNodeRecord extends BaseNodeRecord {
+  type: 'net:tcp-connection';
+  protocol: 'tcp';
+  host?: string;
+  port: number;
+  library: string;
+}
+
+// TCP socket server (network listener)
+export interface NetTcpServerNodeRecord extends BaseNodeRecord {
+  type: 'net:tcp-server';
+  protocol: 'tcp';
+  host?: string;
+  port: number;
+  backlog?: number;
+}
+
 // Union of all node types
 export type NodeRecord =
   | FunctionNodeRecord
@@ -332,6 +374,10 @@ export type NodeRecord =
   | EventListenerNodeRecord
   | GuaranteeNodeRecord
   | PluginNodeRecord
+  | OsUnixSocketNodeRecord
+  | OsUnixServerNodeRecord
+  | NetTcpConnectionNodeRecord
+  | NetTcpServerNodeRecord
   | BaseNodeRecord; // fallback for custom types
 
 // === HELPER FUNCTIONS ===
@@ -358,5 +404,5 @@ export function isEndpointType(nodeType: string): boolean {
 export function isSideEffectType(nodeType: string): boolean {
   if (nodeType === NODE_TYPE.SIDE_EFFECT) return true;
   const ns = getNamespace(nodeType);
-  return ns === 'db' || ns === 'fs' || ns === 'net';
+  return ns === 'db' || ns === 'fs' || ns === 'net' || ns === 'os';
 }

package/src/plugins.ts

@@ -4,7 +4,11 @@
 
 import type { NodeType, NodeRecord } from './nodes.js';
 import type { EdgeType, EdgeRecord } from './edges.js';
-import type { FieldDeclaration } from './rfdb.js';
+import type { AnyBrandedNode } from './branded.js';
+import type { FieldDeclaration, CommitDelta } from './rfdb.js';
+import type { ResourceRegistry } from './resources.js';
+import type { RoutingRule } from './routing.js';
+import type { InfrastructureConfig } from './infrastructure.js';
 
 // === LOG LEVEL ===
 /**
@@ -48,6 +52,16 @@ export interface PluginMetadata {
   dependencies?: string[];
   /** Metadata fields this plugin writes. Used for RFDB server-side indexing. */
   fields?: FieldDeclaration[];
+  /**
+   * Package names this analyzer covers (for coverage tracking).
+   * Only used by package-specific analyzers.
+   * Examples: ['sqlite3'], ['@prisma/client'], ['lodash']
+   */
+  covers?: string[];
+  /** Edge types this plugin reads from the graph (RFD-2). Used for automatic dependency inference. */
+  consumes?: EdgeType[];
+  /** Edge types this plugin creates/modifies (RFD-2). Used for automatic dependency inference. */
+  produces?: EdgeType[];
 }
 
 // === ISSUE SPEC ===
@@ -121,6 +135,13 @@ export interface PluginContext {
    * - Multi root ("backend"): "backend/src/utils.js->global->FUNCTION->foo"
    */
   rootPrefix?: string;
+
+  /**
+   * Resource registry for shared data between plugins (REG-256).
+   * Plugins can read/write typed Resources through this registry.
+   * Available in all phases. Created by Orchestrator at run start.
+   */
+  resources?: ResourceRegistry;
 }
 
 // === PLUGIN RESULT ===
@@ -198,6 +219,15 @@ export interface OrchestratorConfig {
    * Note: node_modules is already excluded by default in JSModuleIndexer.
    */
   exclude?: string[];
+
+  /**
+   * Routing rules from config for cross-service URL mapping (REG-256).
+   * Passed through to plugins via PluginContext.config.
+   */
+  routing?: RoutingRule[];
+
+  /** Infrastructure analysis configuration (USG Phase 1) */
+  infrastructure?: InfrastructureConfig;
 }
 
 /**
@@ -224,20 +254,17 @@ export interface ServiceDefinition {
    * If omitted, auto-detected via resolveSourceEntrypoint() or package.json.main
    */
   entryPoint?: string;
-}
 
-// === GRAPH BACKEND INTERFACE ===
-// Flexible input types for graph operations
-export interface InputNode {
-  id: string;
-  type?: string;
-  nodeType?: string;
-  name?: string;
-  file?: string;
-  line?: number;
-  [key: string]: unknown;
+  /**
+   * Mark this service as customer-facing (REG-256).
+   * Routes in customer-facing services are expected to have frontend consumers.
+   * Unconnected routes in customer-facing services raise issue:connectivity warnings.
+   * Default: false (no issues for unconnected routes).
+   */
+  customerFacing?: boolean;
 }
 
+// === GRAPH BACKEND INTERFACE ===
 export interface InputEdge {
   src: string;
   dst: string;
@@ -247,9 +274,9 @@ export interface InputEdge {
 
 // Minimal interface for graph operations
 export interface GraphBackend {
-  addNode(node: InputNode): Promise<void> | void;
+  addNode(node: AnyBrandedNode): Promise<void> | void;
   addEdge(edge: InputEdge): Promise<void> | void;
-  addNodes(nodes: InputNode[]): Promise<void> | void;
+  addNodes(nodes: AnyBrandedNode[]): Promise<void> | void;
   addEdges(edges: InputEdge[]): Promise<void> | void;
 
   getNode(id: string): Promise<NodeRecord | null>;
@@ -284,6 +311,11 @@ export interface GraphBackend {
 
   // Schema declaration
   declareFields?(fields: FieldDeclaration[]): Promise<number>;
+
+  // Batch operations (RFD-16: CommitBatch protocol)
+  beginBatch?(): void;
+  commitBatch?(tags?: string[]): Promise<CommitDelta>;
+  abortBatch?(): void;
 }
 
 export interface NodeFilter {

package/src/resources.ts

@@ -0,0 +1,58 @@
+/**
+ * Resource Types — shared typed data containers for inter-plugin communication.
+ *
+ * Resources are created during a pipeline run and destroyed when the run ends.
+ * Multiple plugins can write to a Resource; any plugin can read from it.
+ *
+ * Unlike graph nodes, Resources are:
+ * - Not persisted to RFDB
+ * - Not queryable via Datalog
+ * - Typed (each Resource has a known interface)
+ * - Scoped to a single pipeline run
+ *
+ * Resources are for structured data that plugins share but that doesn't
+ * belong in the code graph (config-derived rules, computed indexes, etc.).
+ */
+
+/**
+ * Unique identifier for a Resource type.
+ * Convention: 'domain:name' (e.g., 'routing:map', 'auth:policies').
+ */
+export type ResourceId = string;
+
+/**
+ * Base interface for all Resources.
+ */
+export interface Resource {
+  /** Unique identifier for this Resource type */
+  readonly id: ResourceId;
+}
+
+/**
+ * Registry for managing Resources during a pipeline run.
+ * The Orchestrator creates one ResourceRegistry per run.
+ * Plugins access it via PluginContext.
+ */
+export interface ResourceRegistry {
+  /**
+   * Get or create a Resource by ID.
+   * If the Resource doesn't exist yet, creates it using the factory.
+   * If it already exists, returns the existing instance (factory ignored).
+   *
+   * @param id - Resource identifier
+   * @param factory - Factory function to create the Resource if it doesn't exist
+   * @returns The Resource instance (existing or newly created)
+   */
+  getOrCreate<T extends Resource>(id: ResourceId, factory: () => T): T;
+
+  /**
+   * Get a Resource by ID. Returns undefined if not yet created.
+   * Use this when a plugin wants to READ a Resource but should not create it.
+   */
+  get<T extends Resource>(id: ResourceId): T | undefined;
+
+  /**
+   * Check if a Resource exists.
+   */
+  has(id: ResourceId): boolean;
+}