@datasynx/agentic-ai-cartography 0.3.3 → 0.5.0

package/dist/index.d.ts

@@ -13,6 +13,9 @@ declare const NodeSchema: z.ZodObject<{
     confidence: z.ZodDefault<z.ZodNumber>;
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    domain: z.ZodOptional<z.ZodString>;
+    subDomain: z.ZodOptional<z.ZodString>;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     type: "host" | "database_server" | "database" | "table" | "web_service" | "api_endpoint" | "cache_server" | "message_broker" | "queue" | "topic" | "container" | "pod" | "k8s_cluster" | "config_file" | "saas_tool" | "unknown";
@@ -21,6 +24,9 @@ declare const NodeSchema: z.ZodObject<{
     confidence: number;
     metadata: Record<string, unknown>;
     tags: string[];
+    domain?: string | undefined;
+    subDomain?: string | undefined;
+    qualityScore?: number | undefined;
 }, {
     id: string;
     type: "host" | "database_server" | "database" | "table" | "web_service" | "api_endpoint" | "cache_server" | "message_broker" | "queue" | "topic" | "container" | "pod" | "k8s_cluster" | "config_file" | "saas_tool" | "unknown";
@@ -29,6 +35,9 @@ declare const NodeSchema: z.ZodObject<{
     confidence?: number | undefined;
     metadata?: Record<string, unknown> | undefined;
     tags?: string[] | undefined;
+    domain?: string | undefined;
+    subDomain?: string | undefined;
+    qualityScore?: number | undefined;
 }>;
 type DiscoveryNode = z.infer<typeof NodeSchema>;
 declare const EdgeSchema: z.ZodObject<{
@@ -127,6 +136,115 @@ declare const SOPSchema: z.ZodObject<{
     frequency: string;
 }>;
 type SOP = z.infer<typeof SOPSchema>;
+declare const DataAssetSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    domain: z.ZodString;
+    subDomain: z.ZodOptional<z.ZodString>;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    position: z.ZodObject<{
+        q: z.ZodNumber;
+        r: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        q: number;
+        r: number;
+    }, {
+        q: number;
+        r: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    metadata: Record<string, unknown>;
+    domain: string;
+    position: {
+        q: number;
+        r: number;
+    };
+    subDomain?: string | undefined;
+    qualityScore?: number | undefined;
+}, {
+    id: string;
+    name: string;
+    domain: string;
+    position: {
+        q: number;
+        r: number;
+    };
+    metadata?: Record<string, unknown> | undefined;
+    subDomain?: string | undefined;
+    qualityScore?: number | undefined;
+}>;
+type DataAsset = z.infer<typeof DataAssetSchema>;
+declare const ClusterSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    domain: z.ZodString;
+    color: z.ZodString;
+    assetIds: z.ZodArray<z.ZodString, "many">;
+    centroid: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    domain: string;
+    label: string;
+    color: string;
+    assetIds: string[];
+    centroid: {
+        x: number;
+        y: number;
+    };
+}, {
+    id: string;
+    domain: string;
+    label: string;
+    color: string;
+    assetIds: string[];
+    centroid: {
+        x: number;
+        y: number;
+    };
+}>;
+type Cluster = z.infer<typeof ClusterSchema>;
+declare const ConnectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    sourceAssetId: z.ZodString;
+    targetAssetId: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    sourceAssetId: string;
+    targetAssetId: string;
+    type?: string | undefined;
+}, {
+    id: string;
+    sourceAssetId: string;
+    targetAssetId: string;
+    type?: string | undefined;
+}>;
+type Connection = z.infer<typeof ConnectionSchema>;
+interface CartographyMapData {
+    assets: DataAsset[];
+    clusters: Cluster[];
+    connections: Connection[];
+    meta: {
+        exportedAt: string;
+        theme: 'light' | 'dark';
+    };
+}
+/** Navy → medium blue → periwinkle → teal/cyan palette */
+declare const DOMAIN_COLORS: Record<string, string>;
+/** Ordered palette for dynamic domain assignment */
+declare const DOMAIN_PALETTE: readonly ["#1a2e5a", "#1e3a8a", "#1d4ed8", "#2563eb", "#3b82f6", "#6366f1", "#818cf8", "#7c9fc3", "#0e7490", "#0891b2", "#06b6d4", "#22d3ee", "#0d9488", "#14b8a6", "#2dd4bf", "#5eead4"];
 interface NodeRow extends DiscoveryNode {
     sessionId: string;
     discoveredAt: string;
@@ -158,6 +276,10 @@ interface CartographyConfig {
 }
 declare function defaultConfig(overrides?: Partial<CartographyConfig>): CartographyConfig;
 
+interface ConnectionRow extends Connection {
+    sessionId: string;
+    createdAt: string;
+}
 interface EventRow {
     id: string;
     sessionId: string;
@@ -207,6 +329,7 @@ declare class CartographyDB {
     private mapSession;
     upsertNode(sessionId: string, node: DiscoveryNode, depth?: number): void;
     getNodes(sessionId: string): NodeRow[];
+    private mapNode;
     deleteNode(sessionId: string, nodeId: string): void;
     insertEdge(sessionId: string, edge: DiscoveryEdge): void;
     getEdges(sessionId: string): EdgeRow[];
@@ -233,6 +356,9 @@ declare class CartographyDB {
         workflowId: string;
         generatedAt: string;
     }>;
+    upsertConnection(sessionId: string, conn: Omit<Connection, 'id'>): string;
+    getConnections(sessionId: string): ConnectionRow[];
+    deleteConnection(sessionId: string, connectionId: string): void;
     setApproval(pattern: string, action: 'save' | 'ignore' | 'auto'): void;
     getApproval(pattern: string): string | undefined;
     getStats(sessionId: string): {
@@ -285,8 +411,104 @@ declare function exportSOPDashboard(sops: Array<SOP & {
     workflowId: string;
     generatedAt?: string;
 }>): string;
+declare function exportCartographyMap(nodes: NodeRow[], edges: EdgeRow[], options?: {
+    theme?: 'light' | 'dark';
+}): string;
 declare function exportAll(db: CartographyDB, sessionId: string, outputDir: string, formats?: string[]): void;
 
+/**
+ * Hex Grid Engine — flat-top axial coordinate system.
+ * Reference: https://www.redblobgames.com/grids/hexagons/
+ */
+interface AxialCoord {
+    q: number;
+    r: number;
+}
+interface PixelCoord {
+    x: number;
+    y: number;
+}
+/**
+ * Convert axial hex coordinates to pixel coordinates (flat-top).
+ */
+declare function hexToPixel(q: number, r: number, size: number): PixelCoord;
+/**
+ * Convert pixel coordinates to nearest axial hex (flat-top).
+ */
+declare function pixelToHex(x: number, y: number, size: number): AxialCoord;
+/**
+ * Return the 6 pixel corners of a flat-top hexagon.
+ */
+declare function hexCorners(cx: number, cy: number, size: number): PixelCoord[];
+declare function hexNeighbors(q: number, r: number): AxialCoord[];
+declare function hexDistance(a: AxialCoord, b: AxialCoord): number;
+/**
+ * Generate all hex coordinates on a given ring around center.
+ */
+declare function hexRing(center: AxialCoord, radius: number): AxialCoord[];
+/**
+ * Generate a spiral sequence of hex positions (ring 0, ring 1, ring 2, …).
+ * Returns exactly `count` positions.
+ */
+declare function hexSpiral(center: AxialCoord, count: number): AxialCoord[];
+
+/**
+ * Domain-based clustering and hex grid positioning.
+ * Groups data assets by domain, assigns organic hex positions via spiral fill,
+ * computes cluster centroids and assigns colors from the domain palette.
+ */
+
+/**
+ * Assign colors to all domains in the dataset.
+ */
+declare function assignColors(domains: string[]): Record<string, string>;
+/**
+ * Generate a slightly lighter shade of a hex color string.
+ */
+declare function shadeVariant(hex: string, amount: number): string;
+/**
+ * Group assets by their `domain` field.
+ */
+declare function groupByDomain(assets: DataAsset[]): Map<string, DataAsset[]>;
+/**
+ * Arrange domain clusters on the hex grid without overlap.
+ * Places largest clusters first at the origin, subsequent clusters spiral outward.
+ */
+declare function layoutClusters(groups: Map<string, DataAsset[]>, hexSize: number): {
+    clusters: Cluster[];
+    assets: DataAsset[];
+};
+declare function computeCentroid(positions: AxialCoord[], hexSize: number): {
+    x: number;
+    y: number;
+};
+declare function computeClusterBounds(assets: DataAsset[], hexSize: number): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+
+/**
+ * Node-zu-Asset Mapping.
+ * Converts existing DiscoveryNode/Edge data into the CartographyMap data model.
+ */
+
+/**
+ * Convert NodeRow[] to DataAsset[].
+ */
+declare function nodesToAssets(nodes: NodeRow[]): DataAsset[];
+/**
+ * Convert EdgeRow[] to Connection[].
+ */
+declare function edgesToConnections(edges: EdgeRow[]): Connection[];
+/**
+ * Build a complete CartographyMapData from raw nodes and edges.
+ */
+declare function buildMapData(nodes: NodeRow[], edges: EdgeRow[], options?: {
+    theme?: 'light' | 'dark';
+}): CartographyMapData;
+
 declare function checkPrerequisites(): void;
 
-export { type CartographyConfig, CartographyDB, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryNode, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, NODE_TYPES, type NodeRow, NodeSchema, type NodeType, type SOP, SOPSchema, type SOPStep, SOPStepSchema, type SessionRow, checkPrerequisites, createCartographyTools, CartographyDB as default, defaultConfig, exportAll, exportBackstageYAML, exportHTML, exportJSON, exportSOPDashboard, exportSOPMarkdown, generateDependencyMermaid, generateTopologyMermaid, generateWorkflowMermaid, runDiscovery, safetyHook, stripSensitive };
+export { type CartographyConfig, CartographyDB, type CartographyMapData, type Cluster, ClusterSchema, type Connection, ConnectionSchema, DOMAIN_COLORS, DOMAIN_PALETTE, type DataAsset, DataAssetSchema, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryNode, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, NODE_TYPES, type NodeRow, NodeSchema, type NodeType, type SOP, SOPSchema, type SOPStep, SOPStepSchema, type SessionRow, assignColors, buildMapData, checkPrerequisites, computeCentroid, computeClusterBounds, createCartographyTools, CartographyDB as default, defaultConfig, edgesToConnections, exportAll, exportBackstageYAML, exportCartographyMap, exportHTML, exportJSON, exportSOPDashboard, exportSOPMarkdown, generateDependencyMermaid, generateTopologyMermaid, generateWorkflowMermaid, groupByDomain, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, layoutClusters, nodesToAssets, pixelToHex, runDiscovery, safetyHook, shadeVariant, stripSensitive };