hoodscript 1.1.0__py3-none-any.whl

hoodscript/__init__.py

@@ -0,0 +1,9 @@
+from hoodscript.importer import install, uninstall
+from hoodscript.transpiler import transpile
+
+try:
+    from hoodscript._version import __version__
+except ImportError:
+    __version__ = "1.1.0"
+
+__all__ = ["transpile", "install", "uninstall", "__version__"]

hoodscript/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from hoodscript.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

hoodscript/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)
+
+__commit_id__ = commit_id = None

hoodscript/cache.py

@@ -0,0 +1,36 @@
+import importlib.util
+import marshal
+import os
+import struct
+import sys
+from pathlib import Path
+
+FLAG_HASH_CHECKED = 0x03
+HEADER_SIZE = 16
+
+def get_cache_path(source_path):
+    p = Path(source_path).resolve()
+    tag = sys.implementation.cache_tag or f"cpython-{sys.version_info.major}{sys.version_info.minor}"
+    return p.parent / "__pycache__" / f"{p.stem}.{tag}.pyc"
+
+def read_cache(source_path, source_bytes):
+    f = get_cache_path(source_path)
+    if not f.is_file(): return None
+    try:
+        d = f.read_bytes()
+        if len(d) < HEADER_SIZE or d[0:4] != importlib.util.MAGIC_NUMBER: return None
+        if d[8:16] != importlib.util.source_hash(source_bytes): return None
+        return marshal.loads(d[HEADER_SIZE:])
+    except Exception: return None
+
+def write_cache(source_path, source_bytes, code_obj):
+    f = get_cache_path(source_path)
+    try:
+        f.parent.mkdir(parents=True, exist_ok=True)
+        hdr = (importlib.util.MAGIC_NUMBER + struct.pack("<I", FLAG_HASH_CHECKED)
+               + importlib.util.source_hash(source_bytes))
+        tmp = f.parent / f"{f.name}.tmp.{os.getpid()}"
+        tmp.write_bytes(hdr + marshal.dumps(code_obj))
+        tmp.replace(f)
+        return True
+    except Exception: return False

hoodscript/cli.py

@@ -0,0 +1,468 @@
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from hoodscript import __version__, importer, sandbox, traceback_handler
+from hoodscript.constants import (
+    HOOD_EXCEPTION_NAMES,
+    TIER_A,
+    TIER_B,
+    TIER_C,
+)
+from hoodscript.transpiler import transpile
+
+TOUR_TEXT = f"""HoodScript v{__version__} — AAVE keywords mapped 1:1 to Python 3
+
+Usage:
+  hoodscript <file.hs>              Run a HoodScript program (or `hoodscript run <file.hs>`)
+  hoodscript repl [--mirror]        Start interactive REPL (--mirror echoes Python)
+  hoodscript build <file.hs>        Transpile HoodScript to Python (-c)
+  hoodscript check <file.hs>        Check syntax without executing
+  hoodscript fmt <file.hs>          Format source files
+  hoodscript lint <file.hs>         Lint source files
+  hoodscript learn [topic]          Interactive tutor (try: hoodscript learn basics)
+  hoodscript debug <file.hs>        Debug program under debugpy / DAP
+  hoodscript tokens                 Show all keywords and mappings
+  hoodscript playground [--port]    Launch Web Playground in browser
+  hoodscript lsp                    Start Language Server
+  hoodscript version                Show version information
+  hoodscript completion [bash|zsh]  Generate shell autocompletion
+
+Topics for learn:
+  basics, flow, functions, classes, errors, async, mirror, all
+
+Quick start:
+  $ hoodscript learn basics         # Start the interactive curriculum
+  $ hoodscript repl --mirror        # REPL echoing Python code line-by-line
+  $ hoodscript build app.hs         # See transpiled Python
+"""
+
+
+def _utf8_pipes() -> None:
+    """Crash reports carry non-ASCII (the header, em dashes). A real console handles
+    them; a pipe on Windows defaults to the legacy code page and mangles them."""
+    for stream in (sys.stdout, sys.stderr):
+        if not stream.isatty() and hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def print_tokens() -> None:
+    print(f"HoodScript v{__version__} Keyword and Exception Reference\n")
+    print(f"{'HoodScript':<18} {'Python':<18} {'Category':<15} {'Description'}")
+    print(f"{'-' * 18} {'-' * 18} {'-' * 15} {'-' * 30}")
+    for k, v in sorted(TIER_A.items()):
+        print(f"{k:<18} {v:<18} {'Tier A':<15} Core grammatical feature")
+    for k, v in sorted(TIER_B.items()):
+        print(f"{k:<18} {v:<18} {'Tier B':<15} High-frequency keyword")
+    for k, v in sorted(TIER_C.items()):
+        print(f"{k:<18} {v:<18} {'Tier C':<15} Control / statement")
+    for k, v in sorted(HOOD_EXCEPTION_NAMES.items()):
+        print(f"{k:<18} {v:<18} {'Exception':<15} Builtin exception")
+
+    print("\nMulti-token Patterns (normative R1–R12):")
+    patterns = [
+        ("ain't x", "not x", "R1 Negation"),
+        ("ain't nobody x", "not x", "R2 Emphatic negative concord"),
+        ("no cap", "True", "R3 Truth assertion"),
+        ("cap", "False", "R3 Falsehood"),
+        ("it's x", "(x is not None)", "R4 Existence test"),
+        ("steady:", "while True:", "R5 Persistent loop"),
+        ("a..b", "range(a, (b) + 1)", "R6 Inclusive range"),
+        ("BIN X = v", "X: Final = v", "R7 Constant declaration"),
+        ("else if", "elif", "R8 Chained conditional"),
+        ("holla x, y", "print(x, y)", "R9 Statement-form print"),
+        ("ask x", "input(x)", "R10 Statement-form input"),
+    ]
+    for src, py, desc in patterns:
+        print(f"  {src:<20} -> {py:<25} ({desc})")
+
+
+def print_completion(shell: str) -> int:
+    shell = shell.lower().strip()
+    if shell == "bash":
+        print("""# bash completion for hoodscript
+_hoodscript_completion() {
+    local cur prev words cword
+    _init_completion || return
+
+    local commands="run build check fmt lint repl tokens learn lsp version completion make-stubs debug playground"
+    local topics="basics flow functions classes errors async mirror all"
+
+    if [[ $cword -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+        return 0
+    fi
+
+    case "${words[1]}" in
+        learn)
+            COMPREPLY=( $(compgen -W "$topics" -- "$cur") )
+            return 0
+            ;;
+        completion)
+            COMPREPLY=( $(compgen -W "bash zsh" -- "$cur") )
+            return 0
+            ;;
+        run|build|check|fmt|lint|debug)
+            COMPREPLY=( $(compgen -f -- "$cur") )
+            return 0
+            ;;
+        repl)
+            COMPREPLY=( $(compgen -W "--mirror" -- "$cur") )
+            return 0
+            ;;
+    esac
+}
+complete -F _hoodscript_completion hoodscript
+""")
+        return 0
+    elif shell == "zsh":
+        print("""#compdef hoodscript
+
+_hoodscript() {
+    local -a commands
+    commands=(
+        'run:Run a HoodScript program'
+        'build:Transpile HoodScript to Python stdout'
+        'check:Check syntax without executing'
+        'fmt:Format HoodScript source files'
+        'lint:Lint HoodScript source files'
+        'repl:Start interactive REPL'
+        'tokens:Display language keywords and mappings'
+        'learn:Interactive curriculum lessons'
+        'debug:Debug program under debugpy / DAP'
+        'lsp:Start Language Server'
+        'version:Show version'
+        'completion:Generate shell completion script'
+    )
+
+    _arguments -C \\
+        '1: :->command' \\
+        '*:: :->args'
+
+    case $state in
+        command)
+            _describe -t commands 'hoodscript command' commands
+            ;;
+        args)
+            case $line[1] in
+                learn)
+                    _values 'topics' basics flow functions classes errors async mirror all
+                    ;;
+                completion)
+                    _values 'shell' bash zsh
+                    ;;
+                run|build|check|fmt|lint)
+                    _files
+                    ;;
+                repl)
+                    _arguments '--mirror[Echo Python equivalent under each line]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_hoodscript "$@"
+""")
+        return 0
+    else:
+        sys.stderr.write(f"Unknown shell '{shell}'. Supported: bash, zsh\n")
+        return 1
+
+
+def check_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript check")
+    parser.add_argument("file", help="HoodScript file to check")
+    pargs = parser.parse_args(args)
+
+    traceback_handler.install()
+    try:
+        with open(pargs.file, encoding="utf-8") as fh:
+            src = fh.read()
+        py = transpile(src, pargs.file)
+        compile(py, pargs.file, "exec")
+        print(f"Syntax OK: {pargs.file}")
+        return 0
+    except BaseException as e:
+        traceback_handler.hood_excepthook(type(e), e, e.__traceback__)
+        return 1
+
+
+def fmt_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript fmt")
+    parser.add_argument("files", nargs="+", help="Files or directories to format")
+    parser.add_argument("--check", action="store_true", help="Check if files are formatted without writing")
+    parser.add_argument("--diff", action="store_true", help="Show diff for changes")
+    pargs = parser.parse_args(args)
+
+    from hoodscript.formatter import format_file
+    from hoodscript.linter import ToolMissing
+
+    any_modified = False
+    for path_str in pargs.files:
+        p = Path(path_str)
+        targets = list(p.rglob("*.hs")) + list(p.rglob("*.hood")) if p.is_dir() else [p]
+
+        for target in targets:
+            try:
+                mod, msg = format_file(target, check_only=pargs.check, show_diff=pargs.diff, write=not pargs.check)
+            except ToolMissing as e:
+                sys.stderr.write(f"{e}\n"); return 2
+            if mod:
+                any_modified = True
+            if msg:
+                print(msg)
+
+    if pargs.check and any_modified:
+        return 1
+    return 0
+
+
+def lint_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript lint")
+    parser.add_argument("files", nargs="+", help="Files or directories to lint")
+    parser.add_argument("--types", action="store_true", help="Run mypy type checker (HL003)")
+    pargs = parser.parse_args(args)
+
+    from hoodscript.linter import ToolMissing, lint_file
+
+    all_findings = []
+    for path_str in pargs.files:
+        p = Path(path_str)
+        targets = list(p.rglob("*.hs")) + list(p.rglob("*.hood")) if p.is_dir() else [p]
+
+        for target in targets:
+            try:
+                findings = lint_file(target, check_types=pargs.types)
+            except ToolMissing as e:
+                sys.stderr.write(f"{e}\n"); return 2
+            all_findings.extend(findings)
+
+    for f in all_findings:
+        print(f.format_plain())
+
+    if all_findings:
+        print(f"\n{len(all_findings)} issue(s) found.")
+        return 1
+
+    print("No issues found.")
+    return 0
+
+
+def repl_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript repl")
+    parser.add_argument("--mirror", action="store_true", help="Echo Python equivalent under each input line")
+    pargs = parser.parse_args(args)
+
+    try:
+        from hoodscript.repl import HoodScriptREPL
+    except ImportError:
+        sys.stderr.write(
+            "The interactive REPL requires prompt-toolkit.\n"
+            "Install with: pip install 'hoodscript[repl]'\n"
+        )
+        return 1
+
+    HoodScriptREPL(mirror=pargs.mirror).start()
+    return 0
+
+
+def learn_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript learn")
+    parser.add_argument(
+        "topic",
+        nargs="?",
+        default=None,
+        help="Topic (basics, flow, functions, classes, errors, async, mirror) or lesson #",
+    )
+    parser.add_argument("--mirror", action="store_true", help="Show transpiled Python for each lesson")
+    parser.add_argument("--auto", action="store_true", help="Run lessons automatically without prompting")
+    pargs = parser.parse_args(args)
+
+    from hoodscript.tutor import run_curriculum
+
+    return run_curriculum(pargs.topic, mirror=pargs.mirror, auto_run=pargs.auto)
+
+
+def debug_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript debug")
+    parser.add_argument("file", help="HoodScript file to debug")
+    parser.add_argument("--port", type=int, default=5678, help="debugpy port (default 5678)")
+    parser.add_argument("--host", default="127.0.0.1", help="debugpy host (default 127.0.0.1)")
+    parser.add_argument("--wait", action="store_true", help="Wait for debugger client to attach")
+    parser.add_argument("--listen", action="store_true", help="Start debugpy listener")
+    pargs = parser.parse_args(args)
+
+    from hoodscript.debugger import run_debug
+
+    return run_debug(
+        pargs.file,
+        port=pargs.port,
+        host=pargs.host,
+        wait_for_client=pargs.wait,
+        listen=pargs.listen or pargs.wait,
+    )
+
+
+def playground_command(args: list[str]) -> int:
+    import http.server
+    import socketserver
+    import webbrowser
+    from functools import partial
+
+    parser = argparse.ArgumentParser(prog="hoodscript playground", description="Launch the client-side Web Playground")
+    parser.add_argument("--port", type=int, default=8000, help="port to serve on (default 8000)")
+    parser.add_argument("--no-browser", action="store_true", help="do not open browser automatically")
+    pargs = parser.parse_args(args)
+
+    playground_dir = Path(__file__).resolve().parents[2] / "playground"
+    if not playground_dir.exists():
+        sys.stderr.write("The playground is a static site that lives in the repository, not in the installed package.\n"
+                         "Clone https://github.com/khaoticdev62/hoodscript and run `hoodscript playground` "
+                         "from the checkout.\n")
+        return 1
+
+    handler = partial(http.server.SimpleHTTPRequestHandler, directory=str(playground_dir))
+    port = pargs.port
+    url = f"http://localhost:{port}"
+
+    sys.stdout.write(f"Starting HoodScript Web Playground at {url}\n")
+    sys.stdout.write("Press Ctrl+C to stop.\n")
+    sys.stdout.flush()
+
+    if not pargs.no_browser:
+        import contextlib
+
+        with contextlib.suppress(Exception):
+            webbrowser.open(url)
+
+    try:
+        with socketserver.TCPServer(("", port), handler) as httpd:
+            httpd.serve_forever()
+    except KeyboardInterrupt:
+        sys.stdout.write("\nPlayground stopped.\n")
+        return 0
+    except Exception as exc:
+        sys.stderr.write(f"Playground server error: {exc}\n")
+        return 1
+
+
+def main(argv=None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    _utf8_pipes()
+
+    # If no arguments are passed, show the tour (Sprint 7 item 1)
+    if not argv:
+        sys.stdout.write(TOUR_TEXT)
+        return 0
+
+    cmd = argv[0]
+
+    if cmd in ("version", "--version", "-v"):
+        print(f"HoodScript v{__version__}")
+        return 0
+    if cmd == "tokens":
+        print_tokens()
+        return 0
+    if cmd == "completion":
+        shell = argv[1] if len(argv) > 1 else "bash"
+        return print_completion(shell)
+    if cmd == "lsp":
+        try:
+            from hoodscript.lsp import run_lsp
+        except ImportError:
+            sys.stderr.write(
+                "The LSP server requires pygls and jedi.\n"
+                "Install with: pip install 'hoodscript[lsp]'\n"
+            )
+            return 1
+        run_lsp()
+        return 0
+    if cmd == "make-stubs":
+        from hoodscript.stubs import make_stubs_main
+        return make_stubs_main(argv[1:])
+    if cmd == "check":
+        return check_command(argv[1:])
+    if cmd == "fmt":
+        return fmt_command(argv[1:])
+    if cmd == "lint":
+        return lint_command(argv[1:])
+    if cmd == "repl":
+        return repl_command(argv[1:])
+    if cmd == "learn":
+        return learn_command(argv[1:])
+    if cmd == "debug":
+        return debug_command(argv[1:])
+    if cmd == "playground":
+        return playground_command(argv[1:])
+    if cmd == "build":
+        # build <file> transpiles to stdout (alias for -c)
+        if len(argv) < 2:
+            sys.stderr.write("Usage: hoodscript build <file.hs>\n")
+            return 1
+        filepath = argv[1]
+        with open(filepath, encoding="utf-8") as fh:
+            src = fh.read()
+        sys.stdout.write(transpile(src, filepath) + "\n")
+        return 0
+
+    # If user ran `hoodscript run ...`
+    if cmd == "run":
+        argv = argv[1:]
+
+    # Fallback to standard execution parser (supports `hoodscript <file>`, `-c`, `--sandbox`, etc.)
+    parser = argparse.ArgumentParser(prog="hoodscript")
+    parser.add_argument("file", nargs="?")
+    parser.add_argument("-c", "--compile", action="store_true")
+    parser.add_argument(
+        "--python-traceback",
+        action="store_true",
+        help="show raw Python tracebacks (for debugging the compiler)",
+    )
+    sb = parser.add_argument_group(
+        "sandbox",
+        "run with capabilities closed and budgets on (see SECURITY.md)",
+    )
+    sb.add_argument("--sandbox", action="store_true", help="enable the sandbox (also HOODSCRIPT_SANDBOX=1)")
+    sb.add_argument("--allow-fs", action="store_true", help="grant filesystem access inside the sandbox")
+    sb.add_argument("--allow-net", action="store_true", help="grant network access inside the sandbox")
+    sb.add_argument("--allow-clock", action="store_true", help="grant clock access inside the sandbox")
+    sb.add_argument("--max-seconds", type=float, default=None, help="wall-clock budget (default 10)")
+    sb.add_argument("--max-output", type=int, default=None, help="output budget in bytes (default 1,000,000)")
+    sb.add_argument("--max-depth", type=int, default=None, help="recursion budget (default 256)")
+    args = parser.parse_args(argv)
+
+    if args.python_traceback:
+        os.environ[traceback_handler.ENV_FLAG] = "1"
+    if not args.file:
+        sys.stdout.write(TOUR_TEXT)
+        return 0
+
+    with open(args.file, encoding="utf-8") as fh:
+        src = fh.read()
+    if args.compile:
+        sys.stdout.write(transpile(src, args.file) + "\n")
+        return 0
+
+    sys.path.insert(0, os.path.dirname(os.path.abspath(args.file)))
+    importer.install()
+    traceback_handler.install()
+    if args.sandbox or os.environ.get(sandbox.ENV_FLAG) or sandbox.SANDBOX_BY_DEFAULT:
+        caps = sandbox.Capabilities(filesystem=args.allow_fs, network=args.allow_net, clock=args.allow_clock)
+        defaults = sandbox.Budgets()
+        budgets = sandbox.Budgets(
+            max_recursion_depth=args.max_depth or defaults.max_recursion_depth,
+            max_wall_seconds=args.max_seconds or defaults.max_wall_seconds,
+            max_output_bytes=args.max_output or defaults.max_output_bytes,
+        )
+        sandbox.activate(sandbox.Sandbox(caps, budgets))
+
+    scope = {"__file__": os.path.abspath(args.file), "__name__": "__main__"}
+    exec(compile(transpile(src, args.file), args.file, "exec"), scope)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hoodscript/constants.py

@@ -0,0 +1,69 @@
+"""Keyword tables — the runtime truth. Specified by GRAMMAR.md v1.1; every entry
+has a row in hoodscript/docs/linguistics.md. Do not add a word here without
+the 7-step procedure in hoodscript/docs/lexical-sourcing.md §5.
+
+Tier A: grammar (Yale GDP page each). Tier B: lexical (two dictionaries each;
+`trip` on one, owner-approved). Tier C: plain English kept deliberately.
+Multi-token forms (steady:, no cap, it's, ain't, BIN, a..b, else if, holla
+"x") are the Sprint 3 pattern layer and are not in this table yet.
+"""
+
+import builtins as _b
+
+TIER_A = {
+    "be": "for",          # habitual be          -> ast.For
+    "finna": "async",     # fixin' to            -> ast.AsyncFunctionDef (with bet)
+    "done": "await",      # perfective done      -> ast.Await
+    "tryna": "try",       # tryna                -> ast.Try
+}
+
+TIER_B = {
+    "bet": "def",         # commitment           -> ast.FunctionDef
+    "fam": "class",       # close group          -> ast.ClassDef
+    "holla": "print",     # call out             -> ast.Call
+    "dip": "return",      # leave                -> ast.Return
+    "chill": "pass",      # do nothing           -> ast.Pass
+    "cap": "False",       # a lie                -> ast.Constant
+}
+
+TIER_C = {
+    "skip": "continue",
+    "catch": "except",
+    "regardless": "finally",
+    "throw": "raise",
+    "ask": "input",
+}
+
+# The *Trip family: Python exceptions under HoodScript names. Token-level, so
+# generated Python reads `except ValueError` and py2hood gives `catch BadValueTrip`.
+HOOD_EXCEPTION_NAMES = {
+    "Problem": "Exception",
+    "BaseProblem": "BaseException",
+    "BadValueTrip": "ValueError",
+    "WrongKindTrip": "TypeError",
+    "MissingKeyTrip": "KeyError",
+    "OutOfBoundsTrip": "IndexError",
+    "ZeroSplitTrip": "ZeroDivisionError",
+    "MissingFileTrip": "FileNotFoundError",
+    "AssertTrip": "AssertionError",
+    "UnknownNameTrip": "NameError",
+    "MissingAttrTrip": "AttributeError",
+    "BadSyntaxTrip": "SyntaxError",
+    "InfiniteLoopTrip": "RecursionError",
+    "StopRunTrip": "StopIteration",
+    "MissingModuleTrip": "ModuleNotFoundError",
+    "BadImportTrip": "ImportError",
+    "NoAccessTrip": "PermissionError",
+}
+
+HOOD_KEYWORD_MAP = {**TIER_A, **TIER_B, **TIER_C, **HOOD_EXCEPTION_NAMES}
+
+# Python exception class -> HoodScript name, for crash reports.
+HOOD_EXCEPTIONS = {getattr(_b, py): hood for hood, py in HOOD_EXCEPTION_NAMES.items()}
+
+# Reserved: a HoodScript program cannot use these as variable names, exactly as
+# Python cannot use `pass` or `return`. Attribute names (`future.done()`) are
+# exempt — the transpiler never rewrites a NAME that follows a dot.
+RESERVED = frozenset(HOOD_KEYWORD_MAP)
+
+SUPPORTED_EXTENSIONS = (".hs", ".hood")