Implement BFS and related high-level methods

[mkh-user]

Summary by CodeRabbit

Release Notes

• New Features

  • Added graph traversal algorithms: breadth-first search (BFS), shortest path, all shortest paths, connected components, and neighborhood discovery.
  • Introduced a Direction enum to control outgoing, incoming, or bidirectional traversal.

• Refactor

  • Updated engine querying/traversal to use the new algorithms layer.
  • Centralized save-file versioning and validation.

• Tests

  • Added comprehensive unit tests for all new graph algorithms.

• Documentation

  • Updated query traversal examples and API reference; refreshed example imports.

[mkh-user]

• Add changelog

[coderabbitai]

Warning

Review limit reached

@mkh-user, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 48 minutes and 32 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6129acc2-56b6-4326-bb42-5ee77a911fb9

📥 Commits

Reviewing files that changed from the base of the PR and between 6a66cd4 and 1d2208b.

📒 Files selected for processing (21)

• CHANGELOG.md
• docs/query-engine.md
• docs/references/query.md
• examples/basic_algorithms.py
• examples/example_suite.py
• examples/generic_example.py
• src/graphite/__init__.py
• src/graphite/algorithms.py
• src/graphite/engine.py
• src/graphite/parser.py
• src/graphite/query.py
• src/graphite/serialization.py
• tests/benchmark.py
• tests/conftest.py
• tests/test_integration_basic.py
• tests/test_integration_dsl.py
• tests/test_integration_persistence.py
• tests/test_unit_algorithms.py
• tests/test_unit_engine.py
• tests/test_unit_parser.py
• tests/test_unit_query.py

📝 Walkthrough

Walkthrough

Adds a new algorithms.py module with bfs, shortest_path, all_shortest_paths, connected_components, and neighborhood functions. Introduces a Direction enum in query.py. Extracts serialization validation and SAVE_FILE_VERSION into serialization.py. Moves DSL parsing into GraphiteParser.parse. Refactors GraphiteEngine to delegate to all new modules. Comprehensive unit tests and examples added.

Changes

Graph Algorithms and Engine Refactoring

Layer / File(s)	Summary
Direction enum and QueryResult updates src/graphite/query.py, src/graphite/__init__.py	Direction enum with OUTGOING/INCOMING/BOTH members added to query.py; QueryResult.traverse() signature updated to accept Direction enum (default Direction.OUTGOING); convenience methods outgoing(), incoming(), both() updated to pass enum values; self.direction instance attribute removed; Direction exported from package __all__.
Serialization validation extracted src/graphite/serialization.py	SAVE_FILE_VERSION = "1.0" constant and _validate_loaded_data() function added, enforcing required keys (version, node_types, relation_types, nodes), version match, collection types, warning on unexpected keys, and node type reference integrity checks.
GraphiteParser.parse DSL method src/graphite/parser.py	GraphiteParser.parse(engine, data) method added with TYPE_CHECKING-guarded engine import; parses DSL strings line-by-line, accumulates multiline node/relation definitions via engine.define_node/engine.define_relation, detects relation instances via -[ pattern, and dispatches node/relation creation with parse_fields=True.
Core algorithms module src/graphite/algorithms.py	New module implementing _resolve_neighbors() helper, bfs() (configurable with direction/depth/visited/result constraints, callable end predicates), shortest_path() and all_shortest_paths() wrappers (both raise NotImplementedError when weighted), connected_components(), and neighborhood().
Engine refactoring and delegation src/graphite/engine.py	Engine imports refactored to source _algorithms, _validate_loaded_data, and SAVE_FILE_VERSION from submodules; parse() delegates to self.parser.parse(self, data); load_safe() calls _validate_loaded_data(data) when validation enabled; deprecated remove_node/remove_relation delegate to remove_nodes/remove_relations; all five algorithm methods become forwarding wrappers to _algorithms.*.
Algorithm unit tests tests/test_unit_algorithms.py	Adds TestBFS, TestShortestPath, TestAllShortestPaths, TestConnectedComponents, TestNeighborhood, and TestAlgorithmEdgeCases, covering path discovery, no-path and depth-limit pruning, include_start, callable predicates, bidirectional/unidirectional/directional traversal modes, visited and relation_type filtering, max_results, cycles, and edge cases.
Engine and query test updates tests/test_unit_engine.py, tests/test_unit_query.py, tests/conftest.py	test_unit_engine.py DSL strings reformatted with consistent indentation; test_unit_query.py imports Direction, fixes AttributeError trigger in test_query_builder_invalid_node_type, and updates test_traverse_outgoing to use Direction.OUTGOING; conftest.py fixtures reformat DSL strings for populated_engine and engine_with_inheritance.
Integration test DSL reformatting tests/test_integration_basic.py, tests/test_integration_dsl.py, tests/test_integration_persistence.py, tests/test_unit_parser.py	DSL string literals in integration and unit tests reformatted for consistent indentation and blank-line structure; no logic or assertion changes; one trailing space removed from a field definition in DSL.
Example scripts and documentation examples/basic_algorithms.py, examples/example_suite.py, examples/generic_example.py, CHANGELOG.md, docs/query-engine.md, docs/references/query.md, tests/benchmark.py	New basic_algorithms.py example demonstrates BFS and neighborhood on a randomized graph; example imports updated to from src import graphite; CHANGELOG.md documents new algorithms module and functions; query-engine.md and query.md updated to use Direction.OUTGOING enum; benchmark.py formatting adjusted.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant GraphiteEngine
  participant algorithms
  participant _resolve_neighbors
  participant EngineRelations

  rect rgba(70, 130, 180, 0.5)
    Note over Caller,EngineRelations: BFS / Shortest Path / Neighborhood
    Caller->>GraphiteEngine: bfs(start, end, direction, max_depth, ...)
    GraphiteEngine->>algorithms: bfs(engine, start, end, direction, ...)
    algorithms->>_resolve_neighbors: _resolve_neighbors(engine, node, direction, relation_type)
    _resolve_neighbors->>EngineRelations: relations_from / relations_to
    EngineRelations-->>_resolve_neighbors: [(Relation, Node)]
    _resolve_neighbors-->>algorithms: neighbor pairs
    algorithms-->>GraphiteEngine: [(node_id, depth, path)]
    GraphiteEngine-->>Caller: result list
  end

  rect rgba(60, 179, 113, 0.5)
    Note over Caller,EngineRelations: Connected Components
    Caller->>GraphiteEngine: connected_components(nodes, direction, ...)
    GraphiteEngine->>algorithms: connected_components(engine, nodes, ...)
    algorithms->>algorithms: bfs per unvisited node
    algorithms-->>GraphiteEngine: [set[node_id], ...]
    GraphiteEngine-->>Caller: component sets
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is completely empty, lacking all required sections from the template including Related Issue, Description of Changes, Change Type, Implementation Notes, Testing, and Final Checklist.	Complete the pull request description using the provided template. Include Related Issue, detailed change description, Change Type selection, Implementation Notes, Testing summary with checkboxes, and Final Checklist confirmation before merging.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Implement BFS and related high-level methods' clearly and specifically describes the primary change—adding BFS algorithm functionality and associated utility methods to the Graphite project.
Docstring Coverage	✅ Passed	Docstring coverage is 95.45% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch algorithms/bfs

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}