@dreamtree-org/graphify 1.0.0 → 1.1.2

package/README.md

@@ -1,19 +1,27 @@
 # @dreamtree-org/graphify
 
-Turn a folder of code/docs/papers into a queryable, persistent knowledge graph for AI coding
-assistants. Ships as a CLI, a library, an installable agent skill, and an MCP server.
-
-> **Status: v1.** The full pipeline (`detect -> extract -> build -> cluster -> analyze -> report
-> -> export`), the CLI, the MCP server, and the `graphify install` skill are implemented and
-> tested. Structural (tree-sitter) extraction covers TypeScript/JavaScript (incl. JSX, CommonJS
-> `require()`/dynamic `import()`, decorators, generics), Python, Go, Rust, Java, C#, and Ruby —
-> TypeScript/JavaScript is the most deeply covered of the seven. A few pieces are deliberately
-> deferred rather than faked — see [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the exact list
-> (Obsidian/GraphML/Neo4j export, `--update`/`--mode deep`, real cross-file resolution beyond an
-> import-aware heuristic, non-Claude-Code skill hosts). See
-> [`docs/MASTER-PROMPT.md`](./docs/MASTER-PROMPT.md) for the full spec this package was built
-> from, and [`ARCHITECTURE.md`](./ARCHITECTURE.md) / [`SECURITY.md`](./SECURITY.md) for the
-> architecture and threat model.
+Turn a folder of code into a queryable, persistent knowledge graph — and then use it the way
+a coding agent actually needs to: get the working set for a task, the blast radius of a
+change, the minimal tests to run, a structural review of a diff, and an architecture check —
+each in one command, inside a token budget.
+
+Works with any coding agent that can shell out or speak MCP (Claude Code, Cursor, Windsurf,
+Cline, Codex, opencode, Amp, Gemini CLI, ...). No LLM API key required — extraction is
+tree-sitter AST parsing, deterministic and offline.
+
+## Why
+
+Agents re-read codebases from scratch every session and burn most of their tokens finding
+the right files. A graph fixes retrieval, but node lists alone still leave the agent to
+chase files. graphify closes the loop: its answers are **task-shaped** — actual code
+snippets, test lists, impact checklists, diffs — not just structure.
+
+Token savings depend on the shape of your repo: graph answers have a roughly fixed cost
+(they fill toward their token budget), so the win grows with how much code a naive file
+read would have pulled in. Measured with `graphify benchmark`: **up to ~8x** on this
+repository (~100 files, deep cross-file structure), closer to **~1.5x** on small,
+tightly-organized libraries — and on a trivial question in a tiny repo, reading the file
+directly can be cheaper. Run `graphify benchmark` on your own repo before quoting a number.
 
 ## Install
 
@@ -23,44 +31,111 @@ npm install -g @dreamtree-org/graphify
 npx @dreamtree-org/graphify .
 ```
 
-## Usage
+## Build the graph
 
 ```bash
-graphify .                      # full pipeline on the current directory
-graphify <path>                 # full pipeline on a path
-graphify <github-url>           # git clone --depth 1, then run the pipeline
-graphify <path> --no-viz        # skip graph.html
-graphify <path> --cluster-only  # rerun clustering on an existing graph.json
-graphify <path> --watch         # rebuild on file change (chokidar, no LLM involved)
-graphify <path> --leiden        # cluster with Leiden instead of Louvain (v2 — better community quality)
-graphify <path> --mcp           # start the MCP stdio server instead of the pipeline
-
-graphify query "<question>"     # BFS (or --dfs) traversal — broad context for a question
+graphify .                      # full pipeline: detect -> extract -> build -> cluster -> analyze -> report -> export
+graphify <path>                 # same, on a path
+graphify <github-url>           # git clone --depth 1, then the pipeline
+graphify . --update             # incremental — cached extractions for unchanged files (warm rebuilds ~3x faster)
+graphify . --no-viz             # skip graph.html
+graphify . --leiden             # Leiden instead of Louvain community detection
+graphify . --watch              # rebuild on file change
+graphify . --mysql <dsn>        # also extract a MySQL schema (mysql://user:pass@host:port/db) into the same graph
+graphify . --mcp                # start the MCP stdio server instead of running the pipeline
+```
+
+Outputs land in `graphify-out/`: `graph.json` (GraphRAG-ready), `graph.html` (interactive,
+fully offline), `GRAPH_REPORT.md` (plain-language audit: god nodes, surprises, open questions).
+
+Languages: TypeScript/JavaScript (JSX, CommonJS, decorators, re-exports — deepest coverage),
+Python, Go, Rust, Java, C#, Ruby, plus MySQL schemas. Cross-file references are resolved in a
+whole-corpus pass, so imports land on real definitions, not guesses.
+
+## Ask the graph
+
+```bash
+graphify context "<task>"       # THE first call for any task: a token-budgeted pack of the actual
+                                #   code (real snippets at real line ranges), graph-ranked (--budget)
+graphify query "<question>"     # BFS/DFS traversal — fuzzy and identifier-aware: natural-language
+                                #   words match camelCase symbols, typos still resolve (--budget tokens)
+graphify affected "<node>"      # reverse impact analysis — everything that transitively depends on
+                                #   a node, grouped by depth, blast radius split by confidence
+graphify tests "<node>"         # minimal test files worth running for a change (static, no coverage
+graphify tests --changed [rev]  #   instrumentation) — or for the whole working-tree diff
+graphify review <base> [head]   # structural review between two git revs: added/removed/rewired
+                                #   symbols, each with blast radius + suggested tests
+graphify check                  # architecture guardrails from graphify.rules.json — exits 1 on
+                                #   violations, so agents and CI can gate on it
 graphify path "<A>" "<B>"       # shortest path between two named nodes
-graphify explain "<node>"       # plain-language explanation of a node
-graphify install                # install the skill files into your local AI assistant(s)
+graphify explain "<node>"       # a node's location, community, and every edge in/out
+graphify benchmark [q...]       # measure the token savings on your own repo
 ```
 
-`--svg`/`--graphml`/`--neo4j`/`--obsidian`, `--update`, and `--mode deep` are accepted but not
-yet implemented in v1 (`--svg`/`--graphml`/`--neo4j`/`--obsidian` print a clear warning and are
-skipped; `--update` runs the full pipeline; `--mode deep` is a no-op) — see
-[`ARCHITECTURE.md`](./ARCHITECTURE.md#status--whats-real-vs-deliberately-deferred).
+## Close the loop
+
+```bash
+graphify save-result --question Q --answer A --nodes id... --outcome useful|dead_end|corrected
+graphify reflect                # aggregate results into graphify-out/reflections/LESSONS.md
+                                #   (recency-weighted; agents read it at session start)
+graphify hook install           # auto-rebuild (incremental) after every commit and pull
+graphify install --platform all # install the agent skill/rules: claude, cursor, windsurf, cline,
+                                #   agents (AGENTS.md: Codex/opencode/Amp), gemini
+```
+
+With hooks installed the MCP server always serves a fresh graph — it re-reads `graph.json`
+on every tool call.
+
+## Cross-project graphs
+
+```bash
+graphify global add [path]      # register a built project (name from package.json)
+graphify global build           # merge all registered projects into one global graph
+graphify merge <dirA> <dirB>    # one-shot merge (--out <dir>)
+```
+
+Per-project node ids are namespaced; shared dependencies (`module:lodash`) stay unprefixed,
+so repos that use the same packages are automatically bridged in the merged graph.
+
+## MCP server
+
+`graphify --mcp` (or the `graphify-mcp` binary) exposes `context`, `query`, `path`,
+`explain`, `affected`, and `tests` as MCP tools over stdio. No network listener.
+
+## Guardrails file
+
+`graphify.rules.json` at the repo root (this repo dogfoods its own):
+
+```json
+{
+  "rules": [
+    {
+      "name": "extractors-stay-cli-agnostic",
+      "from": "src/extractors/**",
+      "disallow": ["src/cli/**", "src/mcp/**"],
+      "reason": "language extractors are pure library code"
+    }
+  ]
+}
+```
 
 ## What this does NOT do
 
 - No network listener — the MCP server is stdio-only.
-- No code execution from source content — extraction is AST parsing only, never `eval`/`exec`.
+- No code execution from source content — AST parsing only, never `eval`/`exec`.
 - No `shell: true` / string-built shell commands.
-- No credential persistence — API keys are read from env vars per call.
+- No credential leakage — MySQL DSN credentials never appear in graph output, reports, or
+  logs (only the credential-free `mysql://host:port/db` form does).
 
-See [`SECURITY.md`](./SECURITY.md) for the full threat model.
+Full threat model: [`docs/SECURITY.md`](./docs/SECURITY.md). Architecture and design notes:
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
 
 ## Development
 
 ```bash
 npm install
 npm run build
-npm test
+npm test        # ~300 unit tests, no network, no side effects outside temp dirs
 npm run lint
 ```
 

package/dist/chunk-6JLEILYF.js

@@ -0,0 +1,207 @@
+// src/security.ts
+import { createHash } from "crypto";
+import * as dns from "dns";
+import * as http from "http";
+import * as https from "https";
+import * as fs from "fs";
+import * as net from "net";
+import * as nodePath from "path";
+var ALLOWED_SCHEMES = /* @__PURE__ */ new Set(["http:", "https:"]);
+var MAX_FETCH_BYTES = 50 * 1024 * 1024;
+var MAX_TEXT_BYTES = 10 * 1024 * 1024;
+var MAX_LABEL_LEN = 256;
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "metadata.google.internal",
+  "metadata.internal",
+  "metadata",
+  "metadata.azure.com",
+  "instance-data",
+  "instance-data.ec2.internal"
+]);
+function ipv4ToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let result = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const n = Number(part);
+    if (n > 255) return null;
+    result = result << 8 | n;
+  }
+  return result >>> 0;
+}
+function ipv4InCidr(ipInt, cidr) {
+  const [base, prefixStr] = cidr.split("/");
+  const prefix = Number(prefixStr);
+  const baseInt = ipv4ToInt(base ?? "");
+  if (baseInt === null) return false;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return (ipInt & mask) >>> 0 === (baseInt & mask) >>> 0;
+}
+var BLOCKED_IPV4_CIDRS = [
+  "0.0.0.0/8",
+  // "this" network
+  "10.0.0.0/8",
+  // private
+  "100.64.0.0/10",
+  // carrier-grade NAT (CGN)
+  "127.0.0.0/8",
+  // loopback
+  "169.254.0.0/16",
+  // link-local (covers 169.254.169.254 cloud metadata)
+  "172.16.0.0/12",
+  // private
+  "192.0.0.0/24",
+  // IETF protocol assignments
+  "192.0.2.0/24",
+  // TEST-NET-1
+  "192.168.0.0/16",
+  // private
+  "198.18.0.0/15",
+  // benchmarking
+  "198.51.100.0/24",
+  // TEST-NET-2
+  "203.0.113.0/24",
+  // TEST-NET-3
+  "224.0.0.0/4",
+  // multicast
+  "240.0.0.0/4",
+  // reserved
+  "255.255.255.255/32"
+  // broadcast
+];
+function isForbiddenIpv4(ip) {
+  const ipInt = ipv4ToInt(ip);
+  if (ipInt === null) return true;
+  return BLOCKED_IPV4_CIDRS.some((cidr) => ipv4InCidr(ipInt, cidr));
+}
+function expandIpv6(ip) {
+  const withoutZone = ip.split("%")[0] ?? "";
+  const parts = withoutZone.split("::");
+  if (parts.length > 2) return null;
+  const head = parts[0] ? parts[0].split(":").filter((s) => s.length > 0) : [];
+  const tail = parts.length === 2 && parts[1] ? parts[1].split(":").filter((s) => s.length > 0) : [];
+  let missing = 0;
+  if (parts.length === 2) {
+    missing = 8 - head.length - tail.length;
+    if (missing < 0) return null;
+  } else if (head.length + tail.length !== 8) {
+    return null;
+  }
+  const groupsHex = [...head, ...Array(missing).fill("0"), ...tail];
+  if (groupsHex.length !== 8) return null;
+  const groups = [];
+  for (const g of groupsHex) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null;
+    groups.push(parseInt(g, 16));
+  }
+  return groups;
+}
+function isForbiddenIpv6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === "::1" || lower === "::") return true;
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+  if (mapped) return isForbiddenIpv4(mapped[1]);
+  const groups = expandIpv6(lower);
+  if (groups === null) return true;
+  const first = groups[0];
+  if ((first & 65472) === 65152) return true;
+  if ((first & 65024) === 64512) return true;
+  if ((first & 65280) === 65280) return true;
+  if (groups.every((g) => g === 0)) return true;
+  return false;
+}
+function isForbiddenIp(ip) {
+  return net.isIPv6(ip) ? isForbiddenIpv6(ip) : isForbiddenIpv4(ip);
+}
+function validateUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+    throw new Error(
+      `URL scheme not allowed: "${parsed.protocol}" (allowed: ${[...ALLOWED_SCHEMES].join(", ")})`
+    );
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  if (BLOCKED_HOSTNAMES.has(hostname)) {
+    throw new Error(`URL targets a blocked host: ${hostname}`);
+  }
+  const bareHost = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  if (net.isIP(bareHost) && isForbiddenIp(bareHost)) {
+    throw new Error(`URL targets a forbidden IP address: ${bareHost}`);
+  }
+  return parsed.toString();
+}
+var DEFAULT_MYSQL_PORT = 3306;
+function validateDsn(dsn) {
+  let parsed;
+  try {
+    parsed = new URL(dsn);
+  } catch {
+    throw new Error("Invalid DSN \u2014 expected mysql://user:pass@host:port/database");
+  }
+  if (parsed.protocol !== "mysql:") {
+    throw new Error(`DSN scheme not supported: "${parsed.protocol}" (only mysql: is supported)`);
+  }
+  const database = decodeURIComponent(parsed.pathname.replace(/^\//, ""));
+  if (!database || database.includes("/")) {
+    throw new Error("DSN must name exactly one database, e.g. mysql://localhost:3306/mydb");
+  }
+  if (!parsed.hostname) {
+    throw new Error("DSN must include a host, e.g. mysql://localhost:3306/mydb");
+  }
+  const port = parsed.port ? Number(parsed.port) : DEFAULT_MYSQL_PORT;
+  return {
+    safeDisplay: `mysql://${parsed.hostname}:${port}/${database}`,
+    connection: {
+      host: parsed.hostname,
+      port,
+      user: decodeURIComponent(parsed.username) || "root",
+      password: decodeURIComponent(parsed.password),
+      database
+    }
+  };
+}
+function validateGraphPath(path, base) {
+  const baseDir = base ?? nodePath.join(process.cwd(), "graphify-out");
+  let resolvedBase;
+  try {
+    resolvedBase = fs.realpathSync(baseDir);
+  } catch {
+    throw new Error(`Base directory does not exist: ${baseDir}`);
+  }
+  const candidate = nodePath.isAbsolute(path) ? path : nodePath.join(resolvedBase, path);
+  const resolvedCandidate = nodePath.resolve(candidate);
+  let realCandidate = resolvedCandidate;
+  try {
+    realCandidate = fs.realpathSync(resolvedCandidate);
+  } catch {
+  }
+  const relative2 = nodePath.relative(resolvedBase, realCandidate);
+  const escapes = relative2 === ".." || relative2.startsWith(`..${nodePath.sep}`) || nodePath.isAbsolute(relative2);
+  if (escapes) {
+    throw new Error(`Path escapes graphify-out/: ${path}`);
+  }
+  return realCandidate;
+}
+function sanitizeLabel(text) {
+  if (text == null) return "";
+  const stripped = String(text).replace(/[\x00-\x1f\x7f]/g, "");
+  return stripped.slice(0, MAX_LABEL_LEN);
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+export {
+  validateUrl,
+  validateDsn,
+  validateGraphPath,
+  sanitizeLabel,
+  escapeHtml
+};
+//# sourceMappingURL=chunk-6JLEILYF.js.map

package/dist/chunk-6JLEILYF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/security.ts"],"sourcesContent":["/**\n * Security helpers — URL validation, SSRF-guarded fetch, path guards, label\n * sanitization, prompt-injection defenses. Every control listed in\n * SECURITY.md must have a corresponding function here and a unit test in\n * tests/security.test.ts. See the master prompt §5 for the full checklist.\n */\n\nimport { createHash } from 'node:crypto';\nimport * as dns from 'node:dns';\nimport * as http from 'node:http';\nimport * as https from 'node:https';\nimport * as fs from 'node:fs';\nimport * as net from 'node:net';\nimport * as nodePath from 'node:path';\n\nconst ALLOWED_SCHEMES = new Set(['http:', 'https:']);\nconst MAX_FETCH_BYTES = 50 * 1024 * 1024;\nconst MAX_TEXT_BYTES = 10 * 1024 * 1024;\nconst MAX_LABEL_LEN = 256;\nconst MAX_REDIRECTS = 5;\nconst REQUEST_TIMEOUT_MS = 15_000;\n\n/** Hostnames that must never be reachable, regardless of what they resolve to. */\nconst BLOCKED_HOSTNAMES = new Set([\n  'metadata.google.internal',\n  'metadata.internal',\n  'metadata',\n  'metadata.azure.com',\n  'instance-data',\n  'instance-data.ec2.internal',\n]);\n\n// ---------------------------------------------------------------------------\n// IP range checks (SSRF guard core). Implemented without extra dependencies.\n// ---------------------------------------------------------------------------\n\nfunction ipv4ToInt(ip: string): number | null {\n  const parts = ip.split('.');\n  if (parts.length !== 4) return null;\n  let result = 0;\n  for (const part of parts) {\n    if (!/^\\d{1,3}$/.test(part)) return null;\n    const n = Number(part);\n    if (n > 255) return null;\n    result = (result << 8) | n;\n  }\n  return result >>> 0;\n}\n\nfunction ipv4InCidr(ipInt: number, cidr: string): boolean {\n  const [base, prefixStr] = cidr.split('/');\n  const prefix = Number(prefixStr);\n  const baseInt = ipv4ToInt(base ?? '');\n  if (baseInt === null) return false;\n  const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;\n  return (ipInt & mask) >>> 0 === (baseInt & mask) >>> 0;\n}\n\n/** IPv4 ranges that must never be connected to from a server-side fetch. */\nconst BLOCKED_IPV4_CIDRS = [\n  '0.0.0.0/8', // \"this\" network\n  '10.0.0.0/8', // private\n  '100.64.0.0/10', // carrier-grade NAT (CGN)\n  '127.0.0.0/8', // loopback\n  '169.254.0.0/16', // link-local (covers 169.254.169.254 cloud metadata)\n  '172.16.0.0/12', // private\n  '192.0.0.0/24', // IETF protocol assignments\n  '192.0.2.0/24', // TEST-NET-1\n  '192.168.0.0/16', // private\n  '198.18.0.0/15', // benchmarking\n  '198.51.100.0/24', // TEST-NET-2\n  '203.0.113.0/24', // TEST-NET-3\n  '224.0.0.0/4', // multicast\n  '240.0.0.0/4', // reserved\n  '255.255.255.255/32', // broadcast\n];\n\nexport function isForbiddenIpv4(ip: string): boolean {\n  const ipInt = ipv4ToInt(ip);\n  if (ipInt === null) return true; // malformed -> treat as forbidden, fail closed\n  return BLOCKED_IPV4_CIDRS.some((cidr) => ipv4InCidr(ipInt, cidr));\n}\n\n/** Expand a (possibly `::`-compressed) IPv6 address into 8 16-bit groups. */\nfunction expandIpv6(ip: string): number[] | null {\n  const withoutZone = ip.split('%')[0] ?? '';\n  const parts = withoutZone.split('::');\n  if (parts.length > 2) return null;\n\n  const head = parts[0] ? parts[0].split(':').filter((s) => s.length > 0) : [];\n  const tail = parts.length === 2 && parts[1] ? parts[1].split(':').filter((s) => s.length > 0) : [];\n\n  let missing = 0;\n  if (parts.length === 2) {\n    missing = 8 - head.length - tail.length;\n    if (missing < 0) return null;\n  } else if (head.length + tail.length !== 8) {\n    return null;\n  }\n\n  const groupsHex = [...head, ...Array(missing).fill('0'), ...tail];\n  if (groupsHex.length !== 8) return null;\n\n  const groups: number[] = [];\n  for (const g of groupsHex) {\n    if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null;\n    groups.push(parseInt(g, 16));\n  }\n  return groups;\n}\n\nexport function isForbiddenIpv6(ip: string): boolean {\n  const lower = ip.toLowerCase();\n  if (lower === '::1' || lower === '::') return true;\n\n  const mapped = /^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/.exec(lower);\n  if (mapped) return isForbiddenIpv4(mapped[1] as string);\n\n  const groups = expandIpv6(lower);\n  if (groups === null) return true; // unparsable -> fail closed\n  const first = groups[0] as number;\n  if ((first & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local\n  if ((first & 0xfe00) === 0xfc00) return true; // fc00::/7 unique local\n  if ((first & 0xff00) === 0xff00) return true; // ff00::/8 multicast\n  if (groups.every((g) => g === 0)) return true; // unspecified/all-zero\n  return false;\n}\n\nexport function isForbiddenIp(ip: string): boolean {\n  return net.isIPv6(ip) ? isForbiddenIpv6(ip) : isForbiddenIpv4(ip);\n}\n\n// ---------------------------------------------------------------------------\n// URL validation\n// ---------------------------------------------------------------------------\n\n/**\n * Validate a URL is http/https and, when the hostname is itself a literal\n * IP or a known cloud-metadata hostname, reject it synchronously. DNS-bound\n * hostnames are re-validated at connect time by safeFetch() (see below) —\n * this function alone cannot rule out DNS rebinding for a hostname that\n * currently resolves to a public IP.\n */\nexport function validateUrl(url: string): string {\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    throw new Error(`Invalid URL: ${url}`);\n  }\n\n  if (!ALLOWED_SCHEMES.has(parsed.protocol)) {\n    throw new Error(\n      `URL scheme not allowed: \"${parsed.protocol}\" (allowed: ${[...ALLOWED_SCHEMES].join(', ')})`,\n    );\n  }\n\n  const hostname = parsed.hostname.toLowerCase();\n  if (BLOCKED_HOSTNAMES.has(hostname)) {\n    throw new Error(`URL targets a blocked host: ${hostname}`);\n  }\n\n  // WHATWG URL keeps the brackets on an IPv6 literal host (e.g. \"[::1]\") —\n  // strip them before checking net.isIP()/isForbiddenIp().\n  const bareHost =\n    hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;\n  if (net.isIP(bareHost) && isForbiddenIp(bareHost)) {\n    throw new Error(`URL targets a forbidden IP address: ${bareHost}`);\n  }\n\n  return parsed.toString();\n}\n\n// ---------------------------------------------------------------------------\n// safeFetch — SSRF-guarded, size-capped, redirect-revalidating fetch\n// ---------------------------------------------------------------------------\n\nexport type LookupFn = (hostname: string) => Promise<{ address: string; family: number }>;\n\n/**\n * Resolve a hostname (or pass through a literal IP) and validate the\n * result. `lookup` defaults to the real `dns.promises.lookup` — tests\n * substitute a fake to exercise the rebind guard deterministically without\n * making a real DNS query.\n */\nexport async function resolveAndValidate(\n  hostname: string,\n  lookup: LookupFn = dns.promises.lookup,\n): Promise<{ address: string; family: number }> {\n  if (net.isIP(hostname)) {\n    if (isForbiddenIp(hostname)) {\n      throw new Error(`Refusing to connect to forbidden IP: ${hostname}`);\n    }\n    return { address: hostname, family: net.isIPv6(hostname) ? 6 : 4 };\n  }\n  const result = await lookup(hostname);\n  if (isForbiddenIp(result.address)) {\n    throw new Error(`Refusing to connect to forbidden IP: ${hostname} -> ${result.address}`);\n  }\n  return result;\n}\n\nexport interface RawResponse {\n  statusCode: number;\n  headers: http.IncomingHttpHeaders;\n  body: Buffer;\n}\n\n/** Minimal shape of the `http`/`https` modules that requestOnce() needs — narrow on purpose so tests can substitute a fake transport instead of mocking network I/O. */\nexport type RequestTransport = Pick<typeof http, 'request'>;\n\n/**\n * Issue a single HTTP(S) request, connecting to `resolvedAddress` directly\n * (via a `lookup` override) rather than re-resolving DNS at connect time —\n * this is what prevents a DNS-rebind attacker from swapping the target\n * between validation and connection (TOCTOU). Streams the body and aborts\n * once it exceeds the byte cap for its declared content type.\n */\nexport function requestOnce(\n  target: URL,\n  resolvedAddress: string,\n  resolvedFamily: number,\n  transport: RequestTransport = target.protocol === 'https:' ? https : http,\n): Promise<RawResponse> {\n  return new Promise((resolve, reject) => {\n    const req = transport.request(\n      {\n        protocol: target.protocol,\n        hostname: target.hostname,\n        host: target.hostname,\n        port: target.port || (target.protocol === 'https:' ? 443 : 80),\n        path: `${target.pathname}${target.search}`,\n        method: 'GET',\n        timeout: REQUEST_TIMEOUT_MS,\n        headers: { 'user-agent': 'graphify/0.1', accept: '*/*' },\n        // Force the connection to the address we already validated — do not\n        // let Node re-resolve `target.hostname` at connect time.\n        lookup: (\n          _hostname: string,\n          options: unknown,\n          callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,\n        ) => {\n          callback(null, resolvedAddress, resolvedFamily);\n        },\n      } as http.RequestOptions,\n      (res) => {\n        const statusCode = res.statusCode ?? 0;\n        const contentType = String(res.headers['content-type'] ?? '');\n        const isTextual = /^text\\/|json|xml|html|charset=/i.test(contentType);\n        const cap = isTextual ? MAX_TEXT_BYTES : MAX_FETCH_BYTES;\n\n        const chunks: Buffer[] = [];\n        let total = 0;\n        let aborted = false;\n\n        res.on('data', (chunk: Buffer) => {\n          total += chunk.length;\n          if (total > cap) {\n            aborted = true;\n            res.destroy();\n            req.destroy();\n            reject(new Error(`Response exceeded ${cap} byte cap (content-type: ${contentType})`));\n            return;\n          }\n          chunks.push(chunk);\n        });\n        res.on('end', () => {\n          if (aborted) return;\n          resolve({ statusCode, headers: res.headers, body: Buffer.concat(chunks) });\n        });\n        res.on('error', (err) => {\n          if (!aborted) reject(err);\n        });\n      },\n    );\n\n    req.on('timeout', () => {\n      req.destroy(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`));\n    });\n    req.on('error', reject);\n    req.end();\n  });\n}\n\nexport interface SafeFetchDeps {\n  /** Override DNS resolution + IP validation (default: resolveAndValidate). */\n  resolve?: (hostname: string) => Promise<{ address: string; family: number }>;\n  /** Override the actual request (default: requestOnce against real http/https). */\n  request?: (target: URL, address: string, family: number) => Promise<RawResponse>;\n}\n\n/**\n * Fetch a URL with the SSRF guards from validateUrl() plus streaming size\n * caps (MAX_FETCH_BYTES / MAX_TEXT_BYTES) and a hard error on non-2xx\n * status. Every redirect hop is independently validated and re-resolved —\n * a redirect to a private/loopback/metadata address is rejected exactly\n * like a direct request would be.\n *\n * `deps` exists so tests can substitute the DNS/network collaborators with\n * deterministic fakes (see tests/security.test.ts) instead of mocking\n * Node's core modules or hitting real sockets — production callers should\n * never need to pass it.\n */\nexport async function safeFetch(url: string, deps: SafeFetchDeps = {}): Promise<Buffer> {\n  const resolve = deps.resolve ?? resolveAndValidate;\n  const doRequest = deps.request ?? requestOnce;\n\n  let current = validateUrl(url);\n  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {\n    const target = new URL(current);\n    const { address, family } = await resolve(target.hostname);\n    const response = await doRequest(target, address, family);\n\n    if (response.statusCode >= 300 && response.statusCode < 400) {\n      const location = response.headers.location;\n      if (!location) {\n        throw new Error(`Redirect response (${response.statusCode}) missing Location header`);\n      }\n      const next = new URL(location, target).toString();\n      current = validateUrl(next);\n      continue;\n    }\n\n    if (response.statusCode < 200 || response.statusCode >= 300) {\n      throw new Error(`Non-2xx response: ${response.statusCode}`);\n    }\n\n    return response.body;\n  }\n  throw new Error(`Too many redirects (> ${MAX_REDIRECTS}) while fetching ${url}`);\n}\n\n// ---------------------------------------------------------------------------\n// Database DSN validation (MySQL schema extraction)\n// ---------------------------------------------------------------------------\n\nexport interface ValidatedDsn {\n  /**\n   * Credential-free rendering (`mysql://host:port/db`). This is the ONLY\n   * form that may ever appear in graph nodes, reports, logs, or errors —\n   * the password exists solely inside `connection`.\n   */\n  safeDisplay: string;\n  connection: {\n    host: string;\n    port: number;\n    user: string;\n    password: string;\n    database: string;\n  };\n}\n\nconst DEFAULT_MYSQL_PORT = 3306;\n\n/**\n * Parse and validate a `mysql://user:pass@host:port/database` DSN.\n *\n * Deliberately does NOT apply the SSRF IP blocklist that safeFetch()\n * enforces: connecting to a localhost/private-network database is the\n * primary legitimate use of an explicitly user-supplied DSN, unlike a URL\n * scraped out of corpus content. The security property that matters here\n * is credential containment — see ValidatedDsn.safeDisplay.\n */\nexport function validateDsn(dsn: string): ValidatedDsn {\n  let parsed: URL;\n  try {\n    parsed = new URL(dsn);\n  } catch {\n    throw new Error('Invalid DSN — expected mysql://user:pass@host:port/database');\n  }\n\n  if (parsed.protocol !== 'mysql:') {\n    throw new Error(`DSN scheme not supported: \"${parsed.protocol}\" (only mysql: is supported)`);\n  }\n\n  const database = decodeURIComponent(parsed.pathname.replace(/^\\//, ''));\n  if (!database || database.includes('/')) {\n    throw new Error('DSN must name exactly one database, e.g. mysql://localhost:3306/mydb');\n  }\n  if (!parsed.hostname) {\n    throw new Error('DSN must include a host, e.g. mysql://localhost:3306/mydb');\n  }\n\n  const port = parsed.port ? Number(parsed.port) : DEFAULT_MYSQL_PORT;\n  return {\n    safeDisplay: `mysql://${parsed.hostname}:${port}/${database}`,\n    connection: {\n      host: parsed.hostname,\n      port,\n      user: decodeURIComponent(parsed.username) || 'root',\n      password: decodeURIComponent(parsed.password),\n      database,\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Path traversal guard\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve `path` and require it stays inside `base` (defaults to\n * `<cwd>/graphify-out`). `base` must already exist. Throws on traversal\n * attempts (`../`, absolute escapes, symlink-resolved escapes).\n */\nexport function validateGraphPath(path: string, base?: string): string {\n  const baseDir = base ?? nodePath.join(process.cwd(), 'graphify-out');\n\n  let resolvedBase: string;\n  try {\n    resolvedBase = fs.realpathSync(baseDir);\n  } catch {\n    throw new Error(`Base directory does not exist: ${baseDir}`);\n  }\n\n  const candidate = nodePath.isAbsolute(path) ? path : nodePath.join(resolvedBase, path);\n  const resolvedCandidate = nodePath.resolve(candidate);\n\n  // Resolve symlinks for whichever is the deepest existing ancestor, so a\n  // symlink inside an otherwise-valid path can't escape the base dir either.\n  let realCandidate = resolvedCandidate;\n  try {\n    realCandidate = fs.realpathSync(resolvedCandidate);\n  } catch {\n    // Path (or part of it) may not exist yet (e.g. a file we're about to\n    // write) — fall back to the lexically-resolved path for the check.\n  }\n\n  const relative = nodePath.relative(resolvedBase, realCandidate);\n  const escapes = relative === '..' || relative.startsWith(`..${nodePath.sep}`) || nodePath.isAbsolute(relative);\n  if (escapes) {\n    throw new Error(`Path escapes graphify-out/: ${path}`);\n  }\n\n  return realCandidate;\n}\n\n// ---------------------------------------------------------------------------\n// Label sanitization (unchanged reference implementation) + HTML escaping\n// ---------------------------------------------------------------------------\n\n/** Strip control characters, cap length. Apply to every node/edge label. */\nexport function sanitizeLabel(text: string | null | undefined): string {\n  if (text == null) return '';\n  // eslint-disable-next-line no-control-regex -- intentional: stripping raw control chars\n  const stripped = String(text).replace(/[\\x00-\\x1f\\x7f]/g, '');\n  return stripped.slice(0, MAX_LABEL_LEN);\n}\n\n/**\n * HTML-escape a string. Callers must run sanitizeLabel() first for\n * length/control-char stripping, then escapeHtml() immediately before\n * embedding into graph.html (XSS control, see SECURITY.md).\n */\nexport function escapeHtml(text: string): string {\n  return text\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&#39;');\n}\n\n// ---------------------------------------------------------------------------\n// Prompt-injection defenses for LLM-bound file content\n// ---------------------------------------------------------------------------\n\n/**\n * Known jailbreak / chat-template sentinels that must never reach a prompt\n * unescaped, whether they occur in source files or are forged to spoof our\n * own <untrusted_source> delimiter.\n */\nconst SENTINEL_PATTERNS: RegExp[] = [\n  /<\\|im_start\\|>/gi,\n  /<\\|im_end\\|>/gi,\n  /<\\|system\\|>/gi,\n  /\\[INST\\]/gi,\n  /\\[\\/INST\\]/gi,\n  /<<SYS>>/gi,\n  /<<\\/SYS>>/gi,\n  /<\\/untrusted_source>/gi,\n  /<untrusted_source/gi,\n];\n\n/**\n * Render brackets as fullwidth lookalikes (＜ ＞ ［ ］) so the defanged\n * echo is human-visible but no longer byte-identical to the original\n * sentinel — a naive downstream scan for the literal delimiter/sentinel\n * text will not re-match our own \"we found one\" marker.\n */\nfunction toFullwidthBrackets(text: string): string {\n  return text\n    .replace(/</g, '＜')\n    .replace(/>/g, '＞')\n    .replace(/\\[/g, '［')\n    .replace(/\\]/g, '］');\n}\n\n/**\n * Replace known jailbreak/chat-template sentinels with a visibly defanged\n * form — never silently stripped (silent stripping can itself be an\n * injection vector if it changes meaning unexpectedly).\n */\nfunction defangSentinels(content: string): string {\n  let result = content;\n  for (const pattern of SENTINEL_PATTERNS) {\n    result = result.replace(pattern, (match) => `[DEFANGED:${toFullwidthBrackets(match)}]`);\n  }\n  return result;\n}\n\n/**\n * Wrap file content for LLM prompts in a hash-stamped untrusted-source\n * delimiter and neutralize known jailbreak/chat-template sentinels. This\n * raises the bar against prompt injection; it does not eliminate it —\n * document that plainly wherever this is referenced.\n */\nexport function wrapUntrustedSource(path: string, content: string): string {\n  const sha256 = createHash('sha256').update(content, 'utf8').digest('hex');\n  const safePath = escapeHtml(sanitizeLabel(path));\n  const defanged = defangSentinels(content);\n  return `<untrusted_source path=\"${safePath}\" sha256=\"${sha256}\">\\n${defanged}\\n</untrusted_source>`;\n}\n"],"mappings":"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","names":["relative"]}