shuttlecheck 0.1.0__py3-none-any.whl

shuttlecheck/__init__.py

@@ -0,0 +1,39 @@
+"""ShuttleCheck -- naming and delivery conformance.
+
+Three entry points, in the order you would use them:
+
+    infer_spec / walkthrough   read an existing tree and write the spec it follows
+    Validator / validate       report what does not conform, in name and in
+                               substance -- codec, resolution, audio, packages
+    verify                     check a drive against the sidecar it arrived with
+
+**Nothing in this package modifies media.** That is the whole of it, and it is
+deliberate: a checker that cannot alter anything is a checker a stranger will
+run on a live job, because running it cannot cost them anything.
+
+The operations that write -- conforming, the journal, sealing a drive, vendor
+packs -- are licensed separately and ship as `shuttlecheck_pro`. When it is
+installed, `extensions.load()` finds it and the CLI and app grow the extra
+commands; nothing here imports it, and nothing here requires it.
+"""
+
+from . import extensions
+from .delivery import (FFProbeProber, MediaInfo, NullProber, Prober,
+                       check_deliverable, check_packages, check_sidecars)
+from .infer import InferenceReport, infer_spec
+from .report import Finding, Report
+from .sidecar import (ManifestEntry, Sidecar, SidecarError, read_sidecar,
+                      render_verify, verify)
+from .spec import Spec, SpecError, check_document, load_spec
+from .validate import Validator, validate
+from .version import __version__
+from .walkthrough import present, questionnaire, render_spec_yaml, walkthrough
+
+__all__ = [
+    "Finding", "Report", "Spec", "SpecError", "load_spec", "check_document",
+    "Validator", "validate", "InferenceReport", "infer_spec", "walkthrough",
+    "present", "render_spec_yaml", "questionnaire", "__version__", "extensions",
+    "Sidecar", "SidecarError", "ManifestEntry", "verify", "read_sidecar",
+    "render_verify", "Prober", "FFProbeProber", "NullProber", "MediaInfo",
+    "check_deliverable", "check_packages", "check_sidecars",
+]

shuttlecheck/checks.py

@@ -0,0 +1,156 @@
+"""Portability, structure, and collision checks.
+
+Each of these is a real-world failure that looks like a bug in someone else's
+software when it happens: a drive that ingests on macOS and fails on Windows,
+a conform that cannot relink, a copy that silently drops a file.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+
+from .report import Finding
+
+RESERVED_RANGE = re.compile(r"^([A-Z]+)(\d)-(\d)$")
+
+
+def expand_reserved(names) -> set[str]:
+    """Expand 'COM1-9' into COM1..COM9."""
+    out: set[str] = set()
+    for n in names or []:
+        m = RESERVED_RANGE.fullmatch(str(n).upper())
+        if m:
+            stem, lo, hi = m.group(1), int(m.group(2)), int(m.group(3))
+            out.update(f"{stem}{i}" for i in range(lo, hi + 1))
+        else:
+            out.add(str(n).upper())
+    return out
+
+
+def check_portability(spec, root: Path, path: Path, rel: str) -> list[Finding]:
+    """Cross-platform name and path constraints for one file or directory."""
+    p = spec.portability
+    findings: list[Finding] = []
+    name = path.name
+    stem = path.stem
+
+    forbidden = set(p.get("forbidden_chars") or "") - {"/", "\\", ":"}
+    hit = sorted(set(name) & forbidden)
+    if hit:
+        findings.append(Finding(
+            rule="forbidden-char",
+            severity=spec.severity("forbidden-char", "error"),
+            path=rel,
+            message=("name contains characters that are illegal on "
+                     f"{'/'.join(p['targets'])}: {' '.join(repr(c) for c in hit)}"),
+        ))
+
+    if stem.upper() in expand_reserved(p.get("reserved_names")):
+        findings.append(Finding(
+            rule="reserved-name",
+            severity=spec.severity("reserved-name", "error"),
+            path=rel,
+            message=f"'{stem}' is a reserved device name on Windows and cannot be opened",
+        ))
+
+    for ch in p.get("no_trailing") or []:
+        if name.endswith(ch):
+            findings.append(Finding(
+                rule="trailing-char",
+                severity=spec.severity("trailing-char", "error"),
+                path=rel,
+                message=(f"name ends with {ch!r}; Windows strips it silently, so the "
+                         "name on disk will stop matching the name in your manifest"),
+            ))
+            break
+
+    max_name = p.get("max_filename")
+    if max_name and len(name) > max_name:
+        findings.append(Finding(
+            rule="filename-too-long",
+            severity=spec.severity("filename-too-long", "error"),
+            path=rel,
+            message=f"filename is {len(name)} characters, limit is {max_name}",
+        ))
+
+    max_path = p.get("max_path")
+    if max_path and "windows" in p.get("targets", []):
+        absolute = len(str(path.resolve()))
+        if absolute > max_path:
+            findings.append(Finding(
+                rule="path-too-long",
+                severity=spec.severity("path-too-long", "error"),
+                path=rel,
+                message=(f"absolute path is {absolute} characters, over the "
+                         f"{max_path}-character Windows limit"),
+                detail={"absolute_length": absolute},
+            ))
+
+    if p.get("space_policy") == "forbid" and " " in name:
+        findings.append(Finding(
+            rule="space-in-name",
+            severity=spec.severity("space-in-name", "warning"),
+            path=rel,
+            message="name contains a space and the spec forbids spaces",
+        ))
+
+    if spec.safety.get("unicode") == "nfc" and unicodedata.normalize("NFC", name) != name:
+        findings.append(Finding(
+            rule="unicode-normalisation",
+            severity=spec.severity("unicode-normalisation", "warning"),
+            path=rel,
+            message=("name is not NFC-normalised; macOS stores decomposed and Windows "
+                     "composed, so this name compares unequal across platforms"),
+        ))
+
+    return findings
+
+
+def check_case_collisions(spec, entries: dict[Path, list[str]]) -> list[Finding]:
+    """Sibling names differing only by case break on Windows and macOS."""
+    findings: list[Finding] = []
+    for parent, names in entries.items():
+        buckets: dict[str, list[str]] = {}
+        for n in names:
+            buckets.setdefault(n.lower(), []).append(n)
+        for lowered, group in buckets.items():
+            if len(group) > 1:
+                findings.append(Finding(
+                    rule="case-collision",
+                    severity=spec.severity("case-collision", "error"),
+                    path=str(parent),
+                    message=("names differ only by case and cannot coexist on a "
+                             f"case-insensitive volume: {', '.join(sorted(group))}"),
+                    detail={"names": sorted(group)},
+                ))
+    return findings
+
+
+def check_structure(spec, dirs: list[str], files_by_dir: dict[str, list[str]]) -> list[Finding]:
+    """Required folders present, and no loose files where they are disallowed."""
+    findings: list[Finding] = []
+
+    for pattern, regex in spec.structure.get("_required_re", []):
+        if not any(regex.fullmatch(d) for d in dirs):
+            findings.append(Finding(
+                rule="missing-folder",
+                severity=spec.severity("missing-folder", "warning"),
+                path=pattern,
+                message="no folder in the tree matches this required structure path",
+            ))
+
+    for pattern, regex in spec.structure.get("_loose_re", []):
+        for d, names in files_by_dir.items():
+            if regex.fullmatch(d) and names:
+                findings.append(Finding(
+                    rule="loose-file",
+                    severity=spec.severity("loose-file", "warning"),
+                    path=d or ".",
+                    message=(f"{len(names)} file(s) sit directly in a folder that should "
+                             f"contain only subfolders: {', '.join(sorted(names)[:4])}"
+                             + (" ..." if len(names) > 4 else "")),
+                    detail={"files": sorted(names)},
+                ))
+    return findings

shuttlecheck/cli.py

@@ -0,0 +1,240 @@
+"""Command line entry point.
+
+    shuttlecheck ui        [folder]              open the local app in a browser
+    shuttlecheck init      <folder>              read the convention off an existing tree
+    shuttlecheck validate  <folder> --spec S     report what does not conform
+    shuttlecheck verify    <folder>              check a drive that arrived (no spec needed)
+    shuttlecheck check-spec --spec S             validate the spec itself
+
+None of the above modifies media. That is the whole of this package, and it is
+deliberate: a checker that cannot alter anything is a checker a stranger will
+run on a live job.
+
+Installing ShuttleCheck Pro adds the operations that write -- conform, revert,
+history, seal, pack, vendors -- and they appear here as extra subcommands. When
+it is absent those names are still registered, so asking for one gets an
+explanation rather than "invalid choice".
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+from . import extensions
+from .report import Report
+from .sidecar import SidecarError, render_verify, verify
+from .spec import SpecError, load_spec
+from .ui import serve
+from .validate import Validator
+from .version import __version__
+from .walkthrough import present, render_spec_yaml, walkthrough
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="shuttlecheck",
+        description="Naming and delivery conformance for live video and film.")
+    p.add_argument("--version", action="version", version=f"shuttlecheck {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    v = sub.add_parser("validate", help="check a tree and report violations")
+    v.add_argument("root")
+    v.add_argument("--spec", required=True)
+    v.add_argument("--json", action="store_true", help="emit JSON instead of text")
+    v.add_argument("--out", help="also write the report to this file")
+    v.add_argument("--info", action="store_true", help="include info-level findings")
+    v.add_argument("--limit", type=int, default=200,
+                   help="max findings to print (0 for all)")
+    v.add_argument("--strict", action="store_true",
+                   help="exit non-zero on warnings as well as errors")
+
+    c = sub.add_parser("check-spec", help="validate the spec itself and exit")
+    c.add_argument("--spec", required=True)
+
+    u = sub.add_parser("ui", help="open the local app in a browser")
+    u.add_argument("root", nargs="?", help="folder to open on (optional)")
+    u.add_argument("--port", type=int, default=8765)
+    u.add_argument("--no-browser", action="store_true",
+                   help="print the URL instead of opening it")
+
+    i = sub.add_parser("init", help="read a tree and write the spec it already follows")
+    i.add_argument("root")
+    i.add_argument("--out", help="default: <root>/_SPEC/spec.yaml")
+    i.add_argument("--project-code")
+    i.add_argument("--vocabulary", choices=["events", "film"], default="events")
+    i.add_argument("--id", dest="spec_id")
+    i.add_argument("--yes", action="store_true", help="accept every inference")
+    i.add_argument("--force", action="store_true", help="overwrite an existing spec")
+
+    y = sub.add_parser(
+        "verify", help="check a drive against the sidecar it arrived with")
+    y.add_argument("root")
+    y.add_argument("--hash", action="store_true",
+                   help="verify contents, not just sizes (slow)")
+    y.add_argument("--no-naming", action="store_true",
+                   help="check arrival only, skip the naming check")
+    y.add_argument("--limit", type=int, default=60)
+
+    pro = extensions.load()
+    if pro is not None:
+        pro.add_commands(sub)
+    else:
+        _add_licensed_stubs(sub)
+
+    return p
+
+
+LICENSED = ("conform", "revert", "history", "seal", "pack", "vendors")
+
+
+def _add_licensed_stubs(sub) -> None:
+    """Register the Pro command names so they explain themselves.
+
+    argparse would otherwise answer `shuttlecheck conform` with "invalid
+    choice", which reads like the command was misspelt rather than not
+    installed. These accept anything and fail with a sentence.
+    """
+    for name in LICENSED:
+        stub = sub.add_parser(name, help="(ShuttleCheck Pro -- not installed)",
+                              add_help=False)
+        stub.add_argument("args", nargs=argparse.REMAINDER)
+
+
+def _licensed_stub(args) -> int:
+    try:
+        extensions.require(f"`shuttlecheck {args.command}`")
+    except extensions.ExtensionMissing as exc:
+        print(f"\n{exc}\n", file=sys.stderr)
+        return 2
+    return 2
+
+
+def _load(spec_path: str):
+    try:
+        return load_spec(spec_path)
+    except SpecError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        raise SystemExit(2)
+
+
+def _require_dir(root: str) -> Path:
+    path = Path(root)
+    if not path.is_dir():
+        print(f"error: not a folder: {path}", file=sys.stderr)
+        raise SystemExit(2)
+    return path
+
+
+# --------------------------------------------------------------------------
+
+def _validate(args) -> int:
+    spec = _load(args.spec)
+    root = _require_dir(args.root)
+    report: Report = Validator(spec, root).run()
+    text = (report.to_json() if args.json
+            else report.to_text(show_info=args.info, limit=args.limit))
+    print(text)
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+    if report.errors:
+        return 1
+    return 1 if args.strict and report.warnings else 0
+
+
+def _check_spec(args) -> int:
+    spec = _load(args.spec)
+    if spec.lint:
+        for f in spec.lint:
+            print(f"{f.severity}: {f.rule}: {f.message}", file=sys.stderr)
+        return 1 if any(f.severity == "error" for f in spec.lint) else 0
+    print(f"{args.spec}: valid ({len(spec.tokens)} tokens, {len(spec.contexts)} contexts)")
+    return 0
+
+
+def _ui(args) -> int:
+    root = Path(args.root).resolve() if args.root else None
+    if root and not root.is_dir():
+        print(f"error: not a folder: {root}", file=sys.stderr)
+        return 2
+    serve(root, port=args.port, open_browser=not args.no_browser)
+    return 0
+
+
+def _init(args) -> int:
+    root = _require_dir(args.root)
+    out = Path(args.out) if args.out else root / "_SPEC" / "spec.yaml"
+    if out.exists() and not args.force:
+        print(f"error: {out} already exists; pass --force to overwrite", file=sys.stderr)
+        return 2
+    try:
+        doc, report, validation = walkthrough(
+            root, project_code=args.project_code, vocabulary=args.vocabulary,
+            interactive=not args.yes, spec_id=args.spec_id)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if report is not None:
+        if args.yes:
+            print(present(report, validation))
+        text = render_spec_yaml(doc, report)
+    else:
+        text = yaml.safe_dump(doc, sort_keys=False, allow_unicode=True, width=100)
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text, encoding="utf-8")
+    print(f"\n  spec written to {out}")
+    try:
+        load_spec(out)
+    except SpecError as exc:
+        print(f"\nwarning: the inferred spec does not match the schema:\n{exc}",
+              file=sys.stderr)
+        return 1
+    if report is not None and report.needs_review:
+        print(f"  {len(report.needs_review)} item(s) marked for review in the header.")
+    print(f"\n  next: shuttlecheck validate {root} --spec {out}")
+    return 0
+
+
+def _verify(args) -> int:
+    root = _require_dir(args.root)
+    try:
+        result = verify(root, check_hashes=args.hash,
+                        check_naming=not args.no_naming)
+    except SidecarError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(render_verify(result, limit=args.limit))
+    if not result.intact:
+        return 1
+    return 1 if result.naming is not None and result.naming.errors else 0
+
+
+COMMANDS = {"ui": _ui, "validate": _validate, "check-spec": _check_spec,
+            "init": _init, "verify": _verify}
+
+
+def _handlers() -> dict:
+    handlers = dict(COMMANDS)
+    pro = extensions.load()
+    if pro is not None:
+        handlers.update(pro.COMMANDS)
+    else:
+        handlers.update({name: _licensed_stub for name in LICENSED})
+    return handlers
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return _handlers()[args.command](args)
+    except SystemExit as exc:
+        return int(exc.code or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())