Fix Diviner links to articles by title

Summary:
Ref T988. This fixes the biggest current problem with Diviner, which is dead links to articles.

In the new Diviner, articles can have both a "name" (derived from the file name, and used in the URI) and a "title" (optional, specified explicitly). For example, we have one document with the name "feedback" and the title "Give Feedback! Get Support!".

On disk, we want to use the name for the actual file where the text lives ("feedback.diviner"). We also want to use the name in the URI, to generate a clean URI and to allow us to retitle the document slightly without breaking links to it (for example, we renamed the "Backup" document to "Backups and Migrations").

However, when displaying the article we want to use the title.

Currently, you can //only// link to the name, not the title. This is inconvenient:

  - We have a bunch of existing docs which link to titles.
  - It's natural/intuitive to link to titles.
  - Linking to titles makes it easier/cheaper to generate documentation, because we don't need to be able to resolve things at render time.

To remedy this, allow links to target either names or titles. If we miss on a name query, we'll do a title query. This is implemented with a slug hash to allow approximately correct titles (wrong case/spacing/punctuation, e.g.) and sidestep all the UTF8/column length issues.

(In the long run, atom resolution should theoretically be more sophistiated than it is now, and we should do render-time lookups on at least some documents to catch bad links. However, this is fairly complicated and a relatively advanced feature, and I think allowing links to titles is desirable no matter what.)

Test Plan: The user documentation book now has valid links to articles when the titles and names differ.

Reviewers: btrahan

Reviewed By: btrahan

CC: aran

Maniphest Tasks: T988

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

resources/sql/autopatches/20140305.diviner.1.slugcol.sql

@@ -0,0 +1,2 @@
+ALTER TABLE {$NAMESPACE}_diviner.diviner_livesymbol
+  ADD titleSlugHash CHAR(12) COLLATE latin1_bin AFTER title;

resources/sql/autopatches/20140305.diviner.2.slugkey.sql

@@ -0,0 +1,2 @@
+ALTER TABLE {$NAMESPACE}_diviner.diviner_livesymbol
+  ADD KEY `key_slug` (titleSlugHash);

src/applications/diviner/atom/DivinerAtom.php

@@ -197,6 +197,7 @@ final class DivinerAtom {
     }
 
     $parts = array(
+      $this->getBook(),
       $this->getType(),
       $this->getName(),
       $this->getFile(),

src/applications/diviner/atom/DivinerAtomRef.php

@@ -109,6 +109,10 @@ final class DivinerAtomRef {
     return $this->title;
   }
 
+  public function getTitleSlug() {
+    return self::normalizeTitleString($this->getTitle());
+  }
+
   public function toDictionary() {
     return array(
       'book'    => $this->getBook(),
@@ -144,6 +148,7 @@ final class DivinerAtomRef {
     $obj->index = idx($dict, 'index');
     $obj->summary = idx($dict, 'summary');
     $obj->title = idx($dict, 'title');
+
     return $obj;
   }
 
@@ -193,4 +198,9 @@ final class DivinerAtomRef {
     return idx($alternates, $str, $str);
   }
 
+  public static function normalizeTitleString($str) {
+    $str = self::normalizeString($str);
+    return phutil_utf8_strtolower($str);
+  }
+
 }

src/applications/diviner/controller/DivinerFindController.php

@@ -24,14 +24,7 @@ final class DivinerFindController extends DivinerController {
     }
 
     $query = id(new DivinerAtomQuery())
-      ->setViewer($viewer)
-      ->withNames(
-        array(
-          $request->getStr('name'),
-          // TODO: This could probably be more smartly normalized in the DB,
-          // but just fake it for now.
-          phutil_utf8_strtolower($request->getStr('name')),
-        ));
+      ->setViewer($viewer);
 
     if ($book) {
       $query->withBookPHIDs(array($book->getPHID()));
@@ -47,7 +40,23 @@ final class DivinerFindController extends DivinerController {
       $query->withTypes(array($type));
     }
 
-    $atoms = $query->execute();
+    $name_query = clone $query;
+
+    $name_query->withNames(
+      array(
+        $request->getStr('name'),
+        // TODO: This could probably be more smartly normalized in the DB,
+        // but just fake it for now.
+        phutil_utf8_strtolower($request->getStr('name')),
+      ));
+
+    $atoms = $name_query->execute();
+
+    if (!$atoms) {
+      $title_query = clone $query;
+      $title_query->withTitles(array($request->getStr('name')));
+      $atoms = $title_query->execute();
+    }
 
     if (!$atoms) {
       return new Aphront404Response();

src/applications/diviner/query/DivinerAtomQuery.php

@@ -13,6 +13,7 @@ final class DivinerAtomQuery
   private $includeUndocumentable;
   private $includeGhosts;
   private $nodeHashes;
+  private $titles;
 
   private $needAtoms;
   private $needExtends;
@@ -58,6 +59,11 @@ final class DivinerAtomQuery
     return $this;
   }
 
+  public function withTitles($titles) {
+    $this->titles = $titles;
+    return $this;
+  }
+
   public function needAtoms($need) {
     $this->needAtoms = $need;
     return $this;
@@ -287,6 +293,20 @@ final class DivinerAtomQuery
         $this->names);
     }
 
+    if ($this->titles) {
+      $hashes = array();
+      foreach ($this->titles as $title) {
+        $slug = DivinerAtomRef::normalizeTitleString($title);
+        $hash = PhabricatorHash::digestForIndex($slug);
+        $hashes[] = $hash;
+      }
+
+      $where[] = qsprintf(
+        $conn_r,
+        'titleSlugHash in (%Ls)',
+        $hashes);
+    }
+
     if ($this->contexts) {
       $with_null = false;
       $contexts = $this->contexts;

src/applications/diviner/storage/DivinerLiveSymbol.php

@@ -13,6 +13,7 @@ final class DivinerLiveSymbol extends DivinerDAO
   protected $nodeHash;
 
   protected $title;
+  protected $titleSlugHash;
   protected $groupName;
   protected $summary;
   protected $isDocumentable = 0;
@@ -105,6 +106,18 @@ final class DivinerLiveSymbol extends DivinerDAO
     return $title;
   }
 
+  public function setTitle($value) {
+    $this->writeField('title', $value);
+    if (strlen($value)) {
+      $slug = DivinerAtomRef::normalizeTitleString($value);
+      $hash = PhabricatorHash::digestForIndex($slug);
+      $this->titleSlugHash = $hash;
+    } else {
+      $this->titleSlugHash = null;
+    }
+    return $this;
+  }
+
   public function attachExtends(array $extends) {
     assert_instances_of($extends, 'DivinerLiveSymbol');
     $this->extends = $extends;