Brunobkr/llama.cpp_AlgMor24_github

1# `ast-v8-to-istanbul`2 3[![Version][version-badge]][npm-url]4[![Downloads][downloads-url]][npm-url]5 6> - Speed of V8 coverage 🏎7> - Accuracy of Istanbul coverage 🔍8 9[Ignoring code](#ignoring-code) | [Source maps](#source-maps) | [Istanbul Compatibility](#istanbul-compatibility) | [Limitations](#limitations)10 11---12 13AST-aware [`v8-to-istanbul`](https://www.npmjs.com/package/v8-to-istanbul).14 15Unopinionated - _bring-your-own_ AST parser and source maps.16 17Passes all 195 tests<sup>[*](#istanbul-compatibility)</sup> of [`istanbul-lib-instrument`](https://github.com/istanbuljs/istanbuljs/tree/main/packages/istanbul-lib-instrument/test/specs). ✅18 19Test cases run against:20- `vite/parseAst` ✅21- `acorn` ✅22- `oxc-parser` ✅23- `@babel/parser` ✅24 25See example report at https://ariperkkio.github.io/ast-v8-to-istanbul.26 27```ts28import { convert } from "ast-v8-to-istanbul";29import { parseAstAsync } from "vite";30import type { CoverageMapData } from "istanbul-lib-coverage";31 32const data: CoverageMapData = await convert({33  // Bring-your-own AST parser34  ast: parseAstAsync(<code>),35 36  // Code of the executed file (not the source file)37  code: "function sum(a, b) {\n  return a + b ...",38 39  // Execution wrapper offset40  wrapperLength: 0,41 42  // Script coverage of the executed file43  coverage: {44    scriptId: "123",45    url: "file:///absolute/path/to/dist/index.js",46    functions: [47      {48        functionName: "sum",49        ranges: [{ startOffset: 223, endOffset: 261, count: 0 }],50        isBlockCoverage: false,51      },52      // ... etc53    ],54  },55 56  // Source map of the executed file57  sourceMap: {58    version: 3,59    sources: ["../sources.ts"],60    sourcesContent: ["export function sum(a: number, b: number) {\n..."],61    mappings: ";AAAO,SAAS,...",62    names: [],63  },64});65```66 67## Ignoring code68 69### Ignoring source code70 71#### Ignore hints72 73See live example at https://ariperkkio.github.io/ast-v8-to-istanbul/ignore-examples.html.74 75The typical ignore hints from `nyc` are supported: https://github.com/istanbuljs/nyc?tab=readme-ov-file#parsing-hints-ignoring-lines:76 77> * `/* istanbul ignore if */`: ignore the next if statement.78> * `/* istanbul ignore else */`: ignore the else portion of an if statement.79> * `/* istanbul ignore next */`: ignore the next _thing_ in the source-code (functions, if statements, classes, you name it).80> * `/* istanbul ignore file */`: ignore an entire source-file (this should be placed at the top of the file).81 82In addition to `istanbul` keyword, you can use `v8`, `c8` and `node:coverage`:83 84- `/* istanbul ignore if */`85- `/* v8 ignore else */`86- `/* c8 ignore file */`87- `/* node:coverage ignore next */`88 89Also `start` and `stop` ignore hints from original [`v8-to-istanbul`](https://www.npmjs.com/package/v8-to-istanbul) are supported.90These ignore hints are checked from the original sources instead of transpiled code.91 92> * `/* v8 ignore start */`: start ignoring lines93> * `/* v8 ignore stop */`: stop ignoring lines94> * `<!-- /* v8 ignore start */ -->`: start ignoring lines95> * `<!-- /* v8 ignore stop */ -->`: stop ignoring lines96> * `anything /* v8 ignore start */ anything`: start ignoring lines97> * `anything /* v8 ignore stop */ anything`: stop ignoring lines98 99#### Class methods100 101The `ignore-class-method` from `nyc` is also supported: https://github.com/istanbuljs/nyc?tab=readme-ov-file#ignoring-methods102 103> You can ignore every instance of a method simply by adding its name to the `ignore-class-method` array in your `nyc` config.104 105```ts106import { convert } from "ast-v8-to-istanbul";107 108await convert({109  ignoreClassMethods: ['render']110});111```112 113#### Ignore after remapping114 115You can ignore source code after coverage results have been remapped back to original sources using `ignoreSourceCode`.116This is a high level API that can be exposed to end-users by tooling developers.117 118It's mostly intended for excluding code that is incorrectly shown in coverage report when compilers add generated code in the source maps.119 120Note that as the exclusion happens after remapping, this option is slower than [`ignoreNode`](#ignoring-generated-code) option.121 122```ts123function ignoreSourceCode(124  code: string,125  type: "function" | "statement" | "branch",126  location: Record<"start" | "end", { line: number; column: number }>,127): boolean | void;128```129 130```ts131import { convert } from "ast-v8-to-istanbul";132 133await convert({134  ignoreSourceCode: (code, type, location) => {135    // Ignore all "noop()" calls136    if(type === "function" && code.includes("noop(")) {137      return true;138    }139 140    // In Vue "<script>" tags generate code that is incorrectly left in source maps - exclude it141    if(code === '<script>') {142      return true;143    }144 145    // Ignore anything above line 5146    return location.start.line < 5;147  },148});149```150 151### Ignoring generated code152 153This API is mostly for developers integrating `ast-v8-to-istanbul` with other tooling.154 155If your code transform pipeline is adding generated code that's included in the source maps, it will be included in coverage too.156You can exclude these known patterns by defining `ignoreNode` for filtering such nodes.157 158By returning `"ignore-this-and-nested-nodes"` from the handler, you can ignore all nested nodes too.159This can be useful when you need to ignore everything a certain node wraps, e.g. `IfStatement`.160 161```ts162function ignoreNode(163  node: Node,164  type: "branch" | "function" | "statement"165): boolean | "ignore-this-and-nested-nodes" | void;166```167 168```ts169import { convert } from "ast-v8-to-istanbul";170 171await convert({172  ignoreNode: (node, type) => {173    // Ignore all `await __vite_ssr_import__( ... )` calls that Vite SSR transform adds174    return (175      type === "statement" &&176      node.type === "AwaitExpression" &&177      node.argument.type === "CallExpression" &&178      node.argument.callee.type === "Identifier" &&179      node.argument.callee.name === "__vite_ssr_import__"180    );181  },182});183```184 185## Source maps186 187Source maps are optional and supported by various ways:188 189- Pass directly to `convert` as argument:190  ```ts191  import { convert } from "ast-v8-to-istanbul";192 193  await convert({194    sourceMap: {195      version: 3,196      sources: ["../sources.ts"],197      sourcesContent: ["export function sum(a: number, b: number) {\n..."],198      mappings: ";AAAO,SAAS,...",199      names: [],200    }201  });202  ```203- Include base64 encoded inline maps in `code`:204  ```ts205  await convert({206    code: `\207    function hello() {}208    //# sourceMappingURL=data:application/json;base64,eyJzb3VyY2VzIjpbIi9zb21lL...209    `210  });211  ```212- Include inline maps with filename in `code`:213  ```ts214  await convert({215    code: `\216    function hello() {}217    //# sourceMappingURL=some-file-on-file-system.js.map218    `219  });220  ```221- Don't use source maps at all, and pass original source code in `code`:222  ```ts223  await convert({224    code: `function hello() {}`,225    sourceMap: undefined,226  });227  ```228 229## Istanbul Compatibility230 231This project tests itself against test cases of `istanbul-lib-instrument` and verifies coverage maps are 100% identical. Some cases, like [deprecated `with()` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with) and edge cases of strict mode are skipped, as all tests are run in strict mode.232 233100% istanbul compatibility guarantees that coverage reports between V8 and Istanbul can be merged together.234 235<img src="https://github.com/user-attachments/assets/f74f129c-d63a-403e-8091-aefa53f6f97e" width="400" />236 237## Limitations238 239The way how V8 reports runtime coverage has some limitations when compared to pre-instrumented coverage:240 241- Unable to detect uncovered `AssignmentPattern`'s if line is otherwise covered242  - https://github.com/nodejs/node/issues/57435243 244- Unable to detect uncovered parts when block execution stops due to function throwing:245  - ```js246    function first() {247      throws()248 249      // unreachable, but incorrectly covered250      return "first";251    }252 253    const throws = ()  => { throw new Error() }254 255    try { first(1) } catch {}256    ```257  - ```json258    [259      {260        "ranges": [{ "startOffset": 0, "endOffset": 165, "count": 1 }],261        "isBlockCoverage": true262      },263      {264        "functionName": "first",265        "ranges": [{ "startOffset": 0, "endOffset": 92, "count": 1 }],266        "isBlockCoverage": true267      },268      {269        "functionName": "throws",270        "ranges": [{ "startOffset": 109, "endOffset": 137, "count": 1 }],271        "isBlockCoverage": true272      }273    ]274    ```275 276[version-badge]: https://img.shields.io/npm/v/ast-v8-to-istanbul277[npm-url]: https://www.npmjs.com/package/ast-v8-to-istanbul278[downloads-url]: https://img.shields.io/npm/dm/ast-v8-to-istanbul279