ground-control-cli 0.2.0__py3-none-any.whl

client/probes/code/javascript.js

@@ -0,0 +1,171 @@
+// The JavaScript and TypeScript reader's half that runs on Node, with the TypeScript compiler API.
+//
+// Reads on stdin {"typescript": <the compiler's package folder>, "name": <the file as shown>,
+// "blocks": [{"text", "kind": js|jsx|ts|tsx, "offset": lines before the block}]} and writes on
+// stdout {"symbols": [...], "calls": [...]} or {"error": "..."}. See javascript.py for what a
+// symbol is.
+"use strict";
+
+const input = JSON.parse(require("fs").readFileSync(0, "utf8"));
+const ts = require(input.typescript);
+const K = ts.SyntaxKind;
+const KINDS = { js: ts.ScriptKind.JS, jsx: ts.ScriptKind.JSX, ts: ts.ScriptKind.TS,
+                tsx: ts.ScriptKind.TSX };
+const OPEN = "([{";
+const CLOSE = ")]}";
+const TRIVIA = new Set([K.WhitespaceTrivia, K.NewLineTrivia, K.SingleLineCommentTrivia,
+                        K.MultiLineCommentTrivia, K.ShebangTrivia, K.ConflictMarkerTrivia]);
+
+// The text from start to end on one line, comments dropped, joined the way the Python reader
+// joins a header: one space where the source had a gap, none after an opener or before a closer.
+function oneLine(sf, start, end) {
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, sf.languageVariant,
+                                   sf.text.slice(start, end));
+  const parts = [];
+  const templates = [];
+  let braces = 0;
+  let prevEnd = null;
+  for (let t = scanner.scan(); t !== K.EndOfFileToken; t = scanner.scan()) {
+    if (TRIVIA.has(t)) continue;
+    if (t === K.TemplateHead) templates.push(braces);
+    else if (t === K.OpenBraceToken) braces++;
+    else if (t === K.CloseBraceToken) {
+      if (templates.length && templates[templates.length - 1] === braces) {
+        t = scanner.reScanTemplateToken(false);
+        if (t === K.TemplateTail) templates.pop();
+      } else braces--;
+    }
+    const text = scanner.getTokenText();
+    const at = scanner.getTokenPos ? scanner.getTokenPos() : scanner.getTokenStart();
+    const gap = prevEnd !== null && at !== prevEnd;
+    if (parts.length && gap && !OPEN.includes(parts[parts.length - 1]) && !CLOSE.includes(text)) {
+      parts.push(" ");
+    }
+    parts.push(text);
+    prevEnd = scanner.getTextPos();
+  }
+  return parts.join("").trim();
+}
+
+function child(node, sf, kinds) {
+  return node.getChildren(sf).find((c) => kinds.includes(c.kind));
+}
+
+function nameOf(node, sf) {
+  if (!node.name) return "default";
+  return ts.isIdentifier(node.name) || ts.isPrivateIdentifier(node.name)
+    ? node.name.text : node.name.getText(sf);
+}
+
+// From the type parameters or the parameters of a function to its body (or its `=>`).
+function params(fn, sf) {
+  const open = child(fn, sf, [K.LessThanToken, K.OpenParenToken]);
+  const start = open ? open.getStart(sf) : fn.parameters[0].getStart(sf);
+  const end = ts.isArrowFunction(fn) ? fn.equalsGreaterThanToken.getStart(sf)
+                                     : fn.body.getStart(sf);
+  return oneLine(sf, start, end);
+}
+
+function isFunction(node) {
+  return node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+}
+
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) ||
+                  ts.isSatisfiesExpression && ts.isSatisfiesExpression(node))) {
+    node = node.expression;
+  }
+  return node;
+}
+
+function readBlock(block, found) {
+  const sf = ts.createSourceFile(input.name, block.text, ts.ScriptTarget.Latest, true,
+                                 KINDS[block.kind]);
+  const line = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1 + block.offset;
+  const problems = sf.parseDiagnostics || [];
+  if (problems.length) {
+    const p = problems[0];
+    const message = ts.flattenDiagnosticMessageText(p.messageText, " ");
+    throw new Error(`${input.name}: TypeScript cannot parse it: line ${line(p.start)}: ${message}`);
+  }
+  const symbols = [];
+  const add = (kind, scope, signature, span) => {
+    symbols.push({ kind, name: scope.join("."), signature, first: line(span.getStart(sf)),
+                   last: line(span.getEnd()) });
+  };
+
+  function members(cls, scope) {
+    for (const m of cls.members) {
+      if ((ts.isMethodDeclaration(m) || ts.isConstructorDeclaration(m) ||
+           ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) && m.body) {
+        const name = ts.isConstructorDeclaration(m) ? "constructor" : nameOf(m, sf);
+        const from = ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)
+          ? child(m, sf, [K.GetKeyword, K.SetKeyword])
+          : ts.isConstructorDeclaration(m) ? child(m, sf, [K.ConstructorKeyword]) : m.name;
+        add("method", [...scope, name], oneLine(sf, from.getStart(sf), m.body.getStart(sf)), m);
+      } else if (ts.isPropertyDeclaration(m) && isFunction(unwrap(m.initializer))) {
+        const name = nameOf(m, sf);
+        add("method", [...scope, name], name + params(unwrap(m.initializer), sf), m);
+      }
+    }
+  }
+
+  function cls(node, name, scope, span) {
+    const brace = child(node, sf, [K.OpenBraceToken]);
+    const from = node.name ? node.name.getStart(sf) : brace.getStart(sf);
+    const header = node.name ? oneLine(sf, from, brace.getStart(sf)) : name;
+    add("class", [...scope, name], header, span);
+    members(node, [...scope, name]);
+  }
+
+  for (const st of sf.statements) {
+    if (ts.isFunctionDeclaration(st) && st.body) {
+      const name = nameOf(st, sf);
+      add("function", [name], name + params(st, sf), st);
+    } else if (ts.isClassDeclaration(st)) {
+      cls(st, nameOf(st, sf), [], st);
+    } else if (ts.isVariableStatement(st)) {
+      const list = st.declarationList.declarations;
+      for (const d of list) {
+        const value = unwrap(d.initializer);
+        if (!ts.isIdentifier(d.name) || !value) continue;
+        const span = list.length === 1 ? st : d;
+        if (isFunction(value)) add("function", [d.name.text], d.name.text + params(value, sf), span);
+        else if (ts.isClassExpression(value)) cls(value, d.name.text, [], span);
+      }
+    } else if (ts.isExportAssignment(st) && isFunction(unwrap(st.expression))) {
+      add("function", ["default"], "default" + params(unwrap(st.expression), sf), st);
+    }
+  }
+
+  const calls = [];
+  const visit = (node) => {
+    let callee = null;
+    if (ts.isCallExpression(node) || ts.isNewExpression(node)) callee = node.expression;
+    else if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) &&
+             !/^[a-z]/.test(node.tagName.getText(sf))) callee = node.tagName;  // not <div>
+    if (callee) {
+      const name = ts.isIdentifier(callee) ? callee.text
+        : ts.isPropertyAccessExpression(callee) ? callee.name.text : "";
+      if (name) calls.push({ callee: name, line: line(node.getStart(sf)) });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  found.symbols.push(...symbols);
+  for (const c of calls) {
+    const inside = symbols.filter((s) => s.first <= c.line && c.line <= s.last);
+    inside.sort((a, b) => (a.last - a.first) - (b.last - b.first));
+    found.calls.push({ caller: inside.length ? inside[0].name : "<module>", ...c });
+  }
+}
+
+try {
+  const found = { symbols: [], calls: [] };
+  for (const block of input.blocks) readBlock(block, found);
+  found.calls.sort((a, b) => a.line - b.line);
+  process.stdout.write(JSON.stringify(found));
+} catch (e) {
+  process.stdout.write(JSON.stringify({ error: e.message }));
+}

client/probes/code/javascript.py

@@ -0,0 +1,193 @@
+"""The JavaScript and TypeScript reader, with the TypeScript compiler API on Node.
+
+It reads .js .mjs .cjs .jsx .ts .tsx, and the inline `<script>` blocks of .html files (those
+without `src` whose type is JavaScript), each block parsed on its own with the file's lines.
+Symbols are the module's function declarations, its `const`/`let`/`var` bound to a function or
+an arrow function, its classes (declared or bound to a variable), and the methods of its classes:
+methods, the constructor, get and set accessors, and properties bound to a function. A function
+inside a function is part of the outer one, as in the Python reader. `export default` without a
+name is named `default`.
+
+The signature is the header as written, from the name to the body (to the `=>` for an arrow),
+on one line, comments dropped; a function bound to a variable is its variable's name followed
+by its parameters. The first line is the statement's, decorators and modifiers included.
+
+The compiler is TypeScript 6.0.3, the method's own private copy: installed with
+`npm install --prefix <the method's data folder> typescript@6.0.3` and loaded from there, never
+from a global install. The data folder is METHOD_DATA if set, else ~/.method. `missing()`
+says what to install when Node or that copy is not there.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from html.parser import HTMLParser
+from pathlib import Path
+
+from .. import errors, settings
+
+KINDS = {".js": "js", ".mjs": "js", ".cjs": "js", ".jsx": "jsx", ".ts": "ts", ".tsx": "tsx"}
+HTML = ".html"
+SCRIPT_TYPES = ("", "module", "text/javascript", "application/javascript")
+HELPER = Path(__file__).with_name("javascript.js")
+COMPILER = "typescript@6.0.3"
+
+
+def data_dir() -> Path:
+    """The method's own data folder: METHOD_DATA if set, else ~/.method."""
+    return settings.method_data()
+
+
+def compiler() -> Path:
+    """Where the method's copy of the TypeScript compiler is (or is to be) installed."""
+    return data_dir() / "node_modules" / "typescript"
+
+
+def install_line() -> str:
+    """Return the npm line that installs the method's copy of the TypeScript compiler.
+
+    Returns:
+        An `npm install --prefix` line into the method's data folder.
+
+    Company: assumes none.
+    """
+    return f"npm install --prefix {data_dir()} {COMPILER}"
+
+
+def _installed() -> bool:
+    try:
+        found = json.loads((compiler() / "package.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    return f"typescript@{found.get('version')}" == COMPILER
+
+
+def missing() -> str:
+    """What to install for this reader to run, or "" when Node and the compiler are there."""
+    if not shutil.which("node"):
+        return (
+            f"install Node.js (https://nodejs.org), then the TypeScript compiler: {install_line()}"
+        )
+    if not _installed():
+        return f"install the TypeScript compiler: {install_line()}"
+    return ""
+
+
+def tools_missing() -> list:
+    """The names of its missing tools: node, the method's typescript, or none."""
+    if not shutil.which("node"):
+        return ["node", "typescript"] if not _installed() else ["node"]
+    return [] if _installed() else ["typescript"]
+
+
+class _Scripts(HTMLParser):
+    """The inline JavaScript blocks of an HTML page: (lines before the block, its text)."""
+
+    def __init__(self):
+        super().__init__(convert_charrefs=False)
+        self.blocks, self._open = [], None
+
+    def handle_starttag(self, tag, attrs):
+        if tag != "script":
+            return
+        found = {k.lower(): (v or "") for k, v in attrs}
+        inline = "src" not in found and found.get("type", "").strip().lower() in SCRIPT_TYPES
+        self._open = [None, []] if inline else None
+
+    def handle_data(self, data):
+        if self._open is not None:
+            if self._open[0] is None:
+                self._open[0] = self.getpos()[0] - 1
+            self._open[1].append(data)
+
+    def handle_endtag(self, tag):
+        if tag == "script" and self._open is not None:
+            offset, parts = self._open
+            if "".join(parts).strip():
+                self.blocks.append((offset, "".join(parts)))
+            self._open = None
+
+
+def _blocks(path: Path) -> list:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if path.suffix.lower() != HTML:
+        return [{"text": text, "kind": KINDS[path.suffix.lower()], "offset": 0}]
+    scripts = _Scripts()
+    scripts.feed(text)
+    scripts.close()
+    return [{"text": t, "kind": "js", "offset": offset} for offset, t in scripts.blocks]
+
+
+def _read(path: Path, name: str) -> dict:
+    need = missing()
+    if need:
+        raise errors.Refused(
+            f"{name}: reading it needs Node and the TypeScript compiler: {need}",
+            errors.TOOL_MISSING,
+        )
+    blocks = _blocks(path)
+    if not blocks:
+        return {"symbols": [], "calls": []}
+    request = {"typescript": str(compiler()), "name": name, "blocks": blocks}
+    out = subprocess.run(
+        [shutil.which("node"), str(HELPER)],
+        input=json.dumps(request),
+        capture_output=True,
+        text=True,
+    )
+    try:
+        found = json.loads(out.stdout)
+    except ValueError as e:
+        raise errors.Refused(
+            f"{name}: the TypeScript reader failed: {(out.stderr or out.stdout).strip()[-500:]}"
+        ) from e
+    if "error" in found:
+        raise errors.Refused(found["error"])
+    return found
+
+
+def symbols(path: Path, name: str) -> list:
+    """Return the file's functions, classes and methods, as the Node helper reads them.
+
+    Args:
+        path: The file to read.
+        name: The file as it is shown.
+
+    Returns:
+        A Symbol for each; none for an HTML file without inline scripts.
+
+    Raises:
+        errors.Refused: If Node or the compiler is missing, or the helper fails or reports an
+            error.
+
+    Company: assumes none.
+    """
+    from . import Symbol
+
+    return [
+        Symbol(s["kind"], s["name"], name, s["signature"], s["first"], s["last"])
+        for s in _read(path, name)["symbols"]
+    ]
+
+
+def calls(path: Path, name: str) -> list:
+    """Return each call in the file, `new` and JSX elements included.
+
+    Args:
+        path: The file to read.
+        name: The file as it is shown.
+
+    Returns:
+        A Call for each: the enclosing symbol (or `<module>`), the called name, the line.
+
+    Raises:
+        errors.Refused: If Node or the compiler is missing, or the helper fails or reports an
+            error.
+
+    Company: assumes none.
+    """
+    from . import Call
+
+    return [Call(c["caller"], c["callee"], name, c["line"]) for c in _read(path, name)["calls"]]

client/probes/code/python.py

@@ -0,0 +1,143 @@
+"""The Python reader, with `ast`.
+
+Symbols are the module's classes and functions, and the methods of its classes (nested classes
+included). A function inside a function is part of the outer one, not a symbol of its own.
+The qualified name joins the enclosing classes with `.`; the signature is the header as
+written, from the name to the colon, on one line, comments dropped. The first line is the
+first decorator's.
+"""
+
+from __future__ import annotations
+
+import ast
+import io
+import tokenize
+from pathlib import Path
+
+from .. import errors
+
+DEFS = (ast.FunctionDef, ast.AsyncFunctionDef)
+OPEN, CLOSE = "([{", ")]}"
+
+
+def missing() -> str:
+    """Nothing to install: `ast` is part of Python."""
+    return ""
+
+
+def tools_missing() -> list:
+    """None of its tools is missing: `ast` is part of Python."""
+    return []
+
+
+def _tree(path: Path, name: str):
+    text = path.read_text(encoding="utf-8")
+    try:
+        return text, ast.parse(text, filename=name)
+    except SyntaxError as e:
+        raise errors.Refused(f"{name}: Python cannot parse it: line {e.lineno}: {e.msg}") from e
+
+
+def _header(lines: list, node) -> str:
+    """From the name after `def`/`class` up to the colon that ends the header."""
+    first = node.lineno - 1
+    source = "".join(lines[first : node.body[0].lineno])
+    tokens = tokenize.generate_tokens(io.StringIO(source).readline)
+    parts, depth, prev_end, seen_keyword = [], 0, None, False
+    for tok in tokens:
+        if tok.type in (
+            tokenize.COMMENT,
+            tokenize.NL,
+            tokenize.NEWLINE,
+            tokenize.INDENT,
+            tokenize.DEDENT,
+        ):
+            continue
+        if not seen_keyword:
+            if tok.string in ("def", "class"):
+                seen_keyword = True
+                prev_end = tok.end
+            continue
+        if tok.string == ":" and depth == 0:
+            break
+        if tok.string and tok.string in OPEN:
+            depth += 1
+        elif tok.string and tok.string in CLOSE:
+            depth -= 1
+        gap = prev_end is not None and tok.start != prev_end
+        if parts and gap and parts[-1] not in OPEN and tok.string not in CLOSE:
+            parts.append(" ")
+        parts.append(tok.string)
+        prev_end = tok.end
+    return "".join(parts).strip()
+
+
+def _walk(body, scope: list, inside_class: bool):
+    for node in body:
+        if isinstance(node, ast.ClassDef):
+            yield node, "class", scope + [node.name]
+            yield from _walk(node.body, scope + [node.name], True)
+        elif isinstance(node, DEFS):
+            yield node, "method" if inside_class else "function", scope + [node.name]
+        elif isinstance(node, (ast.If, ast.Try, ast.With, ast.AsyncWith)):
+            # definitions under `if TYPE_CHECKING:`, `try: ... except ImportError:` and the like
+            for field in ("body", "orelse", "finalbody"):
+                yield from _walk(getattr(node, field, []), scope, inside_class)
+            for handler in getattr(node, "handlers", []):
+                yield from _walk(handler.body, scope, inside_class)
+
+
+def _first(node) -> int:
+    """The first line of the symbol: its first decorator, or its `def`/`class` line."""
+    return min([node.lineno] + [d.lineno for d in node.decorator_list])
+
+
+def symbols(path: Path, name: str) -> list:
+    """Return the module's classes and functions, and the methods of its classes.
+
+    Args:
+        path: The file to read.
+        name: The file as it is shown.
+
+    Returns:
+        A Symbol for each, in the order they are written.
+
+    Raises:
+        errors.Refused: If Python cannot parse the file.
+
+    Company: assumes none.
+    """
+    from . import Symbol
+
+    text, tree = _tree(path, name)
+    lines = text.splitlines(keepends=True)
+    return [
+        Symbol(kind, ".".join(qualified), name, _header(lines, node), _first(node), node.end_lineno)
+        for node, kind, qualified in _walk(tree.body, [], False)
+    ]
+
+
+def calls(path: Path, name: str) -> list:
+    """Each call in the file: the enclosing symbol (or `<module>`), the called name, the line."""
+    from . import Call
+
+    _, tree = _tree(path, name)
+    spans = [
+        (_first(node), node.end_lineno, ".".join(q)) for node, _, q in _walk(tree.body, [], False)
+    ]
+    found = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        func = node.func
+        callee = (
+            func.id
+            if isinstance(func, ast.Name)
+            else (func.attr if isinstance(func, ast.Attribute) else "")
+        )
+        if not callee:
+            continue
+        inside = [s for s in spans if s[0] <= node.lineno <= s[1]]
+        caller = min(inside, key=lambda s: s[1] - s[0])[2] if inside else "<module>"
+        found.append(Call(caller, callee, name, node.lineno))
+    return sorted(found, key=lambda c: c.line)

client/probes/errors.py

@@ -0,0 +1,67 @@
+"""Why a probe could not find its fact, as the service's facts name it (app/method/facts.py).
+
+A probe says which of these stopped it, never what a command printed.
+"""
+
+from __future__ import annotations
+
+NO_COMMAND = "no_command"  # the repo names no command for this
+COMMAND_FAILED = "command_failed"  # the repo's command ran and failed
+NO_READER = "no_reader"  # no code reader reads the file
+TOOL_MISSING = "tool_missing"  # a reader's or git's own tooling is missing
+UNREADABLE = "unreadable"  # the reader could not parse the file
+NOT_FOUND = "not_found"  # the ref, file, PR or address is not there
+TIMED_OUT = "timed_out"  # it did not finish in the repo's time
+REFUSED = "refused"  # git or gh refused
+
+ERRORS = (
+    NO_COMMAND,
+    COMMAND_FAILED,
+    NO_READER,
+    TOOL_MISSING,
+    UNREADABLE,
+    NOT_FOUND,
+    TIMED_OUT,
+    REFUSED,
+)
+
+# What git and gh print when the ref, the commit or the PR is not there.
+NOT_THERE = (
+    "unknown revision",
+    "bad revision",
+    "bad object",
+    "not a valid object name",
+    "not a valid commit name",
+    "could not resolve",
+    "no pull requests found",
+    "not found",
+)
+
+
+class Refused(Exception):
+    """A code reader could not read a file; `error` is which of ERRORS stopped it.
+
+    The message says why, for the person on this machine; a probe returns only the error.
+
+    Company: assumes none.
+    """
+
+    def __init__(self, message: str, error: str = UNREADABLE):
+        """Keep the message and the error."""
+        super().__init__(message)
+        self.error = error
+
+
+def failed(stderr: str) -> str:
+    """The error a failed git or gh command stands for: not_found or refused.
+
+    Args:
+        stderr: What the command printed on standard error, read here and never kept.
+
+    Returns:
+        NOT_FOUND when it says the thing asked for is not there; REFUSED otherwise.
+
+    Company: assumes none.
+    """
+    said = (stderr or "").lower()
+    return NOT_FOUND if any(n in said for n in NOT_THERE) else REFUSED