OpenRailAssociation / OpenRailAssociation/osrd
core: `Path` typing isn't consistent
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 660
- Forks
- 87
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 269
Description
Path is an interface that can be used to type Length, Offset, and such.
But we have significant issues with what it actually means. When we handle several types of paths, it generally means "0 = start of the first block included in the path". But there are cases where 0 means the departure point (as in, the travelled path).
That's a significant issue. We should unify this, make the semantics consistent, and document it. We should probably remove the ambiguous Path at least temporarily, and introduce a BlockPath type instead.
Might be addressed at some point (no sub-issue created, TDB if we must track it):
- type offsets in envelope framework, as noted https://github.com/OpenRailAssociation/osrd/pull/11210#discussion_r2007244553
- Rename some types for consistency about use of "sequence"/"path"/"..." https://github.com/OpenRailAssociation/osrd/issues/11259
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with core/kt-osrd-sim-infra/src/main/kotlin/fr/sncf/osrd/sim_infra/api/PathProperties.kt and trace how Path, Length, and Offset are used for different path meanings. Review the envelope framework offset discussion and the related naming issue. Done means the path semantics are unified, ambiguous Path usage is addressed as appropriate, and the resulting types are documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100