Type check JS with typescript

[brendandahl]

In mozilla-central some parts of the code base are now using typescript to do type checks on regular JS that is annotated with jsdoc comments. This could be nice to help us enforce documentation for the API and maybe prevent some bugs.

Example config and JS files that are checked get @ts-check.

[Snuffleupagus]

Given that we're shipping TypeScript definitions in pdfjs-dist, aren't we already doing this at least partially?
If not, we might be able to extend the existing setup to implement the missing pieces.

Please note

pdf.js/gulpfile.js

Lines 1375 to 1392 in 064c21d

	gulp.task("types", function (done) {
	console.log("### Generating TypeScript definitions using `tsc`");
	const args = [
	"target ES2020",
	"allowJS",
	"declaration",
	`outDir ${TYPES_DIR}`,
	"strict",
	"esModuleInterop",
	"forceConsistentCasingInFileNames",
	"emitDeclarationOnly",
	"moduleResolution node",
	].join(" --");
	exec(
	`"node_modules/.bin/tsc" --${args} src/pdf.js web/pdf_viewer.component.js`,
	done
	);
	});

and

pdf.js/gulpfile.js

Lines 1695 to 1726 in 064c21d

	gulp.task(
	"typestest",
	gulp.series(
	setTestEnv,
	"generic",
	"types",
	function createTypesTest() {
	const [packageJsonSrc] = packageBowerJson();
	return merge([
	packageJsonSrc.pipe(gulp.dest(TYPESTEST_DIR)),
	gulp
	.src([
	GENERIC_DIR + "build/pdf.js",
	GENERIC_DIR + "build/pdf.worker.js",
	SRC_DIR + "pdf.worker.entry.js",
	])
	.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
	gulp
	.src(TYPES_DIR + "**/*", { base: TYPES_DIR })
	.pipe(gulp.dest(TYPESTEST_DIR + "types/")),
	]);
	},
	function runTypesTest(done) {
	exec('"node_modules/.bin/tsc" -p test/types', function (err, stdout) {
	if (err) {
	console.log(`Couldn't compile TypeScript test: ${stdout}`);
	}
	done(err);
	});
	}
	)
	);

which runs on every commit/PR thanks to GitHub Actions via

pdf.js/gulpfile.js

Lines 2350 to 2357 in 064c21d

	gulp.task(
	"ci-test",
	gulp.series(
	gulp.parallel("lint", "externaltest", "unittestcli"),
	"lint-chromium",
	"typestest"
	)
	);

[Snuffleupagus]

Looking at https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options, there's a checkJS option that looks relevant here.

I tried adding that to our existing tsc arguments in the gulp types task, but only got a generic/unhelpful error message:

$ gulp types
[14:11:36] Using gulpfile ~\Git\pdf.js\gulpfile.js
[14:11:36] Starting 'types'...
### Generating TypeScript definitions using `tsc`
[14:11:47] 'types' errored after 11 s
[14:11:47] Error: Command failed: "node_modules/.bin/tsc" --target ES2020 --allo
wJS --checkJS --declaration --outDir build/types/ --strict --esModuleInterop --f
orceConsistentCasingInFileNames --emitDeclarationOnly --moduleResolution node sr
c/pdf.js web/pdf_viewer.component.js

    at ChildProcess.exithandler (child_process.js:308:12)
    at ChildProcess.emit (events.js:314:20)
    at ChildProcess.EventEmitter.emit (domain.js:506:15)
    at maybeClose (internal/child_process.js:1022:16)
    at Socket.<anonymous> (internal/child_process.js:444:11)
    at Socket.emit (events.js:314:20)
    at Socket.EventEmitter.emit (domain.js:506:15)
    at Pipe.<anonymous> (net.js:675:12)
    at Pipe.callbackTrampoline (internal/async_hooks.js:126:14)

[Snuffleupagus]

/cc @michael-yx-wu @ineiti @tamuratak Would one you perhaps be able to help out with this, given your TypeScript familiarity?