Introduce a more subtle concept of validity when it comes to revision

indentifiers in IDF - the SCM function isValidRevision has been replaced
by a validateRevision() method which returns one of three states,
valid, invalid or ambiguous.
The source view can then act accordingly and display disambiguate view
for the latter, so the user can select for which revision he actually
wants to execute the requested action. Also, invalid revisions now lead
to another separate view, telling the user that it is invalid / does
not exist and pointing him optionally to the help page where he can read
further how to access his repository to push the first changes into.
(partially resolves issue 525)

src/IDF/Scm/Git.php

@@ -296,10 +296,12 @@ class IDF_Scm_Git extends IDF_Scm
     }
 
 
-    public function isValidRevision($commit)
+    public function validateRevision($commit)
     {
         $type = $this->testHash($commit);
-        return ('commit' == $type || 'tag' == $type);
+        if ('commit' == $type || 'tag' == $type)
+            return IDF_Scm::REVISION_VALID;
+        return IDF_Scm::REVISION_INVALID;
     }
 
     /**

src/IDF/Scm/Mercurial.php

@@ -87,14 +87,19 @@ class IDF_Scm_Mercurial extends IDF_Scm
         return sprintf(Pluf::f('mercurial_remote_url'), $project->shortname);
     }
 
-    public function isValidRevision($rev)
+    public function validateRevision($rev)
     {
         $cmd = sprintf(Pluf::f('hg_path', 'hg').' log -R %s -r %s',
                        escapeshellarg($this->repo),
                        escapeshellarg($rev));
         $cmd = Pluf::f('idf_exec_cmd_prefix', '').$cmd;
         self::exec('IDF_Scm_Mercurial::isValidRevision', $cmd, $out, $ret);
-        return ($ret == 0) && (count($out) > 0);
+
+        // FIXME: apparently a given hg revision can also be ambigious -
+        //        handle this case here sometime
+        if ($ret == 0 && count($out) > 0)
+            return IDF_Scm::REVISION_VALID;
+        return IDF_Scm::REVISION_INVALID;
     }
 
     /**

src/IDF/Scm/Monotone.php

@@ -425,12 +425,53 @@ class IDF_Scm_Monotone extends IDF_Scm
     }
 
     /**
-     * @see IDF_Scm::isValidRevision()
+     * @see IDF_Scm::validateRevision()
      */
-    public function isValidRevision($commit)
+    public function validateRevision($commit)
     {
         $revs = $this->_resolveSelector($commit);
-        return count($revs) == 1;
+        if (count($revs) == 0)
+            return IDF_Scm::REVISION_INVALID;
+
+        if (count($revs) > 1)
+            return IDF_Scm::REVISION_AMBIGUOUS;
+
+        return IDF_Scm::REVISION_VALID;
+    }
+
+    /**
+     * @see IDF_Scm::disambiguateRevision
+     */
+    public function disambiguateRevision($commit)
+    {
+        $revs = $this->_resolveSelector($commit);
+
+        $out = array();
+        foreach ($revs as $rev)
+        {
+            $certs = $this->_getCerts($rev);
+
+            $log = array();
+            $log['author'] = implode(', ', $certs['author']);
+
+            $log['branch'] = implode(', ', $certs['branch']);
+
+            $dates = array();
+            foreach ($certs['date'] as $date)
+                $dates[] = date('Y-m-d H:i:s', strtotime($date));
+            $log['date'] = implode(', ', $dates);
+
+            $combinedChangelog = implode("\n---\n", $certs['changelog']);
+            $split = preg_split("/[\n\r]/", $combinedChangelog, 2);
+            $log['title'] = $split[0];
+            $log['full_message'] = (isset($split[1])) ? trim($split[1]) : '';
+
+            $log['commit'] = $rev;
+
+            $out[] = (object)$log;
+        }
+
+        return $out;
     }
 
     /**
@@ -630,7 +671,7 @@ class IDF_Scm_Monotone extends IDF_Scm
                 --$n;
 
                 $log = array();
-                $log['author'] = implode(", ", $certs['author']);
+                $log['author'] = implode(', ', $certs['author']);
 
                 $dates = array();
                 foreach ($certs['date'] as $date)

src/IDF/Scm/Svn.php

@@ -138,7 +138,7 @@ class IDF_Scm_Svn extends IDF_Scm
     /**
      * Subversion revisions are either a number or 'HEAD'.
      */
-    public function isValidRevision($rev)
+    public function validateRevision($rev)
     {
         if ($rev == 'HEAD') {
             return true;
@@ -149,8 +149,11 @@ class IDF_Scm_Svn extends IDF_Scm
                        escapeshellarg($this->repo),
                        escapeshellarg($rev));
         $cmd = Pluf::f('idf_exec_cmd_prefix', '').$cmd;
-        self::exec('IDF_Scm_Svn::isValidRevision', $cmd, $out, $ret);
-        return (0 == $ret);
+        self::exec('IDF_Scm_Svn::validateRevision', $cmd, $out, $ret);
+
+        if ($ret == 0)
+            return IDF_Scm::REVISION_VALID;
+        return IDF_Scm::REVISION_INVALID;
     }