When available, pass path, line and repository hints to external symbol queries

Summary:
Depends on D18936. Ref T13047. Third parties can define external symbol sources that let users jump to PHP or Python documentation or query some server.

Give these queries more information so they can try to get better results: the path and line where the symbol appeared, and any known repository scope.

Test Plan: Wrote a fake external source that used this data, command-clicked a symbol in Differential, saw a fake external symbol result.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13047

Differential Revision: https://secure.phabricator.com/D18937

src/applications/diffusion/controller/DiffusionSymbolController.php

@@ -22,6 +22,7 @@ final class DiffusionSymbolController extends DiffusionController {
       $query->setLanguage($request->getStr('lang'));
     }
 
+    $repos = array();
     if ($request->getStr('repositories')) {
       $phids = $request->getStr('repositories');
       $phids = explode(',', $phids);
@@ -33,9 +34,9 @@ final class DiffusionSymbolController extends DiffusionController {
           ->withPHIDs($phids)
           ->execute();
 
-        $repos = mpull($repos, 'getPHID');
-        if ($repos) {
-          $query->withRepositoryPHIDs($repos);
+        $repo_phids = mpull($repos, 'getPHID');
+        if ($repo_phids) {
+          $query->withRepositoryPHIDs($repo_phids);
         }
       }
     }
@@ -45,7 +46,6 @@ final class DiffusionSymbolController extends DiffusionController {
 
     $symbols = $query->execute();
 
-
     $external_query = id(new DiffusionExternalSymbolQuery())
       ->withNames(array($name));
 
@@ -61,13 +61,44 @@ final class DiffusionSymbolController extends DiffusionController {
       $external_query->withLanguages(array($request->getStr('lang')));
     }
 
+    if ($request->getStr('path')) {
+      $external_query->withPaths(array($request->getStr('path')));
+    }
+
+    if ($request->getInt('line')) {
+      $external_query->withLines(array($request->getInt('line')));
+    }
+
+    if ($repos) {
+      $external_query->withRepositories($repos);
+    }
+
     $external_sources = id(new PhutilClassMapQuery())
       ->setAncestorClass('DiffusionExternalSymbolsSource')
       ->execute();
 
     $results = array($symbols);
     foreach ($external_sources as $source) {
-      $results[] = $source->executeQuery($external_query);
+      $source_results = $source->executeQuery($external_query);
+
+      if (!is_array($source_results)) {
+        throw new Exception(
+          pht(
+            'Expected a list of results from external symbol source "%s".',
+            get_class($source)));
+      }
+
+      try {
+        assert_instances_of($source_results, 'PhabricatorRepositorySymbol');
+      } catch (InvalidArgumentException $ex) {
+        throw new Exception(
+          pht(
+            'Expected a list of PhabricatorRepositorySymbol objects '.
+            'from external symbol source "%s".',
+            get_class($source)));
+      }
+
+      $results[] = $source_results;
     }
     $symbols = array_mergev($results);
 

src/applications/diffusion/symbol/DiffusionExternalSymbolQuery.php

@@ -1,45 +1,83 @@
 <?php
 
 final class DiffusionExternalSymbolQuery extends Phobject {
+
   private $languages = array();
   private $types = array();
   private $names = array();
   private $contexts = array();
+  private $paths = array();
+  private $lines = array();
+  private $repositories = array();
 
   public function withLanguages(array $languages) {
     $this->languages = $languages;
     return $this;
   }
+
   public function withTypes(array $types) {
     $this->types = $types;
     return $this;
   }
+
   public function withNames(array $names) {
     $this->names = $names;
     return $this;
   }
+
   public function withContexts(array $contexts) {
     $this->contexts = $contexts;
     return $this;
   }
 
+  public function withPaths(array $paths) {
+    $this->paths = $paths;
+    return $this;
+  }
+
+  public function withLines(array $lines) {
+    $this->lines = $lines;
+    return $this;
+  }
+
+  public function withRepositories(array $repositories) {
+    assert_instances_of($repositories, 'PhabricatorRepository');
+    $this->repositories = $repositories;
+    return $this;
+  }
 
   public function getLanguages() {
     return $this->languages;
   }
+
   public function getTypes() {
     return $this->types;
   }
+
   public function getNames() {
     return $this->names;
   }
+
   public function getContexts() {
     return $this->contexts;
   }
 
+  public function getPaths() {
+    return $this->paths;
+  }
+
+  public function getLines() {
+    return $this->lines;
+  }
+
+  public function getRepositories() {
+    return $this->repositories;
+  }
+
   public function matchesAnyLanguage(array $languages) {
     return (!$this->languages) || array_intersect($languages, $this->languages);
   }
+
   public function matchesAnyType(array $types) {
     return (!$this->types) || array_intersect($types, $this->types);
   }