Skip to content

Repository navigation

graphify-development.md

Latest commit

 

History

History
123 lines (93 loc) · 4.52 KB

graphify-development.md

File metadata and controls

123 lines (93 loc) · 4.52 KB
Raw

Graphify development workflow

Purpose

Graphify is a local topology and navigation aid. It does not participate in the Copilot runtime and does not replace tests, TypeScript, RepoWise, security gates, or caller inspection.

Use it to investigate:

  • production callers and affected paths;
  • capability and composition hubs;
  • cross-layer edges and cycles;
  • whether current ports and adapters are connected as intended;
  • impact before retiring a facade or changing a composition root.

Installation

Install graphifyy in an isolated Python environment. Do not add it to package.json, the pnpm lockfile, or production dependencies. The executable may live anywhere on the developer machine; set GRAPHIFY_BIN when it is not on PATH.

python3 -m venv /tmp/copilot-graphify-venv
/tmp/copilot-graphify-venv/bin/python -m pip install 'graphifyy==0.9.46'
/tmp/copilot-graphify-venv/bin/graphify hermes install

The executable is not required to be on PATH. Commands in this repository use:

GRAPHIFY_BIN=/tmp/copilot-graphify-venv/bin/graphify

Current workflow

The authoritative reproducible refresh is the versioned collector:

METRICS_OUTPUT_DIR="$(mktemp -d "/tmp/copilot-architecture-metrics-$(git rev-parse HEAD)-XXXXXX")" \
  pnpm run metrics:architecture

It fixes RepoWise to single-repository scope, derives coverage inventory from LCOV, records reports outside the repository, runs Graphify, and snapshots then restores every mutable workspace path (build/, coverage/, graphify-out/, local RepoWise/editor/agent configuration) byte-for-byte. A run publishes complete.json only after report validation and post-restoration Git checks. For an explicitly destructive, isolated Graphify investigation, use:

rm -rf graphify-out
$GRAPHIFY_BIN update .

This builds the local AST graph in graphify-out/. The directory is generated and ignored by Git.

Query before reading generated JSON manually:

$GRAPHIFY_BIN query "application boundaries and composition roots" --budget 5000
$GRAPHIFY_BIN query "release tag adapters callers and provider clients" --budget 5000
$GRAPHIFY_BIN query "GitHub Action local action CLI runtime composition" --budget 5000

Narrow broad results by naming the concrete symbol or path. Graphify semantic queries may include documentation and test nodes; a returned node is evidence to inspect, not proof of a production dependency.

Use with RepoWise

Graphify -> topology, callers, paths, hubs, impact
RepoWise  -> complexity, duplication, churn, health, risk
Tests     -> behavior and contracts
Source    -> authoritative current implementation
Git       -> publication and version evidence

A RepoWise hotspot is not a refactoring instruction. Use Graphify and source search to identify the real callers and ownership first, define a semantic boundary only when one exists, and add contract tests for intentional changes.

Current graph state

Graphify output is local, generated, and intentionally not a versioned source of truth. Regenerate it with graphify update . and use git rev-parse HEAD for the revision being audited before making architecture decisions. Do not copy node or edge counts from an older checkpoint into current documentation.

The generated graph is currently marked directed: false. It cannot prove the absence of directed dependency cycles. Use source imports and executable architecture tests for dependency direction; use Graphify for connectivity, paths, hubs, and impact.

Current high-degree nodes are headed by logging functions, Execution, Result, ParamUseCase, GithubClientPort, and semantic ports. Logging is a legitimate cross-cutting concern; models and base contracts are monitored for responsibility concentration; provider client contracts remain technical and outside application behavior. Universal facade classes are absent from the current topology.

Persistent tool warning:

docs.json produces zero nodes

The warning is Graphify input behavior, not a production architecture defect. The graph shows current composition roots and application architecture tests as first-class nodes. Query results must always be verified against current source paths before acting.

Privacy and generated artifacts

  • Never index credentials, .env files, auth state, databases, logs, or user data.
  • Review .gitignore and .graphifyignore before indexing a new source.
  • Keep graphify-out/ local unless an explicit reviewed CI policy says otherwise.
  • Never commit generated graph files as architectural source of truth.