Initial implementation of a division migrator

lib/runner.dart

@@ -10,6 +10,7 @@ import 'package:args/command_runner.dart';
 import 'package:path/path.dart' as p;
 import 'package:term_glyph/term_glyph.dart' as glyph;
 
+import 'src/migrators/division.dart';
 import 'src/migrators/module.dart';
 
 /// A command runner that runs a migrator based on provided arguments.
@@ -30,6 +31,7 @@ class MigratorRunner extends CommandRunner<Map<Uri, String>> {
       ..addFlag('verbose',
           abbr: 'v',
           help: 'Print text of migrated files when running with --dry-run.');
+    addCommand(DivisionMigrator());
     addCommand(ModuleMigrator());
   }
 

lib/src/migrators/division.dart

@@ -0,0 +1,238 @@
+// Copyright 2018 Google LLC
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import 'package:args/args.dart';
+
+// The sass package's API is not necessarily stable. It is being imported with
+// the Sass team's explicit knowledge and approval. See
+// https://github.com/sass/dart-sass/issues/236.
+import 'package:sass/src/ast/sass.dart';
+
+import 'package:sass_migrator/src/migration_visitor.dart';
+import 'package:sass_migrator/src/migrator.dart';
+import 'package:sass_migrator/src/patch.dart';
+import 'package:sass_migrator/src/utils.dart';
+
+/// Migrates stylesheets that use the `/` operator for division to use the
+/// `divide` function instead.
+class DivisionMigrator extends Migrator {
+  final name = "division";
+  final description =
+      "Migrates from the / division operator to the divide function";
+
+  @override
+  final argParser = ArgParser()
+    ..addFlag('pessimistic',
+        abbr: 'p',
+        help: r"Only migrate / expressions that are unambiguously division.");
+
+  bool get isPessimistic => argResults['pessimistic'] as bool;
+
+  @override
+  Map<Uri, String> migrateFile(Uri entrypoint) =>
+      _DivisionMigrationVisitor(this.isPessimistic, migrateDependencies)
+          .run(entrypoint);
+}
+
+class _DivisionMigrationVisitor extends MigrationVisitor {
+  final bool isPessimistic;
+
+  _DivisionMigrationVisitor(this.isPessimistic, bool migrateDependencies)
+      : super(migrateDependencies: migrateDependencies);
+
+  /// True when division is allowed by the context the current node is in.
+  var _isDivisionAllowed = false;
+
+  /// True when the current node is expected to evaluate to a number.
+  var _expectsNumericResult = false;
+
+  /// If this is a division operation, migrates it.
+  ///
+  /// If this is any other operator, allows division within its left and right
+  /// operands.
+  @override
+  void visitBinaryOperationExpression(BinaryOperationExpression node) {
+    if (node.operator == BinaryOperator.dividedBy) {
+      var numericResult = false;
+      if (_shouldMigrate(node)) {
+        addPatch(patchBefore(node, "divide("));
+        _patchParensIfAny(node.left);
+        _patchSlashToComma(node);
+        _patchParensIfAny(node.right);
+        addPatch(patchAfter(node, ")"));
+        numericResult = true;
+      }
+      _withContext(() => super.visitBinaryOperationExpression(node),
+          expectsNumericResult: numericResult);
+    } else {
+      _withContext(() => super.visitBinaryOperationExpression(node),
+          isDivisionAllowed: true,
+          expectsNumericResult:
+              _expectsNumericResult || _operatesOnNumbers(node.operator));
+    }
+  }
+
+  /// Disallows division within this list.
+  @override
+  void visitListExpression(ListExpression node) {
+    _withContext(() => super.visitListExpression(node),
+        isDivisionAllowed: false, expectsNumericResult: false);
+  }
+
+  /// If this parenthesized expression contains a division operation, migrates
+  /// it using the parentheses that already exist.
+  @override
+  void visitParenthesizedExpression(ParenthesizedExpression node) {
+    _withContext(() {
+      var expression = node.expression;
+      if (expression is BinaryOperationExpression &&
+          expression.operator == BinaryOperator.dividedBy) {
+        if (_shouldMigrate(expression)) {
+          addPatch(patchBefore(node, "divide"));
+          _patchParensIfAny(expression.left);
+          _patchSlashToComma(expression);
+          _patchParensIfAny(expression.right);
+        }
+        super.visitBinaryOperationExpression(expression);
+      } else {
+        super.visitParenthesizedExpression(node);
+      }
+    }, isDivisionAllowed: true);
+  }
+
+  /// Allows division within this return rule.
+  @override
+  void visitReturnRule(ReturnRule node) {
+    _withContext(() => super.visitReturnRule(node), isDivisionAllowed: true);
+  }
+
+  /// Allows division within this variable declaration.
+  @override
+  void visitVariableDeclaration(VariableDeclaration node) {
+    _withContext(() => super.visitVariableDeclaration(node),
+        isDivisionAllowed: true);
+  }
+
+  /// Returns true if we assume that [operator] always returns a number.
+  ///
+  /// This is always true for `*` and `%`, and it's true for `+` and `-` as long
+  /// as the aggressive option is enabled.
+  bool _returnsNumbers(BinaryOperator operator) =>
+      operator == BinaryOperator.times ||
+      operator == BinaryOperator.modulo ||
+      !isPessimistic &&
+          (operator == BinaryOperator.plus || operator == BinaryOperator.minus);
+
+  /// Returns true if we assume that [operator] always operators on numbers.
+  ///
+  /// This is always true for `*`, `%`, `<`, `<=`, `>`, and `>=`, and it's true
+  /// for `+`, `-`, `==`, and `!=` as long as the aggressive option is enabled.
+  bool _operatesOnNumbers(BinaryOperator operator) =>
+      _returnsNumbers(operator) ||
+      operator == BinaryOperator.lessThan ||
+      operator == BinaryOperator.lessThanOrEquals ||
+      operator == BinaryOperator.greaterThan ||
+      operator == BinaryOperator.greaterThanOrEquals ||
+      !isPessimistic &&
+          (operator == BinaryOperator.equals ||
+              operator == BinaryOperator.notEquals);
+
+  /// Returns true if [node] should be treated as division and migrated.
+  ///
+  /// Warns if division is allowed but it's unclear whether or not all types
+  /// are numeric.
+  bool _shouldMigrate(BinaryOperationExpression node) {
+    if (!_isDivisionAllowed && _onlySlash(node)) return false;
+    if (_isDefinitelyNotNumber(node)) return false;
+    if (_expectsNumericResult || _isDefinitelyNumber(node)) return true;
+    warn("Could not determine whether this is division", node.span);
+    return false;
+  }
+
+  /// Returns true if [node] is entirely composed of number literals and slash
+  /// operations.
+  bool _onlySlash(Expression node) {
+    if (node is NumberExpression) return true;
+    if (node is BinaryOperationExpression) {
+      return node.operator == BinaryOperator.dividedBy &&
+          _onlySlash(node.left) &&
+          _onlySlash(node.right);
+    }
+    return false;
+  }
+
+  /// Returns true if [node] is believed to always evaluate to a number.
+  bool _isDefinitelyNumber(Expression node) {
+    if (node is NumberExpression) return true;
+    if (node is ParenthesizedExpression) {
+      return _isDefinitelyNumber(node.expression);
+    }
+    if (node is UnaryOperationExpression) {
+      return _isDefinitelyNumber(node.operand);
+    }
+    if (node is FunctionExpression || node is VariableExpression) {
+      return !isPessimistic;
+    }
+    if (node is BinaryOperationExpression) {
+      return _returnsNumbers(node.operator) ||
+          (_isDefinitelyNumber(node.left) && _isDefinitelyNumber(node.right));
+    }
+    return false;
+  }
+
+  /// Returns true if [node] contains a subexpression known to not be a number.
+  bool _isDefinitelyNotNumber(Expression node) {
+    if (node is ParenthesizedExpression) {
+      return _isDefinitelyNotNumber(node.expression);
+    }
+    if (node is BinaryOperationExpression) {
+      return _isDefinitelyNotNumber(node.left) ||
+          _isDefinitelyNotNumber(node.right);
+    }
+    return node is BooleanExpression ||
+        node is ColorExpression ||
+        node is ListExpression ||
+        node is MapExpression ||
+        node is NullExpression ||
+        node is StringExpression;
+  }
+
+  /// Adds a patch replacing the operator of [node] with ", ".
+  void _patchSlashToComma(BinaryOperationExpression node) {
+    var start = node.left.span.end;
+    var end = node.right.span.start;
+    addPatch(Patch(start.file.span(start.offset, end.offset), ", "));
+  }
+
+  /// Adds patches removing unnecessary parentheses around [node] if it is a
+  /// ParenthesizedExpression.
+  void _patchParensIfAny(SassNode node) {
+    if (node is! ParenthesizedExpression) return;
+    var expression = (node as ParenthesizedExpression).expression;
+    if (expression is BinaryOperationExpression &&
+        expression.operator == BinaryOperator.dividedBy) {
+      return;
+    }
+    var start = node.span.start;
+    var end = node.span.end;
+    addPatch(Patch(start.file.span(start.offset, start.offset + 1), ""));
+    addPatch(Patch(start.file.span(end.offset - 1, end.offset), ""));
+  }
+
+  /// Runs [operation] with the given context.
+  void _withContext(void operation(),
+      {bool isDivisionAllowed, bool expectsNumericResult}) {
+    var previousDivisionAllowed = _isDivisionAllowed;
+    var previousNumericResult = _expectsNumericResult;
+    if (isDivisionAllowed != null) _isDivisionAllowed = isDivisionAllowed;
+    if (expectsNumericResult != null) {
+      _expectsNumericResult = expectsNumericResult;
+    }
+    operation();
+    _isDivisionAllowed = previousDivisionAllowed;
+    _expectsNumericResult = previousNumericResult;
+  }
+}

test/migrators/division/always_division.hrx

@@ -0,0 +1,52 @@
+<==> arguments
+--pessimistic
+
+<==> input/entrypoint.scss
+@function six-divided-by-three() {
+  @return 6px / 3px;
+}
+
+a {
+  b: (4px + 2px) / 3px;
+  c: 6px/3px + 1;
+  d: (6px / 3px);
+  e: 6px / (2px + 1px) / 2;
+  $f: 6px / 3px;
+
+  // * and % always return numbers, so we can assume division here
+  g: (3 * $x) / 4;
+  h: 3 / $x * 4;
+  i: (3 % $x) / 4;
+  j: 3 / $x % 4;
+
+  // < and similar operators always operate on numbers
+  k: 3 / $x < 1;
+  l: 3 / $x > 1;
+  m: 3 / $x <= 1;
+  n: 3 / $x >= 1;
+}
+
+<==> output/entrypoint.scss
+@function six-divided-by-three() {
+  @return divide(6px, 3px);
+}
+
+a {
+  b: divide(4px + 2px, 3px);
+  c: divide(6px, 3px) + 1;
+  d: divide(6px, 3px);
+  e: divide(divide(6px, 2px + 1px), 2);
+  $f: divide(6px, 3px);
+
+  // * and % always return numbers, so we can assume division here
+  g: divide((3 * $x), 4);
+  h: divide(3, $x) * 4;
+  i: divide((3 % $x), 4);
+  j: divide(3, $x) % 4;
+
+  // < and similar operators always operate on numbers
+  k: divide(3, $x) < 1;
+  l: divide(3, $x) > 1;
+  m: divide(3, $x) <= 1;
+  n: divide(3, $x) >= 1;
+}

test/migrators/division/maybe_division.hrx

@@ -0,0 +1,17 @@
+<==> input/entrypoint.scss
+a {
+  b: (3 / $x) + 4;
+  c: 3 / $x - 4;
+  d: 3 / $x == 4;
+  e: fn() / 3;
+  f: 3 / $x;
+}
+
+<==> output/entrypoint.scss
+a {
+  b: divide(3, $x) + 4;
+  c: divide(3, $x) - 4;
+  d: divide(3, $x) == 4;
+  e: divide(fn(), 3);
+  f: divide(3, $x);
+}

test/migrators/division/maybe_division_pessimistic.hrx

@@ -0,0 +1,39 @@
+<==> arguments
+--pessimistic
+
+<==> input/entrypoint.scss
+a {
+  b: (3 / $x) + 4;
+  c: 3 / $x - 4;
+  d: 3 / $x == 4;
+  e: fn() / 3;
+  f: 3 / $x;
+}
+
+<==> log.txt
+line 2, column 7 of entrypoint.scss: WARNING - Could not determine whether this is division
+  ,
+2 |   b: (3 / $x) + 4;
+  |       ^^^^^^
+  '
+line 3, column 6 of entrypoint.scss: WARNING - Could not determine whether this is division
+  ,
+3 |   c: 3 / $x - 4;
+  |      ^^^^^^
+  '
+line 4, column 6 of entrypoint.scss: WARNING - Could not determine whether this is division
+  ,
+4 |   d: 3 / $x == 4;
+  |      ^^^^^^
+  '
+line 5, column 6 of entrypoint.scss: WARNING - Could not determine whether this is division
+  ,
+5 |   e: fn() / 3;
+  |      ^^^^^^^^
+  '
+line 6, column 6 of entrypoint.scss: WARNING - Could not determine whether this is division
+  ,
+6 |   f: 3 / $x;
+  |      ^^^^^^
+  '
+Nothing to migrate!

test/migrators/division/never_division.hrx

@@ -0,0 +1,13 @@
+<==> input/entrypoint.scss
+:foo(#{6/3}) {
+  b: 6px / 3px;
+  c: 6px / 3px / 2;
+  d: #{4px + 2px} / 3px;
+  e: bold 6px/3px sans-serif;
+  f: (bold 6px/3px sans-serif);
+  g: (six / three);
+  h: 6 / three;
+}
+
+<==> log.txt
+Nothing to migrate!

test/migrators/division_test.dart

@@ -0,0 +1,11 @@
+// Copyright 2019 Google LLC
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import '../migrator_utils.dart';
+
+main() {
+  testMigrator("division");
+}