Capture imports on copy; update imports on paste

pkg/analysis_server/tool/spec/spec_input.html

Index: pkg/analysis_server/tool/spec/spec_input.html
diff --git a/pkg/analysis_server/tool/spec/spec_input.html b/pkg/analysis_server/tool/spec/spec_input.html
index 0415596a2aa7766a0e5504c5fc47ef54393e8246..24db4ee512ef3c127040934980092dddf4f4e478 100644
--- a/pkg/analysis_server/tool/spec/spec_input.html
+++ b/pkg/analysis_server/tool/spec/spec_input.html
@@ -431,49 +431,57 @@
       </field>
     </result>
   </request>
-  <request method="getReachableSources">
+  <request method="getImportedElements" experimental="true">
     <p>
-      Return the transitive closure of reachable sources for a given file.
+      Return a description of all of the elements referenced in a given region
+      of a given file that come from imported libraries.
     </p>
     <p>
-      If a request is made for a file which does not exist, or
-      which is not currently subject to analysis (e.g. because it
-      is not associated with any analysis root specified to
-      analysis.setAnalysisRoots), an error of type
-      <tt>GET_REACHABLE_SOURCES_INVALID_FILE</tt> will be generated.
+      If a request is made for a file that does not exist, or that is not
+      currently subject to analysis (e.g. because it is not associated with any
+      analysis root specified via analysis.setAnalysisRoots), an error of type
+      <tt>GET_IMPORTED_ELEMENTS_INVALID_FILE</tt> will be generated.
     </p>
     <params>
       <field name="file">
         <ref>FilePath</ref>
         <p>
-          The file for which reachable source information is being requested.
+          The file in which import information is being requested.
+        </p>
+      </field>
+      <field name="offset">
+        <ref>int</ref>
+        <p>
+          The offset of the region for which import information is being
+          requested.
+        </p>
+      </field>
+      <field name="length">
+        <ref>int</ref>
+        <p>
+          The length of the region for which import information is being
+          requested.
         </p>
       </field>
     </params>
     <result>
-      <field name="sources">
-        <map>
-          <key>
-            <ref>String</ref>
-          </key>
-          <value>
-            <list>
-              <ref>String</ref>
-            </list>
-          </value>
-        </map>
+      <field name="elements">
+        <list>
+          <ref>ImportedElements</ref>
+        </list>
         <p>
-          A mapping from source URIs to directly reachable source URIs. For
-          example,
-          a file "foo.dart" that imports "bar.dart" would have the corresponding
-          mapping
-          { "file:///foo.dart" : ["file:///bar.dart"] }. If "bar.dart" has
-          further imports
-          (or exports) there will be a mapping from the URI "file:///bar.dart"
-          to them.
-          To check if a specific URI is reachable from a given file, clients can
-          check
-          for its presence in the resulting key set.
+          The information about the elements that are referenced in the
+          specified region of the specified file that come from imported
+          libraries.
+        </p>
+      </field>
+      <field name="complete">
+        <ref>bool</ref>
+        <p>
+          True if all of the elements that are referenced in the specified
+          region are included in the list of elements. The list of elements will
+          be incomplete if there is an error in the specified region that
+          prevents an identifier from being resolved to a single element.
         </p>
       </field>
     </result>
@@ -601,6 +609,53 @@
       </field>
     </result>
   </request>
+  <request method="getReachableSources">
+    <p>
+      Return the transitive closure of reachable sources for a given file.
+    </p>
+    <p>
+      If a request is made for a file which does not exist, or
+      which is not currently subject to analysis (e.g. because it
+      is not associated with any analysis root specified to
+      analysis.setAnalysisRoots), an error of type
+      <tt>GET_REACHABLE_SOURCES_INVALID_FILE</tt> will be generated.
+    </p>
+    <params>
+      <field name="file">
+        <ref>FilePath</ref>
+        <p>
+          The file for which reachable source information is being requested.
+        </p>
+      </field>
+    </params>
+    <result>
+      <field name="sources">
+        <map>
+          <key>
+            <ref>String</ref>
+          </key>
+          <value>
+            <list>
+              <ref>String</ref>
+            </list>
+          </value>
+        </map>
+        <p>
+          A mapping from source URIs to directly reachable source URIs. For
+          example,
+          a file "foo.dart" that imports "bar.dart" would have the corresponding
+          mapping
+          { "file:///foo.dart" : ["file:///bar.dart"] }. If "bar.dart" has
+          further imports
+          (or exports) there will be a mapping from the URI "file:///bar.dart"
+          to them.
+          To check if a specific URI is reachable from a given file, clients can
+          check
+          for its presence in the resulting key set.
+        </p>
+      </field>
+    </result>
+  </request>
   <request method="reanalyze">
     <p>
       Force the re-analysis of everything contained in the specified
@@ -1939,6 +1994,50 @@
       </field>
     </result>
   </request>
+  <request method="importElements" experimental="true">
+    <p>
+      Return a list of edits that would need to be applied in order to ensure
+      that all of the elements in the specified list of imported elements are
+      accessible within the library.
+    </p>
+    <params>
+      <field name="file">
+        <ref>FilePath</ref>
+        <p>
+          The file in which the specified elements are to be made accessible.
+        </p>
+      </field>
+      <field name="elements">
+        <list>
+          <ref>ImportedElements</ref>
+        </list>
+        <p>
+          The elements to be made accessible in the specified file.
+        </p>
+      </field>
+    </params>
+    <result>
+      <field name="edits">
+        <list>
+          <ref>SourceEdit</ref>
+        </list>
+        <p>
+          The edit(s) to be applied in order to make the specified elements
+          accessible.
+        </p>
+      </field>
+      <field name="complete">
+        <ref>bool</ref>
+        <p>
+          True if all of the elements that are to be made accessible would be
+          accessible if the edits were applied. The edits will not be complete,
+          for example, if one of the libraries cannot be referenced in the
+          target library or if one of the element names is already imported from
+          a different library.
+        </p>
+      </field>
+    </result>
+  </request>
   <request method="sortMembers">
     <p>
       Sort all of the directives, unit and class members
@@ -2719,6 +2818,34 @@
       </field>
     </object>
   </type>
+  <type name="ImportedElements">
+    <p>
+      A description of the elements that are referenced in a region of a file
+      that come from a single imported library.
+    </p>
+    <object>
+      <field name="path">

[scheglov, 2017/06/12 23:57:16]

Is path used to verify that URI is resolved to the same file in the target
library as it was in the source one? Should we specify that this is absolute,
normalized path? FilePath?

[Brian Wilkerson, 2017/06/13 04:15:06]

I was trying to anticipate how the edit request would be implemented.

I think that users would prefer that we used the same style of import in the
paste operation as they had in the file from which the copy was taken.
Therefore, I expect that we'd want to use the URI most of the time. But I think
there will be times when the URI is not sufficient and we'll need the file path
in order to create a URI. (I might be wrong about that, though.) So while we
could use it to verify correctness, I was thinking of it as a back-up in case
the URI was not sufficient.

As for how we specify this, yes, it should be absolute and normalized, and a
FilePath.

+        <ref>String</ref>
+        <p>
+          The path of the file containing the library.
+        </p>
+      </field>
+      <field name="uri">
+        <ref>String</ref>
+        <p>
+          The URI that should be used when importing the library.

[scheglov, 2017/06/12 23:57:16]

Should we specify the the URI is absolute?

[Brian Wilkerson, 2017/06/13 04:15:06]

I think we actually want the URI used in the original source so that we can use
the same style of URI for the edit.

[scheglov, 2017/06/13 05:08:00]

Hm...
If the URI is not absolute, i.e. it is relative, it would not mean the same in a
different library.

We might want to stick to the URI style in the target library though. If it uses
relative URIs, and the import URI is for a file in the lib/ of the same package,
we would use relative URI, even if the import was copied as an absolute URI. But
in the target library uses absolute URIs, we want do the same.

[Brian Wilkerson, 2017/06/13 14:01:50]

Agreed. I think keeping the original URI and the file path is enough to allow us
the flexibility to optimize the UX.

+        </p>
+      </field>
+      <field name="elements">
+        <list>
+          <ref>String</ref>
+        </list>
+        <p>
+          The names of the elements imported from the library.
+        </p>
+      </field>

[scheglov, 2017/06/13 05:08:00]

I think we might need also the "prefix" field.

The copied source might reference top-level elements with prefixes, and we need
either make sure that we insert imports with the same prefixes, or we need to
rewrite the copied code to not use prefixes. Actually sometimes we might have to
do this anyway, e.g. if the prefix conflicts with a prefix in the target
library.

Alternatively, we could say that we don't support rewrites on paste, so
conflicts are not "complete". Or maybe we don't support and make as not
"complete" copying imports for code with prefixes.

[Brian Wilkerson, 2017/06/13 14:01:50]

I agree. I'll update the CL.

I've taken the other issues off-line because I think they require a longer
discussion than is convenient in a review.

[Brian Wilkerson, 2017/06/13 14:30:37]

I think we might also need to capture whether there was a show combinator,
whether the import is deferred, and whether the import was conditional. Perhaps
rather than capturing individual pieces we should just capture the text of the
whole import directive.

+    </object>
+  </type>
   <type name="Override">
     <p>
       A description of a member that overrides an inherited member.
@@ -2883,6 +3010,13 @@
         </p>
       </value>
       <value>
+        <code>GET_IMPORTED_ELEMENTS_INVALID_FILE</code>
+        <p>
+          An "analysis.getImportedElements" request specified a FilePath that
+          does not match a file currently subject to analysis.
+        </p>
+      </value>
+      <value>
         <code>GET_NAVIGATION_INVALID_FILE</code>
         <p>
           An "analysis.getNavigation" request specified a FilePath