@exercism/static-analysis
    TypeScript icon, indicating that this package has built-in type declarations

    0.11.0 • Public • Published

    @exercism/static-analysis

    You can use AstExplorer to preview the output of the parser.

    Installation

    You need at least Node 12.x in order to maintain or use this library. This is due to the fact that babel is configured to polyfill as if you're running Node 12.x or higher. jest will fail to run the tests if you run a lower node, and some of the code might not be transpiled correctly. If you MUST use this library in conjunction with a lower Node version, ensure to re-transpile this module.

    Add this library to your project in package.json, for example via:

    yarn add @exercism/static-analysis
    

    Usage

    Note: all types such as Node are not imported from 'typescript', but rather from '@typescript-eslint/typescript-estree' in order to increase compatibility with tooling and normalisation of the output tree. Types such as Node all live on a single export from that package called TSESTree.

    In order to perform statical analysis on estree compatible languages (such as JavaScript or TypeScript), a source first needs to be parsed. This can be accomplished using the AstParser:

    import { AstParser } from '@exercism/statis-analysis/dist/AstParser'
    import { InlineInput } from '@exercism/static-analysis/dist/input/InlineInput'
    
    const input = new InlineInput(['const topLevel = 42;'])
    const [{ program, source }] = await AstParser.ANALYZER.parse(input)

    Any compatible Input works, made available to you are:

    • FileInput which takes a file path
    • DirectoryInput which takes a directory, and uses the TrackOptions to filter them out
    • InlineInput which takes inline string(s) as source(s)

    By default, the AstParser will only parse a single file, but it's possible to parse as many files as necessary. In the case of DirectoryInput, it will search for the most applicable file, based on the TrackOptions.

    Parsers

    The parsers with recommended configuration for certain jobs are assigned as static properties.

    • AstParser.ANALYZER: Holds a parser that is recommended for analysis. This means that it dóés hold locational information (in order to be able to extract tokens), but does not hold any commentary. You can extractSource code using this parser.
    • AstParser.REPRESENTER: Holds a parser that is recommended for representing. This means that it does not hold locational information (where differences are caused by whitespace differences) or commentary. You cannot extractSource code using this parser.
    • new AstParser(options, n): Setup your own parser, which also allows to parse more than one file by changing the n variable.

    Guards

    Guards are named helpers that also work as type guards. You can find them here, and they are imported like this:

    import { guardIdentifier } from '@exercism/statis-analysis'
    import { guardLiteral } from '@exercism/statis-analysis'
    import { guardMemberExpression } from '@exercism/statis-analysis'
    // etc

    Queries

    Queries utilise the AstTraverser to find and/or collect certain node(s). You can find them here, and the are imported like this:

    import { findFirst } from '@exercism/statis-analysis'
    // etc

    Manual traversing is also possible using the more low-level AstTraverser (and traverse helper function):

    import { traverse } from '@exercism/static-analysis'
    
    traverse(root, {
      enter(node): void {
        // When a node is entered
      },
    
      exit(node): void {
        // when a node is exited
      },
    
      [AST_NODE_TYPES.ArrayExpression]: void (
        {
          // when a node with node.type === AST_NODE_TYPES.ArrayExpression is entered
        }
      ),
    })

    All the functions (enter, exit, [type]) are optional. Inside each function, you can use the following:

    • this.skip() to prevent the traverser from traversing a node's children.
    • this.break() to stop traversing.

    Extracts

    It's also possible to extract certain common items from a source or subtree.

    • extractExports
    • extractSource
    • extractTests
    • extractVariables

    Keywords

    none

    Install

    npm i @exercism/static-analysis

    DownloadsWeekly Downloads

    44

    Version

    0.11.0

    License

    MIT

    Unpacked Size

    136 kB

    Total Files

    110

    Last publish

    Collaborators

    • sleeplessbyte
    • ihid