Support doctests for typescript
This commit is contained in:
Dan Rosén
commit
a93318a0b3
4 changed files with 308 additions and 0 deletions
21
LICENSE
Normal file
21
LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
The MIT License (MIT)
|
||||||
|
|
||||||
|
Copyright (c) Dan Rosén
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
34
package.json
Normal file
34
package.json
Normal file
|
|
@ -0,0 +1,34 @@
|
||||||
|
{
|
||||||
|
"name": "typescript-doctest",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"description": "doctest support for typescript",
|
||||||
|
"main": "src/main.ts",
|
||||||
|
"bin": {
|
||||||
|
"typescript-doctest": "src/main.js"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"test": "echo \"Error: no test specified\" && exit 1"
|
||||||
|
},
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "git+https://github.com/danr/typescript-doctest.git"
|
||||||
|
},
|
||||||
|
"keywords": [
|
||||||
|
"doctest",
|
||||||
|
"typescript",
|
||||||
|
"testing"
|
||||||
|
],
|
||||||
|
"author": "Dan Rosén",
|
||||||
|
"license": "MIT",
|
||||||
|
"bugs": {
|
||||||
|
"url": "https://github.com/danr/typescript-doctest/issues"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/danr/typescript-doctest#readme",
|
||||||
|
"dependencies": {
|
||||||
|
"fs": "0.0.1-security",
|
||||||
|
"typescript": "^2.6.1"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^8.0.47"
|
||||||
|
}
|
||||||
|
}
|
||||||
243
src/main.ts
Normal file
243
src/main.ts
Normal file
|
|
@ -0,0 +1,243 @@
|
||||||
|
#!/usr/bin/env node
|
||||||
|
import * as ts from 'typescript'
|
||||||
|
import * as fs from "fs"
|
||||||
|
|
||||||
|
const is_doctest = (s: string) => s.match(/\/\/[ \t]*=>/) != null
|
||||||
|
|
||||||
|
function replicate<A>(i: number, x: A): A[] {
|
||||||
|
const out = [] as A[]
|
||||||
|
while (i-- > 0) out.push(x);
|
||||||
|
return out
|
||||||
|
}
|
||||||
|
|
||||||
|
type Top = {filename: string, defs: Defs}[]
|
||||||
|
|
||||||
|
type Defs = Def[]
|
||||||
|
|
||||||
|
interface Def {
|
||||||
|
name: string,
|
||||||
|
type?: string,
|
||||||
|
doc: string,
|
||||||
|
exported: boolean,
|
||||||
|
typedef: boolean,
|
||||||
|
flags: string[],
|
||||||
|
children: Defs,
|
||||||
|
kind: string,
|
||||||
|
}
|
||||||
|
|
||||||
|
function walk(defs: Defs, f: (def: Def, d: number) => void, d0: number = 0): void {
|
||||||
|
defs.forEach(d => (f(d, d0), walk(d.children, f, d0 + 1)))
|
||||||
|
}
|
||||||
|
|
||||||
|
function flatMap<A, B>(xs: A[], f: (a: A) => B[]): B[] {
|
||||||
|
return ([] as B[]).concat(...xs.map(f))
|
||||||
|
}
|
||||||
|
|
||||||
|
function flatten<A>(xss: A[][]): A[] {
|
||||||
|
return ([] as A[]).concat(...xss)
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Generate documentation for all classes in a set of .ts files */
|
||||||
|
function generateDocumentation(fileNames: string[], options: ts.CompilerOptions): Top {
|
||||||
|
const program = ts.createProgram(fileNames, options)
|
||||||
|
const checker = program.getTypeChecker()
|
||||||
|
const printer = ts.createPrinter()
|
||||||
|
return program.getSourceFiles()
|
||||||
|
.filter(file => -1 != fileNames.indexOf(file.fileName))
|
||||||
|
.map(file => ({
|
||||||
|
filename: file.fileName,
|
||||||
|
defs: flatten(file.statements.map(visits))
|
||||||
|
}))
|
||||||
|
|
||||||
|
function isNodeExported(node: ts.Node): boolean {
|
||||||
|
return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0
|
||||||
|
}
|
||||||
|
|
||||||
|
function visits(node: ts.Node): Defs {
|
||||||
|
if (ts.isVariableStatement(node)) {
|
||||||
|
// top-level const
|
||||||
|
return flatten(node.declarationList.declarations.map(visits))
|
||||||
|
// } else if (ts.isExportAssignment(node)) {
|
||||||
|
// return { exAss: ts.forEachChild(node, visit) }
|
||||||
|
// } else if (ts.isExportDeclaration(node)) {
|
||||||
|
// return { exDecl: ts.forEachChild(node, visit) }
|
||||||
|
} if (
|
||||||
|
( ts.isInterfaceDeclaration(node)
|
||||||
|
|| ts.isClassDeclaration(node)
|
||||||
|
|| ts.isFunctionDeclaration(node)
|
||||||
|
|| ts.isMethodDeclaration(node)
|
||||||
|
|| ts.isPropertyDeclaration(node) // fields in classes
|
||||||
|
|| ts.isTypeElement(node) // fields in interface records
|
||||||
|
|| ts.isTypeAliasDeclaration(node) // type A = ...
|
||||||
|
|| ts.isVariableDeclaration(node) // top-level const
|
||||||
|
|| ts.isModuleDeclaration(node)
|
||||||
|
) && node.name) {
|
||||||
|
const symbol = checker.getSymbolAtLocation(node.name);
|
||||||
|
const doc = (((node as any).jsDoc || [])[0] || {}).comment || ''
|
||||||
|
if (symbol) {
|
||||||
|
const out: Def = {
|
||||||
|
name: symbol.name,
|
||||||
|
doc,
|
||||||
|
exported: isNodeExported(node),
|
||||||
|
kind: ts.SyntaxKind[node.kind],
|
||||||
|
flags: [
|
||||||
|
ts.ModifierFlags.None,
|
||||||
|
ts.ModifierFlags.Export,
|
||||||
|
ts.ModifierFlags.Ambient,
|
||||||
|
ts.ModifierFlags.Public,
|
||||||
|
ts.ModifierFlags.Private,
|
||||||
|
ts.ModifierFlags.Protected,
|
||||||
|
ts.ModifierFlags.Static,
|
||||||
|
ts.ModifierFlags.Readonly,
|
||||||
|
ts.ModifierFlags.Abstract,
|
||||||
|
ts.ModifierFlags.Async,
|
||||||
|
ts.ModifierFlags.Default,
|
||||||
|
ts.ModifierFlags.Const
|
||||||
|
].map(flag => ts.ModifierFlags[symbol.flags & flag])
|
||||||
|
.filter(flag => flag != 'None'),
|
||||||
|
typedef: ts.isInterfaceDeclaration(node)
|
||||||
|
|| ts.isClassDeclaration(node)
|
||||||
|
|| ts.isTypeAliasDeclaration(node),
|
||||||
|
type:
|
||||||
|
(symbol.valueDeclaration && !ts.isClassDeclaration(node))
|
||||||
|
? checker.typeToString(checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration), node, 65535)
|
||||||
|
: undefined,
|
||||||
|
children: []
|
||||||
|
}
|
||||||
|
if ( ts.isInterfaceDeclaration(node) ) {
|
||||||
|
out.children = flatten(node.members.map(visits))
|
||||||
|
}
|
||||||
|
if ( ts.isClassDeclaration(node) ) {
|
||||||
|
out.children = flatten(node.members.map(visits))
|
||||||
|
}
|
||||||
|
if ( ts.isModuleDeclaration(node) && node.body ) {
|
||||||
|
const b = node.body
|
||||||
|
if (b.kind == ts.SyntaxKind.ModuleBlock) {
|
||||||
|
out.children = flatten(b.statements.map(visits))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return [out]
|
||||||
|
}
|
||||||
|
return []
|
||||||
|
} else if (ts.isModuleBlock(node)) {
|
||||||
|
return flatten(node.getChildren().map(visits))
|
||||||
|
} else {
|
||||||
|
console.error("Ignoring " + ts.SyntaxKind[node.kind])
|
||||||
|
return []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const pwoc = ts.createPrinter({removeComments: true})
|
||||||
|
|
||||||
|
function script(s: string): string[] {
|
||||||
|
const f = ts.createSourceFile('test.ts', s, ts.ScriptTarget.ES5, true, ts.ScriptKind.TS)
|
||||||
|
const out =
|
||||||
|
f.statements.map(
|
||||||
|
(now, i) => {
|
||||||
|
if (ts.isExpressionStatement(now)) {
|
||||||
|
const next = f.statements[i+1] // zip with next
|
||||||
|
const [a, z] = next ? [next.pos, next.end] : [now.end, f.end]
|
||||||
|
const after = f.text.slice(a, z)
|
||||||
|
const m = after.match(/^\s*\/\/[ \t]*=>([^\n]*)/m)
|
||||||
|
if (m && m[1]) {
|
||||||
|
const lhs = pwoc.printNode(ts.EmitHint.Expression, now.expression, f)
|
||||||
|
const rhs = m[1].trim()
|
||||||
|
return 'assert.deepEqual(' + lhs + ', ' + rhs + ', ' + JSON.stringify(rhs) + ')'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return pwoc.printNode(ts.EmitHint.Unspecified, now, f)
|
||||||
|
})
|
||||||
|
return out
|
||||||
|
}
|
||||||
|
|
||||||
|
const headers = ["import * as test from 'tape'"]
|
||||||
|
const filenames = [] as string[]
|
||||||
|
let fileout = null
|
||||||
|
const argv = process.argv
|
||||||
|
for (let i = 2; i < argv.length; i++) {
|
||||||
|
const arg = argv[i]
|
||||||
|
if (arg == '-o') {
|
||||||
|
fileout = argv[++i]
|
||||||
|
} else if (arg == '-i') {
|
||||||
|
headers.push(argv[++i])
|
||||||
|
} else {
|
||||||
|
filenames.push(arg)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const top = generateDocumentation(filenames, {
|
||||||
|
target: ts.ScriptTarget.ES5, module: ts.ModuleKind.CommonJS
|
||||||
|
})
|
||||||
|
|
||||||
|
|
||||||
|
if (fileout != null) {
|
||||||
|
const out = headers.slice()
|
||||||
|
|
||||||
|
top.forEach(({filename, defs}) => {
|
||||||
|
walk(defs, d => {
|
||||||
|
let tests = 0
|
||||||
|
d.doc.split(/\n\n+/m).map(s => {
|
||||||
|
if (is_doctest(s)) {
|
||||||
|
out.push(
|
||||||
|
'test(' + JSON.stringify(d.name + ' ' + ++tests) + ', assert => {',
|
||||||
|
...script(s).map(l => ' ' + l),
|
||||||
|
' assert.end()',
|
||||||
|
'})',
|
||||||
|
''
|
||||||
|
)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
fs.writeFileSync(fileout, out.join('\n'));
|
||||||
|
}
|
||||||
|
|
||||||
|
const readme = [] as string[]
|
||||||
|
|
||||||
|
readme.push('## API overview')
|
||||||
|
|
||||||
|
function prettyKind(kind: string) {
|
||||||
|
return kind.replace('Declaration', '').toLowerCase()
|
||||||
|
}
|
||||||
|
|
||||||
|
top.forEach(({defs}) => {
|
||||||
|
walk(defs, (def, i) => {
|
||||||
|
if (def.exported || i > 0) {
|
||||||
|
readme.push(
|
||||||
|
replicate(i, ' ').join('') +
|
||||||
|
'* ' +
|
||||||
|
(def.children.length == 0 ? '' : (prettyKind(def.kind) + ' ')) +
|
||||||
|
def.name)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
top.forEach(({defs}) =>
|
||||||
|
walk(defs, (def, i) => {
|
||||||
|
if (def.exported || i > 0) {
|
||||||
|
let indent = ''
|
||||||
|
if (def.children.length == 0) {
|
||||||
|
//const method = (def.kind == 'MethodDeclaration') ? 'method ' : ''
|
||||||
|
readme.push('* ' + '**' + def.name + '**: `' + def.type + '`')
|
||||||
|
indent = ' '
|
||||||
|
} else {
|
||||||
|
readme.push('### ' + prettyKind(def.kind) + ' ' + def.name)
|
||||||
|
}
|
||||||
|
def.doc.split(/\n\n+/).forEach(s => {
|
||||||
|
readme.push('')
|
||||||
|
if (is_doctest(s)) {
|
||||||
|
readme.push(indent + '```typescript')
|
||||||
|
}
|
||||||
|
readme.push(indent + s.trim().split('\n').join('\n' + indent))
|
||||||
|
if (is_doctest(s)) {
|
||||||
|
readme.push(indent + '```')
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
})
|
||||||
|
)
|
||||||
|
|
||||||
|
console.log(readme.join('\n'))
|
||||||
|
|
||||||
10
tsconfig.json
Normal file
10
tsconfig.json
Normal file
|
|
@ -0,0 +1,10 @@
|
||||||
|
{
|
||||||
|
"compilerOptions": {
|
||||||
|
"target": "es5",
|
||||||
|
"module": "commonjs",
|
||||||
|
"strict": true,
|
||||||
|
"noImplicitAny": true,
|
||||||
|
"strictNullChecks": true,
|
||||||
|
"alwaysStrict": true
|
||||||
|
}
|
||||||
|
}
|
||||||
Loading…
Add table
Reference in a new issue