bug: ToPartitionKeyString(0) throws due to incomplete switch coverage for single-component partition key

[DrBarnabus]

Description

The generated ToPartitionKeyString(int throughPartIndex, bool includeTrailingDelimiter = true) method has incomplete switch coverage when the partition key has a single component.

The switch only handles (0, false). Since the default value of includeTrailingDelimiter is true, calling ToPartitionKeyString(0) hits the _ default case and throws InvalidOperationException.

The generator should emit a (0, true) case that appends the PrimaryKeySeparator to the partition value, similar to how it handles multi-component partition keys in other composite keys.

Reproduction

Visible in the snapshot baseline:
SourceGeneratorSnapshotTests.RepeatingPropertyCompositeKey_SourceOutput#UnitTests.UserTagKey.g.verified.cs (lines ~54-61)

Expected behaviour

ToPartitionKeyString(0) should return the first partition component with the trailing delimiter appended, consistent with multi-component partition key behaviour.

The throwing behaviour for (lastIndex, true) is intentional — there is no following delimiter to include, so the combination is invalid. However:

1. The documentation on IPrimaryKey<TSelf>.ToPartitionKeyString and ICompositePrimaryKey<TSelf>.ToSortKeyString does not communicate this. The param doc says "Whether to include the following delimiter character in the formatted string" but does not explain what happens when there is no following delimiter (i.e. when throughPartIndex refers to the last component).

2. The default value of includeTrailingDelimiter = true makes the most natural call pattern (ToPartitionKeyString(0)) a guaranteed throw for single-component keys, and ToPartitionKeyString(lastIndex) a throw for all keys. The default should be changed to false for safety, so that callers who omit the parameter get the value through the specified index without an unexpected exception.

Both changes constitute a breaking change to the shipped public API (PublicAPI.Shipped.txt).

Discovered via

Snapshot testing added in #48 — this is a pre-existing generator issue, not a regression.

[DrBarnabus]

Investigation Findings

Is this actually a bug?

Partially — the throw is intentional, but the documentation and default parameter value are the real problems.

The throwing behaviour for (lastIndex, true) is by design: there is no following delimiter to include, so the combination is invalid. However, this is not communicated anywhere, and the default parameter value of true makes the most natural call pattern a guaranteed throw.

Scope

The issue affects the last component of ANY key (both partition and sort side), not just single-component keys. The single-component case is the most visible because there's no way to call the indexed overload with the default parameter without throwing.

Affected scenarios:

Scenario	Call with default	Result
Single-component partition key	ToPartitionKeyString(0)	Throws — no valid default-parameter call exists
Single-component sort key	ToSortKeyString(0)	Throws — no valid default-parameter call exists
Multi-component partition key (N parts)	ToPartitionKeyString(N-1)	Throws
Multi-component sort key (N parts)	ToSortKeyString(N-1)	Throws

Root cause

Two issues in combination:

1. Missing documentation — The param doc on both IPrimaryKey<TSelf>.ToPartitionKeyString (IPrimaryKey1.cs:27) and ICompositePrimaryKey.ToSortKeyString (ICompositePrimaryKey1.cs:21) says:

Whether to include the following delimiter character in the formatted string, defaults to true.

It does not explain that passing true when throughPartIndex is the last component (no following delimiter) throws InvalidOperationException. The <example> blocks only show calls up to the second-to-last component, avoiding the edge case entirely.

2. Unsafe default parameter value — includeTrailingDelimiter = true means callers who use the natural pattern ToPartitionKeyString(index) get a throw for the last component. Changing the default to false would make the safe path the default.

Generator code (for reference)

WriteDynamicFormatMethodBodyForFixedKeyParts in SourceGenerator.Emitter.cs (lines 975–1004) generates switch cases by iterating over key parts. A (index, true) case is only emitted when a DelimiterKeyPart is encountered. Since the last component has no trailing delimiter, (lastIndex, true) is never generated — this is correct and intentional.

for (int i = 0, keyPartIndex = -1; i < keyParts.Count; i++)
{
    var keyPart = keyParts[i];
    bool isDelimiter = keyPart is DelimiterKeyPart;
    if (!isDelimiter)
        keyPartIndex++;
    string switchCase = $"({keyPartIndex}, {(isDelimiter ? "true" : "false")}) =>";
    // ...
}

Snapshot evidence

The generated code is behaving as the emitter intends — the issue is at the API design level, not the emitter level:

Single-component partition key (UserTagKey) — only (0, false) exists:

// RepeatingPropertyCompositeKey_SourceOutput#UnitTests.UserTagKey.g.verified.cs:54-61
return (throughPartIndex, includeTrailingDelimiter) switch
{
    (0, false) => string.Create(..., $"{UserId:d}"),
    _ => throw new InvalidOperationException(...)
};

Single-component sort key (InvariantCultureDisabled BasicPrimaryKey) — only (0, false) exists:

// InvariantCultureDisabled_SourceOutput#UnitTests.BasicPrimaryKey.g.verified.cs:50-57
return (throughPartIndex, includeTrailingDelimiter) switch
{
    (0, false) => $"{ThirdPart}",
    _ => throw new InvalidOperationException(...)
};

Multi-component partition key — (lastIndex, true) also absent (by design):

// BasicCompositePrimaryKey_SourceOutput#UnitTests.BasicPrimaryKey.g.verified.cs:76-85
return (throughPartIndex, includeTrailingDelimiter) switch
{
    (0, false) => ...$"{FirstPart:b}",
    (0, true) => ...$"{FirstPart:b}#",
    (1, false) => ...$"{FirstPart:b}#{SecondPart}",
    _ => throw ...  // (1, true) intentionally absent
};

Categorization

• Type: API design issue — documentation gap + unsafe default parameter
• Severity: Medium
• Breaking change: Yes — changing the default from true to false changes the shipped public API
• Pre-existing: Yes, predates refactor: Add snapshot tests using Verify.SourceGenerators #48

Proposed fix

1. Change default parameter on both interfaces to false:

   • IPrimaryKey<TSelf>.ToPartitionKeyString(int throughPartIndex, bool includeTrailingDelimiter = false)
   • ICompositePrimaryKey<TSelf>.ToSortKeyString(int throughPartIndex, bool includeTrailingDelimiter = false)
   • Update the generated method signatures in SourceGenerator.Emitter.cs to match
   • Update PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt to reflect the change

2. Improve documentation on both interface methods:

   • Clarify that includeTrailingDelimiter = true throws InvalidOperationException when throughPartIndex is the last component (no following delimiter exists)
   • Add an example showing the last component explicitly with false
   • Add <exception> tags documenting the throw conditions

3. Update functional tests: CompositePrimaryKeyTests.cs:67-75 currently asserts (1, true) throws — this remains correct but should be expanded to also test single-component keys

4. Update snapshot baselines: The generated method signatures will change from = true to = false