codegraph-engine 2.3.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. codegraph/__init__.py +1 -1
  2. codegraph/__main__.py +7 -0
  3. codegraph/agent_brain.py +253 -2
  4. codegraph/agent_capabilities.py +1348 -67
  5. codegraph/agent_rules.py +2 -1
  6. codegraph/api_drift.py +455 -0
  7. codegraph/architecture_rules.py +123 -0
  8. codegraph/async_queue/__init__.py +50 -0
  9. codegraph/async_queue/detectors/__init__.py +48 -0
  10. codegraph/async_queue/detectors/celery.py +160 -0
  11. codegraph/async_queue/detectors/kafka.py +168 -0
  12. codegraph/async_queue/detectors/rabbitmq.py +116 -0
  13. codegraph/async_queue/detectors/redis.py +130 -0
  14. codegraph/async_queue/detectors/sqs.py +135 -0
  15. codegraph/async_queue/models.py +161 -0
  16. codegraph/async_queue/otel_models.py +74 -0
  17. codegraph/async_queue/otel_parser.py +337 -0
  18. codegraph/async_queue/reconciler.py +427 -0
  19. codegraph/async_queue/scanner.py +291 -0
  20. codegraph/async_queue/traversal.py +447 -0
  21. codegraph/change_impact.py +320 -110
  22. codegraph/changelog.py +170 -0
  23. codegraph/cli.py +1605 -62
  24. codegraph/cli_output.py +17 -2
  25. codegraph/context.py +135 -24
  26. codegraph/context_freshness.py +2 -0
  27. codegraph/database/__init__.py +14 -0
  28. codegraph/database/extractor.py +712 -17
  29. codegraph/database/interrogation.py +388 -2
  30. codegraph/database/schema_drift.py +862 -0
  31. codegraph/dataflow_propagation.py +118 -0
  32. codegraph/dead_code.py +387 -0
  33. codegraph/epistemic.py +15 -0
  34. codegraph/evidence_contract.py +34 -3
  35. codegraph/federation.py +245 -0
  36. codegraph/frameworks.py +234 -12
  37. codegraph/frameworks_nestjs.py +502 -0
  38. codegraph/frameworks_nextjs.py +337 -0
  39. codegraph/frameworks_react.py +457 -0
  40. codegraph/freshness.py +2 -0
  41. codegraph/frontend_html.py +109 -0
  42. codegraph/git.py +2 -0
  43. codegraph/git_state.py +2 -0
  44. codegraph/graph/traversal.py +150 -7
  45. codegraph/graph_csr.py +218 -0
  46. codegraph/incremental.py +150 -0
  47. codegraph/indexing/__init__.py +7 -1
  48. codegraph/indexing/classifier.py +5 -0
  49. codegraph/indexing/indexer.py +292 -38
  50. codegraph/indexing/languages/__init__.py +1 -0
  51. codegraph/indexing/languages/cpp.py +457 -0
  52. codegraph/indexing/languages/go.py +459 -0
  53. codegraph/indexing/languages/jvm.py +583 -0
  54. codegraph/indexing/languages/rust.py +507 -0
  55. codegraph/indexing/models.py +15 -1
  56. codegraph/indexing/parser.py +385 -9
  57. codegraph/indexing/pool.py +136 -0
  58. codegraph/indexing/protocols.py +220 -0
  59. codegraph/indexing/scanner.py +23 -0
  60. codegraph/indexing/templates.py +418 -0
  61. codegraph/interrogation.py +207 -39
  62. codegraph/lsp.py +318 -0
  63. codegraph/lsp_bridge/__init__.py +16 -0
  64. codegraph/lsp_bridge/bridge.py +102 -0
  65. codegraph/lsp_bridge/client.py +207 -0
  66. codegraph/lsp_bridge/models.py +71 -0
  67. codegraph/mcp/server.py +502 -29
  68. codegraph/memory/trajectory.py +282 -0
  69. codegraph/models.py +7 -0
  70. codegraph/monorepo.py +3 -0
  71. codegraph/multi_agent/__init__.py +13 -0
  72. codegraph/multi_agent/coordinator.py +229 -0
  73. codegraph/multi_agent/models.py +76 -0
  74. codegraph/optimizer.py +42 -5
  75. codegraph/polymorphism.py +95 -0
  76. codegraph/pr_review.py +296 -0
  77. codegraph/process_lifecycle.py +50 -12
  78. codegraph/reachability.py +198 -0
  79. codegraph/reachability_index.py +74 -0
  80. codegraph/refactor/__init__.py +48 -0
  81. codegraph/refactor/models.py +114 -0
  82. codegraph/refactor/patcher.py +348 -0
  83. codegraph/refactor/renamer.py +844 -0
  84. codegraph/refactor/transactions.py +414 -0
  85. codegraph/repair.py +233 -0
  86. codegraph/resolver.py +1357 -161
  87. codegraph/retrieval_policy.py +22 -1
  88. codegraph/roblox.py +2174 -0
  89. codegraph/route_composer.py +7 -0
  90. codegraph/route_topology.py +172 -0
  91. codegraph/runtime/__init__.py +25 -0
  92. codegraph/runtime/collector.py +155 -0
  93. codegraph/runtime/db_watcher.py +191 -0
  94. codegraph/runtime/ingestor.py +30 -10
  95. codegraph/runtime/otel_receiver.py +208 -0
  96. codegraph/runtime/port_inspector.py +304 -0
  97. codegraph/runtime/runner.py +155 -6
  98. codegraph/runtime/trace_linker.py +175 -0
  99. codegraph/sandbox.py +215 -0
  100. codegraph/search/hybrid.py +26 -0
  101. codegraph/security/supply_chain.py +188 -0
  102. codegraph/security/taint.py +421 -0
  103. codegraph/semantic_decorators.py +34 -3
  104. codegraph/structural_diff.py +2 -0
  105. codegraph/styles.py +144 -0
  106. codegraph/symbol_history.py +2 -0
  107. codegraph/test_gen.py +437 -0
  108. codegraph/tsconfig.py +236 -0
  109. codegraph/ui/__init__.py +6 -0
  110. codegraph/ui/server.py +876 -0
  111. codegraph/watcher.py +323 -0
  112. {codegraph_engine-2.3.0.dist-info → codegraph_engine-3.0.1.dist-info}/METADATA +365 -67
  113. codegraph_engine-3.0.1.dist-info/RECORD +164 -0
  114. {codegraph_engine-2.3.0.dist-info → codegraph_engine-3.0.1.dist-info}/WHEEL +1 -1
  115. codegraph_engine-2.3.0.dist-info/RECORD +0 -94
  116. {codegraph_engine-2.3.0.dist-info → codegraph_engine-3.0.1.dist-info}/entry_points.txt +0 -0
  117. {codegraph_engine-2.3.0.dist-info → codegraph_engine-3.0.1.dist-info}/licenses/LICENSE +0 -0
  118. {codegraph_engine-2.3.0.dist-info → codegraph_engine-3.0.1.dist-info}/top_level.txt +0 -0
@@ -0,0 +1,208 @@
1
+ """Lightweight, Privacy-Safe OpenTelemetry (OTLP) HTTP Receiver.
2
+
3
+ Listens for standard OpenTelemetry Protocol (OTLP/HTTP) trace exports
4
+ (POST /v1/traces) and streams normalized, redacted observations directly
5
+ into `.codegraph.sqlite3` runtime tables.
6
+
7
+ Invariants:
8
+ 1. Zero third-party runtime dependencies: built entirely on standard library asyncio.
9
+ 2. Complies with OTLP/HTTP 1.0 JSON trace export specification.
10
+ 3. Full CORS support (Access-Control-Allow-Origin: *) for browser/SPA OpenTelemetry SDKs.
11
+ 4. Redacts secrets, headers, and SQL bound parameters in real-time before SQLite persistence.
12
+ 5. Handles optional gzip compression automatically.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import asyncio
17
+ import gzip
18
+ import json
19
+ import sqlite3
20
+ from collections.abc import Callable
21
+ from pathlib import Path
22
+ from typing import Any
23
+
24
+ from codegraph.runtime.ingestor import ingest_runtime_traces
25
+
26
+
27
+ class OTLPReceiver:
28
+ """Embedded asyncio HTTP server receiving OTLP /v1/traces payloads."""
29
+
30
+ def __init__(
31
+ self,
32
+ db_path: Path | str,
33
+ host: str = "127.0.0.1",
34
+ port: int = 4318,
35
+ on_batch: Callable[[dict[str, Any]], None] | None = None,
36
+ ) -> None:
37
+ self.db_path = Path(db_path)
38
+ self.host = host
39
+ self.port = port
40
+ self.on_batch = on_batch
41
+ self.server: asyncio.Server | None = None
42
+ self._is_running = False
43
+ self.total_spans_received = 0
44
+ self.total_batches_received = 0
45
+
46
+ async def start(self) -> None:
47
+ """Start listening for incoming OTLP HTTP requests."""
48
+ self.server = await asyncio.start_server(
49
+ self._handle_client,
50
+ self.host,
51
+ self.port,
52
+ )
53
+ self._is_running = True
54
+
55
+ async def stop(self) -> None:
56
+ """Gracefully terminate the OTLP server."""
57
+ self._is_running = False
58
+ if self.server:
59
+ self.server.close()
60
+ await self.server.wait_closed()
61
+ self.server = None
62
+
63
+ async def _handle_client(
64
+ self,
65
+ reader: asyncio.StreamReader,
66
+ writer: asyncio.StreamWriter,
67
+ ) -> None:
68
+ try:
69
+ # Read HTTP request line
70
+ line = await reader.readline()
71
+ if not line:
72
+ writer.close()
73
+ await writer.wait_closed()
74
+ return
75
+
76
+ req_line = line.decode("utf-8", errors="replace").strip()
77
+ parts = req_line.split()
78
+ if len(parts) < 2:
79
+ self._send_response(writer, 400, "Bad Request")
80
+ return
81
+
82
+ method, path = parts[0].upper(), parts[1]
83
+
84
+ # Read headers
85
+ headers: dict[str, str] = {}
86
+ while True:
87
+ header_line = await reader.readline()
88
+ if not header_line or header_line in (b"\r\n", b"\n"):
89
+ break
90
+ header_text = header_line.decode("utf-8", errors="replace").strip()
91
+ if ":" in header_text:
92
+ k, v = header_text.split(":", 1)
93
+ headers[k.strip().lower()] = v.strip()
94
+
95
+ # Handle CORS preflight
96
+ if method == "OPTIONS":
97
+ self._send_cors_response(writer)
98
+ return
99
+
100
+ # Read body
101
+ content_length = int(headers.get("content-length", 0))
102
+ body = b""
103
+ if content_length > 0:
104
+ body = await reader.readexactly(content_length)
105
+
106
+ if method == "POST" and ("/v1/traces" in path or path == "/"):
107
+ # Handle gzip if present
108
+ if headers.get("content-encoding") == "gzip":
109
+ try:
110
+ body = gzip.decompress(body)
111
+ except Exception:
112
+ self._send_response(writer, 400, "Invalid gzip body")
113
+ return
114
+
115
+ try:
116
+ payload = json.loads(body.decode("utf-8"))
117
+ except Exception:
118
+ self._send_response(writer, 400, "Invalid JSON payload")
119
+ return
120
+
121
+ # Ingest into SQLite
122
+ result = self._persist_batch(payload)
123
+ self.total_batches_received += 1
124
+ self.total_spans_received += result.get("ingested_events", 0)
125
+
126
+ if self.on_batch:
127
+ try:
128
+ self.on_batch(result)
129
+ except Exception:
130
+ pass
131
+
132
+ # Return standard OTLP JSON success response
133
+ resp_payload = json.dumps({"partialSuccess": {}}).encode("utf-8")
134
+ self._send_response(
135
+ writer,
136
+ 200,
137
+ "OK",
138
+ body=resp_payload,
139
+ content_type="application/json",
140
+ )
141
+ else:
142
+ self._send_response(writer, 404, "Not Found")
143
+
144
+ except Exception as exc:
145
+ try:
146
+ self._send_response(writer, 500, f"Internal Error: {exc}")
147
+ except Exception:
148
+ pass
149
+ finally:
150
+ try:
151
+ writer.close()
152
+ await writer.wait_closed()
153
+ except Exception:
154
+ pass
155
+
156
+ def _persist_batch(self, payload: dict[str, Any]) -> dict[str, Any]:
157
+ """Ingest OTLP batch into SQLite database with thread-safe connection."""
158
+ con = sqlite3.connect(str(self.db_path), timeout=10.0)
159
+ con.row_factory = sqlite3.Row
160
+ try:
161
+ con.execute("PRAGMA journal_mode = WAL")
162
+ con.execute("PRAGMA busy_timeout = 5000")
163
+ result = ingest_runtime_traces(con, data_or_path=payload, format="otel")
164
+ con.commit()
165
+ return result
166
+ finally:
167
+ con.close()
168
+
169
+ def _send_response(
170
+ self,
171
+ writer: asyncio.StreamWriter,
172
+ status_code: int,
173
+ status_text: str,
174
+ body: bytes = b"",
175
+ content_type: str = "text/plain",
176
+ ) -> None:
177
+ response = (
178
+ f"HTTP/1.1 {status_code} {status_text}\r\n"
179
+ f"Content-Type: {content_type}\r\n"
180
+ f"Content-Length: {len(body)}\r\n"
181
+ "Access-Control-Allow-Origin: *\r\n"
182
+ "Access-Control-Allow-Headers: *\r\n"
183
+ "Connection: close\r\n\r\n"
184
+ ).encode() + body
185
+ writer.write(response)
186
+
187
+ def _send_cors_response(self, writer: asyncio.StreamWriter) -> None:
188
+ response = (
189
+ b"HTTP/1.1 204 No Content\r\n"
190
+ b"Access-Control-Allow-Origin: *\r\n"
191
+ b"Access-Control-Allow-Methods: POST, OPTIONS\r\n"
192
+ b"Access-Control-Allow-Headers: *\r\n"
193
+ b"Access-Control-Max-Age: 86400\r\n"
194
+ b"Connection: close\r\n\r\n"
195
+ )
196
+ writer.write(response)
197
+
198
+
199
+ async def run_otel_listener(
200
+ db_path: Path | str,
201
+ host: str = "127.0.0.1",
202
+ port: int = 4318,
203
+ on_batch: Callable[[dict[str, Any]], None] | None = None,
204
+ ) -> OTLPReceiver:
205
+ """Start an asynchronous OTLP receiver instance."""
206
+ receiver = OTLPReceiver(db_path, host=host, port=port, on_batch=on_batch)
207
+ await receiver.start()
208
+ return receiver
@@ -0,0 +1,304 @@
1
+ """Localhost Port and Process Inspector for Multi-Service Architectures.
2
+
3
+ Deterministically detects, fingerprints, and attributes running localhost services:
4
+ 1. Port <-> PID mapping via lsof / netstat / /proc.
5
+ 2. Process CWD and command-line attribution to workspace packages.
6
+ 3. Static port inference from docker-compose.yml, package.json, and .env.
7
+ 4. Framework fingerprinting (Next.js, Vite, FastAPI, NestJS, Express, PostgreSQL, MongoDB).
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ import shutil
13
+ import subprocess
14
+ import time
15
+ from dataclasses import dataclass, field
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class ServiceEndpoint:
22
+ port: int
23
+ host: str = "localhost"
24
+ pid: int | None = None
25
+ service_name: str = "unknown"
26
+ framework: str = "unknown"
27
+ process_cwd: str = ""
28
+ relative_repo_path: str = ""
29
+ command: str = ""
30
+ is_live: bool = False
31
+ attributes: dict[str, Any] = field(default_factory=dict)
32
+
33
+ def as_dict(self) -> dict[str, Any]:
34
+ return {
35
+ "port": self.port,
36
+ "host": self.host,
37
+ "pid": self.pid,
38
+ "service_name": self.service_name,
39
+ "framework": self.framework,
40
+ "process_cwd": self.process_cwd,
41
+ "relative_repo_path": self.relative_repo_path,
42
+ "command": self.command,
43
+ "is_live": self.is_live,
44
+ "attributes": dict(self.attributes),
45
+ }
46
+
47
+
48
+ def _infer_framework_from_cmd(cmd: str) -> str:
49
+ cmd_lower = cmd.lower()
50
+ if "next" in cmd_lower:
51
+ return "Next.js"
52
+ if "vite" in cmd_lower:
53
+ return "Vite"
54
+ if "uvicorn" in cmd_lower or "fastapi" in cmd_lower:
55
+ return "FastAPI"
56
+ if "nest" in cmd_lower:
57
+ return "NestJS"
58
+ if "express" in cmd_lower or "node" in cmd_lower:
59
+ return "Node/Express"
60
+ if "postgres" in cmd_lower:
61
+ return "PostgreSQL"
62
+ if "mongod" in cmd_lower or "mongo" in cmd_lower:
63
+ return "MongoDB"
64
+ if "redis" in cmd_lower:
65
+ return "Redis"
66
+ if "celery" in cmd_lower:
67
+ return "Celery"
68
+ return "GenericService"
69
+
70
+
71
+ def _infer_service_name_from_path(repo_root: Path, cwd_path: Path, framework: str) -> str:
72
+ try:
73
+ rel = cwd_path.relative_to(repo_root)
74
+ parts = rel.parts
75
+ if parts:
76
+ if parts[0] in ("apps", "packages", "services") and len(parts) > 1:
77
+ return parts[1]
78
+ return parts[-1]
79
+ except Exception:
80
+ pass
81
+ return framework.lower().replace(".", "").replace("/", "-")
82
+
83
+
84
+ def discover_static_configured_ports(repo_root: Path) -> dict[int, ServiceEndpoint]:
85
+ """Scan docker-compose, package.json, and .env files with in-memory TTL caching."""
86
+ global _STATIC_PORT_CACHE
87
+ root_key = str(repo_root)
88
+ now = time.monotonic()
89
+ if root_key in _STATIC_PORT_CACHE:
90
+ last_t, cached_map = _STATIC_PORT_CACHE[root_key]
91
+ if now - last_t < _PORT_CACHE_TTL_SEC:
92
+ return cached_map
93
+
94
+ results: dict[int, ServiceEndpoint] = {}
95
+
96
+ # 1. docker-compose.yml / compose.yaml
97
+ for compose_name in ("docker-compose.yml", "docker-compose.yaml", "compose.yaml", "compose.yml"):
98
+ compose_file = repo_root / compose_name
99
+ if compose_file.exists():
100
+ try:
101
+ content = compose_file.read_text(encoding="utf-8", errors="replace")
102
+ # match ports: - "3000:3000" or - 8000:8000
103
+ for m in re.finditer(r"""['"]?(\d{2,5}):(\d{2,5})['"]?""", content):
104
+ host_port = int(m.group(1))
105
+ results[host_port] = ServiceEndpoint(
106
+ port=host_port,
107
+ service_name=f"docker-service-{host_port}",
108
+ framework="DockerContainer",
109
+ relative_repo_path=str(compose_file.relative_to(repo_root)),
110
+ is_live=False,
111
+ )
112
+ except Exception:
113
+ pass
114
+
115
+ # 2. package.json scripts (e.g. -p 3000, PORT=4000)
116
+ for pkg_file in repo_root.glob("**/package.json"):
117
+ if "node_modules" in pkg_file.parts:
118
+ continue
119
+ try:
120
+ content = pkg_file.read_text(encoding="utf-8", errors="replace")
121
+ for m in re.finditer(r"""(?:PORT\s*=\s*|-p\s+|--port\s+)(\d{2,5})""", content):
122
+ port_num = int(m.group(1))
123
+ rel_dir = pkg_file.parent.relative_to(repo_root)
124
+ s_name = pkg_file.parent.name or "web"
125
+ results[port_num] = ServiceEndpoint(
126
+ port=port_num,
127
+ service_name=s_name,
128
+ framework="Node/Web",
129
+ relative_repo_path=str(rel_dir),
130
+ is_live=False,
131
+ )
132
+ except Exception:
133
+ pass
134
+
135
+ # 3. .env files
136
+ for env_file in (repo_root / ".env", repo_root / ".env.development", repo_root / ".env.local"):
137
+ if env_file.exists():
138
+ try:
139
+ content = env_file.read_text(encoding="utf-8", errors="replace")
140
+ for m in re.finditer(r"""^\s*(?:PORT|SERVER_PORT|API_PORT)\s*=\s*(\d{2,5})""", content, re.MULTILINE):
141
+ port_num = int(m.group(1))
142
+ results[port_num] = ServiceEndpoint(
143
+ port=port_num,
144
+ service_name="env-service",
145
+ framework="ConfiguredService",
146
+ relative_repo_path=str(env_file.relative_to(repo_root)),
147
+ is_live=False,
148
+ )
149
+ except Exception:
150
+ pass
151
+
152
+ _STATIC_PORT_CACHE[root_key] = (now, results)
153
+ return results
154
+
155
+
156
+ _PORT_CACHE: tuple[float, list[ServiceEndpoint]] = (0.0, [])
157
+ _STATIC_PORT_CACHE: dict[str, tuple[float, dict[int, ServiceEndpoint]]] = {}
158
+ _PORT_CACHE_TTL_SEC = 5.0
159
+
160
+
161
+ def discover_live_listening_ports(repo_root: Path | None = None) -> list[ServiceEndpoint]:
162
+ """Inspect active OS listening ports on localhost with 5-second TTL cache (Zero-CPU idle)."""
163
+ global _PORT_CACHE
164
+ now = time.monotonic()
165
+ last_time, cached_endpoints = _PORT_CACHE
166
+ if now - last_time < _PORT_CACHE_TTL_SEC and cached_endpoints:
167
+ return cached_endpoints
168
+
169
+ endpoints: list[ServiceEndpoint] = []
170
+ seen_ports: set[int] = set()
171
+
172
+ lsof_bin = shutil.which("lsof")
173
+ if lsof_bin:
174
+ try:
175
+ # lsof -iTCP -sTCP:LISTEN -n -P
176
+ proc = subprocess.run(
177
+ [lsof_bin, "-iTCP", "-sTCP:LISTEN", "-n", "-P"],
178
+ capture_output=True,
179
+ text=True,
180
+ timeout=3,
181
+ check=False,
182
+ )
183
+ if proc.returncode == 0:
184
+ for line in proc.stdout.splitlines()[1:]:
185
+ parts = line.split()
186
+ if len(parts) >= 9:
187
+ cmd = parts[0]
188
+ pid_str = parts[1]
189
+ addr_str = parts[8]
190
+ # address format: *:3000, 127.0.0.1:8000, [::1]:5432
191
+ m = re.search(r":(\d+)$", addr_str)
192
+ if m:
193
+ port = int(m.group(1))
194
+ if port in seen_ports:
195
+ continue
196
+ seen_ports.add(port)
197
+ pid = int(pid_str) if pid_str.isdigit() else None
198
+ cwd_str = ""
199
+ rel_repo = ""
200
+ if pid:
201
+ cwd_str = _get_process_cwd(pid)
202
+ if repo_root and cwd_str:
203
+ try:
204
+ rel_repo = str(Path(cwd_str).relative_to(repo_root))
205
+ except Exception:
206
+ rel_repo = ""
207
+ framework = _infer_framework_from_cmd(cmd)
208
+ svc_name = (
209
+ _infer_service_name_from_path(repo_root, Path(cwd_str), framework)
210
+ if repo_root and cwd_str
211
+ else cmd
212
+ )
213
+ endpoints.append(
214
+ ServiceEndpoint(
215
+ port=port,
216
+ pid=pid,
217
+ service_name=svc_name,
218
+ framework=framework,
219
+ process_cwd=cwd_str,
220
+ relative_repo_path=rel_repo,
221
+ command=cmd,
222
+ is_live=True,
223
+ )
224
+ )
225
+ except Exception:
226
+ pass
227
+
228
+ _PORT_CACHE = (now, endpoints)
229
+ return endpoints
230
+
231
+
232
+ def _get_process_cwd(pid: int) -> str:
233
+ """Get process working directory securely across macOS and Linux."""
234
+ # 1. Linux /proc/<pid>/cwd
235
+ proc_cwd = Path(f"/proc/{pid}/cwd")
236
+ if proc_cwd.exists():
237
+ try:
238
+ return str(proc_cwd.resolve())
239
+ except Exception:
240
+ pass
241
+
242
+ # 2. macOS lsof -p <pid> | grep cwd
243
+ lsof_bin = shutil.which("lsof")
244
+ if lsof_bin:
245
+ try:
246
+ proc = subprocess.run(
247
+ [lsof_bin, "-a", "-p", str(pid), "-d", "cwd", "-Fn"],
248
+ capture_output=True,
249
+ text=True,
250
+ timeout=1,
251
+ check=False,
252
+ )
253
+ for line in proc.stdout.splitlines():
254
+ if line.startswith("n"):
255
+ return line[1:].strip()
256
+ except Exception:
257
+ pass
258
+ return ""
259
+
260
+
261
+ def resolve_port_to_service(
262
+ port: int,
263
+ repo_root: Path,
264
+ live_endpoints: list[ServiceEndpoint] | None = None,
265
+ ) -> ServiceEndpoint:
266
+ """Identify the exact service, package, and framework for a given localhost port."""
267
+ if live_endpoints is None:
268
+ live_endpoints = discover_live_listening_ports(repo_root)
269
+
270
+ for ep in live_endpoints:
271
+ if ep.port == port:
272
+ return ep
273
+
274
+ static_map = discover_static_configured_ports(repo_root)
275
+ if port in static_map:
276
+ return static_map[port]
277
+
278
+ # Common standard ports fallback
279
+ standard_defaults: dict[int, tuple[str, str]] = {
280
+ 3000: ("frontend", "Next.js/React"),
281
+ 5173: ("frontend", "Vite"),
282
+ 8000: ("backend-api", "FastAPI/Django"),
283
+ 4000: ("backend-api", "NestJS/Express"),
284
+ 5000: ("backend-api", "Flask/Express"),
285
+ 5432: ("database", "PostgreSQL"),
286
+ 27017: ("database", "MongoDB"),
287
+ 6379: ("cache", "Redis"),
288
+ 3306: ("database", "MySQL"),
289
+ }
290
+ if port in standard_defaults:
291
+ s_name, fw = standard_defaults[port]
292
+ return ServiceEndpoint(
293
+ port=port,
294
+ service_name=s_name,
295
+ framework=fw,
296
+ is_live=False,
297
+ )
298
+
299
+ return ServiceEndpoint(
300
+ port=port,
301
+ service_name=f"service-{port}",
302
+ framework="Unknown",
303
+ is_live=False,
304
+ )