MNT Standardise package

.editorconfig

@@ -0,0 +1,31 @@
+# For more information about the properties used in
+# this file, please see the EditorConfig documentation:
+# http://editorconfig.org/
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,js,json,css,scss,eslintrc,feature}]
+indent_size = 2
+indent_style = space
+
+[composer.json]
+indent_size = 4
+
+# Don't perform any clean-up on thirdparty files
+
+[thirdparty/**]
+trim_trailing_whitespace = false
+insert_final_newline = false
+
+[admin/thirdparty/**]
+trim_trailing_whitespace = false
+insert_final_newline = false

.gitattributes

@@ -0,0 +1,6 @@
+/.github            export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/phpunit.xml.dist   export-ignore
+/tests              export-ignore
+/.editorconfig      export-ignore

.github/workflows/keepalive.yml

@@ -0,0 +1,17 @@
+name: Keepalive
+
+on:
+  # At 6:30 PM UTC, on day 15 of the month
+  schedule:
+    - cron: '30 18 15 * *'
+  workflow_dispatch:
+
+jobs:
+  keepalive:
+    name: Keepalive
+    # Only run cron on the silverstripe account
+    if: (github.event_name == 'schedule' && github.repository_owner == 'silverstripe') || (github.event_name != 'schedule')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Keepalive
+        uses: silverstripe/gha-keepalive@v1

.github/workflows/merge-up.yml

@@ -0,0 +1,17 @@
+name: Merge-up
+
+on:
+  # At 6:30 PM UTC, only on Sunday
+  schedule:
+    - cron: '30 18 * * 0'
+  workflow_dispatch:
+
+jobs:
+  merge-up:
+    name: Merge-up
+    # Only run cron on the silverstripe account
+    if: (github.event_name == 'schedule' && github.repository_owner == 'silverstripe') || (github.event_name != 'schedule')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Merge-up
+        uses: silverstripe/gha-merge-up@v1

.gitignore

@@ -1,2 +1,2 @@
 /vendor/
-/composer.lock
+/composer.lock

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Silverstripe Limited - www.silverstripe.com
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,52 @@
+# Markdown PHP Codesniffer
 
+A wrapper around [`squizlabs/PHP_CodeSniffer`](https://github.com/squizlabs/PHP_CodeSniffer) which lets you lint PHP fenced code blocks in markdown files.
+
+## Installation
+
+Unlike `squizlabs/PHP_CodeSniffer`, this isn't intended to be installed globally - you should install it as a dev dependency of your project.
+
+```bash
+composer require --dev silverstripe/markdown-php-codesniffer
+```
+
+## Usage
+
+To sniff markdown files, run `mdphpcs` from the vendor bin directory:
+
+```bash
+# sniff a directory
+vendor/bin/mdphpcs /path/to/docs
+
+# sniff a specific file
+vendor/bin/mdphpcs /path/to/docs/file.md
+```
+
+Most of the options available with the `phpcs` and `phpcbf` commands from `squizlabs/PHP_CodeSniffer` are available with `mdphpcs` as well.
+See [PHP_CodeSniffer usage](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage) for more details.
+
+### Fixing violations automatically
+
+Some violations can be fixed automatically, and PHP_CodeSniffer will include information about those in the CLI output. To fix them, simply pass the `--fix` option to `mdphpcs`:
+
+```bash
+vendor/bin/mdphpcs /path/to/docs --fix
+```
+
+This is the equivalent of using the `phpcbf` command on regular PHP files.
+
+### Linting other languages
+
+`squizlabs/PHP_CodeSniffer` supports linting some languages other than PHP. Theoretically that can be done with this tool as well. You'll need to pass the language (as it's written in the markdown language hint) in with the `--linting-language` option.
+
+```bash
+vendor/bin/mdphpcs /path/to/docs --linting-language=JS
+```
+
+### Linting rules
+
+If you have a [default configuration file](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file) or explicitly pass in a standard using the `--standard` option, those rules will be used for linting - but be aware that some rules won't be appropriate for linting code blocks.
+
+For example, the `PSR12.Files.FileHeader.HeaderPosition` rule will always fail linting, because we need to include empty lines prior to the content of the code block in the content we pass to `squizlabs/PHP_CodeSniffer` so it can correctly report the line of each violation in the original markdown file.
+
+If you don't specify a standard and have no default configuration file, the default configuration [included in this package](./phpcs.default.xml) will be used. This configuration is based on PSR12, with some exclusions that make it appropriate for use in linting code blocks.

bin/mdphpcs

@@ -42,7 +42,7 @@ for ($i = 0; $i < $numArgs; $i++) {
         $removeArgs[] = $i;
         $removeArgs[] = $i + 1;
     } elseif (str_starts_with($arg, '--lint-language=')) {
-        $lintLanguage = str_replace('--lint-language=', '', $arg);
+        $lintLanguage = strtoupper(str_replace('--lint-language=', '', $arg));
         $removeArgs[] = $i;
     }
 

composer.json

@@ -1,6 +1,16 @@
 {
     "name": "silverstripe/markdown-php-codesniffer",
+    "description": "A wrapper around squizlabs/PHP_CodeSniffer which lets you lint PHP fenced code blocks in markdown files",
+    "keywords": [
+        "phpcs",
+        "standards",
+        "markdown",
+        "sniffer",
+        "codesniffer"
+    ],
+    "license": "BSD-3-Clause",
     "require": {
+        "php": "^8.0",
         "squizlabs/php_codesniffer": "^3.7",
         "league/commonmark": "^2.4"
     },

phpcs.default.xml

@@ -6,4 +6,4 @@
     <exclude name="PSR12.Files.FileHeader.HeaderPosition"/>
     <exclude name="PSR12.Files.FileHeader.SpacingAfterBlock"/>
  </rule>
-</ruleset>
+</ruleset>

src/Sniffer.php

@@ -48,7 +48,6 @@ public function run(string $lintLanguage, bool $fixing, bool $usingExplicitStand
         $sniffer->reporter = new Reporter($sniffer->config);
 
         // Find all the relevant code blocks for linting
-        // $files = $this->findMarkdownFiles($sniffer->config, $sniffer->ruleset);
         if (PHP_CODESNIFFER_VERBOSITY > 0) {
             echo 'Finding markdown files... ';
         }
@@ -165,7 +164,7 @@ private function findFencedCodeblocks(FileList $paths, string $lintLanguage): ar
         }
 
         $blocks = [];
-        
+
         /** @var string $path */
         foreach ($paths as $path => $v) {
             $document = $this->parser->parse(file_get_contents($path));
@@ -211,7 +210,7 @@ private function findFencedCodeblocks(FileList $paths, string $lintLanguage): ar
 
     /**
      * Run the codesniffing rules over the identified markdown codeblocks
-     * 
+     *
      * This is very nearly a direct copy of Runner::run()
      */
     private function sniff(Runner $sniffer, array $todo): int
@@ -236,7 +235,7 @@ private function sniff(Runner $sniffer, array $todo): int
 
                     $lastDir = $currDir;
                 }
-                
+
                 $sniffer->processFile($block);
             } else if (PHP_CODESNIFFER_VERBOSITY > 0) {
                 echo 'Skipping ' . basename($block->path) . PHP_EOL;