API Reference

Auto-generated from source docstrings.

CLI

CLI entry point and subcommand orchestration for yilan.

main()

CLI entry point; dispatches to update or diff flow.

Returns:

Type	Description
int	Exit code: 0 for success, 1 for errors.

parse_args(argv=None)

Build and parse the argument parser.

Parameters:

Name	Type	Description	Default
argv	list[str] | None	Argument list; uses sys.argv[1:] when None.	None

Returns:

Type	Description
Namespace	Parsed namespace with all CLI flags and the optional subcommand field.

Configuration

Configuration dataclasses and TOML loader for yilan.

ApiConfig dataclass

Codeberg API connection settings.

Attributes:

Name	Type	Description
base_url	str	API base URL.
max_retries	int	Retry attempts on HTTP 429.
request_timeout	int	Per-request timeout in seconds.

CacheConfig dataclass

SHA-based response cache settings.

Attributes:

Name	Type	Description
enabled	bool	Whether the cache is active.
path	str	Path to the JSON cache file (supports ~ expansion).

ConceptsConfig dataclass

Source and selection of concept documents.

Attributes:

Name	Type	Description
items	list[str]	Concept folder names to include.
dir	str	Local directory containing concept subdirectories.
repo	str	Remote owner/repo to fetch from; overrides dir when non-empty.

Config dataclass

Root configuration object assembled from config.toml.

Attributes:

Name	Type	Description
owners	OwnersConfig	Account discovery settings.
repos	ReposConfig	Repo-level overrides.
intent_files	IntentFilesConfig	Intent file scanning settings.
concepts	ConceptsConfig	Concept document settings.
api	ApiConfig	API connection settings.
cache	CacheConfig	Cache settings.
paths	PathsConfig	Output path settings.

IntentFilesConfig dataclass

Which intent files to scan and how to parse them.

Attributes:

Name	Type	Description
files	list[str]	Filenames to look for in each repo.
plain_bullet_files	list[str]	Lowercase canonical filenames that use plain bullets instead of checklists (matched case-insensitively at runtime).

OwnersConfig dataclass

Codeberg accounts to discover repos under.

Attributes:

Name	Type	Description
accounts	list[str]	Usernames and org names.

PathsConfig dataclass

Output path settings.

Attributes:

Name	Type	Description
output	str	Path to write the board markdown file.

ReposConfig dataclass

Repo-level overrides.

Attributes:

Name	Type	Description
known_monorepos	list[str]	Repo names to treat as monorepos without probing.

load_config(path)

Load a Config from a TOML file, falling back to defaults.

Parameters:

Name	Type	Description	Default
path	Path | None	Path to config.toml; returns defaults if None or missing.	required

Returns:

Type	Description
Config	Parsed and merged Config.

merge_cli_args(config, args)

Apply CLI argument overrides to a Config, returning a deep copy.

Parameters:

Name	Type	Description	Default
config	Config	Base configuration (from file or defaults).	required
args	Namespace	Parsed CLI arguments namespace.	required

Returns:

Type	Description
Config	New Config with CLI values applied over config.

Data models

Pure data models shared across yilan modules.

ConceptData dataclass

Parsed data for a single concept document.

Attributes:

Name	Type	Description
folder	str	Name of the concept subdirectory.
phase	str	Bold phase/milestone text extracted from the document.
status_line	str	First non-empty, non-heading line from the Status section.
outstanding	list[str]	Open checklist items and questions from the document.
error	str | None	Error message if the concept could not be loaded.

IntentHeading dataclass

A single outstanding heading extracted from an intent file.

Attributes:

Name	Type	Description
heading	str	The ## heading text with ✅ stripped.
open_count	int | None	Number of open checklist items; None for plain-bullet files.
total_count	int	Total items (open + done, or plain bullets).

PackageInfo dataclass

Metadata and intent-file data for a single monorepo package.

Attributes:

Name	Type	Description
name	str	Package name from its pyproject.toml.
version	str	Package version string; empty string if absent.
description	str	Short description from pyproject.toml.
outstanding	list[IntentHeading]	Outstanding intent-file headings for this package.
todo	TodoSummary | None	TODO.md summary for this package, or None if absent.

RepoData dataclass

All fetched data for a single Codeberg repository.

Attributes:

Name	Type	Description
owner	str	Codeberg account or org name.
repo	str	Repository name.
last_commit_sha	str | None	HEAD commit SHA, or None if unavailable.
last_commit_msg	str | None	First line of the HEAD commit message.
last_commit_date	str | None	ISO 8601 date (YYYY-MM-DD) of the HEAD commit.
issues	list[tuple[int, str]]	Open issues as (number, title) tuples.
packages	list[PackageInfo]	Per-package data for monorepos; empty for regular repos.
outstanding	list[IntentHeading]	Outstanding intent-file headings for the repo root.
todo	TodoSummary | None	TODO.md summary, or None if no TODO.md was found.
status_md	str | None	Raw content of STATUS.md if present, otherwise None.
error	str | None	"no token" sentinel when the run had no API token.

TodoSummary dataclass

Aggregate checklist counts from a flat TODO.md file.

Attributes:

Name	Type	Description
open_count	int	Number of unchecked - [ ] items.
total_count	int	Total checklist items (open + done).

HTTP client

Thin HTTP client built on urllib with certifi SSL and retry on 429.

http_get(url, token=None, max_retries=5, timeout=15)

Perform a GET request and return (status_code, body).

Appends the token as a query parameter when provided. Retries up to max_retries times on HTTP 429, honouring Retry-After. Returns (0, "") on network errors or after exhausting retries.

Parameters:

Name	Type	Description	Default
url	str	Full URL to fetch.	required
token	str | None	Codeberg API token; appended as ?token=… when not None.	None
max_retries	int	Maximum number of attempts before giving up.	5
timeout	int	Per-attempt timeout in seconds.	15

Returns:

Type	Description
tuple[int, str]	A tuple of (http_status_code, response_body_text).

raw_url(owner, repo, path)

Build a Codeberg raw-file URL for a path on the main branch.

Parameters:

Name	Type	Description	Default
owner	str	Repository owner (user or org).	required
repo	str	Repository name.	required
path	str	File path relative to the repository root.	required

Returns:

Type	Description
str	Full URL to the raw file contents.

Codeberg API

Codeberg API fetching: repo discovery, commits, issues, intent files.

discover_repos(config, token)

Discover all non-fork, non-archived repos for each configured account.

Tries the /users/{account}/repos endpoint first, falling back to /orgs/{account}/repos on failure. Paginates until exhausted.

Parameters:

Name	Type	Description	Default
config	Config	Configuration with owners.accounts to iterate over.	required
token	str | None	Codeberg API token for authenticated requests.	required

Returns:

Type	Description
list[tuple[str, str]]	List of (owner, repo_name) tuples across all accounts.

fetch_all_data(config, token, cache)

Discover repos and fetch data for all of them sequentially.

Parameters:

Name	Type	Description	Default
config	Config	Full yilan configuration.	required
token	str | None	Codeberg API token.	required
cache	RepoCache | None	In-memory cache; pass None to skip caching.	required

Returns:

Type	Description
list[RepoData]	List of RepoData in discovery order.

fetch_repo_data(owner, repo, token, config, cache=None)

Fetch full data for a single repo, using the cache when the SHA is unchanged.

Parameters:

Name	Type	Description	Default
owner	str	Repository owner.	required
repo	str	Repository name.	required
token	str | None	Codeberg API token; returns a no token stub when None.	required
config	Config	Full yilan configuration.	required
cache	RepoCache | None	In-memory cache; pass None to disable caching.	None

Returns:

Type	Description
RepoData	Populated RepoData, either from cache or freshly fetched.

Concepts

Concept document parsing from local directories and remote Codeberg repos.

fetch_concepts(config, token)

Dispatch to local or remote concept fetching based on config.

Uses remote fetching when config.concepts.repo is non-empty, otherwise reads from the local config.concepts.dir directory.

Parameters:

Name	Type	Description	Default
config	Config	Full yilan configuration.	required
token	str | None	Codeberg API token for remote fetching.	required

Returns:

Type	Description
list[ConceptData]	List of ConceptData for the configured items.

fetch_concepts_local(concepts_dir, items)

Read and parse concept documents from a local directory.

Each item is looked up as a subdirectory of concepts_dir, reading README.md, concept.md, or the first .md file found.

Parameters:

Name	Type	Description	Default
concepts_dir	Path	Base directory containing per-concept subdirectories.	required
items	list[str]	Concept folder names to load.	required

Returns:

Type	Description
list[ConceptData]	List of ConceptData, with error entries for missing or unreadable items.

fetch_concepts_remote(repo, items, token, config)

Fetch and parse concept documents from a remote Codeberg repo.

Tries README.md then concept.md in each item's subdirectory.

Parameters:

Name	Type	Description	Default
repo	str	Remote repo as owner/repo.	required
items	list[str]	Concept folder names to fetch.	required
token	str | None	Codeberg API token.	required
config	Config	Configuration for API settings.	required

Returns:

Type	Description
list[ConceptData]	List of ConceptData, with error entries for items that could not be fetched.

parse_concept_content(folder, content)

Parse markdown content into a ConceptData.

Parameters:

Name	Type	Description	Default
folder	str	Concept folder name used as the identifier.	required
content	str	Raw markdown text of the concept document.	required

Returns:

Type	Description
ConceptData	Populated ConceptData with phase, status line, and outstanding items.

Cache

SHA-based RepoData cache backed by a JSON file.

CacheEntry dataclass

A single cached repo, keyed by the HEAD commit SHA.

Attributes:

Name	Type	Description
sha	str	HEAD commit SHA at the time the entry was written.
data	RepoData	Full RepoData fetched for that SHA.

RepoCache dataclass

In-memory cache state backed by a JSON file.

Attributes:

Name	Type	Description
entries	dict[str, CacheEntry]	Map of owner/repo to CacheEntry.
path	Path	File path for persistence.
dirty	bool	True when entries have been modified since the last save.

load_cache(config)

Load the cache from disk, or return None if caching is disabled.

Parameters:

Name	Type	Description	Default
config	CacheConfig	Cache configuration containing enabled flag and path.	required

Returns:

Type	Description
RepoCache | None	Populated RepoCache, an empty RepoCache if the file doesn't exist yet,
RepoCache | None	or None when config.enabled is False.

lookup(cache, owner, repo, current_sha)

Return cached RepoData if the SHA matches, otherwise None.

Parameters:

Name	Type	Description	Default
cache	RepoCache	The current in-memory cache.	required
owner	str	Repository owner.	required
repo	str	Repository name.	required
current_sha	str	HEAD commit SHA from the latest API response.	required

Returns:

Type	Description
RepoData | None	Cached RepoData with last_commit_sha restored, or None on miss.

save_cache(cache)

Persist the cache to disk if it has been modified.

Writes atomically via a .tmp file. No-op when cache.dirty is False.

Parameters:

Name	Type	Description	Default
cache	RepoCache	Cache to save.	required

update(cache, rd)

Upsert a RepoData entry into the cache and mark it dirty.

Parameters:

Name	Type	Description	Default
cache	RepoCache	The in-memory cache to update.	required
rd	RepoData	Fresh RepoData to store.	required

Renderer

Markdown rendering for the project status board.

format_concept_section(cd)

Render a single concept as a markdown ### section.

render_board(repos, date)

Render the full project status board as a markdown table.

Sorter

Sorting utilities for repo lists.

sort_repos(repos)

Sort repos so active ones come first, then alphabetically by repo name.

Active means the repo has open issues, outstanding intent-file headings, or open TODO items.

Parameters:

Name	Type	Description	Default
repos	list[RepoData]	Unsorted list of repo data.	required

Returns:

Type	Description
list[RepoData]	New list sorted by (0 if active else 1, repo_name.lower()).

Diff

Diff computation and markdown rendering between two board snapshots.

BoardDiff dataclass

Aggregated diff between two board snapshots.

Attributes:

Name	Type	Description
repo_diffs	list[RepoDiff]	Per-repo changes.
concept_diffs	list[ConceptDiff]	Per-concept changes.

is_empty()

Return True when neither repos nor concepts have any changes.

ConceptDiff dataclass

Changes detected for a single concept between two snapshots.

Attributes:

Name	Type	Description
folder	str	Concept folder name.
added	bool	Concept appeared in current snapshot but not previous.
removed	bool	Concept was in previous snapshot but not current.
status_changed	bool	Status line text changed.
status_before	str | None	Previous status line when status_changed is True.
status_after	str | None	Current status line when status_changed is True.
outstanding_added	list[str]	Outstanding items added since previous snapshot.
outstanding_removed	list[str]	Outstanding items removed since previous snapshot.

is_empty()

Return True when no changes were detected for this concept.

RepoDiff dataclass

Changes detected for a single repo between two snapshots.

Attributes:

Name	Type	Description
key	str	owner/repo identifier.
added	bool	Repo appeared in the current snapshot but not the previous.
removed	bool	Repo was in the previous snapshot but not the current.
commit_changed	bool	HEAD commit SHA changed.
commit_msg_before	str | None	Previous commit message when commit_changed is True.
commit_msg_after	str | None	Current commit message when commit_changed is True.
issues_opened	list[tuple[int, str]]	Issues present in current but not previous.
issues_closed	list[tuple[int, str]]	Issues present in previous but not current.
headings_added	list[str]	Outstanding heading texts added since previous snapshot.
headings_removed	list[str]	Outstanding heading texts removed since previous snapshot.
todo_delta	int | None	Change in open TODO count (positive = more open, negative = fewer).

is_empty()

Return True when no changes were detected for this repo.

compute_diff(previous, current)

Compute the full BoardDiff between two snapshots.

Parameters:

Name	Type	Description	Default
previous	Snapshot	Snapshot from the last board update.	required
current	Snapshot	Freshly fetched snapshot.	required

Returns:

Type	Description
BoardDiff	BoardDiff containing all repo and concept changes.

render_diff(diff, prev_date, curr_date)

Render a BoardDiff as a markdown string.

Parameters:

Name	Type	Description	Default
diff	BoardDiff	The computed diff to render.	required
prev_date	str	Date string of the previous snapshot.	required
curr_date	str	Date string of the current snapshot.	required

Returns:

Type	Description
str	Markdown diff report, ending with a newline.

Snapshot

Board snapshot persistence used by the diff subcommand.

Snapshot dataclass

A point-in-time capture of the board state for diffing.

Attributes:

Name	Type	Description
timestamp	str	ISO 8601 date string when the snapshot was taken.
repos	dict[str, RepoData]	Map of owner/repo to RepoData.
concepts	dict[str, ConceptData]	Map of concept folder name to ConceptData.

load_snapshot(cache_config)

Load a previously saved Snapshot, or return None if none exists.

Parameters:

Name	Type	Description	Default
cache_config	CacheConfig	Cache configuration providing the base directory path.	required

Returns:

Type	Description
Snapshot | None	Deserialized Snapshot, or None if the snapshot file is absent.

save_snapshot(repos, concepts, cache_config)

Persist the current board state to a JSON snapshot file.

Writes atomically via a .tmp file to the same directory as the cache.

Parameters:

Name	Type	Description	Default
repos	list[RepoData]	Current repo data list.	required
concepts	list[ConceptData]	Current concept data list.	required
cache_config	CacheConfig	Cache configuration providing the base directory path.	required