Repository Public
1#!/usr/bin/env python32# Author: Simon-Pierre Boucher — contact@spboucher.ai3# File: Scripts/add-headers.py4# Description: Adds the author header (Author / File / Description) to first-party source files that lack it.5#6# The description is the first sentence of the file's first documentation comment, or the fallback given below.7import os, re, subprocess, sys8ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")9os.chdir(ROOT)10FALLBACK = {11 "Package.swift": "Swift package of SP Music's core (audio, networking, sync, downloads, offline library) and its tests.",12 "Core/Metadata/Models.swift": "Value types shared by every layer: artists, albums, tracks, playlists, lyrics, formatting helpers.",13 "Core/Persistence/SQLite.swift": "Thin wrapper over one SQLite connection (statements cache, typed rows, transactions).",14 "Core/Synchronization/WireModels.swift": "JSON shapes of the cluster's API (music.spboucher.ai, /api/v1).",15 "Core/Networking/AdminAPI.swift": "Client of the cluster's administration surface: imports, album edits, server health.",16 "Core/Security/Keychain.swift": "Session credential and its stores (Keychain in release builds, memory and file stores for tests).",17 "Core/Security/PathGuard.swift": "Confines every deletion and move to folders the app created and marked; safe file names.",18 "Core/Authentication/AuthService.swift": "Signing in (passkey, device linking) and out; session refresh.",19 "Core/Audio/AudioQueue.swift": "The play queue as pure data: order, shuffle, repeat, edits.",20 "Core/Audio/AudioOutputManager.swift": "Audio output devices from the Core Audio HAL: list, sample rates, change notifications.",21 "Core/Audio/PlaybackController.swift": "Observable playback state and transport: queue, source resolution, next-track preparation, history.",22 "App/AppSettings.swift": "Preferences of the app on this Mac (UserDefaults) and the configurable keyboard shortcuts.",23 "App/AppEnvironment.swift": "Application model: session lifecycle, sign-in, synchronisation, downloads and playback wiring.",24 "App/AppDelegate.swift": "Application delegate: opened files, Dock menu, wake from sleep, orderly termination.",25 "App/SPMusicApp.swift": "App entry point: windows, main layout, menus and keyboard shortcuts.",26 "Tools/spmusic-cli/main.swift": "Command-line companion of the core package (placeholder entry point).",27}28def describe(path, text):29 if path in FALLBACK: return FALLBACK[path]30 m = re.search(r"^\s*///\s*(.+)$", text, re.M)31 if m:32 s = m.group(1).strip()33 s = re.split(r"(?<=[.:])\s", s)[0].rstrip(":").strip()34 return s if s.endswith(".") else s + "."35 stem = os.path.splitext(os.path.basename(path))[0]36 return ("Tests: " if path.startswith("Tests/") else "SP Music — ") + re.sub(r"(?<=[a-z])(?=[A-Z])", " ", stem).lower() + "."37files = subprocess.run(["git", "ls-files", "-co", "--exclude-standard"], capture_output=True, text=True).stdout.split("\n")38n = 039for f in files:40 if not re.search(r"\.(swift|sh|py|yml)$", f) or not os.path.isfile(f): continue41 t = open(f, encoding="utf-8").read()42 if "Author: Simon-Pierre Boucher" in "\n".join(t.split("\n")[:12]): continue43 c = "//" if f.endswith(".swift") else "#"44 head = f"{c} Author: Simon-Pierre Boucher — contact@spboucher.ai\n{c} File: {f}\n{c} Description: {describe(f, t)}\n"45 lines = t.split("\n")46 # keep a shebang or the swift-tools-version line first47 if lines and (lines[0].startswith("#!") or lines[0].startswith("// swift-tools-version")): out = lines[0] + "\n" + head + "\n".join(lines[1:])48 else: out = head + ("\n" if not f.endswith(".swift") else "") + t49 open(f, "w", encoding="utf-8").write(out); n += 150print(f"headers added: {n}")51