hershel-theodore-layton/portable-hack-ast-linters-server

A non-Hack distribution of PhaLinters to allow HTL packages to use portable-hack-ast-linters without circular dependencies.

v0.0.6 2024-08-11 09:03 UTC

Requires

• hhvm: ^4.128

MIT

README

A non-Hack distribution of PhaLinters to allow HTL packages to use portable-hack-ast-linters without circular dependencies.

How to use

• Optionally install the VSCode extension¹ and configure it in .vscode/settings.json.
  • http://localhost:10641?format=json&action=lint-input is a good default.
• Launch the server using the CLI instructions below.
• Make sure to configure the port is exposed to the host network in Docker.
• Lint the entire project using curl http://localhost:10641.
  • The following query parameters are supported:
    • format=text/vscode-json
      • text (default) output human readable text.
      • vscode-json output json for use with the extension.
    • directories=src,tests
      • A comma separated list of directory names relative to the project root.
      • Only effective when action is lint-all
    • action=lint-all/lint-input
      • lint-all (default) scan all directories for lint errors
      • lint-input lint the Hack source text sent in the request body.
• Lint files interactively by opening them in VSCode with the extension installed.

CLI

This distribution of PhaLinters can be spawned using the vendor/bin/pha-linters-server.sh script. In the examples below $SERVER_SH should expand to the script path above.

# Print help text and exit
$SERVER_SH -h

# Interactive setup, scan for the bundle and prompts you to trust it.
# Hosts the http server on port 10641, or the port specified with `-p`.
$SERVER_SH

# AFK setup which builds and runs the first portable-hack-ast-server-bundle.resource
# Skips the trust prompt, should only be used if you trust every file in the directory.
$SERVER_SH -t

# AFK setup, point $SERVER_SH to a bundle, skips the prompt.
# Recommended setup for CI pipelines
$SERVER_SH -b "vendor/hershel-theodore-layton/portable-hack-ast-server/bin/portable-hack-ast-server-bundle.resource"

When running interactively, you may see the following prompt:

Found the following resource file.
./path/to/portable-hack-ast-linters-server-bundled.resource
If you trust the resource above, type 'I trust this resource' to build and run it.

When you type I trust this resource, you understand the risks involved with compiling and running this resource.

Dependency hacking

This package depends on portable-hack-ast(-linters|-extras) at build time, but the bundled output does not. This bundling process allows portable-hack-ast and portable-hack-ast-extras to use this package without circular dependencies. This is accomplished by publishing an empty composer.json file.

When developing this bundle, you must select the composer file with dependencies. Set the COMPOSER environment variable to composer.dev.json.

COMPOSER=composer.dev.json composer update

This will install the dependencies, whereas composer update without the environment variable set will not install anything.

Developing

Since the bundle can't depend on any unbundled code, for example hhvm-autoload, developing this package requires the ini settinghhvm.autoload.enabled=true. Downstream consumers don't need native autoloading, since the bundle includes all the dependencies in a single file.

When you are testing live (not the bundle itself), you can start the server using:

hhvm -m server -p 8080 -vServer.AllowRunAsRoot=1 -dhhvm.server.global_document=src/main.hack

If you want to test the bundle, use the following command:

./build.sh && bin/pha-linters-server.sh -p 8080 \
-b bin/portable-hack-ast-linters-server-bundled.resource

This will rebuild, recompile and start the lint-server.