pixelweaver 0.1.0

package/scripts/fix-wave-b-void-expr.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Fix @typescript-eslint/no-confusing-void-expression errors by converting
+arrow functions with expression bodies into block bodies:
+  () => doThing()   ->   () => { doThing(); }
+
+Usage:
+  ./scripts/fix-wave-b-void-expr.py <path> [<path>...]
+
+Strategy:
+  1. Run `npx eslint <paths> -f json` to discover error locations.
+  2. For each flagged (line, column), find the nearest `=>` token strictly
+     before that column on the same line.
+  3. Locate the end of the expression after `=>`. For an expression body,
+     we walk forward tracking paren/bracket/brace depth and string quoting
+     until we hit a terminator: `,` `)` `]` `}` `;` or end-of-line.
+  4. Rewrite `=> EXPR` to `=> { EXPR; }`. (Skip if already a block.)
+"""
+import json
+import subprocess
+import sys
+from collections import defaultdict
+
+
+def run_eslint(paths: list[str]) -> list:
+    res = subprocess.run(
+        ['npx', 'eslint', *paths, '-f', 'json'],
+        capture_output=True, text=True
+    )
+    return json.loads(res.stdout)
+
+
+def collect_errors(eslint_data) -> dict:
+    by_file = defaultdict(list)
+    for f in eslint_data:
+        for m in f['messages']:
+            if m.get('severity') != 2: continue
+            if m.get('ruleId') != '@typescript-eslint/no-confusing-void-expression': continue
+            by_file[f['filePath']].append((m['line'], m['column']))
+    return by_file
+
+
+def find_arrow_start(line: str, col_zero: int) -> int:
+    """Find the index of '=>' strictly before col_zero. Return index of '=' or -1."""
+    # Search backward for '=>'
+    for k in range(col_zero - 1, 0, -1):
+        if line[k] == '>' and line[k-1] == '=':
+            return k - 1
+    return -1
+
+
+def find_expr_end(line: str, start: int) -> int:
+    """Walk forward from `start` until the expression terminates.
+    Return the index *after* the last char of the expression.
+    Terminators at depth 0: `,` `)` `]` `}` `;`.
+    Strings, template literals, and regex are not tracked deeply — we just
+    track the common cases (quotes and template backticks).
+    """
+    n = len(line)
+    depth = 0
+    i = start
+    in_str = None  # None or quote char
+    while i < n:
+        c = line[i]
+        if in_str is not None:
+            if c == '\\':
+                i += 2
+                continue
+            if c == in_str:
+                in_str = None
+            elif in_str == '`' and c == '$' and i+1 < n and line[i+1] == '{':
+                # template expression: track as extra { }
+                depth += 1
+                i += 2
+                # switch out of string mode temporarily
+                in_str = None
+                # Push template marker — we approximate: once depth returns
+                # to the saved level, we flip back to backtick mode. To keep
+                # the script simple we use a side stack.
+                tpl_stack.append(depth)
+                continue
+            i += 1
+            continue
+        if c in ('"', "'", '`'):
+            in_str = c
+            i += 1
+            continue
+        if c == '(' or c == '[' or c == '{':
+            depth += 1
+            i += 1
+            continue
+        if c == ')' or c == ']' or c == '}':
+            if depth == 0:
+                return i
+            depth -= 1
+            # check template stack: if we closed a template ${...} block,
+            # resume backtick string mode
+            if tpl_stack and depth == tpl_stack[-1] - 1:
+                tpl_stack.pop()
+                in_str = '`'
+            i += 1
+            continue
+        if depth == 0 and (c == ',' or c == ';'):
+            return i
+        i += 1
+    return n
+
+
+def fix_file(path: str, locations: list[tuple[int, int]]) -> int:
+    with open(path, 'r') as f:
+        lines = f.readlines()
+    # Process bottom-to-top so indices stay valid.
+    uniq = sorted(set(locations), key=lambda lc: (-lc[0], -lc[1]))
+    fixed = 0
+    for line_no, col in uniq:
+        idx = line_no - 1
+        if idx >= len(lines): continue
+        line = lines[idx]
+        col0 = col - 1
+        arrow_eq = find_arrow_start(line, col0)
+        if arrow_eq < 0:
+            continue
+        # Position just after '=>'
+        after = arrow_eq + 2
+        # Skip whitespace
+        while after < len(line) and line[after] == ' ':
+            after += 1
+        if after >= len(line):
+            continue
+        if line[after] == '{':
+            continue  # already a block
+        global tpl_stack
+        tpl_stack = []
+        end = find_expr_end(line, after)
+        expr = line[after:end].rstrip()
+        if not expr:
+            continue
+        # Rebuild
+        before_arrow = line[:after]
+        trailer = line[end:]
+        # Ensure one space between `=>` and `{`
+        # `before_arrow` ends with space(s) usually since we advanced past them.
+        # Strip trailing spaces to normalize.
+        before_arrow = before_arrow.rstrip(' ')
+        new_line = before_arrow + ' { ' + expr + '; }' + trailer
+        lines[idx] = new_line
+        fixed += 1
+    if fixed > 0:
+        with open(path, 'w') as f:
+            f.writelines(lines)
+    return fixed
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("Usage: fix-wave-b-void-expr.py <path> [<path>...]", file=sys.stderr)
+        sys.exit(2)
+    paths = sys.argv[1:]
+    data = run_eslint(paths)
+    by_file = collect_errors(data)
+    total = 0
+    for fpath, locs in by_file.items():
+        n = fix_file(fpath, locs)
+        if n > 0:
+            print(f'{fpath}: {n} fixes')
+        total += n
+    print(f'TOTAL: {total}')

package/scripts/generate-command-params.py

@@ -0,0 +1,540 @@
+#!/usr/bin/env python3
+"""
+Auto-generate TypeScript interfaces from addCommand() param casts.
+
+Scans all .ts files under src/ and plugins/ for api.addCommand(...) calls,
+extracts params["key"] as Type patterns from execute/undo/describe bodies,
+and generates:
+  - A named interface per command (e.g. FloodFillParams)
+  - A declare global { interface CommandParamsMap { ... } } augmentation
+
+Usage:
+  python scripts/generate-command-params.py                    # full output to stdout
+  python scripts/generate-command-params.py --dry-run          # list found commands
+  python scripts/generate-command-params.py --root /path/to/project
+  python scripts/generate-command-params.py > src/lib/core/command-params.generated.ts
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def snake_to_pascal(name: str) -> str:
+    """Convert snake_case command id to PascalCase + 'Params'."""
+    return "".join(part.capitalize() for part in name.split("_")) + "Params"
+
+
+def find_ts_files(root: Path) -> list[Path]:
+    """Collect all .ts files under src/ and plugins/."""
+    dirs = [root / "src", root / "plugins"]
+    files: list[Path] = []
+    for d in dirs:
+        if d.is_dir():
+            files.extend(sorted(d.rglob("*.ts")))
+    return files
+
+
+# ---------------------------------------------------------------------------
+# Brace-matching: extract the full object literal passed to addCommand()
+# ---------------------------------------------------------------------------
+
+def extract_add_command_blocks(source: str) -> list[tuple[str, str, int]]:
+    """
+    Find all addCommand('name', { ... }) calls in source.
+
+    Returns a list of (command_name, body_text, start_line) tuples.
+    The body_text is everything inside the outermost { ... } of the second
+    argument (the command definition object).
+
+    Uses brace counting to handle nested objects, arrow functions, template
+    literals, and string literals.
+    """
+    results: list[tuple[str, str, int]] = []
+
+    # Match the start of an addCommand call with a string-literal first arg
+    pattern = re.compile(
+        r"""addCommand\(\s*(['"`])(\w+)\1\s*,\s*\{""",
+    )
+
+    for m in pattern.finditer(source):
+        cmd_name = m.group(2)
+        # Start counting braces from the opening { we just matched
+        brace_start = m.end() - 1  # index of the '{'
+        start_line = source[:brace_start].count("\n") + 1
+
+        depth = 0
+        i = brace_start
+        in_string: str | None = None  # tracks quote char of current string
+        in_template = False
+        prev_char = ""
+
+        while i < len(source):
+            ch = source[i]
+
+            # Handle escape sequences inside strings
+            if prev_char == "\\":
+                prev_char = ""
+                i += 1
+                continue
+
+            # String/template literal tracking
+            if in_string is not None:
+                if ch == in_string:
+                    in_string = None
+            elif in_template:
+                if ch == "`" and prev_char != "\\":
+                    in_template = False
+            elif ch in ("'", '"'):
+                in_string = ch
+            elif ch == "`":
+                in_template = True
+            elif ch == "/" and i + 1 < len(source):
+                next_ch = source[i + 1]
+                if next_ch == "/":
+                    # Line comment -- skip to end of line
+                    nl = source.find("\n", i)
+                    i = nl if nl != -1 else len(source)
+                    prev_char = ""
+                    continue
+                elif next_ch == "*":
+                    # Block comment -- skip to */
+                    end = source.find("*/", i + 2)
+                    i = end + 2 if end != -1 else len(source)
+                    prev_char = ""
+                    continue
+            elif ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    body = source[brace_start + 1 : i]
+                    results.append((cmd_name, body, start_line))
+                    break
+
+            prev_char = ch
+            i += 1
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Extract params["key"] as Type patterns
+# ---------------------------------------------------------------------------
+
+# Pattern: params["key"] as Type
+# Handles:
+#   params["key"] as Type
+#   (params["key"] as Type | undefined) ?? default
+#   (params["key"] ?? default) as Type
+#   params["key"] as Type | undefined
+# Also matches params['key'] (single quotes)
+PARAM_PATTERN = re.compile(
+    r"""params\[(['"])(\w+)\1\]"""
+)
+
+# After finding a params["key"], look for 'as Type' in the surrounding expression
+# to determine the TypeScript type and optionality.
+AS_CAST_PATTERN = re.compile(
+    r"""as\s+([\w\[\]{}|() '<>:,]+?)(?:\s*[;)\]}]|\s*$)"""
+)
+
+
+def extract_as_type(text: str) -> str | None:
+    """
+    Extract the type from an 'as Type' cast in the given text.
+
+    Handles balanced angle brackets so types like Record<string, string>
+    are captured fully. Returns None if no 'as' cast is found.
+    """
+    as_match = re.search(r"\bas\s+", text)
+    if not as_match:
+        return None
+
+    # Start reading the type after 'as '
+    i = as_match.end()
+    result: list[str] = []
+    angle_depth = 0  # track nested < >
+    paren_depth = 0  # track nested ( )
+
+    bracket_depth = 0  # track nested [ ]
+    curly_depth = 0    # track nested { } (for inline object types)
+
+    def at_top_level() -> bool:
+        """True when not inside any nested brackets."""
+        return angle_depth == 0 and paren_depth == 0 and bracket_depth == 0 and curly_depth == 0
+
+    while i < len(text):
+        ch = text[i]
+
+        if ch == "<":
+            angle_depth += 1
+            result.append(ch)
+        elif ch == ">":
+            if angle_depth > 0:
+                angle_depth -= 1
+                result.append(ch)
+            else:
+                break
+        elif ch == "(":
+            paren_depth += 1
+            result.append(ch)
+        elif ch == ")":
+            if paren_depth > 0:
+                paren_depth -= 1
+                result.append(ch)
+            else:
+                break
+        elif ch == "[":
+            bracket_depth += 1
+            result.append(ch)
+        elif ch == "]":
+            if bracket_depth > 0:
+                bracket_depth -= 1
+                result.append(ch)
+            else:
+                break
+        elif ch == "{":
+            curly_depth += 1
+            result.append(ch)
+        elif ch == "}":
+            if curly_depth > 0:
+                curly_depth -= 1
+                result.append(ch)
+            else:
+                break
+        elif ch == ";" and at_top_level():
+            break
+        elif ch == "," and at_top_level():
+            # Comma outside any brackets = end of this expression
+            break
+        elif ch == "\n" and at_top_level():
+            # Newline may indicate the end of the expression, but only if
+            # we already have content (types can span lines inside brackets)
+            if result and result[-1].strip():
+                break
+        else:
+            result.append(ch)
+
+        i += 1
+
+    return "".join(result).strip() or None
+
+
+def find_top_level_semicolon(text: str, start: int) -> int:
+    """
+    Find the next semicolon in text that is NOT inside curly braces,
+    square brackets, angle brackets, or parentheses.
+
+    Returns the index of the semicolon, or len(text) if not found.
+    """
+    depth = {"(": 0, "[": 0, "{": 0, "<": 0}
+    openers = {"(", "[", "{", "<"}
+    closers = {")": "(", "]": "[", "}": "{", ">": "<"}
+
+    i = start
+    while i < len(text):
+        ch = text[i]
+        if ch in openers:
+            depth[ch] += 1
+        elif ch in closers:
+            opener = closers[ch]
+            if depth[opener] > 0:
+                depth[opener] -= 1
+        elif ch == ";" and all(v == 0 for v in depth.values()):
+            return i
+        i += 1
+
+    return len(text)
+
+
+def extract_params_from_body(body: str) -> dict[str, dict[str, str | bool]]:
+    """
+    Extract all params["key"] patterns and their inferred types from a
+    command definition body.
+
+    Returns a dict mapping param_name -> { type, optional }.
+    Skips internal keys (starting with '_') which are used for stashing
+    data on params for describe/undo.
+    """
+    params: dict[str, dict[str, str | bool]] = {}
+
+    for m in PARAM_PATTERN.finditer(body):
+        key = m.group(2)
+
+        # Skip internal stash keys like _prevColor, _removedName
+        if key.startswith("_"):
+            continue
+
+        # Already found this key -- keep the first (usually from execute)
+        if key in params:
+            continue
+
+        # Extract the containing statement for this params reference.
+        # We find the next TOP-LEVEL semicolon (not inside braces/brackets)
+        # to scope our analysis to just THIS statement.
+        start = m.start()
+        semi_pos = find_top_level_semicolon(body, m.end())
+        # The statement context: from param reference to its semicolon
+        stmt = body[start : semi_pos + 1]
+
+        # Determine if optional: look for ??, | undefined, or !== undefined
+        # guard within this statement
+        is_optional = False
+        if "??" in stmt or "| undefined" in stmt or "!== undefined" in stmt:
+            is_optional = True
+
+        # Find the 'as' cast within the statement
+        after_bracket = stmt[m.end() - start:]
+
+        ts_type = "unknown"
+        raw_type = extract_as_type(after_bracket)
+        if raw_type:
+            # Clean up the type -- remove trailing | undefined, parens
+            raw_type = raw_type.rstrip(")")
+            if raw_type.endswith("| undefined"):
+                raw_type = raw_type[: -len("| undefined")].strip()
+                is_optional = True
+            # Clean up leading parens
+            raw_type = raw_type.lstrip("(").strip()
+            if raw_type:
+                ts_type = raw_type
+
+        params[key] = {"type": ts_type, "optional": is_optional}
+
+    return params
+
+
+# ---------------------------------------------------------------------------
+# Detect dynamic commands (registered in a loop)
+# ---------------------------------------------------------------------------
+
+def is_dynamic_command(source: str, cmd_name: str) -> bool:
+    """
+    Check if a command is registered dynamically (e.g., in a for loop with
+    template literal names like `layout_${presetKey}`).
+
+    We detect this by checking if the addCommand call uses a template literal
+    or variable for the command name instead of a plain string.
+    """
+    # Look for addCommand(`...${...}...`) or addCommand(variable)
+    dynamic_pattern = re.compile(
+        r"""addCommand\(\s*`[^`]*\$\{[^}]+\}[^`]*`"""
+    )
+    return bool(dynamic_pattern.search(source))
+
+
+# ---------------------------------------------------------------------------
+# Main pipeline
+# ---------------------------------------------------------------------------
+
+def process_file(
+    filepath: Path,
+    root: Path,
+) -> list[dict]:
+    """
+    Process a single .ts file: find all addCommand calls, extract params.
+
+    Returns a list of dicts with keys: name, interface_name, params,
+    relative_path, dynamic, line.
+    """
+    source = filepath.read_text(encoding="utf-8")
+    results: list[dict] = []
+
+    # Check for dynamic commands (layout_* in a loop)
+    has_dynamic = is_dynamic_command(source, "")
+
+    blocks = extract_add_command_blocks(source)
+    for cmd_name, body, line in blocks:
+        params = extract_params_from_body(body)
+        rel_path = filepath.relative_to(root)
+        results.append({
+            "name": cmd_name,
+            "interface_name": snake_to_pascal(cmd_name),
+            "params": params,
+            "relative_path": str(rel_path),
+            "line": line,
+            "dynamic": False,
+        })
+
+    # Also detect template-literal addCommand calls (dynamic names)
+    dynamic_pattern = re.compile(
+        r"""addCommand\(\s*`([^`]*\$\{[^}]+\}[^`]*)`\s*,\s*\{"""
+    )
+    for dm in dynamic_pattern.finditer(source):
+        template = dm.group(1)
+        line = source[: dm.start()].count("\n") + 1
+        rel_path = filepath.relative_to(root)
+        results.append({
+            "name": template,
+            "interface_name": None,
+            "params": {},
+            "relative_path": str(rel_path),
+            "line": line,
+            "dynamic": True,
+        })
+
+    # Detect variable-based addCommand calls (e.g. addCommand(config.commandName, ...))
+    # These are used by factory functions like makeStrokeTool.
+    var_pattern = re.compile(
+        r"""addCommand\(\s*(\w+(?:\.\w+)+)\s*,\s*\{"""
+    )
+    for vm in var_pattern.finditer(source):
+        var_name = vm.group(1)
+        line = source[: vm.start()].count("\n") + 1
+        rel_path = filepath.relative_to(root)
+        results.append({
+            "name": var_name,
+            "interface_name": None,
+            "params": {},
+            "relative_path": str(rel_path),
+            "line": line,
+            "dynamic": True,
+        })
+
+    return results
+
+
+def generate_output(
+    all_commands: list[dict],
+) -> str:
+    """
+    Generate the full TypeScript output from the extracted command data.
+
+    Groups commands by source file and generates:
+    - An interface per command (or Record<string, never> for no-param commands)
+    - A declare global block per command
+    """
+    lines: list[str] = []
+    lines.append("// Auto-generated by scripts/generate-command-params.py")
+    lines.append(
+        "// Review and adjust before committing "
+        "-- types are inferred from `as` casts."
+    )
+    lines.append("")
+
+    # Group by relative path
+    by_file: dict[str, list[dict]] = {}
+    for cmd in all_commands:
+        path = cmd["relative_path"]
+        by_file.setdefault(path, []).append(cmd)
+
+    for filepath, commands in by_file.items():
+        lines.append(f"// --- {filepath} ---")
+        lines.append("")
+
+        for cmd in commands:
+            if cmd["dynamic"]:
+                lines.append(
+                    f"// SKIPPED: dynamic command `{cmd['name']}` "
+                    f"(registered in a loop, line {cmd['line']})"
+                )
+                lines.append("")
+                continue
+
+            name = cmd["name"]
+            iface = cmd["interface_name"]
+            params = cmd["params"]
+
+            if not params:
+                # No params -- use Record<string, never>
+                lines.append(f"export interface {iface} extends Record<string, never> {{}}")
+            else:
+                lines.append(f"export interface {iface} {{")
+                for pname, pinfo in params.items():
+                    ts_type = pinfo["type"]
+                    optional = pinfo["optional"]
+                    opt_mark = "?" if optional else ""
+                    # Add a TODO comment for uncertain types
+                    comment = ""
+                    if ts_type == "unknown":
+                        comment = " // TODO: verify"
+                    lines.append(f"  {pname}{opt_mark}: {ts_type};{comment}")
+                lines.append("}")
+
+            lines.append("")
+            lines.append("declare global {")
+            lines.append("  interface CommandParamsMap {")
+            lines.append(f"    {name}: {iface};")
+            lines.append("  }")
+            lines.append("}")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def print_dry_run(all_commands: list[dict]) -> None:
+    """Print a summary table of found commands (dry-run mode)."""
+    print(f"Found {len(all_commands)} command(s):\n")
+    print(f"{'Command':<35} {'Interface':<35} {'Params':<6} {'File'}")
+    print("-" * 120)
+    for cmd in all_commands:
+        name = cmd["name"]
+        if cmd["dynamic"]:
+            iface = "(dynamic -- skipped)"
+        else:
+            iface = cmd["interface_name"]
+        param_count = len(cmd["params"])
+        filepath = cmd["relative_path"]
+        print(f"{name:<35} {iface:<35} {param_count:<6} {filepath}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate TypeScript command params interfaces from addCommand() casts."
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path.cwd(),
+        help="Project root directory (default: cwd)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List found commands without generating code",
+    )
+    args = parser.parse_args()
+    root: Path = args.root.resolve()
+
+    # Validate root
+    src = root / "src"
+    plugins = root / "plugins"
+    if not src.is_dir() and not plugins.is_dir():
+        print(
+            f"Error: neither {src} nor {plugins} exists. "
+            f"Is --root pointing to the PixelWeaver project?",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Collect all .ts files
+    ts_files = find_ts_files(root)
+    if not ts_files:
+        print("No .ts files found.", file=sys.stderr)
+        sys.exit(1)
+
+    # Process each file
+    all_commands: list[dict] = []
+    for filepath in ts_files:
+        cmds = process_file(filepath, root)
+        all_commands.extend(cmds)
+
+    if not all_commands:
+        print("No addCommand() calls found.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.dry_run:
+        print_dry_run(all_commands)
+    else:
+        output = generate_output(all_commands)
+        print(output)
+
+
+if __name__ == "__main__":
+    main()