spark-sql-migrations 0.0.7__tar.gz → 0.0.9__tar.gz

{spark_sql_migrations-0.0.7 → spark_sql_migrations-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spark_sql_migrations
-Version: 0.0.7
+Version: 0.0.9
 Summary: Chained, idempotent SQL migrations for Spark and Databricks.
 Home-page: https://github.com/mcjug2015/spark_sql_migrations
 Author: Victor Semenov
@@ -143,6 +143,49 @@ migrations_dir)` directly.
 Every rendered statement is written to a timestamped folder under `migrations_out/`
 before it is executed, so you can always read the exact SQL a run applied.
 
+## Reading the chain
+
+```bash
+spark-sql-migrations history --migrations-dir path/to/migrations
+```
+
+Prints one line per migration, newest first, in alembic's shape — `prev -> rev, file`,
+with `<base>` standing in for the revision a root migration follows:
+
+```
+07990e2a101e -> 57037b6c19b4 (head), 260901_03_batch_id_for_metrics_e5ce0039b32b.sql
+e5ce0039b32b -> 07990e2a101e, 260831_02_create_metrics_table_07990e2a101e.sql
+<base> -> e5ce0039b32b, 260831_01_create_test_table_e5ce0039b32b.sql
+```
+
+| Flag | Effect |
+|---|---|
+| `-n`, `--limit` | list at most this many, counted from the end the listing starts at |
+| `--oldest-first` | walk from the root up instead of from the head down |
+
+`-n 5` with the default order gives the five newest; with `--oldest-first`, the five
+oldest. The files on disk are the whole of it: `history` reads no catalog and builds no
+session, so it needs no `--cat`, no `--schema` and no Spark flavour installed, and it says
+nothing about how far any catalog has been migrated.
+
+Unlike `run`, `history` refuses nothing — a chain it could not apply is exactly what you
+want it to describe. A fork is tagged where it happens and spelled out below the listing,
+which is kept whole even when `-n` cut the listing short:
+
+```
+c333 -> e555 (head), 260902_04_fork_the_chain_e555f1a2b3c4.sql
+c333 -> d444 (head), 260902_04_add_a_column_d444a1b2c3d4.sql
+b222 -> c333 (branchpoint), 260901_03_create_c_c333a1b2c3d4.sql
+split heads: d444, e555; a chain with more than one head cannot be applied until it is rejoined;
+c333 is the prev_revision_id of 260902_04_add_a_column_d444a1b2c3d4.sql, 260902_04_fork_the_chain_e555f1a2b3c4.sql;
+```
+
+Two migrations with an empty `prev_revision_id` (two chains in one directory) and
+migrations no root reaches (a cycle) get the same treatment. From Python,
+`history(migrations_dir, limit=None, oldest_first=False)` returns those same lines as a
+list, and `summarize_chain(read_migrations_dir(migrations_dir))` returns the heads, roots,
+branch points and orphans as objects.
+
 ## Writing a migration
 
 Generate one rather than hand-rolling the header:

{spark_sql_migrations-0.0.7 → spark_sql_migrations-0.0.9}/setup.py

@@ -147,6 +147,49 @@ migrations_dir)` directly.
 Every rendered statement is written to a timestamped folder under `migrations_out/`
 before it is executed, so you can always read the exact SQL a run applied.
 
+## Reading the chain
+
+```bash
+spark-sql-migrations history --migrations-dir path/to/migrations
+```
+
+Prints one line per migration, newest first, in alembic's shape — `prev -> rev, file`,
+with `<base>` standing in for the revision a root migration follows:
+
+```
+07990e2a101e -> 57037b6c19b4 (head), 260901_03_batch_id_for_metrics_e5ce0039b32b.sql
+e5ce0039b32b -> 07990e2a101e, 260831_02_create_metrics_table_07990e2a101e.sql
+<base> -> e5ce0039b32b, 260831_01_create_test_table_e5ce0039b32b.sql
+```
+
+| Flag | Effect |
+|---|---|
+| `-n`, `--limit` | list at most this many, counted from the end the listing starts at |
+| `--oldest-first` | walk from the root up instead of from the head down |
+
+`-n 5` with the default order gives the five newest; with `--oldest-first`, the five
+oldest. The files on disk are the whole of it: `history` reads no catalog and builds no
+session, so it needs no `--cat`, no `--schema` and no Spark flavour installed, and it says
+nothing about how far any catalog has been migrated.
+
+Unlike `run`, `history` refuses nothing — a chain it could not apply is exactly what you
+want it to describe. A fork is tagged where it happens and spelled out below the listing,
+which is kept whole even when `-n` cut the listing short:
+
+```
+c333 -> e555 (head), 260902_04_fork_the_chain_e555f1a2b3c4.sql
+c333 -> d444 (head), 260902_04_add_a_column_d444a1b2c3d4.sql
+b222 -> c333 (branchpoint), 260901_03_create_c_c333a1b2c3d4.sql
+split heads: d444, e555; a chain with more than one head cannot be applied until it is rejoined;
+c333 is the prev_revision_id of 260902_04_add_a_column_d444a1b2c3d4.sql, 260902_04_fork_the_chain_e555f1a2b3c4.sql;
+```
+
+Two migrations with an empty `prev_revision_id` (two chains in one directory) and
+migrations no root reaches (a cycle) get the same treatment. From Python,
+`history(migrations_dir, limit=None, oldest_first=False)` returns those same lines as a
+list, and `summarize_chain(read_migrations_dir(migrations_dir))` returns the heads, roots,
+branch points and orphans as objects.
+
 ## Writing a migration
 
 Generate one rather than hand-rolling the header:
@@ -299,5 +342,5 @@ Apache License 2.0 — see [LICENSE](LICENSE).
     },
     'python_requires': '>=3.10',
     'url': 'https://github.com/mcjug2015/spark_sql_migrations',
-    'version': '0.0.7',
+    'version': '0.0.9',
 })

{spark_sql_migrations-0.0.7 → spark_sql_migrations-0.0.9}/spark_sql_migrations/spark_sql/spark_sql.py

@@ -27,7 +27,7 @@ import os
 import re
 import uuid
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Set
 
 from jinja2 import Environment, FileSystemLoader, PackageLoader, select_autoescape
 from pyspark.sql.session import SparkSession
@@ -39,6 +39,8 @@ logger = logging.getLogger(__name__)
 
 
 VERSION_TABLE = "_spark_migrations_version"
+# what `history` prints in place of the revision a root migration follows
+BASE_LABEL = "<base>"
 
 PACKAGE_NAME = "spark_sql_migrations"
 INITIAL_MIGRATIONS_PACKAGE_PATH = "migrations_initial"
@@ -54,10 +56,29 @@ _COMMENT_OR_BLANK_RE = re.compile(r"^\s*(--.*)?$")
 @dataclass(frozen=True)
 class Migration:
     revision_id: str
-    prev_revision_id: str | None
+    prev_revision_id: Optional[str]
     template_name: str
 
 
+@dataclass(frozen=True)
+class ChainSummary:
+    """a directory's chain as `history` found it, forks and all.
+
+    ``ordered`` is oldest first and holds every migration in the directory, so a
+    listing built from it never silently drops a file. Everything else is what
+    makes the chain unapplicable: more than one ``heads`` entry is a split head,
+    a ``branch_points`` entry is where it split, more than one ``roots`` entry is
+    a second chain in the same directory, and ``orphans`` are files no walk from
+    any root reaches -- a cycle, in practice.
+    """
+
+    ordered: List[Migration]
+    heads: List[Migration]
+    roots: List[Migration]
+    branch_points: Dict[str, List[Migration]]
+    orphans: List[Migration]
+
+
 def get_default_template_path() -> str:
     """the template this package ships; callers may pass their own instead."""
     return os.path.join(os.path.dirname(__file__), "..", TEMPLATES_PACKAGE_PATH, DEFAULT_TEMPLATE_NAME)
@@ -122,7 +143,7 @@ def get_ordered_migration_objs(migration_objs: List[Migration]) -> List[Migratio
         next_by_revision[migration.prev_revision_id] = migration
 
     ordered = []
-    current: Migration | None = roots[0]
+    current: Optional[Migration] = roots[0]
     while current:
         ordered.append(current)
         current = next_by_revision.get(current.revision_id)
@@ -137,20 +158,130 @@ def get_ordered_migration_objs(migration_objs: List[Migration]) -> List[Migratio
     return ordered
 
 
-def get_migrations_list(migrations_dir: str) -> List[Migration]:
-    """every migration in one directory, walked from its root to its head."""
+def read_migrations_dir(migrations_dir: str) -> List[Migration]:
+    """every .sql file in one directory, parsed, in filename order and unwalked.
+
+    the headers are all this reads, so a chain that forks or points at nothing
+    comes back whole -- it is `get_ordered_migration_objs` that insists on a
+    single walkable chain, and `history` that reports one which is not.
+    """
     if not os.path.isdir(migrations_dir):
         raise ValueError(f"no migrations dir at {migrations_dir};")
 
-    migrations = [
+    return [
         _parse_migration(migrations_dir, template_name)
         for template_name in sorted(os.listdir(migrations_dir))
         if template_name.endswith(".sql")
     ]
+
+
+def get_migrations_list(migrations_dir: str, max_revision_id: Optional[str] = None) -> List[Migration]:
+    """every migration in one directory, walked from its root to its head.
+
+    ``revision_id`` cuts the walk short: the chain is returned up to and including
+    the migration carrying that revision. A revision no migration in the directory
+    carries is not an error -- the whole chain comes back, same as for no revision
+    at all.
+    """
+    migrations = read_migrations_dir(migrations_dir)
     if not migrations:
         return []
 
-    return get_ordered_migration_objs(migrations)
+    ordered = get_ordered_migration_objs(migrations)
+    if max_revision_id is None:
+        return ordered
+
+    for index, migration in enumerate(ordered):
+        if migration.revision_id == max_revision_id:
+            return ordered[: index + 1]
+
+    return ordered
+
+
+def get_children_by_revision(migrations: List[Migration]) -> Dict[Optional[str], List[Migration]]:
+    """each revision's followers, keyed by the revision they follow.
+
+    the root's followers sit under None. A revision with two followers is a fork,
+    which is why this returns a list and not one migration.
+    """
+    children: Dict[Optional[str], List[Migration]] = {}
+    for migration in sorted(migrations, key=lambda migration: migration.template_name):
+        children.setdefault(migration.prev_revision_id, []).append(migration)
+    return children
+
+
+def summarize_chain(migrations: List[Migration]) -> ChainSummary:
+    """walk a chain for reading rather than for applying.
+
+    this raises nothing: a fork, a second root or a revision following one no file
+    carries is what the caller asked to be shown, not a reason to refuse. The walk
+    is depth first from each root, so one branch of a fork is listed to its head
+    before the next branch starts, and a revision already listed is not listed
+    again -- which is what keeps a cycle from looping here.
+    """
+    children = get_children_by_revision(migrations)
+    known_revisions = {migration.revision_id for migration in migrations}
+    roots = [
+        migration
+        for migration in sorted(migrations, key=lambda migration: migration.template_name)
+        if not migration.prev_revision_id or migration.prev_revision_id not in known_revisions
+    ]
+
+    ordered: List[Migration] = []
+    seen: Set[Migration] = set()
+    stack = list(reversed(roots))
+    while stack:
+        migration = stack.pop()
+        if migration in seen:
+            continue
+        seen.add(migration)
+        ordered.append(migration)
+        stack.extend(reversed(children.get(migration.revision_id, [])))
+
+    # orphan - somehow comes from no root
+    orphans = [migration for migration in migrations if migration not in seen]
+    ordered.extend(sorted(orphans, key=lambda migration: migration.template_name))
+
+    return ChainSummary(
+        ordered=ordered,
+        heads=[migration for migration in ordered if not children.get(migration.revision_id)],
+        roots=roots,
+        branch_points={
+            revision_id: followers for revision_id, followers in children.items() if revision_id and len(followers) > 1
+        },
+        orphans=orphans,
+    )
+
+
+def format_history(summary: ChainSummary, limit: Optional[int] = None, oldest_first: bool = False) -> List[str]:
+    """the listing, newest first like alembic's unless asked for the other end.
+
+    ``limit`` cuts from the far end, so it keeps the newest with the default order
+    and the oldest with ``oldest_first`` -- either way, the end the listing starts
+    at is the end that survives. The notes are appended whole, even to a listing
+    cut short, because a split head is the thing worth seeing most.
+    """
+    if limit is not None and limit < 1:
+        raise ValueError(f"a history limit lists at least one migration, got {limit};")
+
+    ordered = summary.ordered if oldest_first else list(reversed(summary.ordered))
+    if limit is not None:
+        ordered = ordered[:limit]
+
+    head_revisions = {migration.revision_id for migration in summary.heads}
+    branch_point_revisions = set(summary.branch_points)
+    lines = [format_history_line(migration, head_revisions, branch_point_revisions) for migration in ordered]
+    return lines + format_chain_notes(summary)
+
+
+def history(migrations_dir: str, limit: Optional[int] = None, oldest_first: bool = False) -> List[str]:
+    """the chain in one directory, as lines ready to be printed.
+
+    the files on disk are the whole of it: no catalog is read and no session is
+    built, so a chain can be read anywhere, whatever any catalog has been migrated
+    to. `get_table_version` is what says where a catalog actually stands.
+    """
+    return format_history(summarize_chain(read_migrations_dir(migrations_dir)), limit=limit, oldest_first=oldest_first)
 
 
 def get_table_version(spark: SparkSession, cat: str, schema: str) -> Optional[Row]:
@@ -161,8 +292,10 @@ def get_table_version(spark: SparkSession, cat: str, schema: str) -> Optional[Ro
     return spark.read.table(version_table).select("version_num").head()
 
 
-def get_unapplied_migrations_list(spark: SparkSession, migrations_dir: str, cat: str, schema: str) -> List[Migration]:
-    ordered = get_migrations_list(migrations_dir)
+def get_unapplied_migrations_list(
+    spark: SparkSession, migrations_dir: str, cat: str, schema: str, max_revision_id: Optional[str] = None
+) -> List[Migration]:
+    ordered = get_migrations_list(migrations_dir, max_revision_id)
     current = get_table_version(spark, cat, schema)
     if not current:
         return ordered
@@ -239,9 +372,15 @@ def apply_template(output_dir: str, template, cat: str, schema: str) -> str:
 
 
 def get_ascending_letters_within_minute() -> str:
-    micros_since_minute = datetime.datetime.now() - datetime.datetime.now().replace(second=0, microsecond=0)
-    result = str(micros_since_minute.microseconds).translate(str.maketrans("0123456789", "ABCDEFGHIJ"))
-    return result
+    """a letter stamp that sorts in the order it was taken, within one minute.
+
+    the full microseconds since the minute began, not timedelta.microseconds -- that
+    holds only the sub-second part and so starts over every second. zero-padded to a
+    fixed width, because these are compared as text once they are folder names.
+    """
+    now = datetime.datetime.now()
+    micros_since_minute = (now - now.replace(second=0, microsecond=0)) // datetime.timedelta(microseconds=1)
+    return f"{micros_since_minute:08d}".translate(str.maketrans("0123456789", "ABCDEFGHIJ"))
 
 
 def get_output_folder(output_parent_path: str) -> str:
@@ -286,7 +425,14 @@ def record_revision(spark: SparkSession, cat: str, schema: str, revision_id: str
     spark.sql(f"insert into {version_table} (version_num) values ('{revision_literal}')")
 
 
-def migrate_w_rev(spark: SparkSession, output_folder: str, migrations_dir: str, cat: str, schema: str) -> None:
+def upgrade(
+    spark: SparkSession,
+    output_folder: str,
+    migrations_dir: str,
+    cat: str,
+    schema: str,
+    max_revision_id: Optional[str] = None,
+) -> None:
     """
     TODO XXX permit applying up to a revision below the head revision
     TODO XXX add backwards migrations, permit migrating backwards
@@ -294,7 +440,9 @@ def migrate_w_rev(spark: SparkSession, output_folder: str, migrations_dir: str,
     if not os.path.isdir(migrations_dir):
         logger.info(f"no chain at {migrations_dir}; skipping it;")
         return
-    unapplied = get_unapplied_migrations_list(spark, migrations_dir, cat=cat, schema=schema)
+    unapplied = get_unapplied_migrations_list(
+        spark, migrations_dir, cat=cat, schema=schema, max_revision_id=max_revision_id
+    )
 
     logger.info(
         f"{len(unapplied)} unapplied migrations; "
@@ -308,7 +456,14 @@ def migrate_w_rev(spark: SparkSession, output_folder: str, migrations_dir: str,
         logger.info(f"{migration.template_name} done; now at {migration.revision_id};")
 
 
-def run_migrations(spark: SparkSession, cat: str, schema: str, output_folder: str, migrations_dir: str) -> None:
+def run_upgrade(
+    spark: SparkSession,
+    cat: str,
+    schema: str,
+    output_folder: str,
+    migrations_dir: str,
+    max_revision_id: Optional[str] = None,
+) -> None:
     initial_output_folder = os.path.join(output_folder, INITIAL_MIGRATIONS_PACKAGE_PATH)
     client_output_folder = os.path.join(output_folder, CLIENT_OUTPUT_DIRNAME)
     os.makedirs(initial_output_folder, exist_ok=True)
@@ -318,17 +473,64 @@ def run_migrations(spark: SparkSession, cat: str, schema: str, output_folder: st
         logger.info(f"{version_table} already exists; skipping the initial migrations;")
     else:
         migrate_initial(spark, initial_output_folder, cat, schema)
-    migrate_w_rev(spark, client_output_folder, migrations_dir, cat, schema)
+    upgrade(spark, client_output_folder, migrations_dir, cat, schema, max_revision_id)
+
+
+def format_history_line(
+    migration: Migration, head_revisions: Set[str], branch_point_revisions: Set[str]
+) -> str:  # pragma: no cover
+    """one alembic-shaped line: `prev -> rev (tags), filename`."""
+    tags = []
+    if migration.revision_id in head_revisions:
+        tags.append("head")
+    if migration.revision_id in branch_point_revisions:
+        tags.append("branchpoint")
+    tag_text = f" ({', '.join(tags)})" if tags else ""
+    return f"{migration.prev_revision_id or BASE_LABEL} -> {migration.revision_id}{tag_text}, {migration.template_name}"
+
+
+def format_chain_notes(summary: ChainSummary) -> List[str]:  # pragma: no cover
+    """what is wrong with this chain, below the listing, or nothing if it is sound."""
+    notes = []
+    if len(summary.heads) > 1:
+        notes.append(
+            f"split heads: {', '.join(migration.revision_id for migration in summary.heads)}; "
+            f"a chain with more than one head cannot be applied until it is rejoined;"
+        )
+    for revision_id, followers in sorted(summary.branch_points.items()):
+        notes.append(
+            f"{revision_id} is the prev_revision_id of "
+            f"{', '.join(migration.template_name for migration in followers)};"
+        )
+    if len(summary.roots) > 1:
+        notes.append(
+            f"more than one root: {', '.join(migration.template_name for migration in summary.roots)}; "
+            f"a chain has exactly one migration following no other;"
+        )
+    if summary.orphans:
+        notes.append(
+            f"no root reaches {', '.join(migration.template_name for migration in summary.orphans)}; "
+            f"they are listed together at the tail end of the chain order, having none of their own;"
+        )
+    return notes
 
 
-def main(cat: str, schema: str, migrations_dir: str, output_parent_path: str | None = None) -> None:
+def main(
+    cat: str,
+    schema: str,
+    migrations_dir: str,
+    output_parent_path: Optional[str] = None,
+    max_revision_id: Optional[str] = None,
+) -> None:
     output_folder = get_output_folder(output_parent_path or os.path.join(os.getcwd(), "migrations_out"))
     os.makedirs(output_folder)
-    run_migrations(get_spark(), cat, schema, output_folder, migrations_dir)
+    run_upgrade(get_spark(), cat, schema, output_folder, migrations_dir, max_revision_id)
 
 
-def _cli_main(cat: str, schema: str, migrations_dir: str) -> None:  # pragma: no cover
-    main(cat, schema, migrations_dir)
+def _cli_main(
+    cat: str, schema: str, migrations_dir: str, max_revision_id: Optional[str] = None
+) -> None:  # pragma: no cover
+    main(cat, schema, migrations_dir, max_revision_id=max_revision_id)
 
 
 def _cli_create_new_migration(
@@ -337,14 +539,26 @@ def _cli_create_new_migration(
     create_new_migration(message, template_path or get_default_template_path(), output_path, add_is_dbr=add_is_dbr)
 
 
+def _cli_history(migrations_dir: str, limit: Optional[int], oldest_first: bool) -> None:  # pragma: no cover
+    """the listing goes to stdout, so it pipes; the log records go to stderr as always."""
+    for line in history(migrations_dir, limit=limit, oldest_first=oldest_first):
+        print(line)
+
+
 def build_parser() -> argparse.ArgumentParser:  # pragma: no cover
     parser = argparse.ArgumentParser(description="spark_sql_migrations migration utilities")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    p_run = subparsers.add_parser("run", help="apply all pending migrations")
+    p_run = subparsers.add_parser("run", help="upgrade to head/apply pending migrations")
     p_run.add_argument("--cat", type=str, default="spark_catalog")
     p_run.add_argument("--schema", type=str, default="default")
     p_run.add_argument("--migrations-dir", type=str, required=True, help="the directory holding the migration chain")
+    p_run.add_argument(
+        "--max-revision-id",
+        type=str,
+        default=None,
+        help="apply the migration carrying this revision_id and stop; defaults to applying the chain to its head",
+    )
     p_run.set_defaults(func=_cli_main)
 
     p_create = subparsers.add_parser("create_new_migration", help="create a new migration from the template")
@@ -367,10 +581,26 @@ def build_parser() -> argparse.ArgumentParser:  # pragma: no cover
     )
     p_create.set_defaults(func=_cli_create_new_migration)
 
+    p_history = subparsers.add_parser("history", help="list the migration chain on disk, newest first")
+    p_history.add_argument("--migrations-dir", type=str, required=True, help="the directory holding the chain")
+    p_history.add_argument(
+        "-n",
+        "--limit",
+        type=int,
+        default=None,
+        help="list at most this many migrations, counted from the end the listing starts at",
+    )
+    p_history.add_argument(
+        "--oldest-first",
+        action="store_true",
+        help="list from the root up instead of from the head down",
+    )
+    p_history.set_defaults(func=_cli_history)
+
     return parser
 
 
-def cli(argv: list[str] | None = None) -> None:  # pragma: no cover
+def cli(argv: Optional[list[str]] = None) -> None:  # pragma: no cover
     """the `spark-sql-migrations` console command.
 
     an application entry point, so unlike the rest of this package it configures

{spark_sql_migrations-0.0.7 → spark_sql_migrations-0.0.9}/spark_sql_migrations.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spark_sql_migrations
-Version: 0.0.7
+Version: 0.0.9
 Summary: Chained, idempotent SQL migrations for Spark and Databricks.
 Home-page: https://github.com/mcjug2015/spark_sql_migrations
 Author: Victor Semenov
@@ -143,6 +143,49 @@ migrations_dir)` directly.
 Every rendered statement is written to a timestamped folder under `migrations_out/`
 before it is executed, so you can always read the exact SQL a run applied.
 
+## Reading the chain
+
+```bash
+spark-sql-migrations history --migrations-dir path/to/migrations
+```
+
+Prints one line per migration, newest first, in alembic's shape — `prev -> rev, file`,
+with `<base>` standing in for the revision a root migration follows:
+
+```
+07990e2a101e -> 57037b6c19b4 (head), 260901_03_batch_id_for_metrics_e5ce0039b32b.sql
+e5ce0039b32b -> 07990e2a101e, 260831_02_create_metrics_table_07990e2a101e.sql
+<base> -> e5ce0039b32b, 260831_01_create_test_table_e5ce0039b32b.sql
+```
+
+| Flag | Effect |
+|---|---|
+| `-n`, `--limit` | list at most this many, counted from the end the listing starts at |
+| `--oldest-first` | walk from the root up instead of from the head down |
+
+`-n 5` with the default order gives the five newest; with `--oldest-first`, the five
+oldest. The files on disk are the whole of it: `history` reads no catalog and builds no
+session, so it needs no `--cat`, no `--schema` and no Spark flavour installed, and it says
+nothing about how far any catalog has been migrated.
+
+Unlike `run`, `history` refuses nothing — a chain it could not apply is exactly what you
+want it to describe. A fork is tagged where it happens and spelled out below the listing,
+which is kept whole even when `-n` cut the listing short:
+
+```
+c333 -> e555 (head), 260902_04_fork_the_chain_e555f1a2b3c4.sql
+c333 -> d444 (head), 260902_04_add_a_column_d444a1b2c3d4.sql
+b222 -> c333 (branchpoint), 260901_03_create_c_c333a1b2c3d4.sql
+split heads: d444, e555; a chain with more than one head cannot be applied until it is rejoined;
+c333 is the prev_revision_id of 260902_04_add_a_column_d444a1b2c3d4.sql, 260902_04_fork_the_chain_e555f1a2b3c4.sql;
+```
+
+Two migrations with an empty `prev_revision_id` (two chains in one directory) and
+migrations no root reaches (a cycle) get the same treatment. From Python,
+`history(migrations_dir, limit=None, oldest_first=False)` returns those same lines as a
+list, and `summarize_chain(read_migrations_dir(migrations_dir))` returns the heads, roots,
+branch points and orphans as objects.
+
 ## Writing a migration
 
 Generate one rather than hand-rolling the header: