cEP-0025.md: Integrate pyflakes AST

Closes #143

cEP-0025.md

@@ -0,0 +1,116 @@
+# Integration of pyflakes-enhanced-AST into coala
+
+| Metadata |                                                 |
+| -------- | ----------------------------------------------- |
+| cEP      | 22                                              |
+| Version  | 1.0                                             |
+| Title    | Integration of pyflakes-enhanced-AST into coala |
+| Authors  | Ankit Joshi <mailto:[email protected]>      |
+| Status   | Proposed                                        |
+| Type     | Feature                                         |
+
+## Abstract
+
+This document describes how to create a metabear to integrate
+pyflakes-enhanced-AST into coala.
+
+## Introduction
+
+The current approach of plugin development for flake8 does not utilises
+the full potential of enhanced AST rather they simply depend on python AST
+and so, a whole lot of rework is required to do the basic traversing
+and collection of important nodes.
+
+Pyflakes provides with a basic API that does the traversing.
+So, if a developer uses enhanced AST he just needs to work on
+the implementation of the new logic that his/her plugin provides
+and not about the fidelity of the basic node handlers.
+
+## Proposed Change
+
+Here is the detailed implementation stepwise:
+
+1. There will be a separate repository named as coala-pyflakes which will
+   be installable via `pip install coala-pyflakes`.
+2. The repository will contain a new package `pyflakes-plugins` which
+   would house all bears which uses pyflakes-enhanced-ast.
+3. The `pyflakes-plugins` would contain a metabear `PyflakesASTBear`
+   which would be used by all other plugin bears.
+
+## Management of the new `coala-pyflakes` repository
+
+The repository will use a similar mechanism of what is being
+used in `coala-bears` to test all its plugins.
+
+## Code Samples/Prototypes
+
+Here is a prototype for the implementations of PyflakesASTBear:
+
+```python
+# Imports not mentioned to maintain brevity
+
+class PyflakesResult(HiddenResult):
+
+    @enforce_signature
+    def __init__(self, origin, deadScopes):
+
+        Result.__init__(self, origin, message='')
+
+        self.class_scope = self.get_scope(ClassScope, deadScopes)
+        self.function_scope = self.get_scope(FunctionScope, deadScopes)
+        self.module_scope = self.get_scope(ModuleScope, deadScopes)
+        self.generator_scope = self.get_scope(GeneratorScope, deadScopes)
+        self.doctest_scope = self.get_scope(DoctestScope, deadScopes)
+
+    def get_scope(self, scope_level, scopes):
+        return list(filter(lambda scope: isinstance(scope, scope_level),
+                           scopes))
+
+    def get_node_location(self, node):
+        return (node.source.lineno,
+                node.source.lineno + node.source.depth - 1,
+                node.source.col_offset)
+
+
+class PyflakesASTBear(LocalBear):
+
+    def run(self, filename, file):
+        """
+        Generates pyflakes-enhance-AST for the input file and returns
+        deadScopes as HiddenResult
+        :return:
+            One HiddenResult containing a dictionary with keys being
+            type of scope and values being a list of scopes generated
+            from the file.
+        """
+        tree = ast.parse(''.join(file))
+        result = Checker(tree, filename)
+
+        yield PyflakesResult(self, result.deadScopes)
+```
+
+Here is a prototype for a plugin that uses PyflakesASTBear:
+
+```python
+# Imports not mentioned to maintain brevity
+
+class FutureImportBear(LocalBear):
+    """
+    Uses pyflakes-enhance-AST to get list of future imports
+    """
+
+    BEAR_DEPS = {PyflakesASTBear}
+
+    def run(self, filename, file,
+            dependency_results=dict()
+            ):
+        for result in dependency_results.get(PyflakesASTBear.name, []):
+            for scope in result.module_scope:
+                for node_name, node in scope.items():
+                    if isinstance(node, FutureImportation):
+                        yield Result.from_values(
+                            origin=self,
+                            message=('Future import %s found' % node_name),
+                            file=filename,
+                            line=result.get_node_location(node)[0])
+```