Specification: Table Rendering & UI

Scope

Defines how the repository overview is transformed into a Markdown table (plus optional group headings) which is then embedded by higher-level renderers (see Renderers).

1. Input Contract

  • Rows – any ordered collection of key→row mappings or a sequence of (key,row) tuples. Each row is a mapping from column-key to cell value.

  • Column Configuration – ordered list where each entry contains:

    • key – the column key present in rows (string). Mandatory.

    • label – heading text shown in the table (string). Optional, defaults to key.

    • visible – whether the column appears (boolean). Optional, defaults to true.

  • Groups (optional) – mapping group-name → [row-keys] enabling logical sections.

2. Column Handling

  1. Preserve the exact order provided by the configuration list.

  2. A column with visible = false is omitted from both header and body.

  3. Cells whose value is None, empty, or one of the placeholder dashes ("-", "–", "—") are rendered as a single m-dash (—).

  4. No implicit data formatting is applied besides formatting explicitly mentioned in the spec; values are rendered verbatim except for the placeholder rule above explicit exceptions below.

3. Table Structure

  • The first line is the header row using configured labels.

  • The second line is the Markdown separator row (| --- | --- | … |).

  • Subsequent lines list body rows in the exact order they were supplied.

  • Each line starts and ends with | and separates cells with |.

  • There is no trailing whitespace.

  • If columns with keys priority or urgency are visible their numeric value will be converted in a Star Scale

4. Star Scale

  • A star scale is a display of low numeric values (usually 0-5)

  • The amount of filled stars (★) is the numeric value, the others empty stars (☆).

  • The amount of stars in the scale is min(5,max(value in column)).

5. Group Sections (optional)

When a Groups mapping is provided:

  1. Emit ### <Group-Name> before the first table pertaining to that group followed by an empty line.

  2. Within each section, include only the rows whose key appears in the corresponding list, and maintain their pre-existing order.

  3. Multiple groups are rendered sequentially by amount of projects within that group (or alphabetically on tie) with empty lines in between.

  4. Rows not referenced by any group appear after all groups under an implicit “Ungrouped” table (heading optional).

6. Error Handling

Issue

Behaviour

Column configuration references unknown key

Fail fast with configuration error.

Duplicate column keys in configuration

Configuration error.

Group lists reference unknown row keys

Warning or silent ignore; never duplicate rows.

7. Non-Goals

  • Styling for HTML previews is out of scope; responsibility of the downstream renderer.

  • Does not define how sorting is performed – see Table Sorting.