JSPM

  • Created
  • Published
  • Downloads 21597
  • Score
    100M100P100Q143593F
  • License Apache-2.0

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (eslint-plugin-codegen) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    eslint-plugin-codegen

    An eslint plugin for inline codegen. Auto-fixes out of sync code, with presets for barrels, jsdoc to markdown and more.

    CI npm

    Motivation

    Sometimes the same information is useful in multiple places - for example, jsdoc comments in code can double as markdown-formatted documentation for a library.

    This allows generating code in a project using eslint, without having to incorporate any extra build tools, either for the codegen itself, or to validate that the generated code is up to date. So references to other parts of the project will always stay up to date - and your existing CI tools can enforce this just by running eslint.

    Here's an example of it being used along with VSCode's eslint plugin, with auto-fix-on-save:

    Contents

    How to use

    Caveat

    Before you use this, note that it's still in v0. That means:

    1. Breaking changes might happen. Presets might be renamed, or have their options changed. The documentation should stay up to date though, since that's partly the point of the project.
    2. There are missing features, or incompletely-implemented ones. For example, markdownFromJsdoc only works with export const ... style exports. Currently most of the features implemented are ones that are specifically needed for this git repo.
    3. There might be bugs. The project is in active development - raise an issue if you find one!

    Setup

    In an eslint-enabled project, install with

    npm install --save-dev eslint-plugin-codegen

    or

    yarn add --dev eslint-plugin-codegen

    Then add the plugin and rule to your eslint config, for example in eslintrc.js:

    module.exports = {
      ...
      plugins: [
        ...
        'codegen'
      ],
      rules: {
        ...
        'codegen/codegen': 'error',
      },
    }

    You can use the rule by running eslint in a standard way, with something like this in an npm script: eslint --ext .ts,.js,.md .

    In vscode, if using the eslint plugin, you may need to tell it to validate markdown files in your repo's .vscode/settings.json file (see this repo for an example):

    {
      "eslint.validate": ["markdown", "javascript", "typescript"],
      "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
      }
    }

    To trigger the rule, add a comment line to a source file.

    In markdown:

    <!-- codegen:start {{ OPTIONS }} -->

    In typescript/javascript:

    // codegen:start {{ OPTIONS }}

    Where {{ OPTIONS }} are an inline object in the format:

    {preset: presetName, key1: value1, key2: value2}

    Where key1 and key2 are options passed to the codegen preset. yaml is used to parse the object, So any valid yaml that fits on one line can be passed as options. In practise, the one-line restriction means using yaml's "flow style" for collections.

    See below for documentation. This repo also has lots of usage examples.

    Presets

    monorepoTOC

    Generate a table of contents for a monorepo.

    Example (basic)

    <!-- codegen:start {preset: monorepoTOC} -->

    Example (using config options)

    <!-- codegen:start {preset: monorepoTOC, repoRoot: .., workspaces: lerna, filter: {package.name: foo}, sort: -readme.length} -->

    Params
    name description
    repoRoot [optional] the relative path to the root of the git repository. By default, searches parent directories for a package.json to find the "root".
    filter [optional] a dictionary of filter rules to whitelist packages. Filters can be applied based on package.json keys,
    e.g. filter: { package.name: someRegex, path: some/relative/path }
    sort [optional] sort based on package properties (see filter), or readme length. Use - as a prefix to sort descending.
    e.g. sort: -readme.length
    Demo

    barrel

    Bundle several modules into a single convenient one.

    Example
    // codegen:start {preset: barrel, include: some/path/*.ts, exclude: some/path/*util.ts}
    export * from './some/path/module-a'
    export * from './some/path/module-b'
    export * from './some/path/module-c'
    // codegen:end
    Params
    name description
    include [optional] If specified, the barrel will only include file paths that match this glob pattern
    exclude [optional] If specified, the barrel will exclude file paths that match these glob patterns
    import [optional] If specified, matching files will be imported and re-exported rather than directly exported
    with export * from './xyz'. Use import: star for import * as xyz from './xyz' style imports.
    Use import: default for import xyz from './xyz' style imports.
    export [optional] Only valid if the import style has been specified (either import: star or import: default).
    If specified, matching modules will be bundled into a const or default export based on this name. If set
    to {name: someName, keys: path} the relative file paths will be used as keys. Otherwise the file paths
    will be camel-cased to make them valid js identifiers.
    extension [optional] Useful for ESM modules. If set to true files will be imported with the file extension.
    If set to an object, extensions will be converted using this object.
    Demo

    markdownFromJsdoc

    Convert jsdoc for an es export from a javascript/typescript file to markdown.

    Example

    <!-- codegen:start {preset: markdownFromJsdoc, source: src/foo.ts, export: bar} -->

    Params
    name description
    source {string} relative file path containing the export with jsdoc that should be copied to markdown
    export {string} the name of the export
    Demo

    markdownTOC

    Generate a table of contents from the current markdown file, based on markdown headers (e.g. ### My section title)

    Example

    <!-- codegen:start {preset: markdownTOC, minDepth: 2, maxDepth: 5} -->

    Params
    name description
    minDepth exclude headers with lower "depth". e.g. if set to 2, # H1 would be excluded but ## H2 would be included.
    maxDepth exclude headers with higher "depth". e.g. if set to 3, #### H4 would be excluded but ### H3 would be included.
    Demo

    markdownFromTests

    Use a test file to generate library usage documentation. Note: this has been tested with jest. It might also work fine with mocha, and maybe ava, but those haven't been tested.

    Example

    <!-- codegen:start {preset: markdownFromTests, source: test/foo.test.ts, headerLevel: 3} -->

    Params
    name description
    source the jest test file
    headerLevel The number of # characters to prefix each title with
    Demo

    labeler

    Generates a yaml config for the GitHub Pull Request Labeler Action. Creates a label per package name, which will be applied to any file modified under the leaf package path. When packages are added or removed from the repo, or renamed, the yaml config will stay in sync with them. Additional labels can be added outside of the generated code block. See https://github.com/mmkal/ts/tree/main/.github/labeler.yml for an example.

    Example
    # codegen:start {preset: labeler}

    Note: eslint and related tools make it quite difficult to lint github action yaml files. To get it working, you'll need to:

    • add '!.github' to your .eslintignore file, or the ignorePatterns property in your lint config.
    • {vscode} add "yaml" to the "eslint.validate" list in vscode/settings.json.
    • {@typescript/eslint} add '.yml' (and/or '.yaml') to the parserOptions.extraFileExtensions list in your lint config.
    • {@typescript/eslint} explicitly include 'hidden' files (with paths starting with .) in your tsconfig. See https://github.com/mmkal/ts/tree/main/tsconfig.eslint.json for an example.
    Params
    name description
    repoRoot [optional] path to the repository root. If not specified, the rule will recursively search parent directories for package.json files
    Demo

    custom

    Define your own codegen function, which will receive all options specified. Import the Preset type from this library to define a strongly-typed preset function:

    Example
    import {Preset} from 'eslint-plugin-codegen'
    
    export const jsonPrinter: Preset<{myCustomProp: string}> = ({meta, options}) => {
      const components = meta.glob('**\/*.tsx') // uses 'globSync' from glob package
      return `filename: ${meta.filename}\ncustom prop: ${options.myCustomProp}\nComponent paths: ${components.join(', ')}`
    }

    This can be used with:

    <!-- codegen:start {preset: custom, source: ./lib/my-custom-preset.js, export: jsonPrinter, myCustomProp: hello} Note that a glob helper method is passed to the preset via meta. This uses the globSync method of https://npm.im/glob. There are also fs and path helpers passed, corresponding to those node modules respectively. These can be useful to allow access to those libraries without them being production dependencies.

    Params
    name description
    source Relative path to the module containing the custom preset. Default: the file being linted.
    export The name of the export. If omitted, the module's default export should be a preset function.
    require A module to load before source. If not set, defaults to ts-node/register/transpile-only for typescript sources.
    dev Set to true to clear the require cache for source before loading. Allows editing the function without requiring an IDE reload. Default false if the CI enviornment variable is set, true otherwise.
    Demo

    Note: right now, this preset isn't smart enough to follow source maps or transpile code, so source should point at compiled javascript, not typescript. And VSCode's eslint plugin caches modules, so if you edit the custom preset, you may need to recompile and reload VSCode for it to work properly.

    Customisation

    In addition to the custom preset, you can also define your own presets in eslint configuration, e.g.:

    module.exports = {
      ...
      plugins: [
        ...
        'codegen'
      ],
      rules: {
        ...
        'codegen/codegen': [
          'error',
          {presets: require('./my-custom-presets')}
        ],
      },
    }

    presets should be a record of preset functions, conforming to the Preset interface from this package. This can be used to extend the in-built ones. For example, you could make generated markdown collapsible:

    Before:

     <!-- codegen:start {preset: markdownTOC}-->
     - [Section1](#section1)
     - [Section2](#section2)
     <!-- codegen:end -->

    my-custom-presets.js:

    const {presets} = require('eslint-plugin-codegen')
    
    module.exports.markdownTOC = (params) => {
      const toc = presets.markdownTOC(params)
      return [
        '<details>',
        '<summary>click to expand</summary>',
        '',
        toc,
        '</details>',
      ].join('\n')
    }

    .eslintrc.js:

    module.exports = {
      ...
      plugins: [
        ...
        'codegen'
      ],
      rules: {
        ...
        'codegen/codegen': ['error', {presets: require('./my-custom-presets')}],
      },
    }

    After:

    readme.md:

     <!-- codegen:start {preset: markdownTOC}-->
     <details>
      <summary>click to expand</summary>
    
     - [Section1](#section1)
     - [Section2](#section2)
     </details>
     <!-- codegen:end -->

    Rendered:

    click to expand

    The code in this repository was moved from https://github.com/mmkal/ts