Skip to content

Commit 64b2bcc

Browse files
docs(identity): fix stale 8-hex / recipe references after the 0.8.0 change
Review caught three rustdoc strings still describing the pre-0.8.0 recipe: - FunctionIdentity::stable_id field doc said `fallow:fn:<8 hex>` (now 16) - the struct-level hash-exclusion doc described the old unseparated `file + name + start_line + "function"` preimage - the 0.6 changelog entry now cross-references the 0.8.0 reconciliation Also updated two opaque deserialize-test stable_id fixtures from the old 8-hex format to a 16-hex example so they stop implying 8-hex is current. No code or wire change.
1 parent 533e641 commit 64b2bcc

1 file changed

Lines changed: 11 additions & 8 deletions

File tree

src/lib.rs

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,10 @@
5252
//! continue to deserialize with `identity: None`; consumers SHOULD prefer
5353
//! `identity.stable_id` as the join key when present and fall back to the
5454
//! legacy `file` + `function` + `line` triple otherwise.
55-
//! - New [`function_identity_id`] helper emitting `fallow:fn:<8 hex>`. The
56-
//! helper hashes only `file + name + start_line + "function"` (NOT
55+
//! - New [`function_identity_id`] helper emitting `fallow:fn:<8 hex>` (this
56+
//! 0.6 recipe was reconciled to a NUL-delimited 16-hex digest in 0.8.0;
57+
//! see `# 0.8 changes`). The helper hashes only `file + name +
58+
//! start_line + "function"` (NOT
5759
//! columns) so producers with different positional fidelity (V8 byte
5860
//! offsets vs Istanbul UTF-16 columns vs oxc spans) agree on the join
5961
//! key for the same function. Columns survive on the wire as descriptive
@@ -621,9 +623,10 @@ pub enum IdentityResolution {
621623
///
622624
/// # Hash exclusion of columns
623625
///
624-
/// [`function_identity_id`] hashes only `file + name + start_line +
625-
/// "function"`. Columns, end positions, and `source_hash` are descriptive
626-
/// metadata for display and same-line disambiguation, but are NOT part of
626+
/// [`function_identity_id`] hashes only the NUL-delimited `file`, `name`,
627+
/// and `start_line` (see its rustdoc for the exact 0.8.0 recipe). Columns,
628+
/// end positions, and `source_hash` are descriptive metadata for display
629+
/// and same-line disambiguation, but are NOT part of
627630
/// the hash. Rationale: V8 runtime dumps frequently lack column info,
628631
/// while Istanbul fnMap and oxc spans always have it. If columns were
629632
/// hashed, the same function observed by two producers with different
@@ -715,7 +718,7 @@ pub struct FunctionIdentity {
715718
/// variants and hide the resolution-confidence signal cloud
716719
/// aggregation needs.
717720
pub resolution: IdentityResolution,
718-
/// Deterministic cross-surface join key of shape `fallow:fn:<8 hex>`.
721+
/// Deterministic cross-surface join key of shape `fallow:fn:<16 hex>`.
719722
/// Producers MUST compute this via [`function_identity_id`] so the
720723
/// CLI, sidecar, and cloud agree on the value for the same function.
721724
/// See the struct-level docs for the hash-input rationale.
@@ -1752,7 +1755,7 @@ mod tests {
17521755
"file": "src/a.ts",
17531756
"name": "foo",
17541757
"start_line": 42,
1755-
"stable_id": "fallow:fn:43629542"
1758+
"stable_id": "fallow:fn:0123456789abcdef"
17561759
}"#;
17571760
let result: Result<FunctionIdentity, _> = serde_json::from_str(json);
17581761
let err = result
@@ -1777,7 +1780,7 @@ mod tests {
17771780
"start_line": 42,
17781781
"start_column": 5,
17791782
"resolution": "unresolved",
1780-
"stable_id": "fallow:fn:43629542"
1783+
"stable_id": "fallow:fn:0123456789abcdef"
17811784
}"#;
17821785
let parsed: FunctionIdentity = serde_json::from_str(json).unwrap();
17831786
assert!(matches!(parsed.resolution, IdentityResolution::Unresolved));

0 commit comments

Comments
 (0)