@caddis/cli 0.4.13 → 0.4.15

package/bundles/antigravity-plugin/skills/confluence-hla/scripts/discover_db_lineage.py

@@ -0,0 +1,970 @@
+#!/usr/bin/env python3
+"""Database Lineage Discovery Tool for Fleet Applications.
+
+Discovers, verifies, and maps the end-to-end database lineage across:
+  Host[Server] -> Database[DB] -> Schema.Table[Table/View]
+
+Active Discovery Protocol:
+1. Inspects configuration files (config/.env*, .env, settings.py).
+   - Priority 1: User credentials found in config (default user 'LinkedUser').
+   - Priority 2: Windows Integrated Authentication (Trusted_Connection=yes).
+2. Queries live database catalogs:
+   - sys.servers (Linked Servers)
+   - INFORMATION_SCHEMA.TABLES / sys.tables (Active tables and schemas)
+   - INFORMATION_SCHEMA.ROUTINES / sys.procedures (Active Stored Procedures)
+   - INFORMATION_SCHEMA.VIEWS (Views and joined dependencies)
+3. Analyzes application code (ORM models, background workers, ETL scripts).
+4. Emits a structured 7-stage lineage table and horizontal stacked diagrams
+   (Mermaid for Markdown, PlantUML for Confluence XHTML).
+
+Usage:
+    python scripts/discover_db_lineage.py [--target-dir <path>] [--output <file>] [--format md|html|json]
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def find_env_files(target_dir: Path) -> List[Path]:
+    """Locate all .env files in config/ and root of the target directory."""
+    candidates = []
+    config_dir = target_dir / "config"
+    if config_dir.is_dir():
+        for p in config_dir.glob(".env*"):
+            if p.is_file():
+                candidates.append(p)
+    for p in target_dir.glob(".env*"):
+        if p.is_file() and p not in candidates:
+            candidates.append(p)
+    return candidates
+
+
+def parse_env_file(path: Path) -> Dict[str, str]:
+    """Extract key-value pairs from a .env file, supporting UTF-8, UTF-16, and CP1252."""
+    kv = {}
+    try:
+        raw = path.read_bytes()
+        text = None
+        for enc in ["utf-8-sig", "utf-8", "utf-16", "utf-16-le", "cp1252"]:
+            try:
+                decoded = raw.decode(enc)
+                if "\x00" not in decoded:
+                    text = decoded
+                    break
+            except Exception:
+                continue
+        if text is None:
+            text = raw.decode("utf-8", errors="replace").replace("\x00", "")
+
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" in line:
+                k, v = line.split("=", 1)
+                kv[k.strip()] = v.strip().strip('"').strip("'")
+    except Exception as e:
+        print(f"Warning: could not read {path}: {e}", file=sys.stderr)
+    return kv
+
+
+def extract_database_targets_from_env(cfg: Dict[str, str], target_name: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Discover all database targets declared in an environment config."""
+    targets: List[Dict[str, Any]] = []
+
+    # 1. Standard DB_HOST & DB_NAME
+    if cfg.get("DB_HOST") and cfg.get("DB_NAME"):
+        targets.append({
+            "host": cfg["DB_HOST"],
+            "db": cfg["DB_NAME"],
+            "user": cfg.get("DB_USER", "LinkedUser"),
+            "password": cfg.get("DB_PASSWORD"),
+            "driver": cfg.get("DB_DRIVER", "ODBC Driver 18 for SQL Server"),
+            "trust_cert": cfg.get("DB_TRUST_SERVER_CERTIFICATE", "yes"),
+            "port": cfg.get("DB_PORT"),
+            "label": "Primary Database",
+        })
+
+    # 2. DERBY_SERVER & DERBY_DATABASE
+    if cfg.get("DERBY_SERVER") and cfg.get("DERBY_DATABASE"):
+        targets.append({
+            "host": cfg["DERBY_SERVER"],
+            "db": cfg["DERBY_DATABASE"],
+            "user": cfg.get("DERBY_USER", "LinkedUser"),
+            "password": cfg.get("DERBY_PASSWORD"),
+            "driver": cfg.get("DERBY_DRIVER", "ODBC Driver 18 for SQL Server"),
+            "trust_cert": cfg.get("DERBY_TRUST_SERVER_CERTIFICATE", "yes"),
+            "port": cfg.get("DERBY_PORT"),
+            "label": "Derby / Telemetry Database",
+        })
+
+    # 3. Dynamic Prefix discovery: e.g. EXTERNAL_DB__SERVER, SERVSIGHT_DB__SERVER, ITDEV_DB__SERVER, CERILLION_DB__SERVER
+    server_keys = [k for k in cfg.keys() if k.endswith("_SERVER") or k.endswith("__SERVER")]
+    for s_key in server_keys:
+        if s_key.endswith("__SERVER"):
+            prefix = s_key[:-8]
+            db_key = f"{prefix}__DATABASE"
+            user_key = f"{prefix}__USERNAME"
+            pwd_key = f"{prefix}__PASSWORD"
+            driver_key = f"{prefix}__DRIVER"
+        else:
+            prefix = s_key[:-7]
+            db_key = f"{prefix}_DATABASE"
+            user_key = f"{prefix}_USER"
+            pwd_key = f"{prefix}_PASSWORD"
+            driver_key = f"{prefix}_DRIVER"
+
+        host = cfg.get(s_key)
+        db = cfg.get(db_key)
+        if host and db:
+            if target_name and target_name.lower() in ("customer-insights", "customer-service"):
+                if db.lower() == "customer_feedback_jit" or prefix.upper() in ("EXTERNAL_DB", "EXTERNAL"):
+                    continue
+            targets.append({
+                "host": host,
+                "db": db,
+                "user": cfg.get(user_key, "LinkedUser"),
+                "password": cfg.get(pwd_key),
+                "driver": cfg.get(driver_key, "ODBC Driver 18 for SQL Server"),
+                "trust_cert": "yes",
+                "port": None,
+                "label": prefix.replace("__", " ").replace("_", " ").title(),
+            })
+
+    return targets
+
+
+def inspect_database_metadata(
+    host: str,
+    db: str,
+    user: Optional[str] = None,
+    password: Optional[str] = None,
+    driver: str = "ODBC Driver 18 for SQL Server",
+    trust_cert: str = "yes",
+    port: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Query live database metadata using pyodbc with LinkedUser or Windows Auth fallback."""
+    results: Dict[str, Any] = {
+        "connected": False,
+        "auth_method": None,
+        "tables": [],
+        "procedures": [],
+        "linked_servers": [],
+        "views": [],
+        "error": None,
+    }
+
+    try:
+        import pyodbc
+    except ImportError:
+        results["error"] = "pyodbc not installed in current Python environment"
+        return results
+
+    if not driver.startswith("{"):
+        driver_str = f"{{{driver}}}"
+    else:
+        driver_str = driver
+
+    server_spec = f"{host},{port}" if port and port != "1433" else host
+
+    # Connection attempts: 1. User/password (e.g. LinkedUser), 2. Windows Auth
+    conn_attempts = []
+    if user and password:
+        conn_attempts.append((
+            f"DRIVER={driver_str};SERVER={server_spec};DATABASE={db};UID={user};PWD={password};TrustServerCertificate={trust_cert};LoginTimeout=4;",
+            f"SQL User ({user})",
+        ))
+    
+    conn_attempts.append((
+        f"DRIVER={driver_str};SERVER={server_spec};DATABASE={db};Trusted_Connection=yes;TrustServerCertificate={trust_cert};LoginTimeout=4;",
+        "Windows Integrated Authentication",
+    ))
+
+    conn = None
+    auth_used = None
+    for conn_str, auth_label in conn_attempts:
+        try:
+            conn = pyodbc.connect(conn_str)
+            auth_used = auth_label
+            break
+        except Exception as exc:
+            results["error"] = str(exc)
+
+    if not conn:
+        return results
+
+    results["connected"] = True
+    results["auth_method"] = auth_used
+
+    try:
+        cursor = conn.cursor()
+
+        # 1. Query Linked Servers
+        try:
+            cursor.execute("SELECT srvname, srvproduct, providername, datasource FROM sys.sysservers")
+            results["linked_servers"] = [
+                {"name": r[0], "product": r[1], "provider": r[2], "datasource": r[3]}
+                for r in cursor.fetchall()
+            ]
+        except Exception:
+            try:
+                cursor.execute("SELECT name, product, provider, data_source FROM sys.servers")
+                results["linked_servers"] = [
+                    {"name": r[0], "product": r[1], "provider": r[2], "datasource": r[3]}
+                    for r in cursor.fetchall()
+                ]
+            except Exception:
+                pass
+
+        # 2. Query Tables
+        cursor.execute(
+            "SELECT TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE FROM INFORMATION_SCHEMA.TABLES "
+            "WHERE TABLE_SCHEMA NOT IN ('sys', 'INFORMATION_SCHEMA') ORDER BY TABLE_NAME"
+        )
+        for row in cursor.fetchall():
+            schema, tname, ttype = row[0], row[1], row[2]
+            # Exclude backup and partition tables (_BU, _P1, _P2, etc.)
+            if re.search(r'(_BU|_P\d+)$', tname, re.IGNORECASE):
+                continue
+            results["tables"].append({
+                "schema": schema,
+                "table": tname,
+                "type": ttype,
+            })
+
+        # 3. Query Stored Procedures
+        cursor.execute(
+            "SELECT ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE FROM INFORMATION_SCHEMA.ROUTINES "
+            "WHERE ROUTINE_SCHEMA NOT IN ('sys', 'INFORMATION_SCHEMA') ORDER BY ROUTINE_NAME"
+        )
+        for row in cursor.fetchall():
+            results["procedures"].append({
+                "schema": row[0],
+                "name": row[1],
+                "type": row[2],
+            })
+
+        # 4. Query Views
+        cursor.execute(
+            "SELECT TABLE_SCHEMA, TABLE_NAME FROM INFORMATION_SCHEMA.VIEWS "
+            "WHERE TABLE_SCHEMA NOT IN ('sys', 'INFORMATION_SCHEMA') ORDER BY TABLE_NAME"
+        )
+        for row in cursor.fetchall():
+            results["views"].append({
+                "schema": row[0],
+                "name": row[1],
+            })
+
+        # 5. Query SQL Server Agent Jobs (when permissions permit)
+        results["jobs"] = []
+        try:
+            cursor.execute(
+                "SELECT j.name, j.enabled, j.description, s.step_id, s.step_name, s.subsystem, s.command "
+                "FROM msdb.dbo.sysjobs j "
+                "JOIN msdb.dbo.sysjobsteps s ON j.job_id = s.job_id "
+                "ORDER BY j.name, s.step_id"
+            )
+            for row in cursor.fetchall():
+                results["jobs"].append({
+                    "job_name": row[0],
+                    "enabled": bool(row[1]),
+                    "description": row[2],
+                    "step_id": row[3],
+                    "step_name": row[4],
+                    "subsystem": row[5],
+                    "command": row[6],
+                })
+        except Exception:
+            pass
+
+    except Exception as e:
+        results["error"] = f"Error during metadata query: {e}"
+    finally:
+        conn.close()
+
+    return results
+
+
+def scan_codebase_lineage(target_dir: Path) -> Dict[str, Any]:
+    """Scan python models, workers, query YAMLs, and SQL strings in target repository."""
+    findings: Dict[str, Any] = {
+        "models": [],
+        "sql_tables_referenced": set(),
+        "scripts": [],
+    }
+
+    reserved_sql = {
+        "SELECT", "SET", "WHERE", "VALUES", "AS", "ON", "INNER", "LEFT", "RIGHT",
+        "FULL", "OUTER", "CROSS", "GROUP", "ORDER", "HAVING", "LIMIT", "TOP",
+        "CASE", "WHEN", "THEN", "ELSE", "END", "AND", "OR", "NOT", "DISTINCT", "EXISTS"
+    }
+
+    # Find models and SQL references across Python, YAML, and SQL files
+    scan_patterns = ["*.py", "*.yaml", "*.yml", "*.sql"]
+    for pattern in scan_patterns:
+        for fpath in target_dir.rglob(pattern):
+            if any(part in fpath.parts for part in [".venv", "venv", ".git", "node_modules", "tests"]):
+                continue
+
+            try:
+                content = fpath.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                continue
+
+            # Look for SQLAlchemy tablename in python files
+            if fpath.suffix == ".py":
+                table_matches = re.findall(r'__tablename__\s*=\s*["\']([^"\']+)["\']', content)
+                for tm in table_matches:
+                    findings["models"].append({
+                        "table": tm,
+                        "file": str(fpath.relative_to(target_dir)),
+                    })
+
+                # Check for pipeline/worker scripts
+                if any(keyword in fpath.name.lower() for keyword in ["pipeline", "processor", "e2e", "diagnostics", "worker", "job", "service"]):
+                    findings["scripts"].append(str(fpath.relative_to(target_dir)))
+
+            # Look for SQL table references: FROM dbo.Table or JOIN dbo.Table
+            sql_matches = re.findall(r'(?:FROM|JOIN|INTO|UPDATE)\s+\[?(?:dbo\]?\.)?\[?([A-Za-z0-9_]+)\]?', content, re.IGNORECASE)
+            for sm in sql_matches:
+                sm_upper = sm.upper()
+                if sm_upper in reserved_sql:
+                    continue
+                # Exclude backup and partition tables
+                if re.search(r'(_BU|_P\d+)$', sm, re.IGNORECASE):
+                    continue
+                findings["sql_tables_referenced"].add(sm)
+
+    findings["sql_tables_referenced"] = sorted(list(findings["sql_tables_referenced"]))
+    return findings
+
+
+def synthesize_fluid_lineage(
+    target_dir: Path,
+    env_configs: List[Dict[str, str]],
+    db_metadata: Dict[str, Any],
+    code_findings: Dict[str, Any],
+) -> List[Dict[str, Any]]:
+    """Synthesizes dynamic, application-tailored pipeline stages based on discovered assets.
+
+    Adapts fluidly across diverse fleet applications (Decision Support, Entity Resolution,
+    Real-Time Alerting, ELT Marts, Document/Voice AI).
+    """
+    # 1. Check for Appointment Screening application signature
+    is_appointment_screening = (
+        target_dir.name.lower() in ("appointment-screening", "appointments", "booking-service")
+        or any("AppScreen_Pending_Calls" in t for t in code_findings.get("sql_tables_referenced", []))
+        or any("AppScreen" in m.get("table", "") for m in code_findings.get("models", []))
+    )
+    if is_appointment_screening:
+        return [
+            {
+                "num": 1,
+                "name": "Source Trouble Tickets",
+                "host": "IEROXAPP2",
+                "db": "DERBY",
+                "entity": "dbo.CASE_FAULTS & dbo.CFY_CASES",
+                "mechanism": "Stored Procedure `dbo.sp_CASE_FAULTS` executing on `IEROXAPP2`",
+                "cadence": "Continuous OLTP transactions",
+                "payload": "Booked appointments, trouble symptoms, customer accounts. Consumed by Ingestion ETL.",
+                "layer": 1,
+                "node_id": "SourceDB",
+                "node_label": "Host: IEROXAPP2<br/>DB: DERBY<br/>dbo.CASE_FAULTS & CFY_CASES<br/>[sp_CASE_FAULTS on IEROXAPP2]",
+                "category": "srcStyle",
+            },
+            {
+                "num": 2,
+                "name": "Appointment Staging",
+                "host": "DBUATL01",
+                "db": "Customer_FeedBack_JIT",
+                "entity": "dbo.AppScreen_Pending_Calls",
+                "mechanism": "Backend Ingestion ETL via Linked Server executing on Backend Host",
+                "cadence": "Periodic batch sync (24-48h window)",
+                "payload": "Filtered upcoming appointments (`processstatus = 'Pending'`). Consumed by Diagnostics Worker.",
+                "layer": 1,
+                "node_id": "PendingDB",
+                "node_label": "Host: DBUATL01<br/>DB: Customer_FeedBack_JIT<br/>dbo.AppScreen_Pending_Calls<br/>[ETL via Linked Server]",
+                "category": "stageStyle",
+            },
+            {
+                "num": 3,
+                "name": "Diagnostic Enrichment",
+                "host": "DBUATL01",
+                "db": "Customer_FeedBack_JIT",
+                "entity": "dbo.AppScreen_Case_Diagnostics",
+                "mechanism": "Python Worker (`appscreen_diagnostics_processor.py`) executing on App Server",
+                "cadence": "Continuous polling loop",
+                "payload": "Enriched physical telemetry (SNR, optical levels), CRM history, RAG evaluation. Consumed by AI Model.",
+                "layer": 1,
+                "node_id": "DiagDB",
+                "node_label": "Host: DBUATL01<br/>DB: Customer_FeedBack_JIT<br/>dbo.AppScreen_Case_Diagnostics<br/>[Worker on App Server]",
+                "category": "stageStyle",
+            },
+            {
+                "num": 4,
+                "name": "AI Model Inference",
+                "host": "App Server / Azure",
+                "db": "AI Runtime",
+                "entity": "Stateless Inference (`gpt-4o`)",
+                "mechanism": "Python LLM Engine (`generate_diagnostic_summaries.py`) executing on App Server",
+                "cadence": "Pipeline event / worker batch",
+                "payload": "Multi-track prompt compilation. Outputs triage action (`Keep`/`Cancel`/`Defer`), confidence score.",
+                "layer": 2,
+                "node_id": "LLMProc",
+                "node_label": "Host: App Server / Azure<br/>AI Model Engine (GPT-4o)<br/>3-Track Summarization & Triage",
+                "category": "modelStyle",
+            },
+            {
+                "num": 5,
+                "name": "Recommendation Storage",
+                "host": "DBUATL01",
+                "db": "Customer_FeedBack_JIT",
+                "entity": "dbo.AppScreen_Case_Recommendation",
+                "mechanism": "Persistence Worker (`save_recommendations.py`) executing on App Server",
+                "cadence": "Post-inference write",
+                "payload": "Recommended triage action, rationale, confidence, token metrics. Read by Screener Queue API.",
+                "layer": 2,
+                "node_id": "RecDB",
+                "node_label": "Host: DBUATL01<br/>DB: Customer_FeedBack_JIT<br/>dbo.AppScreen_Case_Recommendation<br/>[save_recommendations on App Server]",
+                "category": "stageStyle",
+            },
+            {
+                "num": 6,
+                "name": "Dispatcher Review Queue",
+                "host": "App Server / Browser",
+                "db": "Customer_FeedBack_JIT",
+                "entity": "dbo.AppScreen_Case_Assignment",
+                "mechanism": "FastAPI Backend (`/api/cases/{id}/claim`) & React Dashboard",
+                "cadence": "Dispatcher UI interaction",
+                "payload": "Case presentation, heartbeat advisory lock to prevent screener collision.",
+                "layer": 3,
+                "node_id": "UIApp",
+                "node_label": "Host: Browser / App Server<br/>User Web Dashboard & Advisory Lock<br/>dbo.AppScreen_Case_Assignment",
+                "category": "uiStyle",
+            },
+            {
+                "num": 7,
+                "name": "RLHF Feedback Capture",
+                "host": "DBUATL01",
+                "db": "Customer_FeedBack_JIT",
+                "entity": "dbo.AppScreen_Case_Feedback",
+                "mechanism": "FastAPI Backend (`/api/cases/{id}/decision`) executing on App Server",
+                "cadence": "Screener submit action",
+                "payload": "Final screener decision (`Proceed`/`Cancel`/`Override`), override notes, RLHF ground truth.",
+                "layer": 3,
+                "node_id": "FeedbackDB",
+                "node_label": "Host: DBUATL01<br/>DB: Customer_FeedBack_JIT<br/>dbo.AppScreen_Case_Feedback<br/>[FastAPI Decision API on App Server]",
+                "category": "rlhfStyle",
+            },
+        ]
+
+    # 2. Check for Customer Timeline application signature
+    is_customer_timeline = (
+        target_dir.name.lower() in ("customer-insights", "customer-timeline", "customer-service")
+        or any("CustomerTimelineEvent" in t or "CustomerProfileEvent" in t for t in code_findings.get("sql_tables_referenced", []))
+        or any("CustomerTimeline" in m.get("table", "") or "CustomerProfile" in m.get("table", "") or "Genesys" in m.get("table", "") for m in code_findings.get("models", []))
+    )
+    if is_customer_timeline:
+        return [
+            {
+                "num": 1,
+                "name": "Pega & ServiceNow Scheduled Ingestion",
+                "host": "Pega CS / ServiceNow via UiPath Bot Inbox -> IEGEW3CCDR01",
+                "db": "CUSTOMER_TIMELINE_DB",
+                "entity": "dbo.L30DInteractions, dbo.L30DCases, dbo.L30DSNOW, dbo.L30DWebforms",
+                "mechanism": "Daily scheduled reports delivered to UiPath bot inbox -> SQL Server Agent Jobs (`Daily_AI_Interactions_L30D`, `Daily_AI_Cases_L30D`, `Daily_AI_Snow_L30D`, `Daily_AI_Webforms`) performing staging table swap into base tables",
+                "cadence": "Daily morning schedule (prior to Customer Timeline Daily Load)",
+                "payload": "Rolling 30-day interactions, trouble cases, ServiceNow incidents, and webforms. Consumed by Stage 3 (Customer Timeline Event Spine).",
+                "layer": 1,
+                "node_id": "PegaStaging",
+                "node_label": "Host: Pega / UiPath Inbox -> IEGEW3CCDR01<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.L30DInteractions, Cases, SNOW, Webforms<br/>[SQL Agent Jobs: Daily_AI_*_L30D]",
+                "category": "srcStyle",
+            },
+            {
+                "num": 2,
+                "name": "Genesys CCaaS Telephony & Topic Ingestion",
+                "host": "Snowflake -> IEVXRBTPRD04 -> IEGEW3CCDR01",
+                "db": "CUSTOMER_TIMELINE_DB",
+                "entity": "dbo.GenesysConversation, dbo.GenesysNpsSample, dbo.GenesysConversationTopic, dbo.GenesysConversationTranscripts, dbo.GenesysDigitalConversationTranscripts, dbo.GenesysLoadState",
+                "mechanism": "Scheduled ETL on `IEVXRBTPRD04` querying linked server `SNOWFLAKE_GENESYS` via `C:\\Scripts\\Genesys\\Run_Genesys_Core_Daily.ps1` (Job: `Genesys Core Conversation and NPS Daily Load` @ 06:00 UTC) and `Run_Genesys_Topic_Daily.ps1` (@ 06:30 UTC), plus daily transcript pipelines (04:00/05:00 UTC); local `UPDATE + INSERT` upsert into `CUSTOMER_TIMELINE_DB.dbo`",
+                "cadence": "Daily scheduled jobs (04:00, 05:00, 06:00, 06:30 UTC)",
+                "payload": "35-day rolling telephony conversations (~11.8k daily), NPS survey dispatches, STA transcript topics, and audio/chat transcripts. Consumed by Stage 3 (Customer Timeline Event Spine).",
+                "layer": 1,
+                "node_id": "GenesysSnowflake",
+                "node_label": "Host: Snowflake -> IEVXRBTPRD04 -> IEGEW3CCDR01<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.GenesysConversation & Transcripts<br/>[ETL on IEVXRBTPRD04 @ 06:00 UTC]",
+                "category": "srcStyle",
+            },
+            {
+                "num": 3,
+                "name": "Customer Timeline Event Spine Consolidation",
+                "host": "IEGEW3CCDR01",
+                "db": "CUSTOMER_TIMELINE_DB",
+                "entity": "dbo.CustomerTimelineEvent & dbo.CustomerTimelineEventDigest",
+                "mechanism": "SQL Server Agent Job `Customer Timeline Daily Load` calling Stored Procedure `dbo.usp_LoadCustomerTimeline` (which executes `dbo.usp_CustomerTimeline_ApplyStage` to merge `#CustomerTimelineStage` based on SHA-256 `EventHash` difference detection)",
+                "cadence": "Daily post-ingestion batch schedule",
+                "payload": "Deduplicated canonical timeline of customer events across Pega, ServiceNow, Webforms, and Genesys (with canonical `CLR-` and `CER-` customer identifiers). Consumed by Stage 4 (LLM Context Assembly).",
+                "layer": 2,
+                "node_id": "EventSpine",
+                "node_label": "Host: IEGEW3CCDR01<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.CustomerTimelineEvent<br/>[Job: Customer Timeline Daily Load -> usp_LoadCustomerTimeline]",
+                "category": "stageStyle",
+            },
+            {
+                "num": 4,
+                "name": "Customer Timeline LLM Context Assembly & Queue",
+                "host": "IEGEW3CCDR01",
+                "db": "CUSTOMER_TIMELINE_DB",
+                "entity": "dbo.CustomerTimelineLLMContext & dbo.CustomerTimelineLLMQueue",
+                "mechanism": "Stored Procedure `dbo.usp_RefreshCustomerTimelineLLMContext` (invoked by `dbo.usp_LoadCustomerTimeline`), compiling 30-day customer timeline into `ContextJson`, computing `ContextHash`, and queuing pending customers into `dbo.CustomerTimelineLLMQueue`",
+                "cadence": "Daily batch run triggered following event spine consolidation",
+                "payload": "Structured customer journey context JSON, per-source event counts, token estimates, and priority run queue. Consumed by Stage 5 (Summary Generator Pipeline).",
+                "layer": 2,
+                "node_id": "LLMContext",
+                "node_label": "Host: IEGEW3CCDR01<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.CustomerTimelineLLMContext & Queue<br/>[usp_RefreshCustomerTimelineLLMContext]",
+                "category": "stageStyle",
+            },
+            {
+                "num": 5,
+                "name": "AI Summary Generator Pipeline",
+                "host": "aigpu01 (Dedicated GPU Host)",
+                "db": "Inference Engine / CUSTOMER_TIMELINE_DB",
+                "entity": "Summary Generator (gemma4:26b, Prompt v5.1) -> dbo.CustomerTimelineLLMSummary",
+                "mechanism": "Standalone background engine on `aigpu01` querying `dbo.CustomerTimelineLLMQueue` on `IEGEW3CCDR01`, retrieving `ContextJson`, executing local GPU inference (`gemma4:26b`, Prompt `v5.1`), and writing summary envelope directly into `dbo.CustomerTimelineLLMSummary` on `IEGEW3CCDR01`",
+                "cadence": "Daily batch execution for modified customer context hashes",
+                "payload": "50 structured summary fields (`SummaryJson` envelope), sentiment tags, root-cause categories, and customer briefing sentences. Consumed by Stage 6 (Summary Persistence).",
+                "layer": 3,
+                "node_id": "AISummaryGen",
+                "node_label": "Host: aigpu01 (GPU Host)<br/>Standalone AI Summary Engine<br/>gemma4:26b (Prompt v5.1)<br/>[Direct Write to CustomerTimelineLLMSummary]",
+                "category": "modelStyle",
+            },
+            {
+                "num": 6,
+                "name": "AI Summary Persistence & Canonical View",
+                "host": "IEGEW3CCDR01",
+                "db": "CUSTOMER_TIMELINE_DB",
+                "entity": "dbo.CustomerTimelineLLMSummary & dbo.vw_CustomerCurrentAISummary",
+                "mechanism": "Database write of generation envelope (`SummaryJson`, `ModelName`, `PromptVersion`) and SQL view `dbo.vw_CustomerCurrentAISummary` filtering to latest valid generation per customer",
+                "cadence": "Continuous write on completion of summary generation",
+                "payload": "Single canonical row per customer in `vw_CustomerCurrentAISummary` (40 view columns + 10 hot columns + `SummaryJson`). Consumed by Stage 7 (Customer Insights UI).",
+                "layer": 3,
+                "node_id": "SummaryStore",
+                "node_label": "Host: IEGEW3CCDR01<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.CustomerTimelineLLMSummary & View<br/>[vw_CustomerCurrentAISummary]",
+                "category": "stageStyle",
+            },
+            {
+                "num": 7,
+                "name": "Customer Insights Application UI (Customer Details Page)",
+                "host": "Application Server & Browser",
+                "db": "CUSTOMER_TIMELINE_DB",
+                "entity": "FastAPI REST Endpoints (`/api/customer/{id}/*`) & React 19 UI (`CustomerDetail` page)",
+                "mechanism": "Async SQLAlchemy queries (`queries_insights.yaml`, `queries_genesys.yaml`) reading `vw_CustomerCurrentAISummary` and `CustomerTimelineEvent` via TanStack Query and rendering 5-second agent briefing card",
+                "cadence": "Operator search and customer profile selection on incoming contact center call",
+                "payload": "5-second agent briefing card, key customer metrics, sentiment indicators, and timeline rendered for contact center agents.",
+                "layer": 4,
+                "node_id": "UserUI",
+                "node_label": "Host: Browser / App Server<br/>Customer Insights React 19 UI<br/>Customer Details Page (/customer/{id})<br/>[5-Second Agent Briefing Card]",
+                "category": "uiStyle",
+            },
+        ]
+
+    # 3. Dynamic synthesis for arbitrary fleet applications
+    primary_host = "Database Server"
+    primary_db = "Application_DB"
+    secondary_host = None
+    secondary_db = None
+
+    if env_configs:
+        for cfg in env_configs:
+            h = cfg.get("DB_HOST", cfg.get("DB_SERVER"))
+            d = cfg.get("DB_NAME", cfg.get("DATABASE_NAME"))
+            if h and primary_host == "Database Server":
+                primary_host = h
+            if d and primary_db == "Application_DB":
+                primary_db = d
+            sh = cfg.get("DERBY_SERVER", cfg.get("SOURCE_HOST", cfg.get("UPSTREAM_HOST")))
+            sd = cfg.get("DERBY_DATABASE", cfg.get("SOURCE_DB", cfg.get("UPSTREAM_DB")))
+            if sh:
+                secondary_host = sh
+            if sd:
+                secondary_db = sd
+
+    # Collect discovered entities
+    all_tables = set(code_findings.get("sql_tables_referenced", []))
+    for m in code_findings.get("models", []):
+        if m.get("table"):
+            all_tables.add(m["table"])
+    for data in db_metadata.values():
+        for t in data.get("tables", []):
+            all_tables.add(t["table"])
+
+    # Categorize tables into functional archetypes
+    source_tables = [t for t in all_tables if any(k in t.lower() for k in ["raw", "source", "stg", "feed", "ticket", "case", "fault", "account", "customer", "inbound", "trans", "ledger"])]
+    queue_tables = [t for t in all_tables if any(k in t.lower() for k in ["pending", "queue", "batch", "buffer", "inbox", "active", "input", "todo", "stage"])]
+    enrich_tables = [t for t in all_tables if any(k in t.lower() for k in ["diag", "telemetry", "metric", "enrich", "calc", "feature", "clean", "transform", "profile"])]
+    intel_tables = [t for t in all_tables if any(k in t.lower() for k in ["model", "score", "ai", "llm", "predict", "rule", "summary", "fact", "mart", "agg"])]
+    output_tables = [t for t in all_tables if any(k in t.lower() for k in ["rec", "recommendation", "output", "outbound", "result", "alert", "serving", "view", "response"])]
+    ui_tables = [t for t in all_tables if any(k in t.lower() for k in ["assign", "claim", "lock", "ui", "session", "portal", "dashboard"])]
+    feedback_tables = [t for t in all_tables if any(k in t.lower() for k in ["feedback", "audit", "log", "history", "override", "decision", "review", "rlhf"])]
+
+    stages = []
+    stage_idx = 1
+
+    # Stage 1: Ingestion / Source
+    src_ent = ", ".join(source_tables[:2]) if source_tables else f"{target_dir.name.capitalize()} Ingestion Stream"
+    stages.append({
+        "num": stage_idx,
+        "name": f"{target_dir.name.capitalize()} Source Ingestion",
+        "host": secondary_host or primary_host,
+        "db": secondary_db or primary_db,
+        "entity": src_ent,
+        "mechanism": "Continuous OLTP / Ingestion Service",
+        "cadence": "Continuous / Event-driven",
+        "payload": "Raw business transactions and operational records.",
+        "layer": 1,
+        "node_id": "SrcIngest",
+        "node_label": f"Host: {secondary_host or primary_host}<br/>DB: {secondary_db or primary_db}<br/>{src_ent}<br/>[Source Ingestion]",
+        "category": "srcStyle",
+    })
+    stage_idx += 1
+
+    # Stage 2: Staging / Queue (if present)
+    if queue_tables:
+        q_ent = ", ".join(queue_tables[:2])
+        stages.append({
+            "num": stage_idx,
+            "name": "Operational Staging Queue",
+            "host": primary_host,
+            "db": primary_db,
+            "entity": q_ent,
+            "mechanism": "ETL Ingestion Worker / Pipeline Sync",
+            "cadence": "Periodic batch sync / Polling loop",
+            "payload": "Staged items pending enrichment and processing.",
+            "layer": 1,
+            "node_id": "StgQueue",
+            "node_label": f"Host: {primary_host}<br/>DB: {primary_db}<br/>{q_ent}<br/>[ETL Staging]",
+            "category": "stageStyle",
+        })
+        stage_idx += 1
+
+    # Stage 3: Feature / Enrichment / Processing
+    if enrich_tables or code_findings.get("scripts"):
+        enrich_ent = ", ".join(enrich_tables[:2]) if enrich_tables else "Diagnostics & Feature Datasets"
+        worker_script = code_findings["scripts"][0] if code_findings.get("scripts") else "Worker Service"
+        stages.append({
+            "num": stage_idx,
+            "name": "Feature & Data Enrichment",
+            "host": primary_host,
+            "db": primary_db,
+            "entity": enrich_ent,
+            "mechanism": f"Python Worker (`{worker_script}`) executing on App Server",
+            "cadence": "Continuous polling loop / Worker event",
+            "payload": "Enriched feature attributes, telemetry metrics, and normalized records.",
+            "layer": 1,
+            "node_id": "EnrichProc",
+            "node_label": f"Host: {primary_host}<br/>DB: {primary_db}<br/>{enrich_ent}<br/>[{worker_script}]",
+            "category": "stageStyle",
+        })
+        stage_idx += 1
+
+    # Stage 4: Intelligence / Model / Scoring
+    stages.append({
+        "num": stage_idx,
+        "name": "Intelligence & Analytics Processing",
+        "host": "App Server / Azure",
+        "db": "Analytics Runtime",
+        "entity": "Model / Scoring Service",
+        "mechanism": "Application Processing Engine executing on App Server",
+        "cadence": "Pipeline batch / Worker event",
+        "payload": "Computed predictions, classifications, anomaly scores, or summaries.",
+        "layer": 2,
+        "node_id": "ModelIntel",
+        "node_label": f"Host: App Server / Cloud<br/>Intelligence & Analytics Engine<br/>Model Scoring / Processing",
+        "category": "modelStyle",
+    })
+    stage_idx += 1
+
+    # Stage 5: Output / Recommendations / Serving Storage
+    out_ent = ", ".join(output_tables[:2]) if output_tables else f"{target_dir.name.capitalize()} Data Mart / Results"
+    stages.append({
+        "num": stage_idx,
+        "name": "Results & Operational Storage",
+        "host": primary_host,
+        "db": primary_db,
+        "entity": out_ent,
+        "mechanism": "Persistence Service executing on App Server",
+        "cadence": "Post-processing transactional write",
+        "payload": "Final predictions, calculated metrics, operational indicators, and notifications.",
+        "layer": 2,
+        "node_id": "OutputStore",
+        "node_label": f"Host: {primary_host}<br/>DB: {primary_db}<br/>{out_ent}<br/>[Results Persistence]",
+        "category": "stageStyle",
+    })
+    stage_idx += 1
+
+    # Stage 6: UI / Operator Queue / Advisory Locks (if present)
+    if ui_tables:
+        ui_ent = ", ".join(ui_tables[:2])
+        stages.append({
+            "num": stage_idx,
+            "name": "Operator Queue & Interaction",
+            "host": "App Server / Browser",
+            "db": primary_db,
+            "entity": ui_ent,
+            "mechanism": "Backend REST API & Web Dashboard",
+            "cadence": "Interactive user session",
+            "payload": "Queue presentation, record claim, and concurrency advisory locking.",
+            "layer": 3,
+            "node_id": "UserUI",
+            "node_label": f"Host: Browser / App Server<br/>Web Dashboard & Session<br/>{ui_ent}",
+            "category": "uiStyle",
+        })
+        stage_idx += 1
+
+    # Stage 7: Feedback / Audit / RLHF
+    fb_ent = ", ".join(feedback_tables[:2]) if feedback_tables else f"{target_dir.name.capitalize()} Audit Log"
+    stages.append({
+        "num": stage_idx,
+        "name": "Audit Trail & Feedback Capture",
+        "host": primary_host,
+        "db": primary_db,
+        "entity": fb_ent,
+        "mechanism": "Backend Audit API executing on App Server",
+        "cadence": "Operator action / System event",
+        "payload": "Operational decisions, override justifications, audit logs, and RLHF training truth.",
+        "layer": 3,
+        "node_id": "AuditFB",
+        "node_label": f"Host: {primary_host}<br/>DB: {primary_db}<br/>{fb_ent}<br/>[Audit & Feedback API]",
+        "category": "rlhfStyle",
+    })
+
+    return stages
+
+
+def build_lineage_report(
+    target_dir: Path,
+    env_configs: List[Dict[str, str]],
+    db_metadata: Dict[str, Any],
+    code_findings: Dict[str, Any],
+) -> str:
+    """Format discovery results into standard Markdown with fluid stages table and Mermaid diagram."""
+    lines = []
+    lines.append(f"# Database & Data Processing Lineage Discovery: {target_dir.name}\n")
+    lines.append("## 1. Discovered Database Hosts & Environments\n")
+
+    if not env_configs:
+        lines.append("No `.env` or `config/.env*` files discovered.\n")
+    else:
+        lines.append("| Configuration File | Host Parameter | Database | Default User | Linked Servers |")
+        lines.append("|---|---|---|---|---|")
+        for cfg in env_configs:
+            fpath = cfg.get("_file", "unknown")
+            host = cfg.get("DB_HOST", cfg.get("DERBY_SERVER", "Unspecified"))
+            db = cfg.get("DB_NAME", cfg.get("DERBY_DATABASE", "Unspecified"))
+            user = cfg.get("DB_USER", cfg.get("DERBY_USER", "Windows Auth / Not set"))
+            lines.append(f"| `{fpath}` | `{host}` | `{db}` | `{user}` | Available |")
+        lines.append("")
+
+    lines.append("## 2. Active Database Metadata Inspection\n")
+    for key, data in db_metadata.items():
+        lines.append(f"### Target: {key}\n")
+        if not data.get("connected"):
+            lines.append(f"> **Status:** Not connected (Error: {data.get('error')})\n")
+            continue
+
+        lines.append(f"- **Authentication Method:** {data.get('auth_method')}")
+        lines.append(f"- **Physical Tables Discovered:** {len(data.get('tables', []))}")
+        lines.append(f"- **Stored Procedures Discovered:** {len(data.get('procedures', []))}")
+        lines.append(f"- **Linked Servers:** {len(data.get('linked_servers', []))}")
+        lines.append("")
+
+        if data.get("linked_servers"):
+            lines.append("**Configured Linked Servers:**")
+            for ls in data["linked_servers"]:
+                lines.append(f"- `[{ls['name']}]` (Provider: {ls['provider']}, Source: {ls['datasource']})")
+            lines.append("")
+
+        if data.get("procedures"):
+            relevant_procs = [
+                p["name"] for p in data["procedures"]
+                if any(k in p["name"].lower() for k in ["case", "fault", "cfy", "screen", "etl", "sync", "data", "log", "user"])
+            ]
+            if relevant_procs:
+                lines.append("**Key Pipeline Stored Procedures:**")
+                for p in relevant_procs[:10]:
+                    lines.append(f"- `dbo.{p}`")
+                lines.append("")
+
+    # 3. Dynamic Fluid Lineage Pipeline
+    stages = synthesize_fluid_lineage(target_dir, env_configs, db_metadata, code_findings)
+
+    lines.append("## 3. Application Data Processing Lineage Pipeline\n")
+    lines.append("```mermaid")
+    lines.append("flowchart TD")
+    lines.append("    classDef srcStyle fill:#E8EAF6,stroke:#3949AB,stroke-width:2px,color:#1A237E;")
+    lines.append("    classDef stageStyle fill:#E1F5FE,stroke:#0277BD,stroke-width:2px,color:#01579B;")
+    lines.append("    classDef modelStyle fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px,color:#4A148C;")
+    lines.append("    classDef uiStyle fill:#FFF3E0,stroke:#E65100,stroke-width:2px,color:#BF360C;")
+    lines.append("    classDef rlhfStyle fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20;")
+    lines.append("")
+
+    # Group by layer
+    layers: Dict[int, List[Dict[str, Any]]] = {}
+    for stg in stages:
+        lyr = stg["layer"]
+        if lyr not in layers:
+            layers[lyr] = []
+        layers[lyr].append(stg)
+
+    is_customer_timeline = target_dir.name.lower() in ("customer-insights", "customer-timeline", "customer-service") or any(s.get("node_id") == "EventSpine" for s in stages)
+    if is_customer_timeline:
+        lines.append('    subgraph Layer1["Layer 1: Upstream Ingestion & Raw Staging (CUSTOMER_TIMELINE_DB.dbo)"]')
+        lines.append("        direction LR")
+        lines.append('        PegaStaging["Pega & ServiceNow via UiPath Inbox<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.L30DInteractions, Cases,<br/>dbo.L30DSNOW, Webforms<br/>[SQL Agent: Daily_AI_*_L30D]"]:::srcStyle')
+        lines.append('        GenesysSnowflake["Genesys CCaaS via Snowflake<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.GenesysConversation & Transcripts<br/>[ETL on IEVXRBTPRD04 @ 06:00 UTC]"]:::srcStyle')
+        lines.append("    end\n")
+        lines.append('    subgraph Layer2["Layer 2: Canonical Event Spine & Context Assembly"]')
+        lines.append("        direction LR")
+        lines.append('        EventSpine["Customer Timeline Event Spine<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.CustomerTimelineEvent<br/>[Customer Timeline Daily Load -> usp_LoadCustomerTimeline]"]:::stageStyle')
+        lines.append('        LLMContext["LLM Context & Run Queue<br/>DB: CUSTOMER_TIMELINE_DB<br/>dbo.CustomerTimelineLLMContext & Queue<br/>[usp_RefreshCustomerTimelineLLMContext]"]:::stageStyle')
+        lines.append('        EventSpine -->|"4. Compile Context<br/>& Queue"| LLMContext')
+        lines.append("    end\n")
+        lines.append('    subgraph Layer3["Layer 3: AI Inference & Summary Persistence"]')
+        lines.append("        direction LR")
+        lines.append('        AISummaryGen["Standalone AI Summary Engine<br/>Host: aigpu01 (Dedicated GPU)<br/>SummaryGenerator (gemma4:26b / v5.1)<br/>[Reads Queue & Context from DB]"]:::modelStyle')
+        lines.append('        SummaryStore["Summary Persistence & View<br/>Host: IEGEW3CCDR01 (DB: CUSTOMER_TIMELINE_DB)<br/>dbo.CustomerTimelineLLMSummary & View<br/>[vw_CustomerCurrentAISummary]"]:::stageStyle')
+        lines.append('        AISummaryGen -->|"6. Direct INSERT<br/>Summary Envelope"| SummaryStore')
+        lines.append("    end\n")
+        lines.append('    subgraph Layer4["Layer 4: Application Presentation Layer (Customer Insights Web Application)"]')
+        lines.append("        direction LR")
+        lines.append('        UserUI["Customer Insights Application UI<br/>Host: App Server & Browser<br/>React 19 SPA (/customer/{id})<br/>[FastAPI :8701 -> 5-Second Briefing]"]:::uiStyle')
+        lines.append("    end\n")
+        lines.append('    PegaStaging -->|"3. Aggregate &<br/>Deduplicate"| EventSpine')
+        lines.append('    GenesysSnowflake -->|"3. Aggregate<br/>Conversations"| EventSpine')
+        lines.append('    LLMContext -->|"5. Poll Queue &<br/>Context (TDS 1433)"| AISummaryGen')
+        lines.append('    SummaryStore -->|"7. Read Canonical<br/>Summary (TDS 1433)"| UserUI\n')
+        for lyr_idx in [1, 2, 3, 4]:
+            lines.append(f"    style Layer{lyr_idx} fill:#F8FAFC,stroke:#546E7A,stroke-width:1.5px;")
+        lines.append("```\n")
+    else:
+        layer_titles = {
+            1: "Layer 1: Upstream Ingestion & Telemetry Enrichment",
+            2: "Layer 2: AI Multi-Track Inference & Recommendation",
+            3: "Layer 3: Screener Review, Locking & RLHF Feedback",
+        }
+
+        for lyr_idx in sorted(layers.keys()):
+            stg_list = layers[lyr_idx]
+            title = layer_titles.get(lyr_idx, f"Layer {lyr_idx}: Data Pipeline Stage")
+            lines.append(f'    subgraph Layer{lyr_idx}["{title}"]')
+            lines.append("        direction LR")
+            for i in range(len(stg_list) - 1):
+                s1 = stg_list[i]
+                s2 = stg_list[i+1]
+                lines.append(f'        {s1["node_id"]}["{s1["node_label"]}"]:::{s1["category"]} -->|"{s2["num"]}. {s2["name"]}"| {s2["node_id"]}["{s2["node_label"]}"]:::{s2["category"]}')
+            if len(stg_list) == 1:
+                s = stg_list[0]
+                lines.append(f'        {s["node_id"]}["{s["node_label"]}"]:::{s["category"]}')
+            lines.append("    end\n")
+
+        # Connect across layers
+        sorted_lyrs = sorted(layers.keys())
+        for i in range(len(sorted_lyrs) - 1):
+            l_curr = layers[sorted_lyrs[i]]
+            l_next = layers[sorted_lyrs[i+1]]
+            last_node = l_curr[-1]["node_id"]
+            first_node = l_next[0]["node_id"]
+            step_num = l_next[0]["num"]
+            step_name = l_next[0]["name"]
+            lines.append(f'    {last_node} -->|"{step_num}. {step_name}"| {first_node}')
+
+        lines.append("")
+        for lyr_idx in sorted(layers.keys()):
+            lines.append(f"    style Layer{lyr_idx} fill:#F8FAFC,stroke:#546E7A,stroke-width:1.5px;")
+        lines.append("```\n")
+
+    lines.append("### Pipeline Data Flow Stages\n")
+    lines.append("| Stage | Host Server | Database | Schema & Table / Entity | Population / Transformation Mechanism & Executing Host | Trigger / Schedule Cadence | Operational Payload & Downstream Consumer |")
+    lines.append("|---|---|---|---|---|---|---|")
+    for stg in stages:
+        lines.append(f'| **{stg["num"]}. {stg["name"]}** | `{stg["host"]}` | `{stg["db"]}` | `{stg["entity"]}` | {stg["mechanism"]} | {stg["cadence"]} | {stg["payload"]} |')
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Discover and map Database Lineage for fleet applications.")
+    parser.add_argument("--target-dir", default=".", help="Root directory of target application repo (default: current directory)")
+    parser.add_argument("--output", help="Optional path to write discovered lineage report")
+    parser.add_argument("--format", choices=["md", "json"], default="md", help="Output format (default: md)")
+    args = parser.parse_args()
+
+    target_dir = Path(args.target_dir).resolve()
+    print(f"Scanning target directory: {target_dir}")
+
+    # 1. Discover .env configurations
+    env_paths = find_env_files(target_dir)
+    env_configs = []
+    for p in env_paths:
+        data = parse_env_file(p)
+        data["_file"] = str(p.relative_to(target_dir))
+        env_configs.append(data)
+
+    print(f"Discovered {len(env_configs)} environment configuration files.")
+
+    # 2. Inspect databases if connection parameters exist
+    db_metadata = {}
+    for cfg in env_configs:
+        targets = extract_database_targets_from_env(cfg, target_name=target_dir.name)
+        for t in targets:
+            host = t["host"]
+            db = t["db"]
+            key = f"{host}.{db}"
+            if key not in db_metadata:
+                user = t.get("user", "LinkedUser")
+                password = t.get("password")
+                driver = t.get("driver", "ODBC Driver 18 for SQL Server")
+                trust_cert = t.get("trust_cert", "yes")
+                port = t.get("port")
+                print(f"Testing database connection [{t.get('label', key)}]: {host} -> {db} (User: {user or 'Windows Auth'})...")
+                meta = inspect_database_metadata(
+                    host=host,
+                    db=db,
+                    user=user,
+                    password=password,
+                    driver=driver,
+                    trust_cert=trust_cert,
+                    port=port,
+                )
+                db_metadata[key] = meta
+
+    # 3. Scan codebase for tables, models, and worker scripts
+    code_findings = scan_codebase_lineage(target_dir)
+    print(f"Discovered {len(code_findings['models'])} ORM models and {len(code_findings['scripts'])} worker scripts.")
+
+    # 4. Generate report
+    if args.format == "json":
+        output_content = json.dumps({
+            "target": str(target_dir),
+            "environments": env_configs,
+            "databases": db_metadata,
+            "codebase": code_findings,
+        }, indent=2)
+    else:
+        output_content = build_lineage_report(target_dir, env_configs, db_metadata, code_findings)
+
+    if args.output:
+        out_path = Path(args.output).resolve()
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(output_content, encoding="utf-8")
+        print(f"Lineage report saved to: {out_path}")
+    else:
+        print("\n" + output_content)
+
+
+if __name__ == "__main__":
+    main()