Specification: Table Sorting

Overview

This document defines the expected behaviour of the table-sorting logic that orders repository overview rows before they are rendered (see Table Rendering & UI).

The rules apply regardless of the storage format of rows (mapping or sequence) and must remain stable under refactors.

1. Sort-Key Definition

A sort key is expressed as <column-expr>[:<direction>].
<direction> is asc (ascending) or desc (descending). If omitted, the default direction is implementation-defined but must be documented alongside any caller-facing CLI/ENV settings.
Multiple sort keys can be supplied, comma-separated, and are evaluated left-to-right (secondary, tertiary … tiebreakers).

1.1 Column Expressions

Simple column – the literal name of a data column, e.g. priority.
Virtual arithmetic column – an arithmetic expression that combines two or more simple columns using operators: +, -, or * (e.g. priority+urgency).
- Spacing is allowed inside the expression.
- * is evaluated before + and - (normal arithmatic rules).
- Nested arithmetic, parentheses, division, etc. are not supported.

2. General Ordering Rules

Rows with valid, comparable values for the current sort key are always placed before rows with invalid / missing values (e.g. None, "-", en- or em-dash, empty string).
“Valid” is defined per key type:
- Numeric: int, float, or numeric string.
- Date: ISO-8601 YYYY-MM-DD string (see §4).
- For any other literal, lexicographic comparison applies.
Sorting must be stable: when two rows compare equal under a sort key, the next key is evaluated; if no further keys exist, their relative order must remain as in the input sequence.

3. Virtual Arithmetic Columns

Virtual columns treat the operands as numbers and apply the specified operator. The computed result is then compared according to the direction.

Operand conversion: if a value parses as a number → use it; otherwise treat as 0 unless §3.3 applies.
Result type: always numeric; standard arithmetic rules apply.

3.1 Invalid Rows

If one operand cannot be converted to a number and all others evaluate to 0 each after conversion, the row is considered invalid for this virtual column.

3.2 Ordering with Invalid Rows

Invalid rows are always placed after valid rows (both in asc and desc).

3.3 Non-sortable Column Detection

If all rows in the working set are invalid for a given virtual column (i.e. no row contains two numeric operands), a configuration/validation layer must raise a configuration error signalling an unsortable key.

4. Date Handling

ISO-8601 dates (YYYY-MM-DD) are compared lexicographically (string comparison suffices).
For mixed content (some rows with valid dates, others missing) apply the invalid-row rule (§2-1).

5. Missing Values & Dashes

The placeholders None, "-", en-dash "–", em-dash "—" are treated as missing.
Missing values follow the invalid-row ordering rule.

6. Group-Aware Post-Processing

Sorting is applied before grouping. Once sorting is complete, a caller may group rows and render them under headings (see related spec).
The intra-group order must reflect the pre-group global order; no additional per-group sorting occurs unless explicitly requested.

7. Fallback Sorting Behaviour

A helper mechanism must apply the first key; if two rows tie, apply the next key, and so on.
Direction (asc/desc) is honoured individually for each key during fallback.

8. Error Handling Summary

Condition	Expected Reaction
Sort key references unknown column	Configuration error (fail-fast)
Virtual column unsortable (§3.3)	Configuration error
Non-numeric operand in otherwise sortable virtual column	Treat as `0`; row may still be valid if counterpart(s) numeric

9. Non-Goals

The spec does not prescribe a specific API or function signature – only externally visible behaviour.
Performance characteristics are out of scope.