Blog series plan: Code as a Knowledge Graph (communicating the project)

Goal

Communicate the work on ts-knowledge-graph as a blog series. The series tells a
single story across posts: what works today → the vision → the deep dives that
earn it → where it's going. It opens with something a reader can grasp
immediately, sells the larger ambition of #14,
then backs it up with concrete engineering.

This is a tracking/planning issue. Each post below can be split into its own
issue once we start drafting it.

---

Publishing approach

• Canonical venue: Medium — long-form, narrative, lighter on code, leaning on
  diagrams and story.
• Source of truth on disk: each post is authored as a *.article.md under
  docs/blog/ so it flows into the existing content
  pipeline:
  • articlemd-to-slides → a LinkedIn-ready slide deck (.slides.md + .slides.pdf)
  • articlemd-to-social → social posts (.social.md) + a cover image (.social.png)
• Repurposing: the Medium piece is canonical; LinkedIn slides + social posts
  point back to it for reach.

Conventions

• Location: docs/blog/
• File naming: NN_short_snake_case.article.md (numeric prefix preserves
  series order), e.g. 01_codebase_is_a_graph.article.md
• Frontmatter: title, subtitle, description, author, date, tags,
  series, series_part, canonical_repo
• Tone per the decision log below: narrative, first-person, opinionated but
  technically honest. About the project's real state — no aspirational claims
  dressed as shipped features.

Per-post production workflow

1. Draft the *.article.md in docs/blog/.
2. Review tone / length / diagrams.
3. Replace ASCII sketches with proper images where it helps.
4. Run articlemd-to-slides + articlemd-to-social.
5. Publish to Medium; promote via LinkedIn deck + social posts.

---

The series at a glance

#	Working title	Maps to	Status
1	Your TypeScript codebase is already a graph	stages 1–2 (intro/pitch)	✅ drafted
2	Towards a causal knowledge graph for code optimization	#14	✅ drafted
3	Parsing TypeScript with ts-morph: from AST to semantic edges	the "how to build it"	✅ drafted
4	Storing a code graph in an embedded graph DB (Kùzu)	#19 §2/§5	✅ drafted
5	Blast radius, dead code, and safe refactors	works today	✅ drafted
6	Giving an AI agent eyes: the graph as Claude Code tools	#10, #12	✅ drafted
7	Making the graph causal: runtime enrichment	#19 §1/§4	✅ drafted
8	(bonus) Visualizing a code graph in the browser	#7	✅ drafted

---

Post-by-post plan

Post 1 — Your TypeScript codebase is already a graph (intro/pitch) ✅

• Angle: Code is already a graph (calls, imports, types, heritage); we keep
  flattening it into text and squinting at it through grep. Make it explicit and
  queryable.
• Key beats: the "what breaks if I touch this?" hook → code-isn't-text (node
  kinds + structural/type/behavioral edge layers) → the questions we ask are
  graph traversals (blast radius, dead-exports, references) → why grep can't do
  it (semantic symbol resolution, hence ts-morph/Compiler API) → JSONL nodes +
  edges → member-aware dead-exports with no false positives → the graph as a
  substrate, teeing up Post 2.
• Scope decision: intro/pitch only. The build tutorial moves to Post 3.
• Draft: docs/blog/01_codebase_is_a_graph.article.md (pending commit).
• CTA: repo link + series tease.

Post 2 — Towards a causal knowledge graph for code optimization (the vision, #14)

• Angle: The reframe at the heart of #14:
  the knowledge graph is the culmination of analysis, not the starting point;
  optimization is fundamentally causal analysis.
• Key beats: "optimize" is multi-dimensional (latency, memory, cost, tokens,
  maintainability…) → optimization starts from a business problem, not a metric
  → measurable target → baseline → constraints → the seven-stage pipeline
  (structural → dependency → semantic → runtime → knowledge graph → causal →
  optimization surface) → the punchline: turn code into a causal model of cost
  → honest map of where the project sits today, linking #19.
• Tone: the most narrative/"big idea" post in the series; few-to-no code
  blocks, one strong pipeline diagram.
• Draft: docs/blog/02_causal_knowledge_graph_vision.article.md (pending commit).
• CTA: invite readers into the open design discussion in the issues.

Post 3 — Parsing TypeScript with ts-morph: from AST to semantic edges (the build)

• Angle: The hands-on "how to implement it" that Post 1 deferred. The most
  technical, tutorial-flavored post.
• Key beats: syntax-only vs. semantic parsing (why a regex/Tree-sitter can't
  answer "who calls this symbol") → the TypeScript Compiler API via ts-morph
  → walking the structural extractor (CONTAINS/IMPORTS/EXPORTS) vs. the
  semantic extractor (CALLS/USES_TYPE/EXTENDS/IMPLEMENTS/RETURNS/
  PARAM_TYPE) → node identity and the line-bound node-id problem
  (kind:relPath#name@line) and why ids shift across extractions.
• Grounding: src/extract/structural_extractor.ts,
  src/extract/semantic_extractor.ts, src/extract/node_id.ts,
  src/extract/graph_builder.ts (call-site metadata.count),
  src/schema/node.ts, src/schema/edge.ts.
• Note: written against current code — OVERRIDES and call-site
  metadata.count are now emitted (the older #19
  text predates commits d641939/00e83b8).
• Draft: docs/blog/03_parsing_typescript_with_ts_morph.article.md (pending commit).
• CTA: "build your own minimal extractor" + repo link.

Post 4 — Storing a code graph in an embedded graph DB (Kùzu)

• Angle: Why a graph database (not SQL, not grep) is the natural home, and the
  real design tension you hit when you get serious.
• Key beats: JSONL as a portable wire format → loading into embedded Kùzu →
  Cypher-style queries over code → the schema tradeoff: fixed typed columns vs. an
  open metadata map, and why that choice is the foundational blocker for runtime
  enrichment (#19 §2/§5).
• Grounding: src/store/kuzu_store.ts, src/store/jsonl_*, src/query/graph_query.ts.
• Note: written against current code — the store now carries metadata as a
  JSON-string column (the #19
  §2 "drops metadata" blocker is resolved). The post reframes it as the pragmatic
  JSON-string choice and its honest limits (not natively queryable/indexable).
• Draft: docs/blog/04_storing_a_code_graph_in_kuzu.article.md (pending commit).
• CTA: repo link; foreshadow why the store shape matters for Post 7.

Post 5 — Blast radius, dead code, and safe refactors (static analysis in practice)

• Angle: The payoff that works today — used by hand to answer real
  impact/dead-code/dependency questions.
• Key beats: who-calls / calls / references / blast-radius /
  dead-exports / neighbors, each on a worked example from the three sample
  projects (text-kit → structural/dead-exports, calc → behavioral/inline,
  shapes → type-layer/redundant override) → the static-analysis blind spots
  (what the graph honestly can't tell you yet).
• Grounding: docs/STATIC_ANALYSIS.md, sample_projects/. Examples anchored
  on the tool's genuine self-analysis output (dead-exports → Cli/EdgeKind/Range).
• Draft: docs/blog/05_blast_radius_dead_code_safe_refactors.article.md (pending commit).
• CTA: try it on your own repo.

Post 6 — Giving an AI agent eyes: the graph as Claude Code tools

• Angle: The graph stops being a developer toy and becomes an AI agent's map
  of blast radius.
• Key beats: JSON-in/JSON-out query design (every GraphQuery method maps 1:1
  onto an agent tool) → the /code-graph-interview (read-only) and
  /code-graph-optimize Claude Code commands → verified-safe edits (typecheck
  gate today, tests/benchmarks as the goal) → the MCP-server / "graphify"
  direction (#10,
  #12).
• Grounding: dotclaude_folder/commands/code-graph-optimize.md +
  code-graph-interview.md (the interview implements Post 2's five steps; the
  optimize loop is the verified-safe edit), the code-graph-* skills.
• Draft: docs/blog/06_giving_an_ai_agent_eyes.article.md (pending commit).
• CTA: repo link; invite contributions on the MCP server.

Post 7 — Making the graph causal: runtime enrichment (the headline future post)

• Angle: The leap from "what connects to what" to "what causes what" — the
  actual point of #14.
• Key beats: attaching runtime telemetry to nodes (latency, CPU, memory, call
  frequency, cost/call, tokens, error rate) → an enrich command ingesting V8
  CPU profiles / OTLP spans / logs → the hard part: joining runtime frames
  (file+line+function) back to line-bound node ids via symbol resolution → cost
  propagation (inclusive vs. exclusive, weighted by edge count) → "this function
  causes 40% of latency."
• Grounding: #19
  §1 (runtime enrichment) and §4 (causal cost model).
• Note: reframed — the two foundations #19 called blockers (metadata column,
  call-site weight) are now in place, so the post frames the remaining climb
  (enrich, the frame→node join, propagation) rather than the old blockers.
• Draft: docs/blog/07_making_the_graph_causal_runtime_enrichment.article.md (pending commit).
• CTA: this is where the project is heading — call for collaborators.

Post 8 — (bonus) Visualizing a code graph in the browser

• Angle: Seeing the whole thing — pan/zoom, kind filters, symbol search,
  per-node edge listing.
• Key beats: the web command and the web-visualisation contrib → linking
  nodes to the corresponding GitHub HEAD (#7).
• Grounding: contribs/web_visualisation (Cytoscape.js viewer),
  src/commands/web_command.ts (serves Kùzu as window.GRAPH_DATA).
• Draft: docs/blog/08_visualizing_a_code_graph_in_the_browser.article.md
  (pending commit). Contains 📷 placeholders for screenshots/GIF to add before publish.
• CTA: screenshots/GIF; repo link.

---

Decision log

• Post 1 scope: intro/pitch only — the "how to implement" build tutorial moves
  to Post 3. (decided)
• Canonical venue: Medium — narrative tone, lighter code, more diagrams.
  (decided)
• On-disk format: *.article.md in docs/blog/, repurposed via
  articlemd-to-slides + articlemd-to-social. (decided)

Tracking checklist

• Post 1 — drafted
• Post 1 — diagrams + Medium publish
• Post 2 — drafted
• Post 3 — drafted
• Post 4 — drafted
• Post 5 — drafted
• Post 6 — drafted
• Post 7 — drafted
• Post 8 — drafted (optional)
• All posts — diagrams/screenshots + Medium publish
• Commit docs/blog/ to a branch — committed on blog/series (8738e91)
• (optional) Refresh #19 — metadata column, call-site weight, and OVERRIDES are now implemented

Start by reviewing the drafted files under docs/blog/ and the tracking checklist in this issue, then inspect the articlemd-to-slides and articlemd-to-social workflow. Done means the remaining diagrams and screenshots are added, generated slide and social artifacts are checked, and the completed series is published to Medium with the repurposed links.