kdk 2.0.0__py3-none-any.whl

kdk/__init__.py

@@ -0,0 +1,3 @@
+"""KDK - Kodi skin validation tool."""
+
+__version__ = "2.0.0"

kdk/__main__.py

@@ -0,0 +1,202 @@
+"""CLI entry point; run `kdk --help` for the available subcommands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def real_issues(issues):
+    """Drop the sentinel rows checks return when clean: no severity and no source line."""
+    return [i for i in issues if i.get("severity") or (i.get("line") or 0) > 0]
+
+
+def visible_issues(raw, args):
+    """Apply the include filter, sentinel filter, and any --severity/--category narrowing."""
+    from kdk.core import filter_include_warnings
+
+    issues = raw if args.show_include_warnings else filter_include_warnings(raw)
+
+    wanted = (args.category or "").lower()
+    result = {}
+    for category, rows in issues.items():
+        if wanted and wanted not in category.lower():
+            continue
+        rows = real_issues(rows)
+        if args.severity:
+            rows = [i for i in rows if i.get("severity") == args.severity]
+        if rows:
+            result[category] = rows
+    return result
+
+
+def exit_code(issues, strict):
+    """1 on errors, or on anything at all under --strict."""
+    from kdk.output import counts
+
+    errors, warnings = counts(issues)
+    if errors:
+        return 1
+    return 1 if strict and warnings else 0
+
+
+def cmd_validate(args):
+    from kdk.core import CHECK_SEQUENCE, save_report, validate_skin
+    from kdk.output import (
+        RunProgress, browse, console, render_github, render_issues, render_json,
+        render_summary, save_run,
+    )
+
+    skin_path = os.path.abspath(args.path)
+    if not os.path.isdir(skin_path):
+        print(f"Error: {skin_path} is not a directory", file=sys.stderr)
+        return 1
+
+    overrides = {}
+    if args.language:
+        overrides["language"] = args.language
+    if args.kodi_path:
+        overrides["kodi_path"] = args.kodi_path
+
+    with RunProgress(skin_path, len(CHECK_SEQUENCE), enabled=not args.json and not args.quiet) as bar:
+        result = validate_skin(skin_path, config_overrides=overrides, progress_callback=bar.update)
+
+    if result["error"]:
+        if args.json:
+            json.dump({"error": result["error"]}, sys.stdout, indent=2)
+            print()
+        else:
+            print(f"Error: {result['error']}", file=sys.stderr)
+        return 1
+
+    save_run(skin_path, result, result["issues"])
+    issues = visible_issues(result["issues"], args)
+
+    if args.json:
+        payload = render_json(result, issues)
+        text = json.dumps(payload, indent=2)
+        if args.output:
+            with open(args.output, "w", encoding="utf-8") as f:
+                f.write(text + "\n")
+            print(f"Written: {args.output}", file=sys.stderr)
+        else:
+            print(text)
+        return exit_code(issues, args.strict)
+
+    if args.github:
+        render_github(issues)
+
+    render_summary(result, issues)
+
+    if args.report or args.output:
+        report_path = save_report(result, args.output)
+        console.print(f"  [dim]Report saved: {report_path}[/]")
+        console.print()
+
+    if issues and not args.quiet:
+        interactive = console.is_terminal and not args.list and sys.stdin.isatty()
+        if interactive:
+            browse(issues, skin_path)
+        else:
+            render_issues(issues, skin_path)
+
+    return exit_code(issues, args.strict)
+
+
+def cmd_issues(args):
+    from kdk.output import browse, console, load_run, render_github, render_issues, render_json, render_summary
+
+    skin_path = os.path.abspath(args.path)
+    run = load_run(skin_path)
+    if not run:
+        print(f"No cached run for {skin_path} - run 'kdk validate' first", file=sys.stderr)
+        return 1
+
+    issues = visible_issues(run["issues"], args)
+
+    if args.json:
+        print(json.dumps(render_json(run, issues), indent=2))
+        return exit_code(issues, args.strict)
+
+    if args.github:
+        render_github(issues)
+
+    console.print()
+    console.print(f"  [bold]{run['skin_name']}[/]  [dim]validated {run['timestamp']}[/]")
+    console.print()
+
+    if args.browse and console.is_terminal and sys.stdin.isatty():
+        browse(issues, skin_path)
+    else:
+        render_issues(issues, skin_path)
+
+    if args.summary:
+        render_summary(run, issues)
+
+    return exit_code(issues, args.strict)
+
+
+def add_filters(parser):
+    """Flags shared by `validate` and `issues` so both narrow results the same way."""
+    from kdk.libs.validation.constants import SEVERITY_ERROR, SEVERITY_WARNING
+
+    parser.add_argument("--severity", choices=[SEVERITY_ERROR, SEVERITY_WARNING],
+                        help="Only show issues of this severity")
+    parser.add_argument("--category", help="Only show categories matching this text (e.g. fonts)")
+    parser.add_argument("--show-include-warnings", action="store_true",
+                        help="Include warnings that come from include content (hidden by default)")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero on warnings too, not just errors")
+    parser.add_argument("--json", action="store_true", help="Output JSON instead of the terminal view")
+    parser.add_argument("--github", action="store_true",
+                        help="Emit GitHub Actions annotations so CI shows each issue inline")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="kdk",
+        description="KDK - Kodi skin validation tool (CLI). Use kdk-gui for the GUI.",
+    )
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    p_validate = subparsers.add_parser("validate", help="Validate a Kodi skin")
+    # SUPPRESS so omitting it here does not overwrite the same flag given
+    # before the subcommand.
+    p_validate.add_argument("--debug", action="store_true", default=argparse.SUPPRESS,
+                            help="Enable debug logging")
+    p_validate.add_argument("path", nargs="?", default=".", help="Path to the skin addon directory")
+    p_validate.add_argument("--quiet", "-q", action="store_true", help="Summary only, no issue list")
+    p_validate.add_argument("--list", action="store_true", help="Print every issue instead of the picker")
+    p_validate.add_argument("--report", action="store_true", help="Also save the full text report")
+    p_validate.add_argument("--output", "-o", help="Write output to this path")
+    p_validate.add_argument("--language", help="Language code (e.g. resource.language.en_gb)")
+    p_validate.add_argument("--kodi-path", help="Path to Kodi installation")
+    add_filters(p_validate)
+    p_validate.set_defaults(func=cmd_validate)
+
+    p_issues = subparsers.add_parser("issues", help="Show issues from the last validate run")
+    p_issues.add_argument("--debug", action="store_true", default=argparse.SUPPRESS,
+                          help="Enable debug logging")
+    p_issues.add_argument("path", nargs="?", default=".", help="Path to the skin addon directory")
+    p_issues.add_argument("--browse", action="store_true", help="Pick a category instead of printing everything")
+    p_issues.add_argument("--summary", action="store_true", help="Append the per-category summary")
+    add_filters(p_issues)
+    p_issues.set_defaults(func=cmd_issues)
+
+    args = parser.parse_args()
+
+    from kdk.output import quiet_engine_logging
+    quiet_engine_logging(args.debug)
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 1
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kdk/config.py

@@ -0,0 +1,285 @@
+"""Plain-JSON config. Precedence: CLI overrides > `.kdk.json` (skin dir) > `~/.config/kdk/config.json` > defaults."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+logger = logging.getLogger("kdk.config")
+
+
+def _user_config_path() -> Path:
+    """OS-native location for the user config file."""
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA") or str(Path.home())
+        return Path(base) / "kdk" / "config.json"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "kdk" / "config.json"
+    return Path.home() / ".config" / "kdk" / "config.json"
+
+DEFAULTS = {
+    "language": "resource.language.en_gb",
+    "language_folders": ["resource.language.en_gb"],
+    "kodi_path": "",
+    "debug_mode": False,
+    # Editor for "open at line" - one of: code, sublime, notepad++, vim, nano, kate, gedit
+    # or empty string for OS default (no line number support)
+    "editor": "",
+}
+
+# {file} and {line} are substituted at call time. Sublime is handled specially
+# (see `_open_in_sublime`) because the path:line CLI suffix is unreliable.
+EDITOR_PATTERNS = {
+    "code":       ["code", "--goto", "{file}:{line}"],
+    "notepad++":  ["notepad++", "-n{line}", "{file}"],
+    "vim":        ["vim", "+{line}", "{file}"],
+    "nano":       ["nano", "+{line}", "{file}"],
+    "kate":       ["kate", "--line", "{line}", "{file}"],
+    "gedit":      ["gedit", "+{line}", "{file}"],
+}
+
+
+def load_config(skin_path: str | None = None, overrides: dict | None = None) -> dict:
+    """Merge defaults, OS-native user config, `<skin_path>/.kdk.json`, and `overrides` (in that order)."""
+    config = dict(DEFAULTS)
+
+    user_config = _user_config_path()
+    if user_config.exists():
+        try:
+            with open(user_config) as f:
+                config.update(json.load(f))
+        except Exception as e:
+            logger.warning("Failed to load user config %s: %s", user_config, e)
+
+    if skin_path:
+        project_config_path = Path(skin_path) / ".kdk.json"
+        if project_config_path.exists():
+            try:
+                with open(project_config_path) as f:
+                    config.update(json.load(f))
+            except Exception as e:
+                logger.warning("Failed to load project config %s: %s", project_config_path, e)
+
+    if overrides:
+        config.update({k: v for k, v in overrides.items() if v is not None})
+
+    return config
+
+
+class Settings:
+    """Dict-like settings wrapper matching the interface expected by libs/."""
+
+    def __init__(self, data: dict):
+        self._data = data
+
+    def get(self, key: str, default=None):
+        return self._data.get(key, default)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def __getitem__(self, key: str):
+        return self._data[key]
+
+
+def detect_editors() -> list[str]:
+    """Return list of editors found on PATH or common install locations."""
+    import shutil
+    import sys
+
+    candidates = [
+        ("code", ["code", "code.cmd"]),
+        ("sublime", ["subl", "subl.exe", "sublime_text", "sublime_text.exe"]),
+        ("notepad++", ["notepad++", "notepad++.exe"]),
+        ("kate", ["kate"]),
+        ("gedit", ["gedit"]),
+        ("vim", ["vim"]),
+        ("nano", ["nano"]),
+    ]
+
+    # Bundled installs of these editors don't always add themselves to PATH on Windows.
+    win_paths = [
+        ("code", [
+            os.path.expandvars(r"%LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd"),
+            os.path.expandvars(r"%PROGRAMFILES%\Microsoft VS Code\bin\code.cmd"),
+        ]),
+        ("sublime", [
+            os.path.expandvars(r"%PROGRAMFILES%\Sublime Text\subl.exe"),
+            os.path.expandvars(r"%PROGRAMFILES%\Sublime Text 3\subl.exe"),
+            os.path.expandvars(r"%PROGRAMFILES(x86)%\Sublime Text\subl.exe"),
+        ]),
+        ("notepad++", [
+            os.path.expandvars(r"%PROGRAMFILES%\Notepad++\notepad++.exe"),
+            os.path.expandvars(r"%PROGRAMFILES(x86)%\Notepad++\notepad++.exe"),
+        ]),
+    ]
+
+    found = []
+    for name, exes in candidates:
+        if any(shutil.which(exe) for exe in exes):
+            found.append(name)
+            continue
+        # On Windows, check common install locations
+        if sys.platform == "win32":
+            for wname, wpaths in win_paths:
+                if wname == name and any(os.path.isfile(p) for p in wpaths):
+                    found.append(name)
+                    break
+
+    return found
+
+
+EDITOR_DISPLAY_NAMES = {
+    "": "System Default",
+    "code": "VS Code",
+    "sublime": "Sublime Text",
+    "notepad++": "Notepad++",
+    "vim": "Vim",
+    "nano": "Nano",
+    "kate": "Kate",
+    "gedit": "Gedit",
+}
+
+
+def save_user_config(key: str, value) -> None:
+    """Save a single key to the user config file."""
+    config_path = _user_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing = {}
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                existing = json.load(f)
+        except Exception:
+            pass
+
+    existing[key] = value
+    with open(config_path, "w") as f:
+        json.dump(existing, f, indent=2)
+
+
+def _resolve_editor_exe(exe_name: str, editor_key: str) -> str | None:
+    """Resolve `exe_name` via PATH, falling back to known Windows install paths; `None` means use `exe_name` as-is."""
+    import shutil
+    import sys
+
+    if shutil.which(exe_name):
+        return None
+
+    if sys.platform != "win32":
+        return None
+
+    win_exe_map = {
+        "code": [
+            os.path.expandvars(r"%LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd"),
+            os.path.expandvars(r"%PROGRAMFILES%\Microsoft VS Code\bin\code.cmd"),
+        ],
+        "sublime": [
+            os.path.expandvars(r"%PROGRAMFILES%\Sublime Text\subl.exe"),
+            os.path.expandvars(r"%PROGRAMFILES%\Sublime Text 3\subl.exe"),
+        ],
+        "notepad++": [
+            os.path.expandvars(r"%PROGRAMFILES%\Notepad++\notepad++.exe"),
+            os.path.expandvars(r"%PROGRAMFILES(x86)%\Notepad++\notepad++.exe"),
+        ],
+    }
+
+    for path in win_exe_map.get(editor_key, []):
+        if os.path.isfile(path):
+            return path
+
+    return None
+
+
+def _resolve_sublime_exe() -> str | None:
+    """Find a Sublime executable.
+
+    Prefer `subl.exe` (the CLI wrapper) over `sublime_text.exe` because the
+    wrapper routes args through Sublime's existing-instance IPC. Calling
+    `sublime_text.exe` directly on Windows can spawn a new (hidden) instance
+    that receives the line jump while the user's visible Sublime stays put -
+    making the jump look broken even when it technically worked.
+    """
+    import shutil
+    import sys
+
+    if sys.platform == "win32":
+        candidates = [
+            r"%PROGRAMFILES%\Sublime Text\subl.exe",
+            r"%PROGRAMFILES%\Sublime Text 3\subl.exe",
+            r"%PROGRAMFILES(x86)%\Sublime Text\subl.exe",
+            r"%PROGRAMFILES%\Sublime Text\sublime_text.exe",
+            r"%PROGRAMFILES%\Sublime Text 3\sublime_text.exe",
+        ]
+        for c in candidates:
+            expanded = os.path.expandvars(c)
+            if os.path.isfile(expanded):
+                return expanded
+        return shutil.which("subl") or shutil.which("sublime_text")
+    return shutil.which("subl") or shutil.which("sublime_text")
+
+
+def _open_in_sublime(file_path: str, line: int) -> bool:
+    """Open `file_path` at `line` in Sublime via `subl FILE:LINE:COL`.
+
+    The path is normalized to forward slashes - Sublime's path:line:col parser
+    is happier with forward-slash paths on Windows even though backslash paths
+    are documented to work too.
+    """
+    import subprocess
+
+    exe = _resolve_sublime_exe()
+    if not exe:
+        logger.warning("Sublime not found")
+        return False
+
+    abs_path = os.path.abspath(file_path).replace("\\", "/")
+    arg = f"{abs_path}:{int(line)}:0" if line and line > 0 else abs_path
+    try:
+        subprocess.Popen([exe, arg])
+        return True
+    except FileNotFoundError:
+        logger.warning("Sublime executable not launchable: %s", exe)
+        return False
+
+
+def open_in_editor(file_path: str, line: int = 1, editor: str = "") -> bool:
+    """Open `file_path:line` in `editor`; falls back to OS default if `editor` is empty or missing."""
+    import subprocess
+    import sys
+
+    editor = editor.strip().lower()
+
+    if editor == "sublime":
+        return _open_in_sublime(file_path, line)
+
+    if editor and editor in EDITOR_PATTERNS:
+        cmd = [
+            part.replace("{file}", file_path).replace("{line}", str(line))
+            for part in EDITOR_PATTERNS[editor]
+        ]
+        exe = _resolve_editor_exe(cmd[0], editor)
+        if exe:
+            cmd[0] = exe
+        try:
+            subprocess.Popen(cmd)
+            return True
+        except FileNotFoundError:
+            logger.warning("Editor %r not found, falling back to OS default", editor)
+
+    # OS default opener can't take a line number.
+    try:
+        if sys.platform == "win32":
+            os.startfile(file_path)
+        elif sys.platform == "darwin":
+            subprocess.Popen(["open", file_path])
+        else:
+            subprocess.Popen(["xdg-open", file_path])
+        return True
+    except Exception as e:
+        logger.warning("Failed to open file: %s", e)
+        return False

kdk/core.py

@@ -0,0 +1,166 @@
+"""Core validation runner shared by CLI and GUI; no UI code here."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from datetime import datetime
+from typing import Callable
+
+from .config import load_config, Settings
+from .libs.infoprovider import InfoProvider
+from .libs.reporting.text import generate_text_report
+from .libs.validation.constants import SEVERITY_ERROR
+
+logger = logging.getLogger("kdk.core")
+
+CHECK_SEQUENCE = [
+    ("Variables", "check_variables"),
+    ("Includes", "check_includes"),
+    ("Labels", "check_labels"),
+    ("Fonts", "check_fonts"),
+    ("IDs", "check_ids"),
+    ("Images", "check_images"),
+    ("XML Validation", "check_values"),
+    ("File Integrity", "check_file_integrity"),
+]
+
+
+def filter_include_warnings(all_issues: dict) -> dict:
+    """Drop warnings sourced from `<include>` content (kept if severity is `error`); reduces false positives."""
+    filtered = {}
+    for category, issues in all_issues.items():
+        filtered[category] = [
+            i for i in issues
+            if not (i.get("include_name") and i.get("severity") != "error")
+        ]
+    return filtered
+
+
+def validate_skin(
+    skin_path: str,
+    *,
+    config_overrides: dict | None = None,
+    progress_callback: Callable[[int, int, str], None] | None = None,
+) -> dict:
+    """Run every check against the skin at `skin_path`. Returns `{issues, skin_name, skin_path, timestamp, duration, error}`."""
+    skin_path = os.path.abspath(skin_path)
+    config = load_config(skin_path, config_overrides)
+    settings = Settings(config)
+    total_steps = len(CHECK_SEQUENCE)
+
+    def progress(step: int, msg: str):
+        if progress_callback:
+            progress_callback(step, total_steps, msg)
+
+    addon_xml = os.path.join(skin_path, "addon.xml")
+    if not os.path.isfile(addon_xml):
+        return {
+            "issues": {},
+            "skin_name": "",
+            "skin_path": skin_path,
+            "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "duration": 0.0,
+            "error": f"No addon.xml found at {skin_path}",
+        }
+
+    progress(0, "Initializing...")
+
+    provider = InfoProvider()
+    provider.load_settings(settings)
+    provider.init_addon(skin_path)
+
+    if not provider.addon:
+        return {
+            "issues": {},
+            "skin_name": "",
+            "skin_path": skin_path,
+            "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "duration": 0.0,
+            "error": f"Failed to load addon at {skin_path}",
+        }
+
+    # Defensive: a fresh `init_addon` already builds a new `Skin`, but if a
+    # caller ever swaps to reusing one we want stale resolved trees gone.
+    cache = getattr(provider.addon, "_resolved_windows_cache", None)
+    if isinstance(cache, dict):
+        cache.clear()
+
+    fatal = getattr(provider, "_fatal_xml_error", None)
+    if fatal:
+        return {
+            "issues": {},
+            "skin_name": "",
+            "skin_path": skin_path,
+            "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "duration": 0.0,
+            "error": f"XML parse error in {os.path.basename(fatal)} - fix this file before validating",
+        }
+
+    skin_name = getattr(provider.addon, "name", "") or os.path.basename(skin_path)
+
+    start_time = time.time()
+    all_issues = {}
+
+    for step, (name, method_name) in enumerate(CHECK_SEQUENCE, 1):
+        progress(step, f"Checking {name.lower()}...")
+
+        def step_progress(message, _step=step, _name=name):
+            progress(_step, f"{_name}: {message}")
+
+        method = getattr(provider, method_name, None)
+        if method:
+            try:
+                all_issues[name] = method(progress_callback=step_progress) or []
+            except Exception as e:
+                logger.error("Check %s failed: %s", name, e, exc_info=True)
+                # Severity matters: without it the row is filtered out of every
+                # output mode and the run exits 0 despite the check never running.
+                all_issues[name] = [{
+                    "message": f"Check failed: {e}",
+                    "file": "", "line": 0, "severity": SEVERITY_ERROR,
+                }]
+        else:
+            logger.warning("Check method %s not found", method_name)
+
+    duration = time.time() - start_time
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    return {
+        "issues": all_issues,
+        "skin_name": skin_name,
+        "skin_path": skin_path,
+        "timestamp": timestamp,
+        "duration": duration,
+        "error": None,
+    }
+
+
+def get_downloads_folder() -> str:
+    """Return the OS default Downloads folder, or home as fallback."""
+    home = os.path.expanduser("~")
+    downloads = os.path.join(home, "Downloads")
+    if os.path.isdir(downloads):
+        return downloads
+    return home
+
+
+def save_report(result: dict, output_path: str | None = None) -> str:
+    """Write `result` (from `validate_skin`) as a text report; defaults to a timestamped file in the Downloads folder."""
+    if output_path is None:
+        safe_name = "".join(
+            c if c.isalnum() or c in ("-", "_") else "_"
+            for c in result["skin_name"]
+        )
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        output_path = os.path.join(get_downloads_folder(), f"{safe_name}_{ts}_report.txt")
+
+    generate_text_report(
+        all_issues=result["issues"],
+        skin_name=result["skin_name"],
+        skin_path=result["skin_path"],
+        output_path=output_path,
+    )
+
+    return output_path