whygraph 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,340 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import * as yaml from "js-yaml";
+import { generateId } from "../entity/id.js";
+import { writeEntity } from "../entity/writer.js";
+function findWhygraphDir(startDir) {
+    let dir = startDir;
+    while (true) {
+        if (existsSync(join(dir, ".whygraph", "config.yaml")))
+            return dir;
+        const parent = join(dir, "..");
+        /* v8 ignore next 2 */
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function getMcpMode(projectDir) {
+    // Env var takes precedence (useful for testing)
+    if (process.env["WHYGRAPH_MCP_MODE"])
+        return process.env["WHYGRAPH_MCP_MODE"];
+    /* v8 ignore next 9 */
+    if (!projectDir)
+        return "default";
+    try {
+        const raw = readFileSync(join(projectDir, ".whygraph", "config.yaml"), "utf-8");
+        const config = yaml.load(raw);
+        /* v8 ignore next 1 */
+        return config.mcpMode ?? "default";
+    }
+    catch {
+        /* v8 ignore next 1 */
+        return "default";
+    }
+}
+const DEFAULT_PORT = 4777;
+function getPort() {
+    const env = process.env["WHYGRAPH_PORT"];
+    /* v8 ignore next 4 */
+    if (env) {
+        const parsed = parseInt(env, 10);
+        if (!isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_PORT;
+}
+function getEndpoint() {
+    return `http://localhost:${getPort()}/api/graphql`;
+}
+async function queryGraphQL(query, variables) {
+    const endpoint = getEndpoint();
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query, variables }),
+        });
+    }
+    catch {
+        throw new Error(`Cannot connect to whygraph server at ${endpoint}. Is the server running? Start it with: whygraph serve`);
+    }
+    const json = (await response.json());
+    if (json.errors && json.errors.length > 0) {
+        throw new Error(`GraphQL error: ${json.errors.map((e) => e.message).join(", ")}`);
+    }
+    /* v8 ignore next 3 */
+    if (!json.data) {
+        throw new Error("No data returned from GraphQL query");
+    }
+    return json.data;
+}
+function textResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function createMcpServer() {
+    const projectDir = findWhygraphDir(process.cwd());
+    const mcpMode = getMcpMode(projectDir);
+    const server = new McpServer({
+        name: "whygraph",
+        version: "0.2.0",
+    });
+    // whygraph_context
+    server.registerTool("whygraph_context", {
+        description: "Get architectural context for a file/symbol. Returns structural nodes and decisions that affect the given code location.",
+        inputSchema: {
+            file: z.string().describe("File path to get context for"),
+            symbol: z.string().optional().describe("Optional symbol name within the file"),
+        },
+    }, async ({ file, symbol }) => {
+        try {
+            const variables = { file };
+            if (symbol !== undefined)
+                variables["symbol"] = symbol;
+            const query = `
+        query Context($file: String!, $symbol: String) {
+          context(file: $file, symbol: $symbol) {
+            nodes { id label name parentChain }
+            decisions { id title status date affects tags context decision tradeoffs alternatives }
+          }
+        }
+      `;
+            const data = await queryGraphQL(query, variables);
+            return textResult(data.context);
+        }
+        catch (err) {
+            return errorResult(err.message);
+        }
+    });
+    // whygraph_get_decisions
+    server.registerTool("whygraph_get_decisions", {
+        description: "Query decisions with optional filters for status, tags, and date range.",
+        inputSchema: {
+            status: z.string().optional().describe("Filter by decision status (active or superseded)"),
+            tags: z.array(z.string()).optional().describe("Filter by tags"),
+            dateFrom: z.string().optional().describe("Filter decisions from this date (YYYY-MM-DD)"),
+            dateTo: z.string().optional().describe("Filter decisions up to this date (YYYY-MM-DD)"),
+        },
+    }, async ({ status, tags, dateFrom, dateTo }) => {
+        try {
+            const variables = {};
+            if (status !== undefined)
+                variables["status"] = status;
+            if (tags !== undefined)
+                variables["tags"] = tags;
+            if (dateFrom !== undefined)
+                variables["dateFrom"] = dateFrom;
+            if (dateTo !== undefined)
+                variables["dateTo"] = dateTo;
+            const query = `
+        query Decisions($status: String, $tags: [String!], $dateFrom: String, $dateTo: String) {
+          decisions(status: $status, tags: $tags, dateFrom: $dateFrom, dateTo: $dateTo) {
+            id title status date affects tags context decision tradeoffs alternatives
+          }
+        }
+      `;
+            const data = await queryGraphQL(query, variables);
+            return textResult(data.decisions);
+        }
+        catch (err) {
+            return errorResult(err.message);
+        }
+    });
+    // whygraph_get_gaps
+    server.registerTool("whygraph_get_gaps", {
+        description: "Find structural nodes that have no associated decisions (coverage gaps).",
+        inputSchema: {
+            limit: z.number().optional().describe("Maximum number of gaps to return"),
+        },
+    }, async ({ limit }) => {
+        try {
+            const variables = {};
+            if (limit !== undefined)
+                variables["limit"] = limit;
+            const query = `
+        query Gaps($limit: Int) {
+          gaps(limit: $limit) {
+            id label name status parent
+          }
+        }
+      `;
+            const data = await queryGraphQL(query, variables);
+            return textResult(data.gaps);
+        }
+        catch (err) {
+            return errorResult(err.message);
+        }
+    });
+    // whygraph_list_nodes
+    server.registerTool("whygraph_list_nodes", {
+        description: "List structural nodes with optional filters for label, parent, and search text.",
+        inputSchema: {
+            label: z.string().optional().describe("Filter by node label (App, Feature, Component)"),
+            parent: z.string().optional().describe("Filter by parent node ID"),
+            search: z.string().optional().describe("Search nodes by name"),
+        },
+    }, async ({ label, parent, search }) => {
+        try {
+            const variables = {};
+            if (label !== undefined)
+                variables["label"] = label;
+            if (parent !== undefined)
+                variables["parent"] = parent;
+            if (search !== undefined)
+                variables["search"] = search;
+            const query = `
+        query Nodes($label: String, $parent: String, $search: String) {
+          nodes(label: $label, parent: $parent, search: $search) {
+            id label name parent
+          }
+        }
+      `;
+            const data = await queryGraphQL(query, variables);
+            return textResult(data.nodes);
+        }
+        catch (err) {
+            return errorResult(err.message);
+        }
+    });
+    // Write tools — only registered in strict mode
+    if (mcpMode === "strict") {
+        registerWriteTools(server);
+    }
+    return server;
+}
+function registerWriteTools(server) {
+    // whygraph_create_decision
+    server.registerTool("whygraph_create_decision", {
+        description: "Create a new decision node in the whygraph.",
+        inputSchema: {
+            title: z.string().min(1).describe("Decision title"),
+            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("Decision date (YYYY-MM-DD)"),
+            affects: z.array(z.string().min(1)).min(1).describe("IDs of structural nodes this decision affects"),
+            tags: z.array(z.string()).min(1).describe("Decision tags (arch, data, security, performance, integration, infra, ux)"),
+            context: z.string().min(1).describe("Context explaining why this decision was needed"),
+            decision: z.string().min(1).describe("The decision that was made"),
+            tradeoffs: z.string().min(1).describe("Tradeoffs of the decision"),
+            alternatives: z.string().min(1).describe("Alternatives that were considered"),
+            supersedes: z.string().optional().describe("ID of the decision this supersedes"),
+        },
+    }, async ({ title, date, affects, tags, context, decision, tradeoffs, alternatives, supersedes }) => {
+        try {
+            const variables = {
+                title, date, affects, tags, context, decision, tradeoffs, alternatives,
+            };
+            if (supersedes !== undefined)
+                variables["supersedes"] = supersedes;
+            const query = `
+        mutation CreateDecision(
+          $title: String!, $date: String!, $affects: [String!]!, $tags: [String!]!,
+          $context: String!, $decision: String!, $tradeoffs: String!, $alternatives: String!,
+          $supersedes: String
+        ) {
+          createDecision(
+            title: $title, date: $date, affects: $affects, tags: $tags,
+            context: $context, decision: $decision, tradeoffs: $tradeoffs,
+            alternatives: $alternatives, supersedes: $supersedes
+          ) {
+            id title status date affects tags context decision tradeoffs alternatives supersedes
+            created_at updated_at
+          }
+        }
+      `;
+            const data = await queryGraphQL(query, variables);
+            return textResult(data.createDecision);
+        }
+        catch {
+            // Fallback: write directly to disk when server is unreachable
+            const projectDir = findWhygraphDir(process.cwd());
+            /* v8 ignore next 1 */
+            if (!projectDir)
+                return errorResult("Cannot find .whygraph directory and server is unreachable");
+            const now = new Date().toISOString();
+            const id = generateId({ prefix: "wg-", length: 4 });
+            const entity = {
+                id, label: "Decision", title, status: "active", date,
+                affects, tags: tags,
+                context, decision, tradeoffs, alternatives,
+                supersedes, created_at: now, updated_at: now,
+            };
+            const { filePath, validation } = writeEntity(join(projectDir, ".whygraph", "graph"), entity);
+            /* v8 ignore next 2 */
+            const warnings = validation.errors.length > 0
+                ? ` (${validation.errors.length} validation issue(s) — written to disk, server will reconcile)`
+                : "";
+            return textResult({ ...entity, _fallback: true, _filePath: filePath, _note: `Server unreachable, wrote to disk${warnings}` });
+        }
+    });
+    // whygraph_create_node
+    server.registerTool("whygraph_create_node", {
+        description: "Create a new structural node in the whygraph.",
+        inputSchema: {
+            label: z.string().min(1).describe("Node label (App, Feature, Component)"),
+            name: z.string().min(1).describe("Node name"),
+            parent: z.string().optional().describe("Parent node ID"),
+            refs: z.array(z.object({
+                file: z.string(),
+                symbol: z.string().optional(),
+            })).optional().describe("Code references"),
+            description: z.string().optional().describe("Node description"),
+        },
+    }, async ({ label, name, parent, refs, description }) => {
+        try {
+            const variables = { label, name };
+            if (parent !== undefined)
+                variables["parent"] = parent;
+            if (refs !== undefined)
+                variables["refs"] = refs;
+            if (description !== undefined)
+                variables["description"] = description;
+            const query = `
+        mutation CreateNode(
+          $label: String!, $name: String!, $parent: String,
+          $refs: [SymbolRefInput!], $description: String
+        ) {
+          createNode(
+            label: $label, name: $name, parent: $parent,
+            refs: $refs, description: $description
+          ) {
+            id label name status parent refs { file symbol } description
+            created_at updated_at
+          }
+        }
+      `;
+            const data = await queryGraphQL(query, variables);
+            return textResult(data.createNode);
+        }
+        catch {
+            const projectDir = findWhygraphDir(process.cwd());
+            /* v8 ignore next 1 */
+            if (!projectDir)
+                return errorResult("Cannot find .whygraph directory and server is unreachable");
+            const now = new Date().toISOString();
+            const id = generateId({ prefix: "wg-", length: 4 });
+            const entity = {
+                id, label: label, name, status: "active",
+                parent, refs: refs, description,
+                created_at: now, updated_at: now,
+            };
+            const { filePath, validation } = writeEntity(join(projectDir, ".whygraph", "graph"), entity);
+            /* v8 ignore next 2 */
+            const warnings = validation.errors.length > 0
+                ? ` (${validation.errors.length} validation issue(s) — written to disk, server will reconcile)`
+                : "";
+            return textResult({ ...entity, _fallback: true, _filePath: filePath, _note: `Server unreachable, wrote to disk${warnings}` });
+        }
+    });
+}
+/* v8 ignore next 5 */
+export async function startMcpServer() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/onboarding/interview.d.ts

@@ -0,0 +1,22 @@
+export interface InterviewFeatureInput {
+    name: string;
+    files?: string[];
+}
+export interface InterviewComponentInput {
+    name: string;
+    parent: string;
+    files?: string[];
+}
+export interface InterviewOptions {
+    features?: InterviewFeatureInput[];
+    components?: InterviewComponentInput[];
+}
+export interface InterviewResult {
+    created: Array<{
+        id: string;
+        label: string;
+        name: string;
+    }>;
+    gaps: number;
+}
+export declare function runInterview(whygraphDir: string, options?: InterviewOptions): Promise<InterviewResult>;

package/dist/onboarding/interview.js

@@ -0,0 +1,92 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { generateId } from "../entity/id.js";
+import { writeEntity } from "../entity/writer.js";
+import { parseEntity } from "../entity/parser.js";
+import { buildGraph } from "../graph/projection.js";
+import { getGaps } from "../graph/gaps.js";
+// ============================================================
+// Helpers
+// ============================================================
+function loadEntities(graphDir) {
+    if (!existsSync(graphDir))
+        return [];
+    const files = readdirSync(graphDir).filter((f) => f.endsWith(".md"));
+    const entities = [];
+    for (const file of files) {
+        const content = readFileSync(join(graphDir, file), "utf-8");
+        const entity = parseEntity(content);
+        if (entity !== null) {
+            entities.push(entity);
+        }
+    }
+    return entities;
+}
+function filesToRefs(files) {
+    if (!files || files.length === 0)
+        return undefined;
+    return files.map((file) => ({ file }));
+}
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runInterview(whygraphDir, options) {
+    const graphDir = join(whygraphDir, "graph");
+    // Load existing entities to understand current state
+    const existingEntities = loadEntities(graphDir);
+    const graph = buildGraph(existingEntities);
+    const gaps = getGaps(graph);
+    const now = new Date().toISOString();
+    const created = [];
+    // Find an App node to use as parent for features
+    const appNode = existingEntities.find((e) => e.label === "App");
+    const appId = appNode?.id;
+    // Create Feature nodes
+    const featureIdMap = new Map();
+    if (options?.features) {
+        for (const feature of options.features) {
+            const id = generateId();
+            featureIdMap.set(feature.name, id);
+            const refs = filesToRefs(feature.files);
+            const node = {
+                id,
+                label: "Feature",
+                name: feature.name,
+                status: "active",
+                created_at: now,
+                updated_at: now,
+                ...(appId !== undefined ? { parent: appId } : {}),
+                ...(refs !== undefined ? { refs } : {}),
+            };
+            writeEntity(graphDir, node);
+            created.push({ id, label: "Feature", name: feature.name });
+        }
+    }
+    // Create Component nodes
+    if (options?.components) {
+        for (const component of options.components) {
+            const id = generateId();
+            const parentId = featureIdMap.get(component.parent);
+            if (parentId === undefined) {
+                continue;
+            }
+            const refs = filesToRefs(component.files);
+            const node = {
+                id,
+                label: "Component",
+                name: component.name,
+                status: "active",
+                parent: parentId,
+                created_at: now,
+                updated_at: now,
+                ...(refs !== undefined ? { refs } : {}),
+            };
+            writeEntity(graphDir, node);
+            created.push({ id, label: "Component", name: component.name });
+        }
+    }
+    return {
+        created,
+        gaps: gaps.length,
+    };
+}

package/dist/onboarding/scan.d.ts

@@ -0,0 +1,17 @@
+import type { SymbolRef } from "../entity/types.js";
+export interface ScanProposal {
+    features: Array<{
+        name: string;
+        refs: SymbolRef[];
+    }>;
+    components: Array<{
+        name: string;
+        parentFeature: string;
+        refs: SymbolRef[];
+    }>;
+}
+export interface ScanResult {
+    proposal: ScanProposal;
+    scannedDir: string;
+}
+export declare function runScan(projectDir: string, _whygraphDir: string): Promise<ScanResult>;

package/dist/onboarding/scan.js

@@ -0,0 +1,106 @@
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+// ============================================================
+// Constants
+// ============================================================
+const MAIN_FILE_NAMES = new Set([
+    "index.ts",
+    "index.js",
+    "index.tsx",
+    "index.jsx",
+    "mod.ts",
+    "mod.js",
+    "main.ts",
+    "main.js",
+]);
+const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".whygraph",
+    "dist",
+    "build",
+    "coverage",
+    "__pycache__",
+    ".next",
+    ".nuxt",
+]);
+// ============================================================
+// Helpers
+// ============================================================
+function findSourceRoot(projectDir) {
+    const candidates = ["src", "lib", "app", "packages"];
+    for (const candidate of candidates) {
+        const candidatePath = join(projectDir, candidate);
+        if (existsSync(candidatePath) && statSync(candidatePath).isDirectory()) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
+function findMainFiles(dirPath, projectDir) {
+    const refs = [];
+    /* v8 ignore next 1 */
+    if (!existsSync(dirPath))
+        return refs;
+    const entries = readdirSync(dirPath);
+    for (const entry of entries) {
+        if (MAIN_FILE_NAMES.has(entry)) {
+            const fullPath = join(dirPath, entry);
+            if (statSync(fullPath).isFile()) {
+                refs.push({ file: relative(projectDir, fullPath) });
+            }
+        }
+    }
+    return refs;
+}
+function getSubdirectories(dirPath) {
+    /* v8 ignore next 1 */
+    if (!existsSync(dirPath))
+        return [];
+    return readdirSync(dirPath).filter((entry) => {
+        if (IGNORED_DIRS.has(entry))
+            return false;
+        if (entry.startsWith("."))
+            return false;
+        const fullPath = join(dirPath, entry);
+        return statSync(fullPath).isDirectory();
+    });
+}
+// ============================================================
+// Core Logic
+// ============================================================
+export async function runScan(projectDir, _whygraphDir) {
+    const sourceRoot = findSourceRoot(projectDir);
+    if (sourceRoot === null) {
+        return {
+            proposal: { features: [], components: [] },
+            scannedDir: projectDir,
+        };
+    }
+    const features = [];
+    const components = [];
+    const topLevelDirs = getSubdirectories(sourceRoot);
+    for (const dirName of topLevelDirs) {
+        const dirPath = join(sourceRoot, dirName);
+        const mainRefs = findMainFiles(dirPath, projectDir);
+        features.push({
+            name: dirName,
+            refs: mainRefs,
+        });
+        // Look for subdirectories as components
+        const subDirs = getSubdirectories(dirPath);
+        for (const subDirName of subDirs) {
+            const subDirPath = join(dirPath, subDirName);
+            const subRefs = findMainFiles(subDirPath, projectDir);
+            components.push({
+                name: subDirName,
+                parentFeature: dirName,
+                refs: subRefs,
+            });
+        }
+    }
+    return {
+        proposal: { features, components },
+        scannedDir: sourceRoot,
+    };
+}

package/dist/platform/rules.d.ts

@@ -0,0 +1,8 @@
+import type { Environment, WhygraphConfig } from "../entity/types.js";
+export interface PlatformRulesResult {
+    environment: Environment;
+    filePath: string;
+    mcpRegistered: boolean;
+    mcpSetupPath?: string;
+}
+export declare function writePlatformRules(projectDir: string, environment: Environment, _primeOutput: string, config?: WhygraphConfig): PlatformRulesResult;