Specification: Table Configuration (table_config.yaml)

Title and Purpose

Defines the external, user-editable YAML file (table_config.yaml) that controls which columns appear in the repository-overview table, their order, labels, visibility, and the default sort order & group notes used by downstream renderers.
The file is loaded at runtime via Settings.table_config (see src/gitlab_overviewer/config/settings.py) and is consumed by the sorting and rendering infrastructure (Table Sorting, Table Rendering & UI).

Scope and Boundaries

In scope – file structure, required/optional keys, validation rules, default behaviour, error handling.
Out of scope – CLI flags that override sorting (--sort) or alternative configuration sources.
Dependencies – relies on the column semantics defined in the data model and the behaviour specified in related specs above.

1 YAML Top-Level Keys

Key	Type	Required	Purpose
`columns`	list(dict)	Yes	Declares table columns (order = list order).
`default_sort`	list(str)	No	Fallback sort keys (§3) when the user supplies none.
`group_notes`	dict	No	Optional explanatory notes rendered under group sections.

Any additional keys are ignored and MUST NOT influence program flow.

2 `columns` Entries

Each element of columns is a mapping with the following fields:

Field	Type	Required	Default	Behaviour
`key`	str	Yes	–	Column key that must exist in every row.
`label`	str	No	Same as `key`	Header text displayed in the table.
`visible`	bool	No	`true`	If `false`, the column is omitted from header & body.

2.1 Validation Rules

The list must not contain duplicate key values.
Every key must match a property present in the overview data; unknown keys raise a TableConfigurationError before any rendering starts.
visible missing → treated as true (spec default).

3 `default_sort`

A list of sort-key strings complying with the grammar defined in Table Sorting.
They are evaluated left-to-right when no CLI/ENV override is supplied.

Validation occurs via the sort-utilities module:

Unknown columns or unsortable virtual columns raise SortConfigurationError.
If omitted, the application falls back to repo:asc (repository name ascending).

4 `group_notes`

Optional mapping controlling the informational paragraph appended after each group table (see rendering spec §5):

# Example structure
group_notes:
  default: "Note shown for groups without specific override."
  groups:
    alpha-group: "Alpha specific note."
    beta-group: "Beta specific note."

Sub-Key	Type	Required	Meaning
`default`	str	No	Note used for groups not listed under `groups`. May be empty.
`groups`	mapping	No	Explicit overrides `group-name → note`.

When absent entirely, no notes are rendered.

5 Error Handling Summary

Condition	Raised Exception	Origin
`columns` key missing	`TableConfigurationError`	`validate_column_configuration`
Duplicate or unknown column `key`	`TableConfigurationError`	idem
Invalid `default_sort` entry (unknown column, bad direction)	`SortConfigurationError`	`parse_sort_keys`
File path set in `Settings.table_config` does not exist	Runtime warning (log) – not fatal	`Settings.__init__`

The application MUST fail fast on configuration errors but remain robust against a missing config file by issuing a warning and operating with built-in defaults.

6 Testing Requirements

Positive Cases – snapshot tests must include at least one valid table_config.yaml verifying:
- Column order & labels propagate to rendered Markdown.
- Invisible columns are omitted.
- default_sort influences sort order when no CLI override is present.
Negative Cases – unit tests must assert that misconfigurations raise the correct exceptions (see table above).
Integration – approval tests covering the full pipeline (OverviewData → table → Markdown/Quarto) must pass with the gold-standard table_config.yaml located at project root.

7 Non-Goals

The spec does not mandate the location of the YAML file except that its path is provided via Settings.table_config (defaulting to table_config.yaml in the working directory).
Styling of the rendered table (HTML/CSS) is out of scope.
Runtime overrides (CLI --columns, etc.) are beyond this document.