Repository navigation
Conversation
blockedBy followed an element's unfinished needs whatever its own status, so an element the overlay marked done ahead of its needs, or a skipped element consuming an artefact still to be made, reported blockers. Its contract says a done or skipped element is blocked by nothing; it now returns an empty list for both.
explainStatus names the rule of the status table that decided an element's status, the incoming transitions and consumed artefacts it was decided from, and the blocked-by chain: every unfinished need reached from the element with the needs each still waits on. The derivation records this basis as it derives each status, so an explanation never re-derives it and always agrees with deriveStatuses and blockedBy, which now share one waitingOn helper.
StatusBasis is the shape the derivation records for each element, and the fields of a status explanation are drawn from it, so a consumer can name it.
The process-graph command line as a composition root over the other packages: sync from GitHub issues into the SQLite store through sqlite-node, then ready, blocked, impact, path, cycles, handoffs and why over the stored model, show for every view in Mermaid, DOT or the projection as JSON, add and set to author a model and its run state, and validate for the stored model or a model document. runCli takes injected ports (output streams, store opener, sources by prefix, file reads, facts and an abort signal) and resolves with an exit status, so the whole command surface runs in tests and inside a host such as Switchboard without a process; nodePorts wires the real ones, with the GitHub token from the adapter's environment helper. Each command's operation returns plain data, every command writes JSON with --json, and exit statuses separate usage errors, missing identifiers, invalid models and source refusals. A sync merges every page into the model in one write; when a source fails part way the pages already read are saved and the error prints the command that resumes with --after.
The bin runs the command line when it is loaded, so a bundler must not treat it as free of side effects; every other module is.
The entry point now installs the command line as process-graph, delegating to the CLI package's library entry with its own name and version. The library it exports stays isomorphic, because the bin is excluded from the web-only typecheck program and exempt from the import ban, since it is run rather than imported, and the CLI is not re-exported.
Mearman
marked this pull request as ready for review
October 10, 2026 21:43
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Mearman
force-pushed
the
feat/domain-explain
branch
2 times, most recently
from
October 10, 2026 23:47
784a0b3 to
9279367
Compare
Member
Author
|
Superseded by the single-package restructure in PR 41, which has merged and contains this work. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
@exadev/process-graph-cli(packages/targets/graph-cli), the command line and its library entry, and gives the unscopedprocess-graphpackage itsprocess-graphbin, delegating to that library entry. Stacked on #32, which addsexplainStatusto graph-domain forwhy.Commands:
sync <scope...> [--after],ready,blocked <id>,impact <id>,path,cycles,handoffs,why <id>,show --view flowchart|swimlane|state|sequence --format mermaid|dot|json [--subject] [--scenario],add participant|activity|decision|state|event|artefact|transition,set <id> <done|open|unknown>andvalidate [file]. Global options are--data(defaultPROCESS_GRAPH_DATA, elseprocess-graph/graph.sqlite3under the XDG data directory),--model(defaultdefault) and--json. Exit statuses are documented in the README and--help: 0 success, 1 failure, 2 usage, 3 not found, 4 invalid model (includingvalidateissues andcyclesfound), 5 source refusal.runCli(args, ports, identity)is the library entry Switchboard'ssb graphforwards to: it takes injected ports (streams, store opener, sources by prefix, file reads, facts, abort signal) and resolves with the exit status, never touching the process.nodePortswires the real ones, with the GitHub token from the adapter'sgithubTokenFromEnvironment. Each command's operation is also exported and returns plain data, for MCP tools.Two deviations from the plan's row.
setsets an element's run state rather than an artefact's value: the store contract has nowhere to keep facts such as which input artefacts are provided, so that is tracked in #35.addalso coversactivityandtransition, since a decision or state cannot be connected to anything without them.Tests run every command end to end against the source contract's in-memory fake (shaped like the GitHub adapter's output, across two repositories) and a SQLite file through sqlite-node, asserting the full text and JSON output; the emitters have their own content tests; the smoke tests run the built library and the built bin as a process.