Skip to content

Conversation

@sandersn
Copy link
Member

I started adding precise differences for JS semantics to CHANGES.md. As you can see, I accepted 25 tests--and looked at around 40--before I got bored and switched to compiling well-known JSDoc codebases (webpack and svelte). The changes include a couple of diffs from Svelte as well.

I'm not 100% sure that this is worth generating. At some point we may instead want to declare legacy test bankruptcy, if people appear to be using JS features with no complaint. However, the first 2.5% of accepted tests probably has 25% of the semantics changes, so this list is at least worth reviewing by the team for surprises.

A good number of the diffs are due to the reparsing strategy, which gives JS exactly the semantics of TS. The rest are due to cut features, both whole features (eg type annotations on functions) and partial (eg use of @class to mark an otherwise-normal function as a constructor).

Copilot AI review requested due to automatic review settings July 21, 2025 13:10
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR documents and accepts 25 differences in JSDoc test outputs between the legacy TypeScript implementation (Strada) and the new native port (Corsa). The changes primarily reflect semantic differences in JavaScript handling, with many arising from the new reparsing strategy that gives JS exactly the same semantics as TypeScript.

  • Accepts 25 test diffs by adding them to the submoduleAccepted.txt file
  • Documents comprehensive semantic changes in CHANGES.md covering checker behavior, JSDoc types/tags, expandos, and CommonJS modules
  • Includes differences discovered from compiling real-world JSDoc codebases like webpack and svelte

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description
testdata/submoduleAccepted.txt Adds 25 conformance test diffs to the accepted changes list
CHANGES.md Extensive documentation of semantic differences between Strada and Corsa implementations

Copy link
Member

@jakebailey jakebailey left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly my comments are not about the text but about the actual differences themselves ☹️

CHANGES.md Outdated

### JSDoc Tags

1. `@type` tags no longer apply to function declarations, and now contextually type function expressions instead of applying directly. So this annotation no longer does anything:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still really really think we should reconsider this and come up with some sort of way to do it

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The right way is to make a WholeType property for functions and check that if the function's Type and parameter types are nil, then only set WholeType in JS. It's possible but I'd put it even below constructor functions and maybe even Object.defineProperty expandos in importance, since contextual typing occurs in nearly all uses of it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CHANGES.md Outdated
function sum(...ns) {}
```

3. The postfix `=` type no longer adds `undefined` even when `strictNullChecks` is off:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this one just visual? Like, in a parameter position, missing vs undefined is not a real thing that matters.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pretty much. It shows up in the type baselines so I noted it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right; who is the target of this doc? I had figured this was for end users to read when they find something that doesn't work, so this particular one seemed not enough to mention.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be "even when ... is on"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it is supposed to add undefined when it is on. The Strada bug is that it adds it even when strict is off. I will make this note explain it better.

CHANGES.md Outdated

### CommonJS

1. Chained exports no longer work:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this one a cleanup? Or just impossible?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplification -- it's possible, but adds a bunch of code.

CHANGES.md Outdated

This exports `x: undefined` not `x: typeof theRealExport`.

3. Type info for `module` shows a property with name of the export instead of `exports`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what this one means. Are you talking about hover? or something else?

module, and exports are different symbols entirely, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's for hover, yes. module and exports are different symbols.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably this is one we can avoid mentioning for end users. But the doc doesn't structure it like that of course so it's okay.

CHANGES.md Outdated

results in `module: { singleIdentifier: any }`

4. Property access on `require` no longer imports a single property from a module:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are we disallowing this one? I've definitely seen this before...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was extremely rare in the survey I did. And it would require significant hacking to the module exports resolution in the checker, too.

CHANGES.md Outdated
const { x } = require("y")
```

5. `Object.defineProperty` on `exports` no longer creates an export:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a feeling this one will bite us...

Copy link
Member

@weswigham weswigham left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks like a useful summary of where we are right now. A question, though:

A good number of the diffs are due to the reparsing strategy, which gives JS exactly the semantics of TS.

Should we be applying changes to https://github.com/microsoft/TypeScript/tree/tsgo-port to have a strada version with matching semantics for generating matching baselines? Seems like it'd be useful to have a JS version of the compiler that can report the same diagnostics (and maybe provide upgrade fixes? 6.0?).

```

In Strada, `cu` incorrectly narrows to `C` inside the `if` block, unlike with TS assertion syntax.
In Corsa, the behaviour is the same between TS and JS.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...should we change this TS behavior? Seems like a bug, honestly. The presence of the cast doesn't make the truthiness check not present.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have trouble keeping the precise semantics of narrowing in my head, but if (cu.undeclaredProperty) doesn't seem like a truthiness check compared to if (cu?.undeclaredProperty). I guess implicitly it is--"we are here without a crash, so cu must exist". Also casts are often an escape hatch for when the compiler goes wrong, so maybe that's why that's here.


5. `@class` or `@constructor` does not make a function into a constructor function.

Corsa ignores `@class` and `@constructor`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd want it to emit the "convert to class declaration" quickfix on, anyway, right?

CHANGES.md Outdated
They have no other semantics.


2. A variadic type on a parameter no longer makes it a rest parameter. The parameter must use standard rest syntax.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one might need some changes in declaration emit? Or not? ...number still get changed to number[], which is.... still right, I think? Ah, whatever, mental note to check on it.

Copy link
Member Author

@sandersn sandersn Jul 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure; the emit changes for sum but unless you ported the special-case check already, the correct emit is function sum(ns: number[]) and that's what the checker should give you if you're generating from a type.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked and declaration emit does the right thing already.

@sandersn sandersn added this pull request to the merge queue Nov 17, 2025
Merged via the queue into microsoft:main with commit d7d7aa4 Nov 17, 2025
22 checks passed
@sandersn sandersn deleted the accept-jsdoc-diffs-1 branch November 17, 2025 15:44
nathanwhit added a commit to denoland/typescript-go that referenced this pull request Dec 2, 2025
* Port 'go to type definition' tests (microsoft#1883)

* Fix panic in `getTokenAtPosition` for JSDoc type assertions (microsoft#1846)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>
Co-authored-by: andrewbranch <[email protected]>
Co-authored-by: Andrew Branch <[email protected]>

* Don’t look in JSExportAssignment and CommonJSExport for nodes (microsoft#1886)

* Fix link in native preview platform packages (microsoft#1838)

* fix(1880): No error message for JSDoc type parsing (microsoft#1881)

* Add vscode editor issue template (microsoft#1893)

Co-authored-by: Ryan Cavanaugh <[email protected]>

* Add "Report Issue" button to TSGO status bar commands (microsoft#1889)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: DanielRosenwasser <[email protected]>
Co-authored-by: Daniel Rosenwasser <[email protected]>

* fix(1898): adjust location handling in find-refs (microsoft#1901)

* Fix panic of empty string in type reference directive (microsoft#1908)

* Consistently error on full circle of circular import aliases (microsoft#1904)

* Fix panic in textDocument/onTypeFormatting when tokenAtPosition is nil (microsoft#1845)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Update submodule (microsoft#1913)

* Disable create-cache.yml in forks (microsoft#1912)

* Forbid platform specific package uses in agnostic files (microsoft#1911)

* Fix JSDoc comment formatting with tab indentation (microsoft#1900)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Clear local baseline dir in hereby test (microsoft#1921)

* Unskip passing fourslash test (microsoft#1922)

* Support auto-import completion fourslash tests, fix bugs (microsoft#1917)

* Fix JSX indentation in JavaScript output (microsoft#1792)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Implement printAllHelp to fix `tsgo --all` producing no output (microsoft#1843)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Bump the github-actions group across 1 directory with 2 updates (microsoft#1909)

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jake Bailey <[email protected]>

* Ensure os package is forbidden in lint (microsoft#1924)

* Speed up levenshteinWithMax by reusing buffers (microsoft#1823)

* Fix incorrect formatting for comments inside multi-line argument lists and method chains (microsoft#1929)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Handle nil end position in getMappedLocation (microsoft#1920)

* Fix formatter adding extra space at end of line without trailing newline (microsoft#1933)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Fix vscode issue template (microsoft#1934)

* userpreferences parsing/ls config handing (microsoft#1729)

* Plumb through TokenFlagsSingleQuote; use for auto import quote detection (microsoft#1937)

* Invalidate caches on batches of 1000+ watch changes (microsoft#1869)

* Create clickable links in quick info from @link JSDoc tags (microsoft#1935)

* Don't report errors on `{@link foo.bar}` references (microsoft#1941)

* Fix crash in `invocationErrorRecovery` function (microsoft#1944)

* Fix leading source file comment emit bugs (microsoft#1945)

* Implement selection ranges (microsoft#1939)

* Fix porting bug in isArgumentAndStartLineOverlapsExpressionBeingCalled (microsoft#1948)

* Add Range to Hover (microsoft#1489)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: DanielRosenwasser <[email protected]>
Co-authored-by: Jake Bailey <[email protected]>

* Properly handle hovering on `this` (microsoft#1953)

* Bump the github-actions group across 1 directory with 2 updates (microsoft#1959)

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Fixed document highlight for reference directive (microsoft#1951)

* Several fixes to JS typing of functions and methods (microsoft#1960)

* Update submodule, port 6.0 options defaults (microsoft#1961)

* Reapply microsoft#1951 and microsoft#1960 after bad merge (microsoft#1964)

Co-authored-by: Anders Hejlsberg <[email protected]>
Co-authored-by: John Favret <[email protected]>

* Update submodule with ES5 removals (microsoft#1963)

* Actually transform KindCommonJSExport in declaration emit (microsoft#1962)

* Quick Info fixes (microsoft#1971)

* Fix various named enum types (microsoft#1973)

* Move change tracker, converters, utils to separate packages (microsoft#1977)

* Consistent rules for mixing `@type`, `@param`, `@return`, `@template` (microsoft#1979)

* Check for identifier before obtaining text of name (microsoft#1984)

* Respect client capabilities for diagnostics (microsoft#1980)

* Store explicitly declared members ahead of inherited members (microsoft#1987)

* Add --checkers to control number of checkers per Program (microsoft#1985)

* Export all types referenced through other exported APIs, enforce (microsoft#1978)

* Switch custom runners from mariner-2.0 to azure-linux-3 (microsoft#1989)

* Use `LocationLink` in go to definition (microsoft#1884)

* Use a different set of commands to detect fourslash test updates (microsoft#1923)

* Skip erasableSyntaxOnly checks for JavaScript files (microsoft#1956)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Update submodule for new cherry-picks (microsoft#1996)

* Port TypeScript PR #62604: Propagate variance reliability (microsoft#1916)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: RyanCavanaugh <[email protected]>
Co-authored-by: Jake Bailey <[email protected]>

* Only export `@typedef` type aliases in modules (microsoft#1999)

* Bump github/codeql-action from 4.31.0 to 4.31.2 in the github-actions group across 1 directory (microsoft#2005)

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Hoist @typedef and @import tags to containing scopes that permit them (microsoft#2003)

* Remove concept of "unsupported extensions", clean up test skips  (microsoft#2004)

* Update golangci-lint, fix issues, modernize (microsoft#1981)

* Implement more handling of client capabilities (microsoft#1998)

* Add docs to signature help (microsoft#2009)

Co-authored-by: Copilot <[email protected]>

* Fix unused identifier diags, LSP tag diags (microsoft#2007)

* fix(2015): abstract property created, overshadowing override (microsoft#2016)

* Always check refCount after acquiring lock (microsoft#1986)

* Delete resolver unit tests (microsoft#2008)

* Fix missing parent for `Expression` in `TypeParameterDeclaration` (microsoft#2017)

* Add missing nil check in `getCompletionItemActions` (microsoft#2018)

* Fix crash in find-all-refs on `exports.xxx` in .js file (microsoft#2023)

* Properly include JSX attributes in find-all-references (microsoft#2025)

* Fix crash by removing `getNameFromImportDeclaration` in favor of `Node.Name()` (microsoft#2027)

* Fix losing options from command line in watch mode (microsoft#2024)

* Add issue investigator agent (microsoft#2030)

* Switch 1ESPT pipelines to 1ESPT-AzureLinux3 (microsoft#2031)

* Port inlay hints (microsoft#1705)

* Split "use strict" into separate transformer, fix bugs with prologues (microsoft#2028)

Co-authored-by: Sheetal Nandi <[email protected]>

* Use a more cross-architecture-friendly devcontainer image. (microsoft#2034)

* Fix nil pointer dereference in range formatting (microsoft#1993)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: DanielRosenwasser <[email protected]>
Co-authored-by: jakebailey <[email protected]>
Co-authored-by: Daniel Rosenwasser <[email protected]>
Co-authored-by: Copilot <[email protected]>

* Port missing `checkJs` logic (microsoft#2046)

* Ignore reparsed nodes when determining external module indicator (microsoft#2044)

* Fix various fuzzer-caught crashes in the parser (microsoft#2038)

* Fix moduleDetection for node18, fix __esModule in detect=force (microsoft#2045)

* Fix panic in syncmap on loading nil (microsoft#2056)

* Use accessors on `Node` instead of casts and field accesses (microsoft#2052)

* Add locks on concurrent alias following checker accesses under incremental mode (microsoft#2051)

* Don't add `export` modifier to `JSTypeAliasDeclaration` from `@callback` (microsoft#2063)

* Introduce GetECMALineOfPosition to avoid unused rune counting (microsoft#2065)

* Don't add `export` modifier to `KindCommonJSExport` reparsed nodes (microsoft#2066)

* Fix panic in inlay hints for tuple types (microsoft#2040)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Accurately recognize fourslash test as submodule (microsoft#2068)

* Implement auto-import code actions, port tests and fix some bugs (microsoft#2053)

* Port tsc --init (microsoft#2033)

* Make CheckerPool iteration concurrent by default (microsoft#2070)

* Use Microsoft build of Go in CI (microsoft#2069)

* Detect Windows junctions with GetFileAttributesEx (microsoft#2013)

* Fix CI cache workflow (microsoft#2071)

* Use information from contextual type in hovers/quick info (microsoft#2073)

* fix(2074): No quick info on function and other similar tokens (microsoft#2078)

* Unify locks used on checkers between exclusive pool borrows and EmitResolver scopes (microsoft#2080)

* Port non-baseline diagnostics tests (microsoft#2079)

* Use SkipTrivia instead of GetRangeOfTokenAtPosition where possible (microsoft#2089)

* Move unreachable checks to checker, allowing more AST reuse (microsoft#2067)

* Fix scanning of valid surrogate pairs (microsoft#2032)

* Fix misplaced parentheses in `Checker.isIndirectCall` (microsoft#2093)

* Various agent mode updates (microsoft#2094)

* Handle configuration changes in LSP for 'typescript.*' options. (microsoft#2088)

* Fix nil pointer dereference in getAdjustedLocation for type-only exports (microsoft#2090)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Fix nil pointer dereference in code actions when diagnostic code is nil (microsoft#2091)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jakebailey <[email protected]>

* Fully resolve LSP client caps to non-pointers, pass by context (microsoft#2095)

* Fix hover on `module.exports` (microsoft#2098)

* Accept and document jsdoc diffs, round 1 (microsoft#1426)

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Jake Bailey <[email protected]>

* Port baseline diagnostics tests (microsoft#2097)

* Clean up disk space in CI before running (microsoft#2103)

Co-authored-by: Copilot <[email protected]>

* Add GOBIN to PATH in CI (microsoft#2105)

* Make client requests type safe, unmarshal (microsoft#2099)

* Display inherited JSDoc documentation in quick info (microsoft#2111)

* Sort failingTests and manualTests in en-US (microsoft#2113)

* fix(2047): Incomplete declaration emit of callback tag with no return tag (microsoft#2100)

* Fix canHaveSyntheticDefault (microsoft#2101)

* Misc fixes (microsoft#2112)

* chore: fix incorrect function name in comment (microsoft#2109)

Signed-off-by: weifangc <[email protected]>

* Fix typedef binding with CJS `exports=` (microsoft#826)

* Provide Program diagnostics as push diags in tsconfig.json (microsoft#2118)

Co-authored-by: Copilot <[email protected]>

* Update dependencies (microsoft#2116)

* Remove copilot-setup-steps env var (microsoft#2124)

* Fix panic on negative parameterIndex in type predicate flow analysis (microsoft#2122)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: RyanCavanaugh <[email protected]>
Co-authored-by: Ryan Cavanaugh <[email protected]>

* Port tests for go to implementation and diff definitions tests (microsoft#2130)

* Partially fix multi-checker diagnostics consistency (microsoft#2134)

* Implement reportStyleChecksAsWarnings (microsoft#2132)

* Include docs on resolved client caps (microsoft#2135)

* Fix dynamic import grammar check (microsoft#2138)

* Refine LSP with our own types, generate more stuff (microsoft#2141)

* Display all symbol meanings in quick info (microsoft#2144)

* Multiproject requests like find all refs, rename and workspace symbols (microsoft#1991)

* Add stringer-alike String methods to non-string LSP enums (microsoft#2148)

* Enable localization (microsoft#2123)

* Port workspace symbols tests (microsoft#2146)

* Update readme, issue template (microsoft#2140)

* Ignore config port (microsoft#1755)

* fix(2157): jsdocfunction param is inferred as implicit any when directly assigned to module.exports (microsoft#2158)

* fixes after merge

* some more fixes

* more errors

* builds

* fmt

* fix nil pointer deref

* fix error messages

---------

Signed-off-by: dependabot[bot] <[email protected]>
Signed-off-by: weifangc <[email protected]>
Co-authored-by: Gabriela Araujo Britto <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: jakebailey <[email protected]>
Co-authored-by: andrewbranch <[email protected]>
Co-authored-by: Andrew Branch <[email protected]>
Co-authored-by: Andrew Branch <[email protected]>
Co-authored-by: Oleksandr T. <[email protected]>
Co-authored-by: Matt Bierner <[email protected]>
Co-authored-by: Ryan Cavanaugh <[email protected]>
Co-authored-by: DanielRosenwasser <[email protected]>
Co-authored-by: Daniel Rosenwasser <[email protected]>
Co-authored-by: Twacqwq <[email protected]>
Co-authored-by: Anders Hejlsberg <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Isabel Duan <[email protected]>
Co-authored-by: John Favret <[email protected]>
Co-authored-by: Wesley Wigham <[email protected]>
Co-authored-by: RyanCavanaugh <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: xu0o0 <[email protected]>
Co-authored-by: Sheetal Nandi <[email protected]>
Co-authored-by: Nathan Shively-Sanders <[email protected]>
Co-authored-by: weifangc <[email protected]>
Co-authored-by: Ryan Cavanaugh <[email protected]>
Co-authored-by: Nathan Whitaker <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants