Documentation
¶
Overview ¶
Package migrate forward-migrates record types across format versions.
Each record type has a top-level dispatcher (MigrateSymbol, ...) and one or more pairwise migrations (MigrateSymbolV1ToV2, ...). The dispatcher chains migrations forward to core.FormatVersion. We never auto-degrade newer-than-current records — a record claiming a future version is an error.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeAndMigrateSymbol ¶
DecodeAndMigrateSymbol decodes a canonical JSON Symbol blob and forward-migrates the result to core.FormatVersion in one step. Production read paths should use this; core.DecodeSymbol is the raw primitive that does not migrate.
func MigrateSymbol ¶
MigrateSymbol forward-migrates s in place to core.FormatVersion.
Returns an error if s.Version is older than core.MinSupportedVersion or newer than core.FormatVersion. After a successful migration, s.Version == core.FormatVersion.
func MigrateSymbolV1ToV2 ¶
MigrateSymbolV1ToV2 mutates s in place from v1 to v2:
- Sets Language="go" if empty (v1 shipped Go-only).
- Bumps Version to 2.
Preserves Language if already set (defensive; v1 records should not carry Language but we don't fight a writer that included it).
func MigrateSymbolV2ToV3 ¶
MigrateSymbolV2ToV3 mutates s in place from v2 to v3.
v3 changes the Python FQN form from "src/click/core.py:Command.invoke" to "click.core.Command.invoke". Since Symbol.ID = hash(FQN, Kind), changing FQN changes ID, which orphans every edge / lineage record that references the old ID. A faithful in-place migration would be a graph-wide ID remap — that's a tool-sized effort, not a migration function.
Migration posture (per MIGRATION_SPEC.md §12): we advance the version tag but leave the FQN at its v2 form. The supported way to get v3 FQNs is to re-run `crowl analyze`, which extracts fresh from source. v0.3.x had no production Python users, so this is acceptable. Non-Python symbols (Go, TypeScript) have no FQN changes in v3 — they migrate cleanly.
func MigrateSymbolV3ToV4 ¶ added in v0.5.0
MigrateSymbolV3ToV4 mutates s in place from v3 to v4.
v4 is strictly additive at the record-content level: it introduces new SymbolKind values (Enum=13, EnumMember=14, Namespace=15) and a new EdgeKind (Extends=12). Existing v3 records reference only kinds 1..12 and 1..7,9..11, all unchanged in v4. There is no field addition on Symbol, no FQN remap, no signature change.
Per MIGRATION_SPEC.md §12 posture: TypeScript Symbol FQNs change form in v4 (file-path → module-path), but as with the v2→v3 Python transition, we do not rewrite FQNs in place — that would orphan every Edge and Lineage referencing the old ID. The supported way to get v4-form TypeScript FQNs is to re-run `crowl analyze` with the tree-sitter extractor (`--extractor=treesitter`).
Types ¶
This section is empty.
Source Files