import {Cli, Command, Option, UsageError} from 'clipanion'; import fs from 'fs'; import path from 'path'; import ts from 'typescript'; async function parseFile(p: string) { const content = await fs.promises.readFile(p, `utf8`); return ts.createSourceFile( p, content, ts.ScriptTarget.ES2015, /* setParentNodes */ true, ); } type HookDefinition = { name: string; definition: string; file?: string; comment?: string; }; async function processFile(file: ts.SourceFile) { const hooks: Array = []; let isInsideInterface = false; const processNode = (node: ts.Node) => { switch (node.kind) { case ts.SyntaxKind.TypeAliasDeclaration: { const typeAliasNode = node as ts.TypeAliasDeclaration; if (typeAliasNode.name.getText() === `Hooks`) { throw new UsageError(`Hooks should only be declared using interfaces, not type aliases (in ${file.fileName})`); } } break; case ts.SyntaxKind.InterfaceDeclaration: { const interfaceNode = node as ts.InterfaceDeclaration; if (interfaceNode.name.getText() === `Hooks`) { isInsideInterface = true; ts.forEachChild(node, processNode); isInsideInterface = false; } } break; case ts.SyntaxKind.PropertySignature: { const propertySignatureNode = node as ts.PropertySignature; if (isInsideInterface) { const type = propertySignatureNode.type; if (type?.kind === ts.SyntaxKind.FunctionType) { const {character} = file.getLineAndCharacterOfPosition(propertySignatureNode.getStart()); const removeIndent = (code: string) => code.replace(new RegExp(`^ {${character}}`, `gm`), ``); // undocumented const jsDoc = (propertySignatureNode as any).jsDoc; const comment = jsDoc && jsDoc.length > 0 ? jsDoc[jsDoc.length - 1].comment : undefined; hooks.push({ name: propertySignatureNode.name.getText(), definition: removeIndent(propertySignatureNode.getText()), comment, file: file.fileName, }); } } } break; default: { ts.forEachChild(node, processNode); } break; } }; processNode(file); return hooks; } export async function execute(files: Array) { const allHooks = new Map(); for (const relativePath of files) { const absolutePath = path.resolve(relativePath); const file = await parseFile(absolutePath); const fileHooks = await processFile(file); for (const hook of fileHooks) { let existingDefinition = allHooks.get(hook.name); if (typeof existingDefinition === `undefined`) allHooks.set(hook.name, existingDefinition = {...hook, file: undefined}); if (existingDefinition.definition !== hook.definition) throw new UsageError(`Mismatched hook definitions for ${hook.name}`); if (typeof hook.comment !== `undefined`) { if (typeof existingDefinition.file !== `undefined`) if (existingDefinition.file !== hook.file) throw new UsageError(`Duplicate hook documentation; only document it in one file`); existingDefinition.comment = hook.comment; existingDefinition.file = hook.file; } } } const allHooksArray = [...allHooks.values()]; allHooksArray.sort((a, b) => { return a.name < b.name ? -1 : a.name > b.name ? +1 : 0; }); for (const hook of allHooksArray) if (typeof hook.comment === `undefined`) throw new UsageError(`Undocumented hook ${hook.name}`); return allHooksArray; } if (require.main === module) { Cli.from([ class extends Command { files = Option.Rest(); async execute() { const allHooks = await execute(this.files); this.context.stdout.write(`${JSON.stringify(allHooks, null, 2)}\n`); } }, ]).runExit( process.argv.slice(2), Cli.defaultContext, ); }