Documentation Coverage Plugin (jsdocs-plugin)

[aramirezj]

Documentation Coverage Plugin

Documentation coverage of JS/TS codebases

Seamlessly analyze the coverage of documentation of your codebase.

🧪 Reference PR

👉 #896 - Documentation Coverage Plugin PoC

Metric

Documentation coverage based on JSDocs present on the codebase.

Property	Value	Description
value	48	Total number of undocumented nodes.
displayValue	48 undocumented functions	Human-readable representation of the value.
score	0	Indicates whether the audit passed (1) or failed (0).

💡 Node: Anything that can get a JSDoc applied (EX: Function, Class, Method, Property, etc)

User Story

As a developer, or as a team lead, I want to ensure that the codebase documentation coverage does not get worse as the codebase grows:

The plugin should:

• Display the current state of the documentation coverage.
• Group it by type of node.
• Show me what line is undocummented and exactly what.

Setup and Requirements

📦Package Dependencies

• Dependencies:
  • ts-morph
• Dev Dependencies: N/A
• Optional Dependencies: N/A

📝 Configuration Files

N/A

📖 Audit, groups and category maintenance

📋 Audit: An audit per node. [ 'classes-coverage', 'methods-coverage', 'functions-coverage', 'interfaces-coverage', 'variables-coverage', 'properties coverage', 'types-coverage', 'enums-coverage']
🗂 Group: A general one grouping all the audits.
🗃 Category: A general one grouping all the audits.

🔨 Details maintenance

Minimum, there are not anything in particular to considerate.

Acceptance criteria

• The plugin can be configured through parameters.
  • It can include and exclude files through patterns
  • Audits are filtered by onlyAudits or by skipAudits if specified.
• Issues are grouped by an audit slug.
• Audits are organized into logically linked groups.
• Works with both TS and JS codebases.

Implementation details

1. With the library ts-morph, a "project" or "codebase" can be instantiated from the file patterns.
2. Then, we can retrieve every matching file found.
3. From each file, every possible node is retrieve
4. Every node is analyzed to determine if it's documented or not, and if it should analyze it's inside nodes in correlation (example, classes have methods inside and properties, not function and variables)

A implementation of the plugin can be found here.

Setup

The plugin needs / accepts the following options:

type DocCoveragePluginConfig = {
    sourceGlob: string[]; // to match or exclude the files
    skipAudits?: string[] | undefined;
    onlyAudits?: string[] | undefined;
}

Retrieving the files to analyze

import { Project } from 'ts-morph';

const project = new Project();
project.addSourceFilesAtPaths(config.sourceGlob);
project.getSourceFiles();

Processing each file

Once the sourceFiles are get, every possible node is retrieved.

export function getAllNodesFromASourceFile(sourceFile: SourceFile) {
  const classes = sourceFile.getClasses();
  return [
    ...sourceFile.getFunctions(),
    ...classes,
    ...getClassNodes(classes),
    ...sourceFile.getTypeAliases(),
    ...sourceFile.getEnums(),
    ...sourceFile.getInterfaces(),
    ...getVariablesInformation(sourceFile.getVariableStatements()),
  ];
}

And then, every node, can BE ask for different information such as:

node.getKind() // What's the node? EX: 'method'
node.getJsDocs().length // It's docummented? EX: 1 === true
name: node.getName() //  What's the name of the node? EX: 'retrieveUsers'
node.getStartLineNumber() // What's the line of the node? EX: 24

This information will be attached with some information of the sourceFile itself like the path:

sourceFile.getFilePath() //projects/pg-library/domains/core/feat/componentA/componentA.component.ts

There is some extra logic in order to get methods and properties inside classes, but besides this:

export function getClassNodes(classNodes: ClassDeclaration[]) {
  return classNodes.flatMap(classNode => [
    ...classNode.getMethods(),
    ...classNode.getProperties(),
  ]);
}

That would wrap up the implementation details 🎁.