Skip to content

Commit

Permalink
refactor: add prettier-plugin-jsdoc
Browse files Browse the repository at this point in the history
  • Loading branch information
danielpza committed Aug 18, 2024
1 parent 6f0a280 commit 0b5fd4c
Show file tree
Hide file tree
Showing 14 changed files with 425 additions and 90 deletions.
6 changes: 6 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@
"eslint": "9.x",
"globals": "^15.9.0",
"prettier": "^3.3.3",
"prettier-plugin-jsdoc": "^1.3.0",
"ts-patch": "^3.2.1",
"typescript": "^5.5.4",
"typescript-eslint": "^8.0.1"
Expand All @@ -83,5 +84,10 @@
"dependencies": {
"minimatch": "^10.0.1"
},
"prettier": {
"plugins": [
"prettier-plugin-jsdoc"
]
},
"packageManager": "[email protected]+sha512.91d93b445d9284e7ed52931369bc89a663414e5582d00eea45c67ddc459a2582919eece27c412d6ffd1bd0793ff35399381cb229326b961798ce4f4cc60ddfdb"
}
4 changes: 1 addition & 3 deletions src/harmony/harmony-factory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@ export interface HarmonyFactory extends TS.NodeFactory {}
// region: Utilities
/* ****************************************************************************************************************** */

/**
* Creates a node factory compatible with TS v3+
*/
/** Creates a node factory compatible with TS v3+ */
export function createHarmonyFactory(context: TsTransformPathsContext): HarmonyFactory {
return new Proxy(context.tsFactory ?? context.tsInstance, {
get(target, prop) {
Expand Down
4 changes: 1 addition & 3 deletions src/harmony/versions/four-seven.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
/**
* Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-48
*/
/** Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-48 */
import type {
default as TsCurrentModule,
AssertClause,
Expand Down
4 changes: 1 addition & 3 deletions src/harmony/versions/three-eight.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
/**
* Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-40
*/
/** Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-40 */
import type {
default as TsCurrentModule,
EntityName,
Expand Down
4 changes: 1 addition & 3 deletions src/transformer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,7 @@ export default function transformer(
program?: ts.Program,
pluginConfig?: TsTransformPathsConfig,
transformerExtras?: TransformerExtras,
/**
* Supply if manually transforming with compiler API via 'transformNodes' / 'transformModule'
*/
/** Supply if manually transforming with compiler API via 'transformNodes' / 'transformModule' */
manualTransformOptions?: {
compilerOptions?: ts.CompilerOptions;
fileNames?: string[];
Expand Down
4 changes: 1 addition & 3 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,7 @@ export interface TsTransformPathsConfig extends PluginConfig {
/* ****************************************************************************************************************** */

export interface TsTransformPathsContext {
/**
* TS Instance passed from ts-patch / ttypescript
*/
/** TS Instance passed from ts-patch / ttypescript */
readonly tsInstance: typeof ts;
readonly tsVersionMajor: number;
readonly tsVersionMinor: number;
Expand Down
46 changes: 21 additions & 25 deletions src/utils/elide-import-export.ts
Original file line number Diff line number Diff line change
@@ -1,40 +1,39 @@
/**
* ----------------------------------------------------------------------------
* UPDATE:
*
* TODO - In next major version, we can remove this file entirely due to TS PR 57223
* https://github.com/microsoft/TypeScript/pull/57223
* ----------------------------------------------------------------------------
*
* This file and its contents are due to an issue in TypeScript (affecting *at least* up to 4.1) which causes type
* This file and its contents are due to an issue in TypeScript (affecting _at least_ up to 4.1) which causes type
* elision to break during emit for nodes which have been transformed. Specifically, if the 'original' property is set,
* elision functionality no longer works.
*
* This results in module specifiers for types being output in import/export declarations in the compiled *JS files*
* This results in module specifiers for types being output in import/export declarations in the compiled _JS files_
*
* The logic herein compensates for that issue by recreating type elision separately so that the transformer can update
* the clause with the properly elided information
*
* Issues:
* @see https://github.com/LeDDGroup/typescript-transform-paths/issues/184
* @see https://github.com/microsoft/TypeScript/issues/40603
* @see https://github.com/microsoft/TypeScript/issues/31446
*
* - See https://github.com/LeDDGroup/typescript-transform-paths/issues/184
* - See https://github.com/microsoft/TypeScript/issues/40603
* - See https://github.com/microsoft/TypeScript/issues/31446
*
* @example
* // a.ts
* export type A = string
* export const B = 2
* // a.ts
* export type A = string;
* export const B = 2;
*
* // b.ts
* import { A, B } from './b'
* export { A } from './b'
* // b.ts
* import { A, B } from "./b";
* export { A } from "./b";
*
* // Expected output for b.js
* import { B } from './b'
* // Expected output for b.js
* import { B } from "./b";
*
* // Actual output for b.js
* import { A, B } from './b'
* export { A } from './b'
* // Actual output for b.js
* import { A, B } from "./b";
* export { A } from "./b";
*/
import { ImportOrExportDeclaration, VisitorContext } from "../types";
import {
Expand All @@ -60,10 +59,10 @@ import {
/* ****************************************************************************************************************** */

/**
* Get import / export clause for node (replicates TS elision behaviour for js files)
* See notes in get-import-export-clause.ts header for why this is necessary
* Get import / export clause for node (replicates TS elision behaviour for js files) See notes in
* get-import-export-clause.ts header for why this is necessary
*
* @returns import or export clause or undefined if it entire declaration should be elided
* @returns Import or export clause or undefined if it entire declaration should be elided
*/
export function elideImportOrExportDeclaration<T extends ImportOrExportDeclaration>(
context: VisitorContext,
Expand Down Expand Up @@ -208,10 +207,7 @@ export function elideImportOrExportDeclaration(
return !node.isTypeOnly && shouldEmitAliasDeclaration(node) ? node : undefined;
}

/**
* Visits named exports, eliding it if it does not contain an export specifier that
* resolves to a value.
*/
/** Visits named exports, eliding it if it does not contain an export specifier that resolves to a value. */
function visitNamedExports(node: NamedExports, allowEmpty: boolean): VisitResult<NamedExports> | undefined {
// Elide the named exports if all of its export specifiers were elided.
const elements = visitNodes(node.elements, <Visitor>visitExportSpecifier, isExportSpecifier);
Expand Down
16 changes: 4 additions & 12 deletions src/utils/resolve-module-name.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,11 @@ import { getRelativePath } from "./get-relative-path";
/* ****************************************************************************************************************** */

export interface ResolvedModule {
/**
* Absolute path to resolved module
*/
/** Absolute path to resolved module */
resolvedPath: string | undefined;
/**
* Output path
*/
/** Output path */
outputPath: string;
/**
* Resolved to URL
*/
/** Resolved to URL */
isURL: boolean;
}

Expand Down Expand Up @@ -117,9 +111,7 @@ function getResolvedSourceFile(context: VisitorContext, fileName: string): Sourc
// region: Utils
/* ****************************************************************************************************************** */

/**
* Resolve a module name
*/
/** Resolve a module name */
export function resolveModuleName(context: VisitorContext, moduleName: string): ResolvedModule | undefined {
const { tsInstance, compilerOptions, sourceFile, config, rootDirs } = context;

Expand Down
4 changes: 1 addition & 3 deletions src/utils/resolve-path-update-node.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,7 @@ import { resolveModuleName } from "./resolve-module-name";
// region: Node Updater Utility
/* ****************************************************************************************************************** */

/**
* Gets proper path and calls updaterFn to get the new node if it should be updated
*/
/** Gets proper path and calls updaterFn to get the new node if it should be updated */
export function resolvePathAndUpdateNode(
context: VisitorContext,
node: ts.Node,
Expand Down
16 changes: 4 additions & 12 deletions src/utils/ts-helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,7 @@ import type { REGISTER_INSTANCE } from "ts-node";
// region: TS Helpers
/* ****************************************************************************************************************** */

/**
* Determine output file path for source file
*/
/** Determine output file path for source file */
export function getOutputDirForSourceFile(context: VisitorContext, sourceFile: SourceFile): string {
const {
tsInstance,
Expand Down Expand Up @@ -45,9 +43,7 @@ export function getOutputDirForSourceFile(context: VisitorContext, sourceFile: S
return tsInstance.normalizePath(res);
}

/**
* Determine if moduleName matches config in paths
*/
/** Determine if moduleName matches config in paths */
export function isModulePathsMatch(context: VisitorContext, moduleName: string): boolean {
const {
pathsPatterns,
Expand All @@ -56,9 +52,7 @@ export function isModulePathsMatch(context: VisitorContext, moduleName: string):
return !!(pathsPatterns && matchPatternOrExact(pathsPatterns as readonly string[], moduleName));
}

/**
* Create barebones EmitHost (for no-Program transform)
*/
/** Create barebones EmitHost (for no-Program transform) */
export function createSyntheticEmitHost(
compilerOptions: ts.CompilerOptions,
tsInstance: typeof ts,
Expand All @@ -77,9 +71,7 @@ export function createSyntheticEmitHost(
} as unknown as ts.EmitHost;
}

/**
* Get ts-node register info
*/
/** Get ts-node register info */
export function getTsNodeRegistrationProperties(tsInstance: typeof ts) {
let tsNodeSymbol: typeof REGISTER_INSTANCE;
try {
Expand Down
27 changes: 14 additions & 13 deletions src/visitor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,16 @@ const isRequire = ({ tsInstance }: VisitorContext, node: ts.Node): node is ts.Ca
* Node Visitor
* ****************************************************************************************************************** */

/**
* Visit and replace nodes with module specifiers
*/
/** Visit and replace nodes with module specifiers */
export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | undefined {
const { factory, tsInstance, transformationContext } = this;

/**
* Update require / import functions
*
* require('module')
* import('module')
* @example
* require("module");
* import("module");
*/
if (isRequire(this, node) || isAsyncImport(this, node))
return resolvePathAndUpdateNode(this, node, (<ts.StringLiteral>node.arguments[0]).text, (p) => {
Expand Down Expand Up @@ -67,7 +66,8 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
/**
* Update ExternalModuleReference
*
* import foo = require("foo");
* @example
* import foo = require("foo");
*/
if (tsInstance.isExternalModuleReference(node) && tsInstance.isStringLiteral(node.expression))
return resolvePathAndUpdateNode(this, node, node.expression.text, (p) =>
Expand All @@ -77,8 +77,9 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
/**
* Update ImportTypeNode
*
* typeof import("./bar");
* import ("package").MyType;
* @example
* typeof import("./bar");
* import("package").MyType;
*/
if (tsInstance.isImportTypeNode(node)) {
const argument = node.argument as ts.LiteralTypeNode;
Expand All @@ -104,7 +105,8 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
/**
* Update ImportDeclaration
*
* import ... 'module';
* @example
* import ... 'module';
*/
if (tsInstance.isImportDeclaration(node) && node.moduleSpecifier && tsInstance.isStringLiteral(node.moduleSpecifier))
return resolvePathAndUpdateNode(this, node, node.moduleSpecifier.text, (p) => {
Expand All @@ -123,7 +125,8 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
/**
* Update ExportDeclaration
*
* export ... 'module';
* @example
* export ... 'module';
*/
if (tsInstance.isExportDeclaration(node) && node.moduleSpecifier && tsInstance.isStringLiteral(node.moduleSpecifier))
return resolvePathAndUpdateNode(this, node, node.moduleSpecifier.text, (p) => {
Expand All @@ -146,9 +149,7 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
);
});

/**
* Update module augmentation
*/
/** Update module augmentation */
if (tsInstance.isModuleDeclaration(node) && tsInstance.isStringLiteral(node.name))
return resolvePathAndUpdateNode(this, node, node.name.text, (p) =>
factory.updateModuleDeclaration(node, node.modifiers, p, node.body),
Expand Down
4 changes: 1 addition & 3 deletions test/projects/specific/src/tags.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@
* JSDoc
* ****************************************************************************************************************** */

/**
* @no-transform-path
*/
/** @no-transform-path */
import * as skipTransform1 from "#root/index";

/**
Expand Down
8 changes: 2 additions & 6 deletions test/utils/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,7 @@ function createReadFile(
// region: Utilities
/* ****************************************************************************************************************** */

/**
* Create TS Program with faux files and options
*/
/** Create TS Program with faux files and options */
export function createTsProgram(
opt: CreateTsProgramOptions,
transformerPath: string = config.transformerPath,
Expand Down Expand Up @@ -148,9 +146,7 @@ export function createTsSolutionBuilder(
});
}

/**
* Get emitted files for program
*/
/** Get emitted files for program */
export function getEmitResultFromProgram(program: ts.Program): EmittedFiles {
const outputFiles: EmittedFiles = {};
program.emit(undefined, createWriteFile(outputFiles));
Expand Down
Loading

0 comments on commit 0b5fd4c

Please sign in to comment.