settled-reach/tooling/wiki/generate-stubs.py

#!/usr/bin/env python3
"""
generate-stubs.py
Generates wiki stub markdown files for all 300 star systems from star-map.json.

Each system gets: docs/wiki/systems/{gj_dir}/index.md
where {gj_dir} is the astronomical_id with spaces replaced by hyphens.

Pre-fills all fields available from star-map.json; marks the rest as null (~).
Safe to re-run: skips files that already exist.
"""

import json
import re
from pathlib import Path

STAR_MAP_PATH = Path(__file__).parent.parent.parent / "docs/design/star-map.json"
WIKI_DIR = Path(__file__).parent.parent.parent / "docs/wiki/systems"


def gj_to_dirname(astronomical_id: str) -> str:
    """Convert 'GJ 71' to 'GJ-71', '2MASS J...' to '2MASS-J...'."""
    return astronomical_id.replace(" ", "-")


def render_stub(node: dict, adjacent_ids: list[str]) -> str:
    """Render a wiki stub markdown file for a single system."""
    sid = node["system_id"]
    astro_id = node["astronomical_id"]
    proper_name = node.get("proper_name")
    system_name = proper_name if proper_name else node.get("system_name", f"System {sid}")
    star_type = node.get("star_type", "~")
    sector = node.get("geographic_sector", "~")
    band = node.get("geographic_band", "~")
    zone = node.get("political_zone", "~")
    wave = node.get("settlement_wave", "~")
    horizon = node.get("aperture_count", 0) > 0
    aperture = node.get("aperture_count", 0)
    connections = node.get("gate_connections", 0)
    topology = node.get("gate_topology", "~")
    earth_prox = node.get("earth_proximity", "~")
    hop = node.get("hop_distance_from_gateway", "~")

    # Format proper_name for YAML (null or quoted string)
    proper_yaml = f'"{proper_name}"' if proper_name else "~"

    # Adjacent systems list for derived section
    adjacent_str = ", ".join(adjacent_ids) if adjacent_ids else "none"

    # Approximate settlement age from wave
    wave_ages = {
        "wave_1": "~550 years",
        "wave_2": "~400 years",
        "wave_3": "~200 years",
        "wave_4": "~70 years",
        "wave_5": "~20 years",
        "unsettled": "unsettled",
    }
    age_str = wave_ages.get(wave, "unknown")

    # Compound zone display
    compound = f"{sector} / {band} / {zone}"

    return f"""---
# ============================================================
# {astro_id} — {system_name}
# Star Systems Wiki — The Settled Reach
# ============================================================
# Auto-generated stub. Pre-filled fields from star-map.json.
# Fields marked ~ require authoring.
# ============================================================

# I. Identity and Location
system_id: {sid}
astronomical_id: "{astro_id}"
proper_name: {proper_yaml}
system_name: "{system_name}"
star_type: {star_type}
geographic_sector: {sector}
geographic_band: {band}
political_zone: {zone}

# II. Physical Character
habitable_planet_count: ~
inhabited_planet_count: ~
asteroid_belt: ~
gas_giant: ~
habitability_profile: ~

# III. Gate Infrastructure
horizon_station: {str(horizon).lower()}
aperture_count: {aperture}
gate_connections: {connections}
gate_topology: {topology}
span_gate_network: ~

# IV. Settlement History
settlement_wave: {wave}
founding_motivation: ~
founding_culture_primary: ~
founding_culture_secondary: ~
cultural_persistence: ~
historical_event: ~
historical_event_age_years: ~
religious_status: ~
religious_generation_count: ~

# V. Economic Life
economic_tier: ~
population: ~
economic_base_primary: ~
economic_base_secondary: ~
distribution_index: ~
imprint_access: ~

# VI. Governance
governance_type: ~
dominant_faction: ~
primary_fault_line: ~
secondary_fault_line: ~

# VII. Faction Presence
assembly_presence: ~
commission_presence: ~
syndic_presence: ~
syndic_type: ~
separatist_presence: ~
separatist_type: ~
institute_presence: ~
guardians_presence: ~

# VIII. Cultural Voice
cultural_register: ~
cultural_register_secondary: ~
ambient_anxiety: ~
local_pride: ~
atmospheric_tone: ~
atmospheric_tone_secondary: ~
active_situation: ~
silence_threshold: ~

# IX. Political Character
earth_alignment: ~
earth_proximity: {earth_prox}
earth_tension: ~

# X. Narrative Profile
primary_archetype: ~
secondary_archetype: ~
narrative_notable: ~
generation_priority: ~

# XI. Content Notes
stability_index: ~
system_volatility: ~
cultural_corridor: ~
---

# {system_name}
**{astro_id}** | {sid} | {star_type}-type | {sector} {band}

## Supply Dependency
<!-- Required for manufacturing/transit_logistics base and narrative_notable systems -->

## Faction Notes
<!-- Significant local factions not covered by standard columns -->

## Silence Topic
<!-- Required for narrative_notable and Institutional Core / Diplomatic Periphery zones -->

## Narrative Hook
<!-- Required if narrative_notable = true. One sentence. -->

## Calibration Note
<!-- Unusual column combinations requiring justification -->

## Derived Fields
<!-- Auto-generated from star-map.json, do not edit manually -->
- **Compound Zone:** {compound}
- **Settlement Age:** {age_str}
- **Hop Distance from Gateway:** {hop}
- **Adjacent Systems:** {adjacent_str}
"""


def main():
    with open(STAR_MAP_PATH, "r") as f:
        data = json.load(f)

    nodes = data["nodes"]
    edges = data["edges"]

    # Build adjacency map: system_id -> list of connected system_ids
    adj: dict[str, list[str]] = {n["system_id"]: [] for n in nodes}
    for a, b in edges:
        adj[a].append(b)
        adj[b].append(a)

    # Sort adjacency lists for deterministic output
    for sid in adj:
        adj[sid].sort()

    created = 0
    skipped = 0

    for node in sorted(nodes, key=lambda n: n["system_id"]):
        sid = node["system_id"]
        astro_id = node["astronomical_id"]
        dirname = gj_to_dirname(astro_id)
        outdir = WIKI_DIR / dirname
        outfile = outdir / "index.md"

        if outfile.exists():
            skipped += 1
            continue

        outdir.mkdir(parents=True, exist_ok=True)

        adjacent = adj.get(sid, [])
        content = render_stub(node, adjacent)

        outfile.write_text(content)
        created += 1

    print(f"Wiki stubs generated: {created} created, {skipped} skipped (already exist)")
    print(f"Output directory: {WIKI_DIR}")

    # Print a few examples
    print(f"\nExample directories:")
    dirs = sorted(WIKI_DIR.iterdir())[:5]
    for d in dirs:
        if d.is_dir():
            idx = d / "index.md"
            size = idx.stat().st_size if idx.exists() else 0
            print(f"  {d.name}/index.md  ({size} bytes)")


if __name__ == "__main__":
    main()