JS and JSDoc support

The compiler can type-check plain JavaScript via --allowJs (and report errors via --checkJs). JSDoc comments serve as a first-class type-annotation language for .js files.

Where JS support touches the codebase

Subsystem	File	Role
Parser	src/compiler/parser.ts	JSDoc sub-parser; populates node.jsDoc
Binder	src/compiler/binder.ts	getAssignmentDeclarationKind, module.exports/exports.foo recognition
Checker	src/compiler/checker.ts	JSDoc type resolution, Object.defineProperty patterns, JS-specific narrowing
Language service	src/services/jsDoc.ts	JSDoc-template completions, hover, signature help
Code fixes	src/services/codefixes/annotateWithTypeFromJSDoc.ts	Migrate JSDoc → real type annotations
Refactors	src/services/refactors/convertJSDocTypedef.ts	Convert JSDoc patterns

--allowJs and --checkJs

• --allowJs lets .js and .jsx files participate in the program. They're parsed, bound, and emitted alongside .ts files.
• --checkJs tells the checker to surface diagnostics for them, with // @ts-check and // @ts-nocheck comments for per-file overrides.

When both are on, the workflow is "JavaScript with optional types via JSDoc, gradually migratable to TypeScript".

JSDoc as a type language

The parser's JSDocParser namespace parses comment text into a tree. Recognised tags include:

• @param, @returns, @type, @typedef, @callback, @template
• @enum, @implements, @extends
• @property, @override, @public, @private, @protected, @readonly
• @see, @deprecated, @example, @author
• @satisfies (TS 4.9+)

JSDoc has its own type subset: object types { a: string }, function types function(x: number): string, optional { string= }, nullable { ?string }, non-nullable { !string }, arrays { string[] }, generics { Promise<T> }, type imports { import("./mod").Foo }. The checker maps these to TypeScript types.

JSDoc-typed .js files behave nearly identically to .ts files in the language service — completions, hover, find-references all work.

CommonJS-shaped declarations

JS files often build classes via Function.prototype.bar = function() {} and namespaces via Foo.X = 0. The binder recognises these patterns and synthesises class-like or namespace-like symbols. The relevant code lives in bindCommonJsModuleAssignment, bindThisPropertyAssignment, bindStaticPropertyAssignment, and bindObjectDefinePropertyAssignment in binder.ts, with the canonical patterns enumerated in AssignmentDeclarationKind.

The checker then applies these bindings to give the user IntelliSense for code like:

function Foo() {}
Foo.prototype.greet = function (msg) {
  /* ... */
};
Foo.staticHelper = 0;

@ts-check / @ts-nocheck / @ts-ignore / @ts-expect-error

Comment directives recognised by the parser (recorded on SourceFile.commentDirectives) and applied at diagnostic-output time:

• // @ts-check — opt the file in to checking even if --checkJs is off.
• // @ts-nocheck — opt out of checking for the entire file.
• // @ts-ignore — suppress the next line's diagnostics.
• // @ts-expect-error — like @ts-ignore but errors if no diagnostic was suppressed.

Salsa

"Salsa" is the team's nickname for the JS-checking subsystem (the original code-name for the language-service support for JavaScript). Conformance tests for Salsa-specific behaviours live under tests/cases/conformance/salsa/.

Emit

JS files are emitted unchanged unless --target is below their natural level (e.g., emitting modern JS as ES5). JSDoc comments are preserved in output by default. With --declaration + --allowJs, the compiler synthesises .d.ts files for JS sources from their JSDoc — same nodeBuilder machinery as TypeScript declaration emit (see features/declaration-emit).

Migration tooling

The language service offers code fixes to graduate from JSDoc to TypeScript:

• annotateWithTypeFromJSDoc.ts — convert /** @type {string} */ let x into let x: string.
• convertTypedefToType.ts — @typedef → type alias.
• convertToTypeOnlyExport.ts / convertToTypeOnlyImport.ts — when a .js becomes a .ts, type-only imports become available.

Tests

JS-specific tests are scattered:

• tests/cases/conformance/jsdoc/ — JSDoc syntax conformance.
• tests/cases/conformance/salsa/ — JS-only patterns.
• tests/cases/fourslash/ — many tests with JS/Js in the name.

Entry points for modification

• New JSDoc tag — extend the JSDoc parser in parser.ts and the checker resolution path.
• New JS assignment idiom — extend getAssignmentDeclarationKind in utilities.ts and the corresponding binder cases in binder.ts.
• New code fix or refactor — see features/refactors-and-codefixes.

See systems/parser and systems/binder for the foundations.