feat: add find_index() for list-of-dicts lookup

[nathanjmcdougall]

Adds Document.find_index() and Editor.find_index() methods that return the index of the first list item matching a set of key/value constraints.

API

idx = doc.find_index("repos", where={"repo": url})
# Returns int | None

Behavior

• Retrieves the parsed list at the given path
• Returns index of first item where all where key/value pairs match (AND semantics)
• Returns None if no item matches
• Raises QueryError if path doesn't exist
• Raises NodeTypeError if value at path is not a list
• Raises ValueError if where is empty
• Non-dict items in the list are skipped

Motivation

YAML configs frequently use lists of dicts keyed by a distinguishing field (e.g. pre-commit repos by URL, CI steps by uses). Finding an item currently requires manual iteration:

repos = doc["repos"]
idx = next((i for i, r in enumerate(repos) if r["repo"] == url), None)

find_index makes this a single call.

[Copilot]

Pull request overview

This PR adds a convenience lookup API to yamltrip’s Python layer for locating the first matching entry in a list-of-dicts at a given document path, exposed on both Document (immutable) and Editor (context-managed mutable wrapper).

Changes:

• Add Document.find_index(*keys, where=...) -> int | None implementing AND-match semantics and skipping non-dict list items.
• Add Editor.find_index(...) delegating to Document.find_index(...).
• Add new test coverage for Document.find_index and basic Editor.find_index behavior, plus a design/spec markdown.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/yamltrip/document.py	Implements Document.find_index() and its validation/error behavior.
src/yamltrip/editor.py	Adds Editor.find_index() delegating to the underlying Document.
tests/test_document.py	Adds comprehensive tests for Document.find_index() (matching, errors, nested paths, int path keys, etc.).
tests/test_editor.py	Adds tests for Editor.find_index() basic matching and empty-where validation.
doc/specs/2026-05-22-find-index-design.md	Adds a design/spec document describing the new API and intended semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.