- First PHP_CodeSniffer rule added that checks all files for a valid file doc

  comment as specified in "1.ii. File Header" of the phpBB Coding Guidelines.

git-svn-id: file:///svn/phpbb/trunk@8435 89ea8834-ac86-4346-8a33-228a782c2dd0

5 files changed, 348 insertions, 6 deletions

diff --git a/code_sniffer/Sniffs/Commenting/FileCommentSniff.php b/code_sniffer/Sniffs/Commenting/FileCommentSniff.php
new file mode 100644
index 0000000000..e63c3f65fd
--- /dev/null
+++ b/code_sniffer/Sniffs/Commenting/FileCommentSniff.php
@@ -0,0 +1,210 @@
+<?php
+/** 
+*
+* @package code_sniffer
+* @version $Id: $
+* @copyright (c) 2007 phpBB Group 
+* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
+*
+*/
+
+/**
+* Checks that each source file contains the standard header.
+* 
+* Based on Coding Guidelines 1.ii File Header.
+*
+* @package code_sniffer
+* @author Manuel Pichler <mapi@phpundercontrol.org>
+*/
+class phpbb_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_Sniff
+{
+	/**
+	* Returns an array of tokens this test wants to listen for.
+	*
+	* @return array
+	*/
+	public function register()
+	{
+		return array(T_OPEN_TAG);
+	}
+
+	/**
+	* Processes this test, when one of its tokens is encountered.
+	*
+	* @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
+	* @param int				  $stackPtr  The position of the current token
+	*										in the stack passed in $tokens.
+	*
+	* @return void
+	*/
+	public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
+	{
+		// We are only interested in the first file comment.
+		if ($stackPtr !== 0)
+		{
+			if ($phpcsFile->findPrevious(T_OPEN_TAG, $stackPtr - 1) !== false)
+			{
+                return;
+			}
+		}
+		
+		// Fetch next non whitespace token
+		$tokens = $phpcsFile->getTokens();
+		$start  = $phpcsFile->findNext(T_WHITESPACE, $stackPtr + 1, null, true);
+
+		// Skip empty files
+		if ($tokens[$start]['code'] === T_CLOSE_TAG)
+		{
+			return;
+		}
+		// Mark as error if this is not a doc comment
+		else if ($start === false || $tokens[$start]['code'] !== T_DOC_COMMENT)
+		{
+			$phpcsFile->addError('Missing required file doc comment.', $stackPtr);
+			return;
+		}
+		
+		// Find comment end token
+		$end = $phpcsFile->findNext(T_DOC_COMMENT, $start + 1, null, true) - 1;
+		
+		// If there is no end, skip processing here
+		if ($end === false)
+		{
+			return;
+		}
+		
+		// List of found comment tags
+		$tags = array();
+		
+		// check comment lines without the first(/**) an last(*/) line
+		for ($i = $start + 1, $c = ($end - $start); $i <= $c; ++$i)
+		{
+			$line = $tokens[$i]['content'];
+
+			// Check that each line starts with a '*'
+			if (substr($line, 0, 1) !== '*')
+			{
+                $message = 'The file doc comment should not be idented.';
+				$phpcsFile->addWarning($message, $i);
+			}
+			else if (preg_match('/^\*\s+@([\w]+)\s+(.*)$/', $line, $match) !== 0)
+			{
+				$tags[$match[1]] = array($match[2], $i);
+			}
+		}
+		
+		// Check that the first and last line is empty
+		if (trim($tokens[$start + 1]['content']) !== '*')
+		{
+			$message = 'The first file comment line should be empty.';
+            $phpcsFile->addWarning($message, ($start + 1));			
+		}
+        if (trim($tokens[$end - $start]['content']) !== '*')
+        {
+        	$message = 'The last file comment line should be empty.';
+            $phpcsFile->addWarning($message, ($end - $start));         
+        }
+        
+        $this->processPackage($phpcsFile, $start, $tags);
+        $this->processVersion($phpcsFile, $start, $tags);
+        $this->processCopyright($phpcsFile, $start, $tags);
+        $this->processLicense($phpcsFile, $start, $tags);
+		
+        //print_r($tags);
+	}
+	
+	/**
+	 * Checks that the tags array contains a valid package tag
+	 *
+	 * @param PHP_CodeSniffer_File $phpcsFile The context source file instance.
+	 * @param integer The stack pointer for the first comment token.
+	 * @param array(string=>array) $tags The found file doc comment tags.
+	 * 
+	 * @return void
+	 */
+	protected function processPackage(PHP_CodeSniffer_File $phpcsFile, $ptr, $tags)
+	{
+		if (!isset($tags['package']))
+		{
+			$message = 'Missing require @package tag in file doc comment.';
+			$phpcsFile->addError($message, $ptr);
+		}
+		else if (preg_match('/^([\w]+)$/', $tags['package'][0]) === 0)
+		{
+            $message = 'Invalid content found for @package tag.';
+            $phpcsFile->addWarning($message, $tags['package'][1]);			
+		}
+	}
+	
+	/**
+     * Checks that the tags array contains a valid version tag
+     *
+     * @param PHP_CodeSniffer_File $phpcsFile The context source file instance.
+     * @param integer The stack pointer for the first comment token.
+     * @param array(string=>array) $tags The found file doc comment tags.
+     * 
+     * @return void
+	 */
+	protected function processVersion(PHP_CodeSniffer_File $phpcsFile, $ptr, $tags)
+    {
+        if (!isset($tags['version']))
+        {
+            $message = 'Missing require @version tag in file doc comment.';
+            $phpcsFile->addError($message, $ptr);
+        }
+        else if (preg_match('/^\$Id:[^\$]+\$$/', $tags['version'][0]) === 0)
+        {
+            $message = 'Invalid content found for @version tag, use "$Id: $".';
+            $phpcsFile->addError($message, $tags['version'][1]);            
+        }
+    }
+    
+    /**
+     * Checks that the tags array contains a valid copyright tag
+     *
+     * @param PHP_CodeSniffer_File $phpcsFile The context source file instance.
+     * @param integer The stack pointer for the first comment token.
+     * @param array(string=>array) $tags The found file doc comment tags.
+     * 
+     * @return void
+     */
+    protected function processCopyright(PHP_CodeSniffer_File $phpcsFile, $ptr, $tags)
+    {
+        if (!isset($tags['copyright']))
+        {
+            $message = 'Missing require @copyright tag in file doc comment.';
+            $phpcsFile->addError($message, $ptr);
+        }
+        else if (preg_match('/^\(c\) 2[0-9]{3} phpBB Group\s*$/', $tags['copyright'][0]) === 0)
+        {
+            $message = 'Invalid content found for @copyright tag, use "(c) <year> phpBB Group".';
+            $phpcsFile->addError($message, $tags['copyright'][1]);            
+        }
+    }
+    
+    /**
+     * Checks that the tags array contains a valid license tag
+     *
+     * @param PHP_CodeSniffer_File $phpcsFile The context source file instance.
+     * @param integer The stack pointer for the first comment token.
+     * @param array(string=>array) $tags The found file doc comment tags.
+     * 
+     * @return void
+     */
+    protected function processLicense(PHP_CodeSniffer_File $phpcsFile, $ptr, $tags)
+    {
+    	$license = 'http://opensource.org/licenses/gpl-license.php GNU Public License';
+    	
+        if (!isset($tags['license']))
+        {
+            $message = 'Missing require @license tag in file doc comment.';
+            $phpcsFile->addError($message, $ptr);
+        }
+        else if (trim($tags['license'][0]) !== $license)
+        {
+            $message = 'Invalid content found for @license tag, use ' 
+                     . '"' . $license . '".';
+            $phpcsFile->addError($message, $tags['license'][1]);            
+        }
+    }
+}
\ No newline at end of file
diff --git a/code_sniffer/Tests/Commenting/FileCommentUnitTest.inc b/code_sniffer/Tests/Commenting/FileCommentUnitTest.inc
new file mode 100644
index 0000000000..0ace1c1bda
--- /dev/null
+++ b/code_sniffer/Tests/Commenting/FileCommentUnitTest.inc
@@ -0,0 +1,19 @@
+<?php
+/** 
+*
+* @package code_sniffer³
+* @version $Id: $
+* @copyright (c) 2008 phpBB Group 
+* @license http://opensource.org/licenses/gpl-license.php BSD License
+ *
+*/
+?>
+<?php
+/** 
+* Broken but not first file doc comment.
+* 
+* @version @package_version@
+* @license   http://www.opensource.org/licenses/bsd-license.php  BSD License
+* @copyright (c) 2007 phpBB Group  
+*
+*/
diff --git a/code_sniffer/Tests/Commenting/FileCommentUnitTest.php b/code_sniffer/Tests/Commenting/FileCommentUnitTest.php
new file mode 100644
index 0000000000..849a7fb9a0
--- /dev/null
+++ b/code_sniffer/Tests/Commenting/FileCommentUnitTest.php
@@ -0,0 +1,51 @@
+<?php
+/** 
+*
+* @package code_sniffer
+* @version $Id: $
+* @copyright (c) 2007 phpBB Group 
+* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
+*
+*/
+
+/**
+* Unit test class for the EmptyStatement sniff.
+*
+* @package code_sniffer
+* @author Manuel Pichler <mapi@phpundercontrol.org>
+*/
+class phpbb_Tests_Commenting_FileCommentUnitTest extends AbstractSniffUnitTest
+{
+	
+	/**
+	* Returns the lines where errors should occur.
+	*
+	* The key of the array should represent the line number and the value
+	* should represent the number of errors that should occur on that line.
+	*
+	* @return array(int => int)
+	*/
+	public function getErrorList()
+	{
+		return array(
+            7  =>  1 // BSD License error :)
+		);
+	}//end getErrorList()
+
+
+	/**
+	* Returns the lines where warnings should occur.
+	*
+	* The key of the array should represent the line number and the value
+	* should represent the number of warnings that should occur on that line.
+	*
+	* @return array(int => int)
+	*/
+	public function getWarningList()
+	{
+		return array(
+		    4  =>  1,
+            8  =>  1
+        );
+	}//end getWarningList()
+}
\ No newline at end of file
diff --git a/code_sniffer/build.xml b/code_sniffer/build.xml
index df200bd821..e5d75b5393 100644
--- a/code_sniffer/build.xml
+++ b/code_sniffer/build.xml
@@ -2,8 +2,8 @@
 <project name="code_sniffer" basedir="." default="phpunit">
 
   <property name="cvs.module" value="pear/PHP_CodeSniffer" />
-  <property name="working.dir" value="/tmp/phpcs-test" />
-  <property name="test.coverage" value="/tmp/phpcs-cov" />
+  <property name="working.dir" value="${basedir}/_work/code" />
+  <property name="test.coverage" value="${basedir}/_work/coverage" />
 
   <target name="phpunit" depends="update,prepare">
     <exec executable="phpunit">
@@ -14,15 +14,20 @@
   </target>
 
   <target name="prepare">
-    <delete dir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpBB" />
-    <copy todir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpBB">
+    <delete dir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpbb" />
+  	<mkdir dir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpbb"/>
+  	
+    <copy todir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpbb/Sniffs">
       <fileset dir="${basedir}/Sniffs" />
     </copy>
 
-    <delete dir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpBB/Tests" />
-    <copy todir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpBB/Tests">
+    <copy todir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpbb/Tests">
       <fileset dir="${basedir}/Tests" />
     </copy>
+  	
+  	<copy todir="${working.dir}/${cvs.module}/CodeSniffer/Standards/phpbb">
+  	  <fileset file="${basedir}/phpbbCodingStandard.php" />
+  	</copy>
   </target>
 
   <target name="cleanup">
@@ -41,6 +46,20 @@
          package="${cvs.module}"
          dest="${working.dir}" />
   </target>
+	
+  <!--
+  Installs the sniffs on my local development machine
+  -->
+  <target name="install">
+	<delete dir="/usr/local/pear/PEAR/PHP/CodeSniffer/Standards/phpbb" />
+  	<mkdir dir="/usr/local/pear/PEAR/PHP/CodeSniffer/Standards/phpbb" />
 
+  	<copy todir="/usr/local/pear/PEAR/PHP/CodeSniffer/Standards/phpbb">
+  	  <fileset file="${basedir}/phpbbCodingStandard.php" />
+  	</copy>
+    <copy todir="/usr/local/pear/PEAR/PHP/CodeSniffer/Standards/phpbb/Sniffs">
+      <fileset dir="${basedir}/Sniffs" />
+    </copy>
+  </target>
 
 </project>
diff --git a/code_sniffer/phpbbCodingStandard.php b/code_sniffer/phpbbCodingStandard.php
new file mode 100644
index 0000000000..be51b54b40
--- /dev/null
+++ b/code_sniffer/phpbbCodingStandard.php
@@ -0,0 +1,43 @@
+<?php
+/** 
+*
+* @package code_sniffer
+* @version $Id: $
+* @copyright (c) 2007 phpBB Group 
+* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
+*
+*/
+
+/**
+ * @ignore
+ */
+if (class_exists('PHP_CodeSniffer_Standards_CodingStandard', true) === false) {
+    throw new PHP_CodeSniffer_Exception(
+        'Class PHP_CodeSniffer_Standards_CodingStandard not found'
+    );
+}
+
+/**
+ * Primary class for the phpbb coding standard.
+ *
+ * @package code_sniffer
+ */
+class PHP_CodeSniffer_Standards_phpbb_phpbbCodingStandard extends PHP_CodeSniffer_Standards_CodingStandard
+{
+	/**
+    * Return a list of external sniffs to include with this standard.
+    *
+    * External locations can be single sniffs, a whole directory of sniffs, or
+    * an entire coding standard. Locations start with the standard name. For
+    * example:
+    *  PEAR                              => include all sniffs in this standard
+    *  PEAR/Sniffs/Files                 => include all sniffs in this dir
+    *  PEAR/Sniffs/Files/LineLengthSniff => include this single sniff
+    *
+    * @return array
+    */
+    public function getIncludedSniffs()
+    {
+        return array();
+    }
+}
\ No newline at end of file