{"id":13495844,"url":"https://github.com/slackhq/tree-sitter-hack","last_synced_at":"2025-08-25T18:50:55.251Z","repository":{"id":37271688,"uuid":"276317942","full_name":"slackhq/tree-sitter-hack","owner":"slackhq","description":"Hack grammar for tree-sitter","archived":false,"fork":false,"pushed_at":"2025-01-22T22:06:29.000Z","size":14838,"stargazers_count":33,"open_issues_count":11,"forks_count":17,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-09T23:05:22.464Z","etag":null,"topics":["hack","hacklang","hhvm","parser","php","tree-sitter"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slackhq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-01T08:13:02.000Z","updated_at":"2025-01-22T22:06:35.000Z","dependencies_parsed_at":"2024-10-14T14:21:13.052Z","dependency_job_id":"e9bc25f3-e8f8-44ca-926b-1de19a883948","html_url":"https://github.com/slackhq/tree-sitter-hack","commit_stats":null,"previous_names":["antoniodejesusochoasolano/tree-sitter-hack"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Ftree-sitter-hack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Ftree-sitter-hack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Ftree-sitter-hack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Ftree-sitter-hack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slackhq","download_url":"https://codeload.github.com/slackhq/tree-sitter-hack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239635518,"owners_count":19672190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hack","hacklang","hhvm","parser","php","tree-sitter"],"created_at":"2024-07-31T19:01:38.826Z","updated_at":"2025-02-19T09:45:27.708Z","avatar_url":"https://github.com/slackhq.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# tree-sitter-hack\n\n![build](https://github.com/slackhq/tree-sitter-hack/actions/workflows/ci.yml/badge.svg)\n\nAt Slack proactively securing our systems is a top priority. One way we achieve this is by automating the detection of vulnerabilities with static code analysis scanning. Although an abundance of tools exist for scanning the majority of programming languages, our codebase is overwhelmingly written in [Hack](https://hacklang.org/) - a language not widely used outside of Slack. Rather than building our own tool from scratch, we are extending the functionality of an open source static analysis tool, [Semgrep](https://github.com/returntocorp/semgrep), to be compatible with Hack. But how do we teach Semgrep the Hack programming language?\n\nLike all human languages, programming languages have a structure to them known as grammar. Grammar rules are used to create a parser which converts source code into a concrete syntax tree (CST) which is a structural representation of the code. [Tree-Sitter](https://github.com/tree-sitter/tree-sitter) is a fast and robust library that can generate a CST from our Hack grammar rules. This CST has many use cases such as robust syntax highlighting, code folding, linting, etc. Most importantly, Semgrep uses this CST to understand Hack on a semantic level. This semantic understanding in conjunction with Semgrep rules can detect vulnerabilities in source code. This process is demonstrated by the following diagram.\n\n![tree-sitter-hack use in Semgrep](diagram.png)\n\nIn summary, we use tree-sitter-hack to teach Semgrep the Hack programming language.\n\n## Installation\n\n```\n$ git clone https://github.com/slackhq/tree-sitter-hack\n$ cd tree-sitter-hack\n$ npm install\n```\n## Usage\n\n```\n$ echo 'function main(): void { print \"wyd, world\\\\n\"; }' \u003e script.hack\n$ npx tree-sitter generate\n$ npx tree-sitter parse script.hack\n(script [0, 0] - [3, 0]\n  (function_declaration [0, 0] - [2, 1]\n    name: (identifier [0, 9] - [0, 13])\n    (parameters [0, 13] - [0, 15])\n    return_type: (primitive_type [0, 17] - [0, 21])\n    body: (compound_statement [0, 22] - [2, 1]\n      (expression_statement [1, 2] - [1, 23]\n        (print_expression [1, 2] - [1, 22]\n          (string [1, 8] - [1, 22]))))))\n```\n\n## Testing\n```\n$ npx tree-sitter generate\n$ bin/test-corpus\n```\n\n## Scripts\n\n**`bin/generate-parser`**\n\nWrapper around `tree-sitter generate` that skips parser generation if `grammar.js` hasn't changed since last run.\n\n**`bin/generate-corpus`**\n\nUnlike most other Tree-sitter projects, we breakout test cases into separate files (see [`test/cases`](test/cases)). This is done so editors have an easier time syntax highlighting test cases. But also I find individual files easier to navigate than the `corpus.txt` files used by Tree-sitter.\n\nWe use `bin/generate-corpus` to generate the `test/corpus/case1.txt` from individual `test/cases` files so we can still use `tree-sitter test`.\n\n**`bin/test-corpus`**\n\nRun `bin/generate-corpus` and `bin/generate-parser` before running `tree-sitter test`.\n\n**`bin/test-dir`**\n\nRun `bin/ts-errors` on all files with `.hack` or `.php` extension in the given directory recursively.\n\n```\n$ ./bin/test-dir hhvm/hphp/hack/test\nexamples/hhvm/hphp/hack/test/error_formatting_highlighted/zero_width_syntax_err.php\n(3,11)-(3,18) extends\nexamples/hhvm/hphp/hack/test/autocomplete/not_shape_key_string.php\n(3,1)-(6,1) function foo(): string {\\n  return \"AUTO332\\n}\\n\n(4,10)-(6,1) \"AUTO332\\n}\\n\n...\n```\n\n**`bin/test-dir-quiet`**\n\nA quieter version of `bin/test-dir` that only outputs failing files.\n\n## Contributing\n\nIf you're interested in contributing, please see the [guide](.github/CONTRIBUTING.md).\n\n## Note\n\nnpm doesn't allow packages with the word \"hack\" in their registry which is why the repo\nname does not match the package name.\n\n\u003e Unfortunately, the word \"hack\" triggers our spam detection and can't be used in package names. We recommend choosing other keywords that highlight your package's functionality.\n\n## References\n\nThere's no published official Hacklang language spec so we have to make do.\n\n- [HHVM Blog](https://hhvm.com/blog/) - Good source of language [deprecations](https://hhvm.com/blog/2019/10/01/deprecating-references.html) and [changes](https://hhvm.com/blog/2020/07/06/hhvm-4.65.html#breaking-changes).\n- [Hack Documentation](https://docs.hhvm.com/hack/) - Source at [hhvm/user-documentation](https://github.com/hhvm/user-documentation).\n- [Hack Parser Source](https://github.com/facebook/hhvm/tree/4da98da2f5ddc0989d3d150dddc1b06ee4087440/hphp/hack/src/parser)\n- [tree-sitter-javascript](https://github.com/tree-sitter/tree-sitter-javascript) and [tree-sitter-php](https://github.com/tree-sitter/tree-sitter-php) - Used to guide writing [`grammar.js`](grammar.js)\n- Deprecated [Hack Language Specification](https://github.com/facebookarchive/hack-langspec)\n- [PHP Language Specification](https://github.com/php/php-langspec) -\n  Does not apply 100% to Hacklang, but still a good reference.\n- Bug icon in diagram made by Freepik\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslackhq%2Ftree-sitter-hack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslackhq%2Ftree-sitter-hack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslackhq%2Ftree-sitter-hack/lists"}