ttsc 0.16.2 → 0.16.5

package/README.md

@@ -6,7 +6,7 @@
 
 A `typescript-go` toolchain for compiler-powered plugins and type-safe execution.
 
-Benchmarked against the legacy `tsc` + `eslint`/`prettier` path on real repositories; see the [benchmark guide](https://ttsc.dev/docs/benchmark) for per-project ratios.
+Benchmarked against the legacy `tsc` + `eslint`/`prettier` path on real repositories; see the [benchmark guide](https://ttsc.dev/docs/benchmark/performance) for per-project ratios.
 
 - **`ttsc`**: build, check, and transform.
 - **`ttsx`**: execute TypeScript with type checking.
@@ -15,6 +15,8 @@ Benchmarked against the legacy `tsc` + `eslint`/`prettier` path on real reposito
 - **`@ttsc/lint`**: replaces `eslint` and `prettier`.
   - lint violations as TS compile errors.
   - format autofixes via `ttsc format`.
+- **`@ttsc/graph`**: a code map for coding agents, over MCP.
+  - what calls what, and a change's blast radius, from the type checker.
 - **plugin support**: compiler-powered libraries, such as `typia`.
 
 ## Setup
@@ -49,29 +51,6 @@ Rewrite source files in place with the `@ttsc/lint` format rules:
 npx ttsc format
 ```
 
-### VS Code Extension
-
-Install the VS Code extension for live TypeScript-Go editor features plus saved-state ttsc plugin diagnostics and actions.
-
-Install it from the VS Code Marketplace by searching `ttsc`, or run:
-
-```bash
-npx @ttsc/vscode
-```
-
-Then turn on format-on-save in `.vscode/settings.json`:
-
-```jsonc
-"[typescript][typescriptreact]": {
-  "editor.defaultFormatter": "samchon.ttsc",
-  "editor.formatOnSave": true
-}
-```
-
-Lint fixes stay off-save by default; opt in with `"editor.codeActionsOnSave": { "source.fixAll.ttsc": "explicit" }`.
-
-See [`@ttsc/vscode`](https://github.com/samchon/ttsc/tree/master/packages/vscode) for requirements and settings.
-
 ### Bundlers
 
 Use `@ttsc/unplugin` when a bundler owns your build.
@@ -109,6 +88,79 @@ Supported bundlers:
 
 See [`@ttsc/unplugin`](https://github.com/samchon/ttsc/tree/master/packages/unplugin) for full setup and adapter options.
 
+### React Native / Expo
+
+React Native and Expo bundle with Metro, so the `ttsc` CLI and `@ttsc/unplugin` never run. `@ttsc/metro` is a Metro transformer that runs `ttsc` plugins on each TypeScript file, then hands the result to your existing Expo or React-Native Babel transformer.
+
+```bash
+npm install -D ttsc @ttsc/lint typescript@rc
+npm install -D @ttsc/metro
+```
+
+Wrap your Metro config (CommonJS, the standard for `metro.config.js`):
+
+```js
+// metro.config.js (Expo)
+const { getDefaultConfig } = require("expo/metro-config");
+const { withTtsc } = require("@ttsc/metro");
+
+module.exports = withTtsc(getDefaultConfig(__dirname));
+```
+
+For bare React Native, wrap `getDefaultConfig` from `@react-native/metro-config` instead. See [`@ttsc/metro`](https://github.com/samchon/ttsc/tree/master/packages/metro) for options and the v1 caveats.
+
+### VS Code Extension
+
+Install the VS Code extension for live TypeScript-Go editor features plus saved-state ttsc plugin diagnostics and actions.
+
+Install it from the VS Code Marketplace by searching `ttsc`, or run:
+
+```bash
+npx @ttsc/vscode
+```
+
+Then turn on format-on-save in `.vscode/settings.json`:
+
+```jsonc
+"[typescript][typescriptreact]": {
+  "editor.defaultFormatter": "samchon.ttsc",
+  "editor.formatOnSave": true
+}
+```
+
+Lint fixes stay off-save by default; opt in with `"editor.codeActionsOnSave": { "source.fixAll.ttsc": "explicit" }`.
+
+See [`@ttsc/vscode`](https://github.com/samchon/ttsc/tree/master/packages/vscode) for requirements and settings.
+
+### Coding Agents (MCP)
+
+`@ttsc/graph` gives a coding agent a checker-resolved map of your project, over MCP.
+
+It answers what relates to a symbol and what a change affects, straight from the type checker, so the agent stops grepping and re-reading files.
+
+It also carries the project's full diagnostics: type errors, `@ttsc/lint` violations, and plugin findings. They are fused onto the graph, so an agent sees a change's reach over what is already broken before editing.
+
+```bash
+npm install -D ttsc @ttsc/graph typescript@rc
+```
+
+Point your agent's MCP client at it. For Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "ttsc-graph": {
+      "command": "npx",
+      "args": ["-y", "@ttsc/graph"]
+    }
+  }
+}
+```
+
+On codegraph's own agent-cost benchmark, Claude agents answer reading zero files, cutting tokens by 77% to 86% and tool calls by 94% to 95%. See [`@ttsc/graph`](https://github.com/samchon/ttsc/tree/master/packages/graph) and the [benchmark](https://ttsc.dev/docs/benchmark/graph).
+
+Your agent picks the tools up from the MCP handshake and uses them on its own. See [Setup](https://ttsc.dev/docs/setup#coding-agents-ttscgraph) for the full walk-through.
+
 ## Plugins
 
 Plugins let libraries add compile-time checks, transforms, and type-driven code generation to normal `ttsc` and `ttsx` runs.
@@ -196,6 +248,23 @@ if (result.type === "success") {
 }
 ```
 
+When one process transforms a project's files repeatedly (a watch server, an editor, a codegen tool), `TtscService` keeps the compiler host warm instead of recompiling per call. It compiles the project once, then answers per-file transform requests, and reflects in-memory edits through `updateFile`:
+
+```ts
+import { TtscService } from "ttsc";
+
+const service = new TtscService({ cwd: "./project" });
+try {
+  const code = await service.transformFile("src/index.ts");
+  await service.updateFile("src/index.ts", "export const x: number = 2;\n");
+  const next = await service.transformFile("src/index.ts");
+} finally {
+  service.dispose();
+}
+```
+
+`TtscService` runs through the linked-plugin host, so the project must declare at least one transform-stage plugin.
+
 See the [Programmatic API guide](https://ttsc.dev/docs/ttsc/api) for the full lifecycle, plugin overrides, and patterns. For browser embedding, see [`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm) and the higher-level [`@ttsc/playground`](https://github.com/samchon/ttsc/tree/master/packages/playground) package.
 
 ### List of Plugins
@@ -204,9 +273,11 @@ See the [Programmatic API guide](https://ttsc.dev/docs/ttsc/api) for the full li
 
 - [`@ttsc/banner`](https://github.com/samchon/ttsc/tree/master/packages/banner): adds `@packageDocumentation` JSDoc banners.
 - [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): lints and formats TypeScript source.
+- [`@ttsc/graph`](https://github.com/samchon/ttsc/tree/master/packages/graph): MCP server exposing a checker-resolved code graph and diagnostics to coding agents.
 - [`@ttsc/paths`](https://github.com/samchon/ttsc/tree/master/packages/paths): rewrites source path aliases so JS and declaration emit receive relative imports.
 - [`@ttsc/strip`](https://github.com/samchon/ttsc/tree/master/packages/strip): removes configured calls and `debugger` statements.
 - [`@ttsc/unplugin`](https://github.com/samchon/ttsc/tree/master/packages/unplugin): runs `ttsc` plugins inside bundlers supported by `unplugin`.
+- [`@ttsc/metro`](https://github.com/samchon/ttsc/tree/master/packages/metro): runs `ttsc` plugins inside Metro for React Native and Expo.
 
 Plugin authors should start from the [`Guide Documents`](https://ttsc.dev/docs).
 
@@ -227,4 +298,4 @@ Your [donation](https://github.com/sponsors/samchon) encourages `ttsc` developme
 
 - TypeScript runners: [`ts-node`](https://github.com/TypeStrong/ts-node) and [`tsx`](https://github.com/privatenumber/tsx)
 - Transformer tooling: [`ttypescript`](https://github.com/cevek/ttypescript) and [`ts-patch`](https://github.com/nonara/ts-patch)
-- Inspired by: [`typical`](https://github.com/elliots/typical) and [`tsgonest`](https://github.com/tsgonest/tsgonest)
+- Inspired by: [`typical`](https://github.com/elliots/typical), [`tsgonest`](https://github.com/tsgonest/tsgonest) and [`codegraph`](https://github.com/colbymchenry/codegraph).

package/cmd/graphbench/main.go

@@ -0,0 +1,135 @@
+// Command graphbench measures @ttsc/graph against a real project: how long the
+// resident Program takes to load, how long graph extraction takes on top of that
+// already-built Program, how many nodes and edges result, and the codegraph-style
+// "fair coverage" (share of symbol-bearing source files with at least one
+// resolved cross-file edge). It prints one JSON line so an orchestrator can run
+// it N times and take medians.
+//
+// Counts and coverage are deterministic; timings are indicative and only
+// meaningful on a quiet host (see .codex/skills/benchmark).
+package main
+
+import (
+  "encoding/json"
+  "flag"
+  "fmt"
+  "os"
+  "time"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+type metrics struct {
+  Project       string         `json:"project"`
+  LoadMs        float64        `json:"loadMs"`
+  BuildMs       float64        `json:"buildMs"`
+  BuildShare    float64        `json:"buildShareOfLoad"`
+  SourceFiles   int            `json:"sourceFiles"`
+  Nodes         int            `json:"nodes"`
+  ExternalNodes int            `json:"externalNodes"`
+  Edges         map[string]int `json:"edges"`
+  TotalEdges    int            `json:"totalEdges"`
+  SymbolFiles   int            `json:"symbolFiles"`
+  CoveredFiles  int            `json:"coveredFiles"`
+  Coverage      float64        `json:"coverage"`
+}
+
+func main() {
+  os.Exit(run())
+}
+
+func run() int {
+  cwd := flag.String("cwd", ".", "project root")
+  tsconfig := flag.String("tsconfig", "tsconfig.json", "tsconfig path, relative to cwd")
+  flag.Parse()
+
+  loadStart := time.Now()
+  prog, _, err := driver.LoadProgram(*cwd, *tsconfig, driver.LoadProgramOptions{})
+  loadMs := time.Since(loadStart).Seconds() * 1000
+  if err != nil {
+    fmt.Fprintf(os.Stderr, "graphbench: could not load %s/%s: %v\n", *cwd, *tsconfig, err)
+    return 1
+  }
+  if prog == nil {
+    fmt.Fprintf(os.Stderr, "graphbench: could not load %s/%s\n", *cwd, *tsconfig)
+    return 1
+  }
+  defer func() { _ = prog.Close() }()
+
+  buildStart := time.Now()
+  g := graph.Build(prog)
+  buildMs := time.Since(buildStart).Seconds() * 1000
+
+  m := summarize(g, len(prog.SourceFiles()))
+  m.Project = *cwd
+  m.LoadMs = loadMs
+  m.BuildMs = buildMs
+  if loadMs > 0 {
+    m.BuildShare = buildMs / loadMs
+  }
+
+  out, err := json.Marshal(m)
+  if err != nil {
+    fmt.Fprintf(os.Stderr, "graphbench: %v\n", err)
+    return 1
+  }
+  fmt.Println(string(out))
+  return 0
+}
+
+// summarize reduces a built graph to the reported metrics: node and external
+// counts, edges per kind, and fair coverage (workspace files holding at least one
+// node that an edge connects to a node in another file).
+func summarize(g *graph.Graph, sourceFiles int) metrics {
+  edges := map[string]int{
+    string(graph.EdgeHeritage):  0,
+    string(graph.EdgeValueCall): 0,
+    string(graph.EdgeTypeRef):   0,
+  }
+  for _, edge := range g.Edges {
+    edges[string(edge.Kind)]++
+  }
+
+  fileOf := make(map[string]string, len(g.Nodes))
+  symbolFiles := map[string]bool{}
+  external := 0
+  for id, node := range g.Nodes {
+    fileOf[id] = node.File
+    if node.External {
+      external++
+      continue
+    }
+    symbolFiles[node.File] = true
+  }
+
+  coveredFiles := map[string]bool{}
+  for _, edge := range g.Edges {
+    from, to := fileOf[edge.From], fileOf[edge.To]
+    if from == "" || to == "" || from == to {
+      continue
+    }
+    if symbolFiles[from] {
+      coveredFiles[from] = true
+    }
+    if symbolFiles[to] {
+      coveredFiles[to] = true
+    }
+  }
+
+  coverage := 0.0
+  if len(symbolFiles) > 0 {
+    coverage = float64(len(coveredFiles)) / float64(len(symbolFiles))
+  }
+
+  return metrics{
+    SourceFiles:   sourceFiles,
+    Nodes:         len(g.Nodes),
+    ExternalNodes: external,
+    Edges:         edges,
+    TotalEdges:    len(g.Edges),
+    SymbolFiles:   len(symbolFiles),
+    CoveredFiles:  len(coveredFiles),
+    Coverage:      coverage,
+  }
+}

package/cmd/graphdump/main.go

@@ -0,0 +1,60 @@
+// Command graphdump builds the @ttsc/graph code graph for a project and prints
+// the entire graph (every node and every edge, with none of the MCP response
+// caps) as one JSON document. It is the repo-internal one-shot used by the
+// graph-bench viewer pipeline; the shipped equivalent is `ttscgraph dump`. Both
+// serialize through graph.MarshalDump.
+package main
+
+import (
+  "flag"
+  "fmt"
+  "os"
+  "path/filepath"
+
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+func main() {
+  os.Exit(run())
+}
+
+func run() int {
+  cwd := flag.String("cwd", ".", "project root")
+  tsconfig := flag.String("tsconfig", "tsconfig.json", "tsconfig path, relative to cwd")
+  pretty := flag.Bool("pretty", false, "indent the JSON output")
+  flag.Parse()
+
+  // Resolve the project root the same way LoadProgram does (absolute, then
+  // tsgo-normalized) so it shares the node file paths' drive-letter case on
+  // Windows; otherwise the dump's prefix-based relativization would miss and
+  // leave every path absolute.
+  root := *cwd
+  if abs, err := filepath.Abs(root); err == nil {
+    root = abs
+  }
+  root = shimtspath.ResolvePath(root)
+
+  prog, _, err := driver.LoadProgram(root, *tsconfig, driver.LoadProgramOptions{})
+  if err != nil {
+    fmt.Fprintf(os.Stderr, "graphdump: could not load %s/%s: %v\n", root, *tsconfig, err)
+    return 1
+  }
+  if prog == nil {
+    fmt.Fprintf(os.Stderr, "graphdump: could not load %s/%s\n", root, *tsconfig)
+    return 1
+  }
+  defer func() { _ = prog.Close() }()
+
+  g := graph.Build(prog)
+  ignored := graph.GitIgnoredFiles(root, g)
+  data, err := graph.MarshalDump(g, root, *tsconfig, ignored, graph.SourceTexts(prog), *pretty)
+  if err != nil {
+    fmt.Fprintf(os.Stderr, "graphdump: %v\n", err)
+    return 1
+  }
+  fmt.Println(string(data))
+  return 0
+}

package/cmd/ttscgraph/dump.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+  "flag"
+  "fmt"
+  "path/filepath"
+  "strings"
+
+  shimtspath "github.com/microsoft/typescript-go/shim/tspath"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+// runDump builds the full code graph for a project and prints it as JSON to
+// stdout, then exits. Unlike serve it does not stay resident: it is the one-shot
+// `ttscgraph dump` a user pipes into a file to feed the 3D viewer or any other
+// tooling. Every node and edge is included, with none of the MCP response caps.
+// Returns 0 on success, 1 on a load or serialize error, 2 on invalid invocation.
+func runDump(args []string) int {
+  fs := flag.NewFlagSet("ttscgraph dump", flag.ContinueOnError)
+  fs.SetOutput(stderr)
+  cwdFlag := fs.String("cwd", "", "project root (defaults to process cwd)")
+  tsconfigFlag := fs.String("tsconfig", "tsconfig.json", "project tsconfig path")
+  prettyFlag := fs.Bool("pretty", false, "indent the JSON output")
+  if err := fs.Parse(args); err != nil {
+    return 2
+  }
+
+  cwd := strings.TrimSpace(*cwdFlag)
+  if cwd == "" {
+    resolved, err := getwd()
+    if err != nil {
+      fmt.Fprintf(stderr, "ttscgraph: could not resolve working directory: %v\n", err)
+      return 2
+    }
+    cwd = resolved
+  }
+  // Resolve the project root the same way LoadProgram does (absolute, then
+  // tsgo-normalized) so it shares the node file paths' drive-letter case on
+  // Windows; otherwise the dump's prefix-based relativization would miss and
+  // leave every path absolute.
+  if abs, err := filepath.Abs(cwd); err == nil {
+    cwd = abs
+  }
+  cwd = shimtspath.ResolvePath(cwd)
+  tsconfig := strings.TrimSpace(*tsconfigFlag)
+
+  prog, _, err := driver.LoadProgram(cwd, tsconfig, driver.LoadProgramOptions{})
+  if err != nil {
+    fmt.Fprintf(stderr, "ttscgraph: could not load %s/%s: %v\n", cwd, tsconfig, err)
+    return 1
+  }
+  if prog == nil {
+    fmt.Fprintf(stderr, "ttscgraph: could not load %s/%s\n", cwd, tsconfig)
+    return 1
+  }
+  defer func() { _ = prog.Close() }()
+
+  g := graph.Build(prog)
+  ignored := graph.GitIgnoredFiles(cwd, g)
+  data, err := graph.MarshalDump(g, cwd, tsconfig, ignored, graph.SourceTexts(prog), *prettyFlag)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttscgraph: %v\n", err)
+    return 1
+  }
+  fmt.Fprintln(stdout, string(data))
+  return 0
+}

package/cmd/ttscgraph/main.go

@@ -0,0 +1,91 @@
+// Command ttscgraph builds the checker-resolved code graph for a project and
+// prints it as JSON (`ttscgraph dump`). It is the native data provider for
+// @ttsc/graph: the JavaScript launcher runs `ttscgraph dump` once, then serves
+// the Model Context Protocol from the in-memory graph itself. The MCP server,
+// its tools, and their schemas live in @ttsc/graph (TypeScript); nothing here
+// answers tool calls.
+package main
+
+import (
+  "fmt"
+  "io"
+  "os"
+  "runtime"
+  "strings"
+)
+
+// Build metadata; overwritten via -ldflags in release builds.
+var (
+  version = "0.0.0-dev"
+  commit  = "dev"
+  date    = "unknown"
+)
+
+// Package-level streams so command tests can capture I/O without patching the
+// os globals.
+var (
+  stdout io.Writer = os.Stdout
+  stderr io.Writer = os.Stderr
+)
+
+// getwd is the seam command tests use to simulate a working-directory failure.
+var getwd = os.Getwd
+
+func main() {
+  os.Exit(run(os.Args[1:]))
+}
+
+// run dispatches the top-level command and returns an exit code. ttscgraph is
+// dump-only; anything that is not help/version/dump prints usage and exits 2,
+// since serving MCP is the launcher's job.
+func run(args []string) int {
+  if len(args) > 0 {
+    switch args[0] {
+    case "-h", "--help", "help":
+      printHelp(stdout)
+      return 0
+    case "-v", "--version", "version":
+      printVersion(stdout)
+      return 0
+    case "dump":
+      return runDump(args[1:])
+    }
+  }
+  printHelp(stderr)
+  return 2
+}
+
+func printVersion(w io.Writer) {
+  fmt.Fprintf(
+    w,
+    "ttscgraph %s (commit %s, built %s, %s/%s, go %s)\n",
+    version,
+    commit,
+    date,
+    runtime.GOOS,
+    runtime.GOARCH,
+    runtime.Version(),
+  )
+}
+
+func printHelp(w io.Writer) {
+  fmt.Fprintln(w, strings.TrimSpace(`
+ttscgraph — checker-resolved code graph for ttsc.
+
+Builds the project's code graph and prints it as JSON. The @ttsc/graph launcher
+runs this and serves the Model Context Protocol from the result; the MCP tools
+live in @ttsc/graph, not here.
+
+Usage:
+  ttscgraph dump [--cwd <dir>] [--tsconfig <path>] [--pretty] > graph.json
+  ttscgraph --version
+  ttscgraph --help
+
+Dump:
+  dump                 Build the whole graph and print it as JSON to stdout, then
+                       exit. Every node and edge, none of the MCP response caps.
+  --cwd <dir>          Project root (defaults to the process working directory).
+  --tsconfig <path>    Project tsconfig path (default: tsconfig.json).
+  --pretty             Indent the JSON output.
+`))
+}

package/cmd/ttscgraph/run_dump_prints_the_graph_as_json_test.go

@@ -0,0 +1,80 @@
+package main
+
+import (
+  "bytes"
+  "encoding/json"
+  "os"
+  "path/filepath"
+  "testing"
+)
+
+// writeGraphFile writes content to path under a fixture project, creating parent
+// directories as needed.
+func writeGraphFile(t *testing.T, path, content string) {
+  t.Helper()
+  if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+    t.Fatal(err)
+  }
+}
+
+// TestRunDumpPrintsTheGraphAsJSON verifies the `dump` subcommand end to end: run
+// dispatches it, it loads the project, builds the graph, and prints the export
+// JSON to stdout with exit 0. This is the shipped path a user runs as
+// `npx @ttsc/graph dump > graph.json` to feed the 3D viewer, so a regression that
+// stops it printing, or makes it serve instead of exit, would break that flow
+// silently.
+//
+//  1. Write a two-function fixture (one call) under a temp project.
+//  2. run dump --cwd <root> --tsconfig tsconfig.json, capturing stdout.
+//  3. Assert exit 0 and that stdout is the graph envelope with nodes and edges.
+func TestRunDumpPrintsTheGraphAsJSON(t *testing.T) {
+  root := t.TempDir()
+  writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "strict": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "files": ["src/main.ts"]
+}
+`)
+  writeGraphFile(t, filepath.Join(root, "src", "main.ts"), `export function helper(): void {}
+export function main(): void {
+  helper();
+}
+`)
+
+  oldStdout, oldStderr := stdout, stderr
+  defer func() { stdout, stderr = oldStdout, oldStderr }()
+  var out, errBuf bytes.Buffer
+  stdout, stderr = &out, &errBuf
+
+  if code := run([]string{"dump", "--cwd", root, "--tsconfig", "tsconfig.json"}); code != 0 {
+    t.Fatalf("run dump exit = %d, want 0; stderr:\n%s", code, errBuf.String())
+  }
+
+  var dump struct {
+    Nodes []map[string]any `json:"nodes"`
+    Edges []map[string]any `json:"edges"`
+  }
+  if err := json.Unmarshal(out.Bytes(), &dump); err != nil {
+    t.Fatalf("dump output is not valid JSON: %v\n%s", err, out.String())
+  }
+  if len(dump.Nodes) == 0 || len(dump.Edges) == 0 {
+    t.Fatalf("expected nodes and edges, got %d/%d", len(dump.Nodes), len(dump.Edges))
+  }
+  // Each edge carries its endpoints and kind, and nothing more — the graph is
+  // wholly checker-resolved, so there is no per-edge trust flag to negotiate.
+  edge := dump.Edges[0]
+  if _, ok := edge["from"].(string); !ok {
+    t.Fatalf("edge missing from: %v", edge)
+  }
+  if _, ok := edge["kind"].(string); !ok {
+    t.Fatalf("edge missing kind: %v", edge)
+  }
+}

package/cmd/ttscgraph/run_help_version_and_bad_flags_exit_codes_test.go

@@ -0,0 +1,75 @@
+package main
+
+import (
+  "bytes"
+  "errors"
+  "strings"
+  "testing"
+)
+
+// TestRunHelpVersionAndBadFlagsExitCodes verifies the top-level run dispatcher
+// returns the documented exit codes for the dump-only command surface: help and
+// version short-circuit to 0, an unknown command prints usage and exits 2, and a
+// dump that cannot resolve its working directory exits 2 with an explanation.
+//
+// These are the non-load paths a user hits with a typo or `--help`; each must
+// resolve to a code without building a Program. The getwd seam stands in for an
+// unreadable working directory so the resolve-failure branch is reachable
+// without a real filesystem fault.
+//
+//  1. run --help and run --version exit 0, printing the command name / version.
+//  2. run --bogus (unknown command) exits 2 and prints usage.
+//  3. run dump --nope exits 2 (dump flag parse failure).
+//  4. With getwd forced to fail, run dump exits 2 and explains why.
+func TestRunHelpVersionAndBadFlagsExitCodes(t *testing.T) {
+  oldStdout, oldStderr, oldGetwd := stdout, stderr, getwd
+  defer func() { stdout, stderr, getwd = oldStdout, oldStderr, oldGetwd }()
+
+  // --help exits 0 and names the command on stdout.
+  var helpOut bytes.Buffer
+  stdout = &helpOut
+  if code := run([]string{"--help"}); code != 0 {
+    t.Fatalf("run --help exit = %d, want 0", code)
+  }
+  if !strings.Contains(helpOut.String(), "ttscgraph") {
+    t.Fatalf("run --help did not print the command name:\n%s", helpOut.String())
+  }
+
+  // --version exits 0 and prints a version-ish string.
+  var versionOut bytes.Buffer
+  stdout = &versionOut
+  if code := run([]string{"--version"}); code != 0 {
+    t.Fatalf("run --version exit = %d, want 0", code)
+  }
+  if got := versionOut.String(); !strings.Contains(got, "ttscgraph") || !strings.Contains(got, version) {
+    t.Fatalf("run --version did not print a version string:\n%s", got)
+  }
+
+  // An unknown command is an invalid invocation: print usage and exit 2.
+  var badErr bytes.Buffer
+  stderr = &badErr
+  if code := run([]string{"--bogus"}); code != 2 {
+    t.Fatalf("run --bogus exit = %d, want 2", code)
+  }
+  if !strings.Contains(badErr.String(), "Usage:") {
+    t.Fatalf("run --bogus exited 2 but did not print usage:\n%s", badErr.String())
+  }
+
+  // An unknown dump flag is an invalid invocation: dump's flag.Parse fails -> 2.
+  var dumpFlagErr bytes.Buffer
+  stderr = &dumpFlagErr
+  if code := run([]string{"dump", "--nope"}); code != 2 {
+    t.Fatalf("run dump --nope exit = %d, want 2", code)
+  }
+
+  // A getwd failure (no --cwd given) is an invalid invocation -> 2, explained.
+  var wdErr bytes.Buffer
+  stderr = &wdErr
+  getwd = func() (string, error) { return "", errors.New("boom") }
+  if code := run([]string{"dump"}); code != 2 {
+    t.Fatalf("run dump with getwd failure exit = %d, want 2", code)
+  }
+  if !strings.Contains(wdErr.String(), "could not resolve working directory") {
+    t.Fatalf("getwd failure did not explain itself:\n%s", wdErr.String())
+  }
+}