Add protosourcepath package

[doriable]

This PR adds a new package, protosourcepath. The API is
a single function, GetAssociatedSourcePaths that takes a protoreflect.SourcePath
and the option to excludeChildAssociatedPaths, and returns a list of associated paths, []protoreflect.SourcePath:

func GetAssociatedSourcePaths(
	sourcePath protoreflect.SourcePath,
	excludeChildAssociatedPaths bool,
) ([]protoreflect.SourcePath, error)

• We expect there always to be at least one associated path.
• excludeChildAssociatedPaths will only include complete/top-level declarations as associated paths

Semantics

• All associated paths are based on:
  • Parent paths
  • Child paths
• We do not consider all child paths as associated, only some
• Some “parent paths” may actually be the associated child paths of the parent path
• For example, a path to a field definition, [4, 0, 2, 0] would have the following associated paths:
  • [4, 0, 2, 0] the field definition
  • [4, 0] the message definition (parent path)
  • [4, 0, 1] the message name (parent associated child path)
  • [4, 0, 2, 0, 1] the field name (child path)
  • [4, 0, 2, 0, 3] the field number (child path)
  • [4, 0, 2, 0, 5] the field type (child path)
  • [4, 0, 2, 0, 6] the field type name (child path)
  • [4, 0, 2, 0, 4] the field label (child path)
• If excludeChildAssociatedPaths == true , then child paths and parent-associated child paths would not be included.
• So for the example above, we could get the following associated paths:
  • [4, 0, 2, 0] the field definition
  • [4, 0] the message definition (parent path)

Implementation

• GetAssociatedSourcePaths iterates through path elements and checks them through a DFA.
• Each state will take the current token, the full source path, and the index being parsed, and return
  the next state and associated source paths:

type state func(
	token int32,
	sourcePath protoreflect.SourcePath,
	index int, // needed to handle nested structures
	excludeChildAssociatedPaths bool,
) (state, []protoreflect.SourcePath, error)

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Aug 13, 2024, 6:57 PM

[bufdev]

Still needs work but we've logged what that is, merging into bufplugin so I can use this.