Skip to content

Scale pm-graph item exports and expose pure graph projection - #122

Merged
unbraind merged 4 commits into
mainfrom
perf/pm-graph-linear-export-2026-09-29
Oct 4, 2026
Merged

unbraind merged 4 commits into
mainfrom
perf/pm-graph-linear-export-2026-09-29

Conversation

@unbraind

@unbraind unbraind commented Sep 29, 2026 •

Copy link
Copy Markdown
Owner

PM ownership

Dependency

This PR is stacked on pm-graph #116, which certifies the CLI/SDK toolchain and canonical pm-ops merge launcher. Its base is fix/pm-graph-github-extension-cli-compat-2026-09-27; update the base to main after #116 merges. Keep this PR open until that dependency and its own review gates close.

Change

graphFromItems now indexes item IDs and deduplicates relationship keys at insertion. The first edge's properties, node and edge order, and external target nodes are preserved. It is exported as a pure TypeScript API for consumers that already have a certified complete, authorization-scoped item collection. The README documents that caller boundary and corrects the stale description of the SDK read path.

Exact-head local evidence

  • npm run release:check: 295 tests passed, zero failures or skips; 0 duplicated lines; 90 documented declarations; production audit, package dry run, changelog, and release-attestation checks passed.
  • Coverage gate measured 99.65% lines, 94.07% branches, 100% functions. Statement and all-source 100/100/100/100 are not certified; pm-graph-6zil remains open.
  • A 3,000-item graph with parent, blocker, duplicate dependency, and tag edges built in 73.47 ms in the latest full coverage run. The direct focused run after stacking took 79.93 ms; its 5 s assertion budget is intentionally loose for CI hosts.
  • Fresh isolated npm/Node and Bun 1.3.5 installs of the packed tarball loaded and exercised the exported pure API.
  • pm test pm-graph-3a1p --run --fail-on-skipped --fail-on-empty-test-run passed both focused tests. pm health --strict-exit --json passed on the stacked branch with two stale-item advisories.

No hosted user data, private repository content, or pm-cli source changes are included. This PR does not certify pm-web graph export parity or hosted deployment.

Summary by Sourcery

Improve graph projection scalability and expose it for direct use by TypeScript consumers.

New Features:

  • Expose graphFromItems as a pure TypeScript API for projecting certified item collections into the standard graph shape.

Bug Fixes:

  • Prevent duplicate relationships while preserving the first edge properties and stable node and relationship ordering.

Enhancements:

  • Scale graph projection for large item collections by using indexed item membership and insertion-time relationship deduplication.
  • Document the pure projection API, its caller responsibilities, and the SDK-based metadata read path.

Tests:

  • Add contract coverage for duplicate relationships, external targets, output ordering, and large graph projection performance.

Summary by cubic

Scales graphFromItems from repeated item and edge scans to indexed membership and insertion-time deduplication, and exposes it as a pure TypeScript API for certified, authorization-scoped item collections. The graph keeps the existing export shape, first-edge properties, node order, relationship order, and external target nodes.

  • Documents the caller boundary, dependency inputs, and the current SDK metadata read path in the README.
  • Adds contract coverage for duplicate edges and exact output order, plus a 3,000-item performance test.
  • Stacked on pm-graph Align pm-graph GitHub sync extension with compatible PM SDK #116; update the base to main after that PR merges.
  • The API does not verify collection completeness or authorization for callers.

Written for commit 3d97a75. Summary will update on new commits.

Review in cubic

Review fix

Greptile's output-order finding was accepted at d27eefc: the small contract case now asserts exact node and relationship order in addition to first-edge properties. The 295-test full local release gate passed after this change. New-head CI and bot reviews are pending.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @unbraind, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 hour and 23 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@coderabbitai

coderabbitai Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 76931e98-1e2a-419f-993b-506a56ca6215

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: a56e16d1-9eca-47e3-9819-e4ad10b8c23e
📥 Commits

Reviewing files that changed from the base of the PR and between baabeef and e7d30d4.

⛔ Files ignored due to path filters (3)
  • dist/index.d.ts is excluded by !**/dist/**
  • dist/index.js is excluded by !**/dist/**
  • dist/index.js.map is excluded by !**/dist/**, !**/*.map
📒 Files selected for processing (3)
  • .agents/pm/history/pm-graph-3a1p.jsonl
  • .agents/pm/issues/pm-graph-3a1p.toon
  • test/graph-builder-scale.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.


Summary by CodeRabbit

  • Improvements

    • Graph generation now handles large item collections more efficiently by checking item membership without repeatedly scanning the full collection.
    • Duplicate relationships are filtered as they are added, preserving the properties of the first relationship with the same source, target, and type.
    • Dependencies that point outside the supplied item collection are represented as external items.
  • Documentation

    • Clarified how to provide item data and dependencies through the graph-generation API, including how duplicate relationships are handled. The extension now documents reading item metadata through the pm SDK.

Walkthrough

graphFromItems now uses indexed membership checks and deduplicates relationships as it adds them. The README documents the projection API, and new tests cover external dependencies and projection of a 3,000-item graph.

Changes

Graph projection

Layer / File(s) Summary
Projection optimization and validation
README.md, src/index.ts, test/graph-builder-scale.test.ts, .agents/pm/issues/*, .agents/pm/history/*
graphFromItems checks target membership with a precomputed ID set and skips duplicate relationships during insertion. Tests check external-target edge properties and node and relationship counts for a 3,000-item graph. The README documents the API contract, and issue records capture implementation and validation evidence.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to e7d30

The projection change has no established merge-blocking defect. The performance threshold remains worth monitoring in normal CI runs.

Architecture Summary

Architecture risk: 🔵 Low · up to e7d30

The change affects 3 systems.

Changed systems: README.md, src, test

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — README.md (service) was modified; 1 changed file maps to changed impact.
  • observed — src (service) was modified; 1 changed file maps to changed impact.
  • observed — test (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in README.md: The README replaces the description of reading workspace data through pm list-all and pm deps with reading item metadata through the pm SDK.
  • observed — Modified behavior in README.md: The README adds a “Pure graph projection” section documenting graphFromItems, its inputs and graph output, the caller’s responsibility to provide a certified authorization-scoped collection, optional extra dependencies keyed by item ID, and first-occurrence handling of duplicate relationships.
  • observed — Modified behavior in src/index.ts: graphFromItems now precomputes item IDs and tracks relationship keys. addRelationship skips duplicate (from, to, type) edges and uses the ID set to distinguish item targets from external targets when deciding whether to create an ExternalPmItem.
  • observed — Modified behavior in src/index.ts: The returned graph now uses the relationships accumulated by addRelationship directly; the former final pass that removed duplicate relationships by matching their source, target, and type is deleted.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main changes: scaling graph exports and exposing pure graph projection.
Description check ✅ Passed The description explains the graph projection changes, API contract, tests, and review status.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 …
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@unbraind

Copy link
Copy Markdown
Owner Author

@greptileai please review exact head baabeef, especially edge-order and first-property preservation, the pure API contract, and the scale test.

@unbraind

Copy link
Copy Markdown
Owner Author

/gemini review

@unbraind

Copy link
Copy Markdown
Owner Author

@coderabbitai full review

@sourcery-ai

sourcery-ai Bot commented Sep 29, 2026

Copy link
Copy Markdown

Reviewer's Guide

This PR turns graphFromItems into a packaged pure projection API, clarifies that it requires a prevalidated complete item collection, and replaces repeated item scans and end-of-build deduplication with indexed insertion-time handling; focused tests cover first-edge semantics, external targets, and 3,000-item export-scale behavior.

Sequence diagram for insertion-time graph export deduplication

sequenceDiagram
    participant Consumer
    participant Projection as graphFromItems
    participant Index as Item ID index
    participant Store as Node and relationship stores

    Consumer->>Projection: graphFromItems(items, workspace, depsByItem)
    Projection->>Index: Build item ID Set
    loop each item relationship
        Projection->>Store: addRelationship(from, to, type, properties)
        Store->>Store: Check relationship key
        alt first relationship key
            Store->>Store: Preserve first properties and order
            alt target is not indexed
                Store->>Store: Add ExternalPmItem node
            end
        else duplicate relationship key
            Store-->>Projection: Skip duplicate
        end
    end
    Projection-->>Consumer: Graph with nodes and relationships
Loading

Flow diagram for indexed pure graph projection

flowchart LR
    A["Complete authorized item collection"] --> B[graphFromItems]
    X["extraDependencies Map"] --> B
    W["workspace"] --> B
    B --> C["Index item IDs"]
    C --> D["Insert nodes and relationships"]
    D --> E["Deduplicate relationship keys"]
    E --> F["Materialize external target nodes"]
    F --> G["Graph: nodes + relationships"]
Loading

File-Level Changes

Change Details Files
Expose the graph builder as a pure public API and document its caller contract.
  • Export graphFromItems from the TypeScript source and package declarations.
  • Document that callers provide a complete, authorization-scoped item set and optional dependency map.
  • Correct the README description of the SDK-based read path.
src/index.ts
dist/index.d.ts
dist/index.js
README.md
Make relationship construction scale linearly while preserving graph semantics.
  • Index input item IDs once instead of scanning the full item list for each relationship.
  • Deduplicate relationship keys during insertion, retaining the first edge's properties and order.
  • Continue materializing missing relationship targets as ExternalPmItem nodes.
src/index.ts
dist/index.js
dist/index.js.map
Add contract and large-input performance coverage for the projection API.
  • Verify duplicate blocker/dependency edges retain the first properties and create an external target node.
  • Exercise a 3,000-item graph with dense facets and relationships under the export time budget.
test/graph-builder-scale.test.ts
Record PM ownership and review-tracking metadata for the scale issue.
  • Add the issue definition and append its PM history record.
.agents/pm/issues/pm-graph-3a1p.toon
.agents/pm/history/pm-graph-3a1p.jsonl

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@coderabbitai

coderabbitai Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
✅ Action performed

Full review finished.

@greptile-apps

greptile-apps Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

RetriggerConfidence Score: 5/5

[Medium risk] Optimizes graph construction and exposes it as a public API.

The PR appears safe to merge from this review; the previous output-order concern is fixed and no new actionable issue was established.

Summary

The PR indexes item IDs and deduplicates relationships as they are inserted, while exposing graphFromItems for callers with a complete, authorization-scoped item collection.

  • Adds exact-order, duplicate-edge, external-target, and scale tests.
  • Documents the pure API and updates the SDK read-path description.
  • The previous output-order finding is fixed by exact node and relationship order assertions.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Caller-supplied item collection] --> B[graphFromItems]
  C[Extra dependencies] --> B
  B --> D[Indexed item IDs]
  B --> E[First-seen relationship keys]
  D --> F[Graph nodes]
  E --> G[Ordered, deduplicated relationships]
  F --> H[Workspace graph]
  G --> H
Loading

Reviews (5) · Last reviewed commit: "Merge branch 'main' into perf/pm-graph-l..."

Comment thread test/graph-builder-scale.test.ts
unbraind added a commit that referenced this pull request Sep 29, 2026
Accept Greptile PR #122 finding by asserting the exact node and relationship order of a graph with a duplicate blocker edge and an external target. Preserve first-edge properties. Record the 295-test exact local release gate and remaining measured coverage gap in the package PM item.
@unbraind

Copy link
Copy Markdown
Owner Author

@greptileai please review exact head d27eefc, including the accepted output-order test fix and any remaining source or contract issues.

@unbraind

Copy link
Copy Markdown
Owner Author

/gemini review

@unbraind

Copy link
Copy Markdown
Owner Author

@coderabbitai full review

@coderabbitai

coderabbitai Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
⚠️ Action not completed

Review rate limited.


Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 48 minutes.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sourcery assessment

Approved.

@unbraind

Copy link
Copy Markdown
Owner Author

Review-round readback for exact heads (each bot comment above has a reaction and a disposition):

The PR remains open for the stacked base, exact-head CI and review, and the separately tracked 100% coverage mandate.

@unbraind

Copy link
Copy Markdown
Owner Author

On Sourcery’s exact-head approval: read and upvoted. It covers d27eefc and reports no findings. I also upvoted and dispositioned the earlier Sourcery quota review and Greptile first-head review; Greptile’s actionable inline finding was fixed and answered. CodeRabbit’s d27eefc request was rate limited, so its first-head summary is not carried forward as a new-head approval. The PR stays open for remaining exact-head checks and review receipts.

@unbraind

unbraind commented Oct 2, 2026

Copy link
Copy Markdown
Owner Author

On review 5350502548: This is a quota/skip notice, not a substantive review. It remains missing review evidence; no implementation finding was delivered.

@unbraind

unbraind commented Oct 2, 2026

Copy link
Copy Markdown
Owner Author

On review 5350545329: The graph output-order finding was fixed in d27eefc with exact node/edge assertions. Existing inline dispositions remain valid; no new finding is present in this artifact.

unbraind added a commit that referenced this pull request Oct 2, 2026
Accept Greptile PR #122 finding by asserting the exact node and relationship order of a graph with a duplicate blocker edge and an external target. Preserve first-edge properties. Record the 295-test exact local release gate and remaining measured coverage gap in the package PM item.
unbraind added a commit that referenced this pull request Oct 2, 2026
@unbraind

unbraind commented Oct 2, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review
@greptileai
/gemini review

@unbraind
unbraind force-pushed the perf/pm-graph-linear-export-2026-09-29 branch from d27eefc to e5cee3b Compare October 2, 2026 23:07
@coderabbitai

coderabbitai Bot commented Oct 2, 2026

Copy link
Copy Markdown

Rate Limit Exceeded

@unbraind have exceeded the limit for the number of chat messages per hour. Please wait 14 minutes and 32 seconds before sending another message.

@unbraind

unbraind commented Oct 2, 2026

Copy link
Copy Markdown
Owner Author

On issue 5962880460: This is a quota notice, not a substantive review of e5cee3b. The requested review did not run. The full 300-test gate and passing status checks remain separate from missing current-head review.

@unbraind
unbraind changed the base branch from fix/pm-graph-github-extension-cli-compat-2026-09-27 to main October 4, 2026 08:24
Replace repeated item and relationship scans with indexed membership and insertion-time deduplication while preserving first-edge metadata and external nodes. Export the pure projection for future observational consumers and document its authorization boundary. Add a 3,000-item scale and contract test and record PM-linked acceptance. Align the merge-driver launcher with the published pm-ops template so the release gate passes on the certified toolchain.
Accept Greptile PR #122 finding by asserting the exact node and relationship order of a graph with a duplicate blocker edge and an external target. Preserve first-edge properties. Record the 295-test exact local release gate and remaining measured coverage gap in the package PM item.
@unbraind
unbraind force-pushed the perf/pm-graph-linear-export-2026-09-29 branch from e5cee3b to e7d30d4 Compare October 4, 2026 08:51
@unbraind

unbraind commented Oct 4, 2026

Copy link
Copy Markdown
Owner Author

Rebased onto current main (dropped the six base commits already squashed into #116; the PR-specific perf/test/docs commits are replayed unchanged, head e7d30d4). The exact-head local gate passed: npm ci, the managed pm-github extension install, pm health --strict-exit --require-merge-drivers, and the full npm run release:check (300/300 tests, zero skips, no dist drift). Fresh exact-head CI and reviews are requested.

@coderabbitai review
@greptileai
/gemini review

@coderabbitai

coderabbitai Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@unbraind

unbraind commented Oct 4, 2026

Copy link
Copy Markdown
Owner Author

On comment 5978265616: the requested CodeRabbit review of the rebased head e7d30d4 ran to completion and posted no actionable finding. All exact-head checks are green; remaining bot artifacts (Greptile summary pass, Sourcery quota skip) are already dispositioned.

@unbraind
unbraind merged commit 1d47a84 into main Oct 4, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant