From 71c3aff53173cc83a96d7d2715b7918bdbc2d8a5 Mon Sep 17 00:00:00 2001 From: toasted-nutbread Date: Mon, 5 Feb 2024 06:11:08 -0500 Subject: kbn-handlebars dependency update (#613) * Update kbn-handlebars dependency * Move handlebars dependency to dev * Update package * Update readme * Update readme * Ignore legal file --- dev/lib/handlebars.js | 2 +- dev/lib/handlebars/LICENSE | 29 - dev/lib/handlebars/README.md | 165 ---- .../handlebars/__snapshots__/index.test.ts.snap | 91 -- dev/lib/handlebars/index.test.ts | 567 ------------ dev/lib/handlebars/index.ts | 33 - dev/lib/handlebars/jest.config.js | 10 - dev/lib/handlebars/kibana.jsonc | 5 - dev/lib/handlebars/package.json | 6 - .../scripts/check_for_upstream_updates.sh | 45 - dev/lib/handlebars/scripts/print_ast.js | 64 -- .../handlebars/scripts/update_upstream_git_hash.sh | 24 - dev/lib/handlebars/src/__jest__/test_bench.ts | 207 ----- dev/lib/handlebars/src/handlebars.ts | 47 - dev/lib/handlebars/src/spec/.upstream_git_hash | 1 - dev/lib/handlebars/src/spec/index.basic.test.ts | 481 ----------- dev/lib/handlebars/src/spec/index.blocks.test.ts | 366 -------- dev/lib/handlebars/src/spec/index.builtins.test.ts | 676 --------------- dev/lib/handlebars/src/spec/index.compiler.test.ts | 86 -- dev/lib/handlebars/src/spec/index.data.test.ts | 269 ------ dev/lib/handlebars/src/spec/index.helpers.test.ts | 958 --------------------- dev/lib/handlebars/src/spec/index.partials.test.ts | 591 ------------- .../handlebars/src/spec/index.regressions.test.ts | 379 -------- dev/lib/handlebars/src/spec/index.security.test.ts | 132 --- dev/lib/handlebars/src/spec/index.strict.test.ts | 164 ---- .../src/spec/index.subexpressions.test.ts | 214 ----- dev/lib/handlebars/src/spec/index.utils.test.ts | 24 - .../src/spec/index.whitespace_control.test.ts | 88 -- dev/lib/handlebars/src/symbols.ts | 8 - dev/lib/handlebars/src/types.ts | 225 ----- dev/lib/handlebars/src/utils.ts | 69 -- dev/lib/handlebars/src/visitor.ts | 778 ----------------- dev/lib/handlebars/tsconfig.json | 15 - 33 files changed, 1 insertion(+), 6818 deletions(-) delete mode 100644 dev/lib/handlebars/LICENSE delete mode 100644 dev/lib/handlebars/README.md delete mode 100644 dev/lib/handlebars/__snapshots__/index.test.ts.snap delete mode 100644 dev/lib/handlebars/index.test.ts delete mode 100644 dev/lib/handlebars/index.ts delete mode 100644 dev/lib/handlebars/jest.config.js delete mode 100644 dev/lib/handlebars/kibana.jsonc delete mode 100644 dev/lib/handlebars/package.json delete mode 100755 dev/lib/handlebars/scripts/check_for_upstream_updates.sh delete mode 100755 dev/lib/handlebars/scripts/print_ast.js delete mode 100755 dev/lib/handlebars/scripts/update_upstream_git_hash.sh delete mode 100644 dev/lib/handlebars/src/__jest__/test_bench.ts delete mode 100644 dev/lib/handlebars/src/handlebars.ts delete mode 100644 dev/lib/handlebars/src/spec/.upstream_git_hash delete mode 100644 dev/lib/handlebars/src/spec/index.basic.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.blocks.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.builtins.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.compiler.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.data.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.helpers.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.partials.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.regressions.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.security.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.strict.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.subexpressions.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.utils.test.ts delete mode 100644 dev/lib/handlebars/src/spec/index.whitespace_control.test.ts delete mode 100644 dev/lib/handlebars/src/symbols.ts delete mode 100644 dev/lib/handlebars/src/types.ts delete mode 100644 dev/lib/handlebars/src/utils.ts delete mode 100644 dev/lib/handlebars/src/visitor.ts delete mode 100644 dev/lib/handlebars/tsconfig.json (limited to 'dev') diff --git a/dev/lib/handlebars.js b/dev/lib/handlebars.js index c99a3b13..82fa4552 100644 --- a/dev/lib/handlebars.js +++ b/dev/lib/handlebars.js @@ -14,5 +14,5 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ -export {Handlebars} from './handlebars/src/handlebars.js'; +export {Handlebars} from 'yomitan-handlebars/src/handlebars.js'; diff --git a/dev/lib/handlebars/LICENSE b/dev/lib/handlebars/LICENSE deleted file mode 100644 index 5d971a17..00000000 --- a/dev/lib/handlebars/LICENSE +++ /dev/null @@ -1,29 +0,0 @@ -The MIT License (MIT) - -Copyright (c) Elasticsearch BV -Copyright (c) Copyright (C) 2011-2019 by Yehuda Katz - -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. - -This software consists of voluntary contributions made by many -individuals. For exact contribution history, see the revision history -available at the following locations: - - https://github.com/handlebars-lang/handlebars.js - - https://github.com/elastic/kibana/tree/main/packages/kbn-handlebars diff --git a/dev/lib/handlebars/README.md b/dev/lib/handlebars/README.md deleted file mode 100644 index 1ec14ef4..00000000 --- a/dev/lib/handlebars/README.md +++ /dev/null @@ -1,165 +0,0 @@ -# @kbn/handlebars - -A custom version of the handlebars package which, to improve security, does not use `eval` or `new Function`. This means that templates can't be compiled into JavaScript functions in advance and hence, rendering the templates is a lot slower. - -## Limitations - -- Only the following compile options are supported: - - - `data` - - `knownHelpers` - - `knownHelpersOnly` - - `noEscape` - - `strict` - - `assumeObjects` - - `preventIndent` - - `explicitPartialContext` - -- Only the following runtime options are supported: - - `data` - - `helpers` - - `partials` - - `decorators` (not documented in the official Handlebars [runtime options documentation](https://handlebarsjs.com/api-reference/runtime-options.html)) - - `blockParams` (not documented in the official Handlebars [runtime options documentation](https://handlebarsjs.com/api-reference/runtime-options.html)) - -## Implementation differences - -The standard `handlebars` implementation: - -1. When given a template string, e.g. `Hello {{x}}`, return a "render" function which takes an "input" object, e.g. `{ x: 'World' }`. -1. The first time the "render" function is called the following happens: - 1. Turn the template string into an Abstract Syntax Tree (AST). - 1. Convert the AST into a hyper optimized JavaScript function which takes the input object as an argument. - 1. Call the generate JavaScript function with the given "input" object to produce and return the final output string (`Hello World`). -1. Subsequent calls to the "render" function will re-use the already generated JavaScript function. - -The custom `@kbn/handlebars` implementation: - -1. When given a template string, e.g. `Hello {{x}}`, return a "render" function which takes an "input" object, e.g. `{ x: 'World' }`. -1. The first time the "render" function is called the following happens: - 1. Turn the template string into an Abstract Syntax Tree (AST). - 1. Process the AST with the given "input" object to produce and return the final output string (`Hello World`). -1. Subsequent calls to the "render" function will re-use the already generated AST. - -_Note: Not parsing of the template string until the first call to the "render" function is deliberate as it mimics the original `handlebars` implementation. This means that any errors that occur due to an invalid template string will not be thrown until the first call to the "render" function._ - -## Technical details - -The `handlebars` library exposes the API for both [generating the AST](https://github.com/handlebars-lang/handlebars.js/blob/master/docs/compiler-api.md#ast) and walking it by implementing the [Visitor API](https://github.com/handlebars-lang/handlebars.js/blob/master/docs/compiler-api.md#ast-visitor). We can leverage that to our advantage and create our own "render" function, which internally calls this API to generate the AST and then the API to walk the AST. - -The `@kbn/handlebars` implementation of the `Visitor` class implements all the necessary methods called by the parent `Visitor` code when instructed to walk the AST. They all start with an upppercase letter, e.g. `MustacheStatement` or `SubExpression`. We call this class `ElasticHandlebarsVisitor`. - -To parse the template string to an AST representation, we call `Handlebars.parse(templateString)`, which returns an AST object. - -The AST object contains a bunch of nodes, one for each element of the template string, all arranged in a tree-like structure. The root of the AST object is a node of type `Program`. This is a special node, which we do not need to worry about, but each of its direct children has a type named like the method which will be called when the walking algorithm reaches that node, e.g. `ContentStatement` or `BlockStatement`. These are the methods that our `Visitor` implementation implements. - -To instruct our `ElasticHandlebarsVisitor` class to start walking the AST object, we call the `accept()` method inherited from the parent `Visitor` class with the main AST object. The `Visitor` will walk each node in turn that is directly attached to the root `Program` node. For each node it traverses, it will call the matching method in our `ElasticHandlebarsVisitor` class. - -To instruct the `Visitor` code to traverse any child nodes of a given node, our implementation needs to manually call `accept(childNode)`, `acceptArray(arrayOfChildNodes)`, `acceptKey(node, childKeyName)`, or `acceptRequired(node, childKeyName)` from within any of the "node" methods, otherwise the child nodes are ignored. - -### State - -We keep state internally in the `ElasticHandlebarsVisitor` object using the following private properties: - -- `contexts`: An array (stack) of `context` objects. In a simple template this array will always only contain a single element: The main `context` object. In more complicated scenarios, new `context` objects will be pushed and popped to and from the `contexts` stack as needed. -- `output`: An array containing the "rendered" output of each node (normally just one element per node). In the most simple template, this is simply joined together into a the final output string after the AST has been traversed. In more complicated templates, we use this array temporarily to collect parameters to give to helper functions (see the `getParams` function). - -## Testing - -The tests for `@kbn/handlebars` are integrated into the regular test suite of Kibana and are all jest tests. To run them all, simply do: - -```sh -node scripts/jest packages/kbn-handlebars -``` - -By default, each test will run both the original `handlebars` code and the modified `@kbn/handlebars` code to compare if the output of the two are identical. To isolate a test run to just one or the other, you can use the following environment variables: - -- `EVAL=1` - Set to only run the original `handlebars` implementation that uses `eval`. -- `AST=1` - Set to only run the modified `@kbn/handlebars` implementation that doesn't use `eval`. - -## Development - -Some of the tests have been copied from the upstream `handlebars` project and modified to fit our use-case, test-suite, and coding conventions. They are all located under the `packages/kbn-handlebars/src/spec` directory. To check if any of the copied files have received updates upstream that we might want to include in our copies, you can run the following script: - -```sh -./packages/kbn-handlebars/scripts/check_for_upstream_updates.sh -``` - -_Note: This will look for changes in the `4.x` branch of the `handlebars.js` repo only. Changes in the `master` branch are ignored._ - -Once all updates have been manually merged with our versions of the files, run the following script to "lock" us into the new updates: - -```sh -./packages/kbn-handlebars/scripts/update_upstream_git_hash.sh -``` - -This will update file `packages/kbn-handlebars/src/spec/.upstream_git_hash`. Make sure to commit changes to this file as well. - -## Debugging - -### Print AST - -To output the generated AST object structure in a somewhat readable form, use the following script: - -```sh -./packages/kbn-handlebars/scripts/print_ast.js -``` - -Example: - -```sh -./packages/kbn-handlebars/scripts/print_ast.js '{{value}}' -``` - -Output: - -```js -{ - type: 'Program', - body: [ - { - type: 'MustacheStatement', - path: { - type: 'PathExpression', - data: false, - depth: 0, - parts: [ 'value' ], - original: 'value' - }, - params: [], - hash: undefined, - escaped: true - } - ] -} -``` - -By default certain properties will be hidden in the output. -For more control over the output, check out the options by running the script without any arguments. - -### Print generated code - -It's possible to see the generated JavaScript code that `handlebars` create for a given template using the following command line tool: - -```sh -./node_modules/handlebars/print-script