platformos-check 0.0.1

data/CONTRIBUTING.md

@@ -0,0 +1,209 @@
+# Contributing to platformOS Check
+
+## Standards
+
+* Checks should do one thing, and do it well.
+* PR should explain what the feature does, and why the change exists.
+* PR should include any carrier specific documentation explaining how it works.
+* Code _must_ be tested.
+* Be consistent. Write clean code that follows [Ruby community standards](https://github.com/bbatsov/ruby-style-guide).
+* Code should be generic and reusable.
+
+## How to contribute
+
+1. Fork it ( https://github.com/Platform-OS/platformos-lsp )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Run Language Server
+
+If you're making changes to the language server and you want to debug, you can run the repo's version of `platformos-check-language-server`.
+
+### Setup
+
+Before configuring your IDE, run the following commands in a terminal:
+
+  * Make sure you have a `$HOME/bin`
+      ```bash
+      mkdir -p $HOME/bin
+      ```
+  * Paste this script to create an executable wrapper in `$HOME/bin/platformos-check-language-server` for language server
+      ```bash
+      cat <<-'EOF' > $HOME/bin/platformos-check-language-server
+      #!/usr/bin/env bash
+      cd "$HOME/src/github.com/Platform-OS/platformos-lsp" &> /dev/null
+      export PLATFORMOS_CHECK_DEBUG=true
+      export PLATFORMOS_CHECK_DEBUG_LOG_FILE="/tmp/platformos-check-debug.log"
+      touch "$PLATFORMOS_CHECK_DEBUG_LOG_FILE"
+      gem env &>/dev/null
+      bundle install &>/dev/null
+      bin/platformos-check-language-server
+      EOF
+      ```
+  * Make the script executable
+      ```bash
+      chmod u+x $HOME/bin/platformos-check-language-server
+      ```
+
+#### Configure VS Code
+
+1. Download provided .vsix file
+2. Install it manually via View -> Extensions -> ... -> Install from VSIX
+3. Configure settings.json
+
+```
+"platformosCheck.checkOnChange": true,
+"platformosCheck.onlySingleFileChecks": false,
+"platformOSLiquid.languageServerPath": "/Users/<your user>/bin/platformos-check-language-server",
+"platformosCheck.checkOnOpen": true,
+"platformosCheck.checkOnSave": true
+```
+
+#### Configure Vim
+
+If you use `coc.nvim` as your completion engine, add this to your CocConfig:
+
+```json
+{
+  "languageserver": {
+    "platformos-check": {
+      "command": "/Users/<YOUR_USERNAME>/bin/platformos-check-language-server",
+      "trace.server": "verbose",
+      "filetypes": ["liquid", "graphql", "yaml", "yml"],
+      "rootPatterns": [".platformos-check.yml", ".pos"],
+      "settings": {
+        "platformosCheck": {
+          "checkOnSave": true,
+          "checkEnter": true,
+          "onlySingleFileChecks": false,
+          "checkOnChange": true,
+          "checkOnOpen": true
+        }
+      }
+    }
+  }
+}
+
+```
+
+### Confirm Setup
+
+* In another terminal from the root of theme check run `tail -f /tmp/platformos-check-debug.log` to watch the server logs
+* Restart your IDE, confirm the response for initialize in the logs is pointing to the language server in the `$HOME/bin` directory (the version will be different)
+
+```json
+    "serverInfo": {
+        "name": "/Users/johndoe/bin/platformos-check-language-server",
+        "version": "1.10.3"
+    }
+```
+
+
+## Running Tests
+
+```
+bundle install
+bundle exec rake
+```
+
+## Checking a pOS app
+
+```
+bin/platformos-check /path/to/your/app
+```
+
+## Creating a new "Check"
+
+Run `bundle exec rake "new_check[MyNewCheckName]"` to generate all the files required to create a new check.
+
+Check the [Check API](/docs/api/check.md) for how to implement a check. Also take a look at other checks in [lib/platformos_check/checks](/lib/platformos_check/checks).
+
+We done implementing your check, add it to `config/default.yml` to enable it:
+
+```yaml
+MyNewCheckName:
+  enabled: true
+  ignore: []
+```
+
+If the check is configurable, the `initialize` argument names and default values should also be duplicated inside `config/default.yml`. eg.:
+
+```ruby
+class MyCheckName < LiquidCheck
+  def initialize(muffin_mode: true)
+    @muffin_mode = muffin_mode
+  end
+  # ...
+end
+```
+
+```yaml
+MyNewCheckName:
+  enabled: true
+  ignore: []
+  muffin_mode: true
+```
+
+## Debugging
+
+A couple of things are turned on when the `PLATFORMOS_CHECK_DEBUG` environment variable is set.
+
+1. The check timeout is turned off. This means you can add `binding.pry` in tests and properly debug with `bundle exec rake tests:in_memory`
+2. The `--profile` flag appears. You can now create Flamegraphs to inspect performance.
+
+```
+export PLATFORMOS_CHECK_DEBUG=true
+
+# The following will behave slightly differently
+bin/platformos-check ../dawn
+bundle exec rake tests:in_memory
+
+# The following becomes available
+bin/platformos-check --profile ../dawn
+
+# The LanguageServer will log the JSONRPC calls to STDERR
+bin/platformos-check-language-server
+```
+
+### Profiling
+
+`ruby-prof` and `ruby-prof-flamegraph` are both included as development dependencies.
+
+#### Flamegraph
+
+With the `--profile` flag, you can run platformos-check on a theme and the `ruby-prof-flamegraph` printer will output profiling information in a format [Flamegraph](/brendangregg/FlameGraph) understands.
+
+
+**Setup:**
+
+```bash
+# clone the FlameGraph repo somewhere
+git clone https://github.com/brendangregg/FlameGraph.git
+
+# the flamegraph.pl perl script is in that repo
+alias flamegraph=/path/to/FlameGraph/flamegraph.pl
+```
+
+**Profiling:**
+
+```
+# run platformos-check with --profile
+# pass the output to flamegraph
+# dump the output into an svg file
+bin/platformos-check --profile ../dawn \
+  | flamegraph --countname=ms --width=1750 \
+  > /tmp/fg.svg
+
+# open the svg file in Chrome to look at the flamegraph
+chrome /tmp/fg.svg
+```
+
+What you'll see is an interactive version of the following image:
+
+![flamegraph](docs/flamegraph.svg)
+
+## Troubleshooting
+
+If you run into issues during development, see the [troubleshooting guide](/TROUBLESHOOTING.md)

data/Gemfile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in platformos-check.gemspec
+gemspec
+
+gem 'bundler'
+gem 'graphql'
+gem 'rake'
+
+group :test do
+  gem 'debug'
+  gem 'minitest'
+  gem 'minitest-focus'
+  gem 'mocha'
+  gem 'pry-byebug'
+end
+
+group :development do
+  gem 'guard'
+  gem 'guard-minitest'
+  gem 'ruby-prof'
+  gem 'ruby-prof-flamegraph'
+  gem 'solargraph'
+end
+
+gem 'rubocop', require: false
+gem 'rubocop-minitest', require: false
+gem 'rubocop-performance', require: false
+gem 'rubocop-rake', require: false

data/Guardfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+guard :minitest do
+  watch(%r{^test/(.*)_test.rb$})
+  watch(%r{^lib/platformos_check/(.*)\.rb$}) { |m| "test/#{m[1]}_test.rb" }
+  watch(%r{^test/test_helper\.rb$}) { 'test' }
+end

data/LICENSE.md

@@ -0,0 +1,10 @@
+
+Copyright 2023-present, platformOS.
+
+Contains code from activesupport Copyright (c) 2005-2019 David Heinemeier Hansson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Makefile

@@ -0,0 +1,18 @@
+IMAGE_NAMES := lsp check
+BUILD_TARGETS := $(patsubst %,build-%,$(IMAGE_NAMES))
+PUSH_TARGETS := $(patsubst %,push-%,$(IMAGE_NAMES))
+
+VERSION=0.0.1
+
+IMAGE_NAME=platformos/platformos
+
+build: $(BUILD_TARGETS)
+build-%:
+	docker build -t ${IMAGE_NAME}-$*:${VERSION} -f docker/$*.Dockerfile .
+	docker tag ${IMAGE_NAME}-$*:${VERSION} ${IMAGE_NAME}-$*:latest
+
+push: $(PUSH_TARGETS)
+push-%:
+	docker push ${IMAGE_NAME}-$*:${VERSION}
+	docker push ${IMAGE_NAME}-$*:latest
+

data/README.md

@@ -0,0 +1,189 @@
+# platformOS Check ✅ - A linter for platformOS
+
+PlatformOS Check is a tool that helps you follow platformOS recommendations & best practices by analyzing the Liquid inside your app.
+
+![](docs/preview.png)
+
+## Supported Checks
+
+PlatformOS Check currently checks for the following:
+
+✅ Liquid syntax errors
+✅ JSON syntax errors
+✅ Missing snippet & section templates
+✅ Unused `{% assign ... %}`
+✅ Unused snippet templates
+✅ Template length
+✅ Deprecated tags
+✅ Unknown tags
+✅ Unknown filters
+✅ Missing or extra spaces inside `{% ... %}` and `{{ ... }}`
+✅ Using several `{% ... %}` instead of `{% liquid ... %}`
+✅ Undefined objects
+✅ Deprecated filters
+✅ Missing `platformos-check-enable` comment
+
+As well as checks that prevent easy to spot performance problems:
+
+✅ Use of [parser-blocking](/docs/checks/parser_blocking_javascript.md) JavaScript
+✅ [Use of non-platformOS domains for assets](/docs/checks/remote_asset.md)
+✅ [Missing width and height attributes on `img` tags](/docs/checks/img_width_and_height.md)
+✅ [Too much JavaScript](/docs/checks/asset_size_javascript.md)
+✅ [Too much CSS](/docs/checks/asset_size_css.md)
+
+For detailed descriptions and configuration options, [take a look at the complete list.](/docs/checks/)
+
+With more to come! Suggestions welcome ([create an issue](https://github.com/Platform-OS/platformos-lsp/issues)).
+
+## Installation
+
+- download and install the extension [more]
+- next steps
+  -> [using-local-ruby]
+  -> [docker]
+
+### Using locally installed ruby
+
+#### Requirements
+
+- Ruby 3.2+
+
+TODO
+
+### Using Docker
+
+#### PlatformOS Check Language Server
+
+- Create an executable `platformos-check-language-server` file and place it within a directory listed in your $PATH variable.
+
+```bash
+DIR=$(pwd)
+IMAGE_NAME=platformos/platformos-lsp:latest
+
+LOG_DIR=$DIR/logs
+mkdir $LOG_DIR
+LOG_FILE=$LOG_DIR/platformos-lsp.log
+
+exec docker run -i \
+  -v $DIR:$DIR \
+  -w $DIR \
+  -e PLATFORMOS_CHECK_DEBUG=true \
+  -e PLATFORMOS_CHECK_DEBUG_LOG_FILE=$LOG_FILE \
+   $IMAGE_NAME
+```
+This script will automatically download the latest Docker image and initiate a language server. Visual Studio Code (VSC) manages this process automatically. However, you can run the script for verification if needed."
+
+#### Troubleshooting
+
+- In the event of `onlySingleFileChecks: true` not functioning as expected, please examine your Visual Studio Code (VSC) workspace. Ensure that the workspace contains only a single project.
+
+#### PlatformOS Check
+
+PlatformOS Check can be used also as a standalone function. Prepare the following executable script:
+
+```bash
+DIR=$(pwd)
+IMAGE_NAME=platformos/platformos-check:latest
+
+LOG_DIR=$DIR/logs
+mkdir $LOG_DIR
+LOG_FILE=$LOG_DIR/platformos-check.log
+
+exec docker run -i \
+  -v $DIR:$DIR \
+  -w $DIR \
+  -e PLATFORMOS_CHECK_DEBUG=true \
+  -e PLATFORMOS_CHECK_DEBUG_LOG_FILE=$LOG_FILE \
+   $IMAGE_NAME
+```
+
+## Configuration
+
+Add a `.platformos-check.yml` file at the root of your app.
+
+See [config/default.yml](config/default.yml) for available options & defaults.
+
+## Disable checks with comments
+
+Use Liquid comments to disable and re-enable all checks for a section of your file:
+
+```liquid
+{% # platformos-check-disable %}
+{% assign x = 1 %}
+{% # platformos-check-enable %}
+```
+
+Disable a specific check by including it in the comment:
+
+```liquid
+{% # platformos-check-disable UnusedAssign %}
+{% assign x = 1 %}
+{% # platformos-check-enable UnusedAssign %}
+```
+
+Disable multiple checks by including them as a comma-separated list:
+
+```liquid
+{% # platformos-check-disable UnusedAssign,SpaceInsideBraces %}
+{%assign x = 1%}
+{% # platformos-check-enable UnusedAssign,SpaceInsideBraces %}
+```
+
+Disable checks for the _entire document_ by placing the comment on the first line:
+
+```liquid
+{% # platformos-check-disable SpaceInsideBraces %}
+{%assign x = 1%}
+```
+
+## Exit Code and `--fail-level`
+
+Use the `--fail-level` (default: `error`) flag to configure the exit code of platformos-check. Useful in CI scenarios.
+
+Example:
+
+```
+# Make CI fail on styles warnings, suggestions, and errors
+platformos-check --fail-level style path_to_app
+
+# Make CI fail on suggestions, and errors
+platformos-check --fail-level suggestion path_to_app
+
+# Make CI fail on errors
+platformos-check path_to_app
+```
+
+There are three fail levels:
+
+- `error`
+- `suggestion`
+- `style`
+
+Exit code meanings:
+
+- 0: Success!
+- 1: Your code doesn't pass the checks
+- 2: There's a bug in platformos-check
+
+If you would like to change the severity of a check, you can do so with the `severity` attribute. Example:
+
+```yaml
+DeprecateLazysizes:
+  enabled: true
+  severity: error
+```
+
+## Language Server Configurations
+
+- `platformosCheck.checkOnOpen` (default: `true`) makes it so theme check runs on file open.
+- `platformosCheck.checkOnChange` (default: `true`) makes it so theme check runs on file change.
+- `platformosCheck.checkOnSave` (default: `true`) makes it so theme check runs on file save.
+- `platformosCheck.onlySingleFileChecks` (default: `false`) makes it so we only check the opened files and disable "whole theme" checks (e.g. UnusedPartial, TranslationKeyExists)
+
+⚠️ **Note:** Quickfixes only work on a freshly checked file. If any of those configurations are turned off, you will need to rerun platformos-check in order to apply quickfixes.
+
+In VS Code, these can be set directly in your `settings.json`.
+
+## Contributing
+
+For guidance on contributing, refer to this [doc](/CONTRIBUTING.md)

data/RELEASING.md

@@ -0,0 +1,35 @@
+## Releasing platformOS Check
+
+1. Check the Semantic Versioning page for info on how to version the new release: http://semver.org
+
+2. Run the following command to update the version in `lib/platformos_check/version.rb` and replace the `PLATFORMOS_CHECK_VERSION` placeholder in the documentation for new rules:
+
+   ```bash
+   VERSION="X.X.X"
+   rake prerelease[$VERSION]
+   ```
+
+3. Run [`git changelog`](https://github.com/tj/git-extras) to update `CHANGELOG.md`.
+
+4. Commit your changes and make a PR.
+
+   ```bash
+   git checkout -b "bump/platformos-check-$VERSION"
+   git add docs/checks CHANGELOG.md lib/platformos_check/version.rb
+   git commit -m "Bump platformos-check version to $VERSION"
+   hub compare "main:bump/platformos-check-$VERSION"
+   ```
+
+5. Merge your PR to main.
+
+6. [Create a GitHub release](https://github.com/Platform-OS/platformos-lsp/releases/new) for the change.
+
+   ```
+   VERSION=v1.X.Y
+   git fetch origin
+   git fetch origin --tags
+   git reset origin $VERSION
+   gh release create -t $VERSION
+   ```
+
+   (It's a good idea to copy parts of the CHANGELOG in there)

data/Rakefile

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "rubocop/rake_task"
+require "bundler/gem_tasks"
+
+namespace :tests do
+  task all: %i[in_memory file_system]
+
+  Rake::TestTask.new(:suite) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/**/*_test.rb"]
+  end
+
+  desc("Runs the tests with InMemoryStorage")
+  task :in_memory do
+    ENV["THEME_STORAGE"] = 'InMemoryStorage'
+    puts "Running tests with #{ENV.fetch('THEME_STORAGE', nil)}"
+    Rake::Task['tests:suite'].execute
+  end
+
+  desc("Runs the tests with FileSystemStorage")
+  task :file_system do
+    ENV["THEME_STORAGE"] = 'FileSystemStorage'
+    puts "Running tests with #{ENV.fetch('THEME_STORAGE', nil)}"
+    Rake::Task['tests:suite'].execute
+  end
+end
+
+desc("Runs all tests")
+task(test: 'tests:all')
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+
+desc("Builds all distribution packages of the CLI")
+task(package: 'package:all')
+
+desc("Update files in the repo to match new version")
+task :prerelease, [:version] do |_t, args|
+  require 'platformos_check/releaser'
+  PlatformosCheck::Releaser.new.release(args.version)
+end
+
+desc("Download theme-liquid-docs")
+task :download_theme_liquid_docs do
+  require 'platformos_check/platformos_liquid/source_manager'
+
+  PlatformosCheck::PlatformosLiquid::SourceManager.download
+end
+
+desc "Create a new check"
+task :new_check, [:name] do |_t, args|
+  require "platformos_check/string_helpers"
+  class_name = args.name
+  base_name = PlatformosCheck::StringHelpers.underscore(class_name)
+  code_source = "lib/platformos_check/checks/#{base_name}.rb"
+  doc_source = "docs/checks/#{base_name}.md"
+  test_source = "test/checks/#{base_name}_test.rb"
+  erb(
+    "lib/platformos_check/checks/TEMPLATE.rb.erb", code_source,
+    class_name:
+  )
+  erb(
+    "test/checks/TEMPLATE.rb.erb", test_source,
+    class_name:
+  )
+  erb(
+    "docs/checks/TEMPLATE.md.erb", doc_source,
+    class_name:,
+    code_source:,
+    doc_source:
+  )
+  sh "bundle exec ruby -Itest #{test_source}"
+end
+
+def erb(file, to, **args)
+  require "erb"
+  File.write(to, ERB.new(File.read(file)).result_with_hash(args))
+  puts "Generated #{to}"
+end

data/TROUBLESHOOTING.md

@@ -0,0 +1,35 @@
+# Troubleshooting
+
+## Issues with Language Server
+
+### Language server erroring out on startup
+
+The following error can cause language server to crash:
+```bash
+Calling `DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated. Please call `DidYouMean.correct_error(error_name, spell_checker)' instead.
+/Users/johndoe/.gem/ruby/3.1.2/gems/bundler-2.2.22/lib/bundler/spec_set.rb:91:in `block in materialize': Could not find ruby-prof-0.18.0 in any of the sources (Bundler::GemNotFound)
+```
+
+Confirm the version of platformos-check matches the version in the wrapper in `~/bin/platformos-check-language-server`. If it doesn't match the ruby version, run the following from the platformos-check directory:
+
+```bash
+chruby 3.1.2 #your `~/bin/platformos-check-language-server` ruby version
+bundle install
+```
+
+### Language server sends an `initialize()` request to the client and stops
+
+To debug, confirm these steps are included in your local language server startup script:
+
+```bash
+export PLATFORMOS_CHECK_DEBUG=true
+export PLATFORMOS_CHECK_DEBUG_LOG_FILE="/tmp/platformos-check-debug.log"
+touch "$PLATFORMOS_CHECK_DEBUG_LOG_FILE"
+```
+
+An example script can be found [here](/CONTRIBUTING.md#run-language-server).
+
+Open `/tmp/platformos-check-debug.log` in your IDE. Check if there are any exceptions being raised by language server.
+
+If there are no exceptions, check if there are any logs that aren't in jsonrpc. The language server and client use stdin and stdout to communicate using jsonrpc. Debugging statements that aren't in a jsonrpc format might trigger unexpected behavior (this includes any logs from language server or echo statements in your language server script).
+

data/bin/platformos-check

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'platformos-check' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("platformos-check", "platformos-check")

data/bin/platformos-check-language-server

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'platformos-check-language-server' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("platformos-check", "platformos-check-language-server")