@youichi/repograph 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# repograph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Export repository indexes as JSON graphs for other programs using the [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) CLI. No language model, API key, or MCP client is required.
+
+## Installation
+
+Requires Node.js 22 or later. Run directly with `npx`:
+
+```bash
+npx @youichi/repograph export /path/to/repository
+```
+
+The project pins `codebase-memory-mcp@0.12.1`. The initial installation downloads the native binary for your platform and requires access to npm and GitHub. Subsequent indexing runs locally. No global installation or editor/agent configuration through `codebase-memory-mcp install` is required.
+
+## Exporting graphs
+
+Run these commands from any directory:
+
+```bash
+# Export all indexed nodes and relationships, plus source-derived class members and dependencies
+npx @youichi/repograph export ../anureo-sdk
+
+# Specify an output file
+npx @youichi/repograph export /path/to/repository --out .repograph/repository.json
+
+# Export only CALLS edges, functions/methods, and their endpoints
+npx @youichi/repograph export ../anureo-sdk --kind calls --out .repograph/calls.json
+
+# Show available options
+npx @youichi/repograph --help
+```
+
+The default output is `.repograph/graph.json` under the current working directory. Progress goes to stderr. On success, stdout reports the output path and node and edge counts. Failures exit with code 1, and partial results never replace an existing output file.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `--out`, `-o` | `.repograph/graph.json` | JSON output path |
+| `--kind` | `all` | `all` includes class structure and dependencies; `calls` keeps only direct call relationships |
+| `--project` | Directory name + hash of the absolute path | Override the upstream index name |
+| `--page-size` | `500` | Rows per query batch, from 1 to 10000 |
+
+Each export refreshes the index before reading nodes and edges separately. Queries support pagination and response cursors. Export stops if it detects evaluation limits, truncation without a continuation cursor, duplicate IDs, missing endpoints, or count mismatches. Call graphs retain functions and methods with no call edges.
+
+## Output structure
+
+The following is a simplified example. Actual properties depend on the language and upstream analysis results:
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-11-12T00:00:00.000Z",
+  "repositoryPath": "/path/to/repository",
+  "project": "repository-0123456789ab",
+  "kind": "calls",
+  "indexReport": { "status": "indexed", "nodes": 2, "edges": 1 },
+  "files": {
+    "main.ts": { "lines": 7 }
+  },
+  "nodes": [
+    {
+      "id": "1",
+      "labels": ["Function"],
+      "name": "checkout",
+      "qualifiedName": "repository.main.checkout",
+      "filePath": "main.ts",
+      "startLine": 1,
+      "endLine": 3,
+      "properties": {},
+      "callable": { "parameters": [], "returnType": null }
+    },
+    {
+      "id": "2",
+      "labels": ["Function"],
+      "name": "validate",
+      "qualifiedName": "repository.main.validate",
+      "filePath": "main.ts",
+      "startLine": 5,
+      "endLine": 7,
+      "properties": {},
+      "callable": { "parameters": [], "returnType": null }
+    }
+  ],
+  "edges": [
+    { "id": "1", "source": "1", "target": "2", "type": "CALLS", "properties": {} }
+  ]
+}
+```
+
+Node IDs and edge IDs are strings in separate namespaces. An edge's `source` and `target` refer to node IDs. IDs link records within the current export and are not guaranteed to remain stable across indexing runs. `indexReport` preserves the upstream indexing report; its counts describe the upstream index and can differ from the exported graph after filtering or adding source-derived class data.
+
+TypeScript and JavaScript `Function` and `Method` nodes include `callable` metadata in both `all` and `calls` exports. The exporter parses upstream `properties.signature` and `properties.return_type` with the TypeScript parser, without loading the target project's dependencies or inferring types. Supported file extensions are `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, and `.cjs`. Other languages and node labels omit `callable`. The original `properties` remain intact, and this additive field retains `schemaVersion: 1`.
+
+In `all` exports, TypeScript and JavaScript `Class` and `Interface` nodes include a `members` array for declared fields and accessors. Entries retain declared type text (or `null` when absent), source lines, visibility, static, optional, and readonly flags. The exporter also adds `DEPENDS_ON` edges for resolvable field, method-parameter, and method-return type references, plus method calls between classes. These source-derived edges have `properties.derivedFrom: "typescript-ast"` and a `reason`; they are omitted when a referenced class cannot be resolved without ambiguity. `calls` exports intentionally omit these class members and dependencies. Other languages retain whatever class, field, inheritance, implementation, and dependency nodes and edges the upstream indexer supplies.
+
+For example, `Customer` with an `address?: Address` field and a `save(input: Address): Result` method includes:
+
+```json
+{
+  "labels": ["Class"],
+  "name": "Customer",
+  "members": [
+    {
+      "name": "address",
+      "kind": "field",
+      "type": "Address",
+      "filePath": "model.ts",
+      "startLine": 6,
+      "endLine": 6,
+      "visibility": "public",
+      "static": false,
+      "optional": true,
+      "readonly": false
+    }
+  ]
+}
+```
+
+The graph also contains edges such as `{ "source": "<Customer id>", "target": "<Address id>", "type": "DEPENDS_ON", "properties": { "derivedFrom": "typescript-ast", "reason": "field-type", "member": "address" } }`. Existing upstream `INHERITS` and `IMPLEMENTS` edges are retained as-is.
+
+For example, `function load(id: string, count = 1, ...tags: string[]): Promise<string[]>` produces:
+
+```json
+{
+  "callable": {
+    "parameters": [
+      { "name": "id", "type": "string", "optional": false, "rest": false },
+      { "name": "count", "type": null, "optional": true, "rest": false },
+      { "name": "tags", "type": "string[]", "optional": false, "rest": true }
+    ],
+    "returnType": "Promise<string[]>"
+  }
+}
+```
+
+Parameter order follows the signature. `name` retains the source binding name or destructuring pattern. `type` is the declared type text, or `null` when no annotation is available. `optional` is true for a `?` marker or default initializer; `rest` identifies a `...` parameter. Default values do not cause type inference. Source-level TypeScript `this` parameters are retained when present in the upstream signature.
+
+`parameters: []` means a known empty parameter list; `parameters: null` means the upstream signature is missing or could not be parsed. `returnType` excludes the leading colon and is `null` when no annotation is available; explicit `void`, `never`, and `Promise<T>` are preserved. If the combined signature and return annotation are malformed, both fields are `null`. Missing types are never replaced with `any` or `void`. Only the signature retained on each upstream node is exported; separate overloads, accessor pairs, generic parameter declarations, and omitted upstream symbols are not reconstructed.
+
+`files` uses each `File` node's `filePath` as its key and records the physical line count in `lines`, including blank lines and comments. Empty files have `0` lines, and a trailing line ending does not add an extra line. LF, CRLF, and CR line endings are supported. Unreadable files have `null` lines. Counts come directly from source files at export time, rather than being inferred from upstream nodes' `properties.lines`. Both `all` and `calls` retain file information from the complete index, even when file nodes are filtered out of the call graph. Files outside the index are not scanned.
+
+## TypeScript usage
+
+The project also exports a thin wrapper that uses the CLI internally:
+
+```typescript
+import { exportGraph } from "./src/index.ts";
+
+const graph = await exportGraph("../anureo-sdk", {
+  kind: "calls",
+  onProgress: console.error,
+});
+
+console.log(graph.nodes, graph.edges);
+
+for (const node of graph.nodes) {
+  if (node.callable) console.log(node.name, node.callable.parameters, node.callable.returnType);
+}
+```
+
+## Development and validation
+
+```bash
+bun run typecheck
+bun test
+bun run test:integration
+```
+
+Unit tests cover pagination, cursors, truncation handling, file line counts, and structured callable metadata. The integration test uses the real native backend to index a temporary TypeScript project, checks cross-file calls, isolated functions, parameter and return annotations, methods, and export counts, and cleans up its temporary index.
+
+## Publishing
+
+Releases are published from GitHub Actions when a version tag is pushed. Before the first release, configure npm Trusted Publishing for package `@youichi/repograph` with GitHub user `hi-youichi`, repository `repograph`, and workflow file `publish-npm.yml`; allow direct `npm publish` for that publisher. Then update `package.json` to the new version and push the matching tag, for example `v0.1.1`. The workflow checks that the tag matches the package version, installs dependencies, runs typecheck and unit tests, then builds and publishes with npm provenance. No npm token is stored in GitHub Secrets.
+
+## Limitations
+
+- Exports contain the static relationships actually indexed upstream and do not guarantee coverage of all runtime calls. Support for reflection, dynamic dispatch, and framework conventions varies by language.
+- The upstream indexer skips `node_modules`, files matching ignore rules, and other excluded inputs. Use the skip and parse counts in `indexReport` to assess coverage.
+- `calls` mode retains only `CALLS` edges. It does not treat `CALL_REFERENCE` or `USAGE` as direct calls. The upstream analyzer may also record recursion in properties while omitting self-call edges.
+- Source-derived class members and type dependencies currently cover TypeScript and JavaScript files. Other languages depend on the class, field, and relationship data available from the pinned upstream indexer; type references are not inferred from unannotated initializers.
+- Keep source files and the project's index unchanged during export, and prevent other processes from rebuilding the index concurrently. Exports are not transactional snapshots across queries.
+- Results are assembled in memory before being written to disk. Large repositories require sufficient memory, and upstream evaluation limits cause an error.
+- Place output outside the target repository to prevent a later indexing run from treating exported files as input. Upstream indexes remain in the local cache.
+
+The project currently exports JSON only. Graphviz, Cytoscape, or other frontend tools can consume it for visualization.

package/dist/callables.js

@@ -0,0 +1,63 @@
+// src/callables.ts
+import { extname } from "node:path";
+import ts from "typescript";
+var EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+function addCallables(nodes) {
+  const inputs = nodes.filter((node) => node.labels.some((label) => label === "Function" || label === "Method") && EXTENSIONS.has(extname(node.filePath).toLowerCase()));
+  if (inputs.length === 0)
+    return;
+  const sources = new Map;
+  const signatures = inputs.map((node, i) => {
+    const rawSignature = node.properties.signature;
+    const signature = typeof rawSignature === "string" && rawSignature.trim() !== "" ? rawSignature.trim() : null;
+    const rawReturn = node.properties.return_type;
+    const returnType = typeof rawReturn === "string" && rawReturn.trim() !== "" ? rawReturn.trim().replace(/^:\s*/, "") : null;
+    const jsx = [".tsx", ".jsx"].includes(extname(node.filePath).toLowerCase());
+    const path = `/__repograph_signatures__/${i}.${jsx ? "tsx" : "ts"}`;
+    const text = `function __repograph${signature ?? "()"}${returnType !== null ? `: ${returnType}` : ""}
+{}`;
+    sources.set(path, ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, jsx ? ts.ScriptKind.TSX : ts.ScriptKind.TS));
+    return { node, path, signature };
+  });
+  const options = {
+    noLib: true,
+    noResolve: true,
+    noEmit: true,
+    target: ts.ScriptTarget.Latest,
+    jsx: ts.JsxEmit.Preserve
+  };
+  const host = {
+    getSourceFile: (path) => sources.get(path),
+    getDefaultLibFileName: () => "",
+    writeFile: () => {},
+    getCurrentDirectory: () => "/",
+    getDirectories: () => [],
+    fileExists: (path) => sources.has(path),
+    readFile: (path) => sources.get(path)?.text,
+    getCanonicalFileName: (path) => path,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => `
+`
+  };
+  const program = ts.createProgram([...sources.keys()], options, host);
+  for (const { node, path, signature } of signatures) {
+    const callable = { parameters: null, returnType: null };
+    node.callable = callable;
+    const source = sources.get(path);
+    const declaration = source.statements[0];
+    if (program.getSyntacticDiagnostics(source).length !== 0 || source.statements.length !== 1 || !declaration || !ts.isFunctionDeclaration(declaration) || declaration.name?.text !== "__repograph" || !declaration.body || declaration.body.statements.length !== 0)
+      continue;
+    if (signature !== null) {
+      callable.parameters = declaration.parameters.map((parameter) => ({
+        name: parameter.name.getText(source),
+        type: parameter.type?.getText(source) ?? null,
+        optional: parameter.questionToken !== undefined || parameter.initializer !== undefined,
+        rest: parameter.dotDotDotToken !== undefined
+      }));
+    }
+    callable.returnType = declaration.type?.getText(source) ?? null;
+  }
+}
+export {
+  addCallables
+};

package/dist/cbm.js

@@ -0,0 +1,72 @@
+// src/cbm.ts
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+var runTool = async (tool, args) => {
+  const shim = createRequire(import.meta.url).resolve("codebase-memory-mcp/bin.js");
+  const stdout = await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [shim, "cli", "--json", tool], { stdio: ["pipe", "pipe", "inherit"] });
+    let output = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => {
+      output += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve(output) : reject(new Error(`codebase-memory-mcp ${tool} exited with ${code}`)));
+    child.stdin.end(JSON.stringify(args));
+  });
+  const envelope = JSON.parse(stdout);
+  const message = envelope.content?.filter((part) => part.type === "text").map((part) => part.text ?? "").join(`
+`) ?? "";
+  if (envelope.isError)
+    throw new Error(message || `${tool} failed`);
+  const payload = envelope.structuredContent ?? JSON.parse(message);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error(`${tool} returned an invalid payload`);
+  }
+  return payload;
+};
+async function collectRows(run, project, baseQuery, pageSize) {
+  const result = [];
+  for (let offset = 0;; offset += pageSize) {
+    const query = `${baseQuery} ORDER BY id SKIP ${offset} LIMIT ${pageSize}`;
+    let cursor;
+    let count = 0;
+    const seenCursors = new Set;
+    do {
+      const page = await run("query_graph", {
+        project,
+        query,
+        format: "json",
+        max_rows: pageSize,
+        max_output_tokens: 1e6,
+        ...cursor ? { cursor } : {}
+      });
+      if (page.total_relation !== "eq" || page.warning) {
+        throw new Error(`Query evaluation is incomplete: ${page.warning ?? page.truncation_reason ?? "inexact total"}`);
+      }
+      if (!Array.isArray(page.columns) || !page.columns.every((x) => typeof x === "string") || !Array.isArray(page.rows)) {
+        throw new Error("Unexpected query_graph response shape");
+      }
+      const columns = page.columns;
+      for (const row of page.rows) {
+        if (!Array.isArray(row) || row.length !== columns.length || !row.every((value) => typeof value === "string")) {
+          throw new Error("Unexpected query_graph row shape");
+        }
+        result.push(Object.fromEntries(columns.map((name, i) => [name, row[i]])));
+        count++;
+      }
+      if (page.has_more === false && page.truncated === false)
+        break;
+      if (typeof page.next_cursor !== "string" || seenCursors.has(page.next_cursor)) {
+        throw new Error("Query result was truncated without an advancing cursor; export aborted");
+      }
+      cursor = page.next_cursor;
+      seenCursors.add(cursor);
+    } while (true);
+    if (count < pageSize)
+      return result;
+  }
+}
+export {
+  runTool,
+  collectRows
+};

package/dist/classes.js

@@ -0,0 +1,192 @@
+// src/classes.ts
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import ts from "typescript";
+var CLASS_LABELS = new Set(["Class", "Interface", "Struct", "Trait"]);
+var SCRIPT_KINDS = {
+  ".ts": ts.ScriptKind.TS,
+  ".tsx": ts.ScriptKind.TSX,
+  ".mts": ts.ScriptKind.TS,
+  ".cts": ts.ScriptKind.TS,
+  ".js": ts.ScriptKind.JS,
+  ".jsx": ts.ScriptKind.JSX,
+  ".mjs": ts.ScriptKind.JS,
+  ".cjs": ts.ScriptKind.JS
+};
+function modifiers(node) {
+  return ts.canHaveModifiers(node) ? ts.getModifiers(node) ?? [] : [];
+}
+function memberName(name) {
+  if (!name)
+    return;
+  if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name))
+    return name.text;
+  if (ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+    return name.text;
+  if (ts.isComputedPropertyName(name) && (ts.isStringLiteral(name.expression) || ts.isNumericLiteral(name.expression)))
+    return name.expression.text;
+  return;
+}
+function typeNames(type, into = new Set) {
+  const visit = (node) => {
+    if (ts.isTypeReferenceNode(node)) {
+      const name = node.typeName.getText().split(".").at(-1);
+      if (name)
+        into.add(name);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(type);
+  return into;
+}
+function sourceLine(file, node) {
+  return file.getLineAndCharacterOfPosition(node.getStart(file)).line + 1;
+}
+function sourceEndLine(file, node) {
+  return file.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+}
+function toMember(file, filePath, node) {
+  if (!ts.isPropertyDeclaration(node) && !ts.isPropertySignature(node) && !ts.isGetAccessorDeclaration(node) && !ts.isSetAccessorDeclaration(node))
+    return;
+  const name = memberName(node.name);
+  if (name === undefined)
+    return;
+  const flags = modifiers(node);
+  const visibility = flags.some((flag) => flag.kind === ts.SyntaxKind.PrivateKeyword) || name.startsWith("#") ? "private" : flags.some((flag) => flag.kind === ts.SyntaxKind.ProtectedKeyword) ? "protected" : "public";
+  const kind = ts.isGetAccessorDeclaration(node) ? "getter" : ts.isSetAccessorDeclaration(node) ? "setter" : "field";
+  return {
+    name,
+    kind,
+    type: node.type?.getText(file) ?? null,
+    filePath,
+    startLine: sourceLine(file, node),
+    endLine: sourceEndLine(file, node),
+    visibility,
+    static: flags.some((flag) => flag.kind === ts.SyntaxKind.StaticKeyword),
+    optional: !!node.questionToken,
+    readonly: flags.some((flag) => flag.kind === ts.SyntaxKind.ReadonlyKeyword)
+  };
+}
+function declaredType(node) {
+  if (ts.isPropertyDeclaration(node) || ts.isPropertySignature(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node))
+    return node.type;
+  return;
+}
+function isClassLike(node) {
+  return ts.isClassDeclaration(node) || ts.isClassExpression(node) || ts.isInterfaceDeclaration(node);
+}
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 20);
+}
+async function addClassMetadata(repositoryPath, nodes, edges) {
+  const byFileAndName = new Map;
+  const classNodes = nodes.filter((node) => node.labels.some((label) => CLASS_LABELS.has(label)));
+  for (const node of classNodes) {
+    const key = `${node.filePath}\x00${node.name}`;
+    byFileAndName.set(key, [...byFileAndName.get(key) ?? [], node]);
+  }
+  const byName = new Map;
+  for (const node of classNodes)
+    byName.set(node.name, [...byName.get(node.name) ?? [], node]);
+  const sources = new Map;
+  const paths = new Set(classNodes.map((node) => node.filePath).filter(Boolean));
+  for (const filePath of paths) {
+    const scriptKind = SCRIPT_KINDS[extname(filePath).toLowerCase()];
+    if (scriptKind === undefined)
+      continue;
+    try {
+      const text = await readFile(resolve(repositoryPath, filePath), "utf8");
+      sources.set(filePath, ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, scriptKind));
+    } catch {}
+  }
+  const dependencies = new Map;
+  const existingDependencyPairs = new Set(edges.filter((edge) => edge.type === "DEPENDS_ON").map((edge) => `${edge.source}\x00${edge.target}`));
+  const addDependency = (source, target, reason, member) => {
+    if (source.id === target.id)
+      return;
+    const pair = `${source.id}\x00${target.id}`;
+    if (existingDependencyPairs.has(pair))
+      return;
+    const id = `derived:${hash(`${source.id}\x00${target.id}\x00${reason}\x00${member}`)}`;
+    dependencies.set(id, {
+      id,
+      source: source.id,
+      target: target.id,
+      type: "DEPENDS_ON",
+      properties: { derivedFrom: "typescript-ast", reason, member }
+    });
+  };
+  for (const [filePath, file] of sources) {
+    const visit = (node) => {
+      if (!isClassLike(node) || !node.name) {
+        ts.forEachChild(node, visit);
+        return;
+      }
+      const name = node.name.text;
+      const candidates = byFileAndName.get(`${filePath}\x00${name}`) ?? [];
+      const start = sourceLine(file, node);
+      const owner = candidates.find((candidate) => candidate.startLine === start) ?? (candidates.length === 1 ? candidates[0] : undefined);
+      if (!owner) {
+        ts.forEachChild(node, visit);
+        return;
+      }
+      const members = [];
+      const collect = (member) => {
+        const value = toMember(file, filePath, member);
+        const propertyType = declaredType(member);
+        if (value) {
+          members.push(value);
+          if (propertyType) {
+            for (const typeName of typeNames(propertyType)) {
+              const targets = byName.get(typeName) ?? [];
+              const target = targets.length === 1 ? targets[0] : targets.find((item) => item.filePath === filePath);
+              if (target)
+                addDependency(owner, target, "field-type", value.name);
+            }
+          }
+        }
+        if ((ts.isMethodDeclaration(member) || ts.isMethodSignature(member)) && (member.type || member.parameters.length)) {
+          for (const parameter of member.parameters) {
+            if (!parameter.type)
+              continue;
+            for (const typeName of typeNames(parameter.type)) {
+              const targets = byName.get(typeName) ?? [];
+              const target = targets.length === 1 ? targets[0] : targets.find((item) => item.filePath === filePath);
+              if (target)
+                addDependency(owner, target, "method-parameter", member.name.getText(file));
+            }
+          }
+          if (member.type) {
+            for (const typeName of typeNames(member.type)) {
+              const targets = byName.get(typeName) ?? [];
+              const target = targets.length === 1 ? targets[0] : targets.find((item) => item.filePath === filePath);
+              if (target)
+                addDependency(owner, target, "method-return", member.name.getText(file));
+            }
+          }
+        }
+      };
+      for (const member of node.members)
+        collect(member);
+      if (members.length)
+        owner.members = members;
+      ts.forEachChild(node, visit);
+    };
+    visit(file);
+  }
+  const classesByQualifiedName = new Map(classNodes.map((node) => [node.qualifiedName, node]));
+  const methodOwners = new Map(nodes.filter((node) => node.labels.includes("Method") && typeof node.properties.parent_class === "string").map((node) => [node.id, classesByQualifiedName.get(node.properties.parent_class)]));
+  const nodesById = new Map(nodes.map((node) => [node.id, node]));
+  for (const edge of edges.filter((item) => item.type === "CALLS")) {
+    const source = methodOwners.get(edge.source);
+    const targetNode = nodesById.get(edge.target);
+    const target = targetNode && methodOwners.get(targetNode.id) || (targetNode?.labels.some((label) => CLASS_LABELS.has(label)) ? targetNode : undefined);
+    if (source && target)
+      addDependency(source, target, "method-call", targetNode?.name ?? "");
+  }
+  edges.push(...dependencies.values());
+}
+export {
+  addClassMetadata
+};

package/dist/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { exportGraph } from "./index.js";
+var HELP = `repograph — export repository graphs with codebase-memory-mcp
+
+Usage: repograph export <repository> [options]
+
+Options:
+  -o, --out <file>       JSON output (default: .repograph/graph.json)
+      --kind <all|calls> Export all relationships or CALLS only (default: all)
+      --project <name>   Override the path-derived index name
+      --page-size <n>    Query batch size, 1–10000 (default: 500)
+  -h, --help            Show help
+`;
+async function main() {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+    strict: true,
+    options: {
+      out: { type: "string", short: "o" },
+      kind: { type: "string" },
+      project: { type: "string" },
+      "page-size": { type: "string" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help || positionals.length === 0) {
+    console.log(HELP);
+    return;
+  }
+  if (positionals[0] !== "export" || positionals.length !== 2) {
+    throw new Error("Expected: export <repository>. Use --help for usage.");
+  }
+  const kind = values.kind ?? "all";
+  if (kind !== "all" && kind !== "calls")
+    throw new Error("--kind must be all or calls");
+  if (values.project !== undefined && !values.project.trim())
+    throw new Error("--project cannot be empty");
+  const graph = await exportGraph(positionals[1], {
+    kind,
+    project: values.project,
+    pageSize: values["page-size"] === undefined ? undefined : Number(values["page-size"]),
+    onProgress: (message) => console.error(message)
+  });
+  const output = resolve(values.out ?? ".repograph/graph.json");
+  await mkdir(dirname(output), { recursive: true });
+  const temporary = `${output}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(graph, null, 2)}
+`, { flag: "wx" });
+    await rename(temporary, output);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  console.log(JSON.stringify({ output, nodes: graph.nodes.length, edges: graph.edges.length, kind }));
+}
+main().catch((error) => {
+  console.error(`repograph: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/dist/index.js

@@ -0,0 +1,140 @@
+// src/index.ts
+import { readFile, realpath, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { collectRows, runTool } from "./cbm.js";
+import { addCallables } from "./callables.js";
+import { addClassMetadata } from "./classes.js";
+var NODE_QUERY = `MATCH (n) RETURN id(n) AS id, labels(n) AS labels,
+  n.name AS name, n.qualified_name AS qualifiedName, n.file_path AS filePath,
+  n.start_line AS startLine, n.end_line AS endLine, properties(n) AS properties`;
+var EDGE_QUERY = `MATCH (a)-[r]->(b) RETURN id(r) AS id,
+  id(a) AS source, id(b) AS target, type(r) AS type, properties(r) AS properties`;
+function field(row, key) {
+  const value = row[key];
+  if (value === undefined)
+    throw new Error(`Missing graph field: ${key}`);
+  return value;
+}
+function properties(text) {
+  const value = JSON.parse(text);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid graph properties");
+  }
+  return value;
+}
+function line(value) {
+  if (value === "" || value === "null" || value === "0")
+    return null;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 0)
+    throw new Error(`Invalid line: ${value}`);
+  return number;
+}
+async function fileLines(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  if (text.length === 0)
+    return 0;
+  let lines = 0;
+  for (let i = 0;i < text.length; i++) {
+    if (text[i] === "\r") {
+      lines++;
+      if (text[i + 1] === `
+`)
+        i++;
+    } else if (text[i] === `
+`) {
+      lines++;
+    }
+  }
+  return lines + (text.endsWith(`
+`) || text.endsWith("\r") ? 0 : 1);
+}
+async function exportGraph(repository, options = {}, run = runTool) {
+  const repositoryPath = await realpath(repository);
+  if (!(await stat(repositoryPath)).isDirectory())
+    throw new Error("Repository must be a directory");
+  const pageSize = options.pageSize ?? 500;
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 1e4) {
+    throw new Error("pageSize must be an integer between 1 and 10000");
+  }
+  const kind = options.kind ?? "all";
+  if (kind !== "all" && kind !== "calls")
+    throw new Error("kind must be all or calls");
+  const suffix = createHash("sha256").update(repositoryPath).digest("hex").slice(0, 12);
+  const name = options.project ?? `${basename(repositoryPath)}-${suffix}`;
+  options.onProgress?.(`Indexing ${repositoryPath}`);
+  const indexReport = await run("index_repository", { repo_path: repositoryPath, name });
+  if (indexReport.status !== "indexed" || typeof indexReport.project !== "string") {
+    throw new Error(`Indexing did not complete: ${JSON.stringify(indexReport)}`);
+  }
+  const project = indexReport.project;
+  options.onProgress?.("Exporting nodes");
+  const nodeRows = await collectRows(run, project, NODE_QUERY, pageSize);
+  const nodes = nodeRows.map((row) => {
+    const labels = JSON.parse(field(row, "labels"));
+    if (!Array.isArray(labels) || !labels.every((label) => typeof label === "string")) {
+      throw new Error("Invalid node labels");
+    }
+    return {
+      id: field(row, "id"),
+      labels,
+      name: field(row, "name"),
+      qualifiedName: field(row, "qualifiedName"),
+      filePath: field(row, "filePath"),
+      startLine: line(field(row, "startLine")),
+      endLine: line(field(row, "endLine")),
+      properties: properties(field(row, "properties"))
+    };
+  });
+  options.onProgress?.("Exporting edges");
+  const edgeRows = await collectRows(run, project, EDGE_QUERY, pageSize);
+  const edges = edgeRows.map((row) => ({
+    id: field(row, "id"),
+    source: field(row, "source"),
+    target: field(row, "target"),
+    type: field(row, "type"),
+    properties: properties(field(row, "properties"))
+  }));
+  if (nodes.length !== indexReport.nodes || edges.length !== indexReport.edges) {
+    throw new Error("Export counts differ from the index; the index may have changed or queries were limited");
+  }
+  const ids = new Set(nodes.map((node) => node.id));
+  if (ids.size !== nodes.length || new Set(edges.map((edge) => edge.id)).size !== edges.length || edges.some((edge) => !ids.has(edge.source) || !ids.has(edge.target))) {
+    throw new Error("Graph contains duplicate IDs or missing edge endpoints");
+  }
+  options.onProgress?.("Counting file lines");
+  const filePaths = new Set(nodes.filter((node) => node.labels.includes("File")).map((node) => node.filePath).filter((path) => path !== "" && path !== "{}" && path !== "null"));
+  const files = Object.create(null);
+  for (const path of filePaths) {
+    files[path] = { lines: await fileLines(resolve(repositoryPath, path)) };
+  }
+  const selectedEdges = kind === "calls" ? edges.filter((edge) => edge.type === "CALLS") : edges;
+  const endpoints = new Set(selectedEdges.flatMap((edge) => [edge.source, edge.target]));
+  const selectedNodes = kind === "calls" ? nodes.filter((node) => endpoints.has(node.id) || node.labels.some((label) => label === "Function" || label === "Method")) : nodes;
+  options.onProgress?.("Extracting callable signatures");
+  addCallables(selectedNodes);
+  if (kind === "all") {
+    options.onProgress?.("Extracting class members and type dependencies");
+    addClassMetadata(repositoryPath, nodes, edges);
+  }
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    repositoryPath,
+    project,
+    kind,
+    indexReport,
+    files,
+    nodes: selectedNodes,
+    edges: selectedEdges
+  };
+}
+export {
+  exportGraph
+};

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@youichi/repograph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Export repository code graphs with codebase-memory-mcp.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hi-youichi/repograph.git"
+  },
+  "type": "module",
+  "bin": {
+    "repograph": "dist/cli.js"
+  },
+  "exports": "./dist/index.js",
+  "scripts": {
+    "start": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:integration": "REPOGRAPH_INTEGRATION=1 bun test test/integration.test.ts",
+    "build": "bun build ./src/cli.ts ./src/index.ts ./src/cbm.ts ./src/callables.ts ./src/classes.ts --target node --outdir dist --external \"*\"",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "codebase-memory-mcp": "0.12.1",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6"
+  },
+  "trustedDependencies": [
+    "codebase-memory-mcp"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}