Skip to content

fix(cli): upgrade reads each TypeScript file in its own grammar - #11863

Merged
josephfarina merged 3 commits into
mainfrom
fix/codemods-typescript-grammar
Nov 15, 2026
Merged

josephfarina merged 3 commits into
mainfrom
fix/codemods-typescript-grammar

Conversation

@josephfarina

@josephfarina josephfarina commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

User impact

astryx upgrade fails on a TypeScript project whose sources use ordinary TypeScript syntax. A .ts file with a type assertion (<Item>value), or a declaration file with a declaration that has no value (export const limit: number;), is reported as a parse error, and the run ends with Upgrade failed (exit 1) even when no codemod would change that file. The project cannot be upgraded until those files are moved out of --path.

Problem and solution fit

  • Why does it fail? The codemod runner parses every .ts file, declaration files included, with the TSX grammar.
  • Why does that harm the run? The TSX grammar reads <Item>value as JSX, and code may not declare a const without a value, so valid files do not parse; a file that does not parse is reported and fails the run (a codemod cannot prove an unparseable file needs no change).
  • Why does that matter? Valid source makes the upgrade unusable for the whole project.

The fix gives each file its own grammar: TSX for .tsx, TypeScript without JSX for .ts/.mts/.cts, TypeScript in declaration mode for a declaration file as TypeScript names one (.d.ts, .d.mts, .d.cts, or a .ts file whose name holds .d., such as styles.d.css.ts), and Babel for JavaScript as before. TypeScript allows JSX only in .tsx files, so a .ts file never needs the TSX grammar.

Expected behavior and authority

TypeScript's own rules: JSX is allowed only in .tsx files, and a declaration file holds declarations without values. The runner chose TSX for .ts files when it moved off the plain Babel grammar, which had no TypeScript at all; nothing in that change needed JSX in .ts files.

Smallest restoration

  • assets/codemods/run-codemod.mjs: one grammarOf(filePath) decides the grammar, and both the config codemod and the code codemod paths bind jscodeshift with it. A declaration file uses jscodeshift's own TypeScript parser options with the TypeScript plugin in declaration mode, built once on first use.
  • Supporting: the CLI's own ambient declaration for jscodeshift now says withParser takes a parser object as well as a parser's name, as jscodeshift does, and the codemod runners type the module with it. The published authoring types are unchanged.

Evidence

  • Reproduction before the change (current main): a project with lib/protocol.d.ts (export const MAX_ITEMS: number;) and lib/util.ts (<{id: string}>x), astryx upgrade --from 0.6.0 --path lib prints Missing initializer in const declaration and Unexpected token for both files under every codemod, then Found 0 changes across 0 files and Upgrade failed (exit 1).
  • Result after the change: both files parse; a codemod that names words skips them because they say none, a codemod that names none reads them without an error, and a codemod that changes them writes them in their own grammar (tests below).
  • Representative unchanged path: .tsx, .jsx, .js files bind the same parsers as before; the codemod, upgrade API and upgrade command suites pass unchanged (109 files, 1,291 tests).
  • Regression test: run-codemod.test.mjs adds a grammar table (arbitrary-extension declaration files included), a run over a type assertion and declaration files with and without declared words (no errors), and a rename codemod that changes a .ts type assertion and a .d.ts declaration in place. doc-loads.test.mjs lists the two parser modules the declaration grammar loads on first use.

Scope

Components: cli (codemod runner)

  • One defect is restored.
  • Separable contradictory or unsettled tagalongs were removed or split.
  • No new public API, visual representation, default, or interaction model is hidden under the bug-fix label.
  • Public text and artifacts contain no internal Meta context.

Testing

  • npx vitest run --project node packages/cli/assets/codemods packages/cli/api/upgrade packages/cli/clients/cli/commands/upgrade (109 files passed)
  • pnpm -F @astryxdesign/cli typecheck:strict
  • node .github/scripts/cli-api-types-verify.mjs

@vercel

vercel Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 15, 2026 12:00pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 15, 2026
@astracat-bot

astracat-bot Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 15, 2026, 12:17 PM UTC

@josephfarina

Copy link
Copy Markdown
Contributor Author

Packed-install check (same two files in lib/, astryx upgrade --from 0.6.0 --path lib):

  • current main's canary (0.7.17-canary.g64806d0): exit 1, 10 errors during codemods (Missing initializer in const declaration for the .d.ts, Unexpected token for the .ts), Upgrade failed.
  • this branch, packed and installed (0.7.17): exit 0, no errors, 11 codemods to run (dry run).

@github-actions

Copy link
Copy Markdown
Contributor

PR Analysis Report

🔎 Preview · b3f0c3c

Storybook · Sandbox · built from this PR's head

Package size: @astryxdesign/cli 4.83 MB packed (+552 B); no new dependencies.

Not run on this PR: add ci:run-visual for Visual, ci:run-a11y for Accessibility, ci:run-rtl for RTL.

Current run: CI concluded failure; parts of this report may be missing.


Generated by PR Enrichment workflow | View full report

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Requesting changes. The grammar fix works: both failing cases from the description now parse, and the existing upgrade suites pass unchanged. A CI test fails, and two claims about the fix do not match what the code does.

  • CI's test-node (6/7) job, and with it the aggregate test check, fails on packages/cli/foundation/doc-compiler/doc-loads.test.mjs:1379 because the two new requires in run-codemod.mjs:88-89 (@babel/parser and jscodeshift's ./parser/tsOptions.js) are missing from its inventory of modules that run code outside their static imports, so please add a RUNNERS entry for assets/codemods/run-codemod.mjs with exactly those two sites.
  • The changeset (line 5), the description and the grammarOf comment (run-codemod.mjs:57) say a generic arrow such as <T>(value: T) => value stopped astryx upgrade, but the previous TSX parser already reads it (on the base, a file holding only that arrow upgrades without an error), so please drop the generic arrow from those texts and retitle the test at run-codemod.test.mjs:199.
  • The title and the changeset's opening sentence promise that each TypeScript file is read in its own grammar, but grammarOf (run-codemod.mjs:64) recognises only .d.ts, .d.mts and .d.cts, so a TypeScript arbitrary-extension declaration file such as styles.d.css.ts still fails with Missing initializer in const declaration; either follow TypeScript's rule (for example /\.d\.([^/\\]+\.)?ts$|\.d\.[cm]ts$/ with a grammar-table case) or narrow the wording to those three extensions.
Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: a .ts file with a type assertion is reported as a parse error and the upgrade fails with exit 1. Verified: reproduced on the base (Unexpected token, Upgrade failed, exit 1).
  • Claim: a .ts file with a generic arrow is reported as a parse error. False: the base parses it, and a file holding only that arrow produces no error.
  • Claim: a declaration file with a value-less declaration is reported as a parse error. Verified: Missing initializer in const declaration on the base.
  • Claim: the cause is that every .ts file, declaration files included, is parsed with the TSX grammar. Verified: the base's runner chooses tsx for .tsx and .ts in both codemod paths.
  • Claim: each file gets its own grammar (TSX, TypeScript without JSX, declaration mode, Babel). Verified for the listed extensions by the grammar table; TypeScript's *.d.<ext>.ts declaration files are not covered (second finding).
  • Claim: one grammarOf decides, both config and code codemods bind with it, and the declaration parser is built once. Verified: run-codemod.mjs:63-98, :317, :544.
  • Claim: the CLI's ambient jscodeshift declaration accepts a parser object and the published authoring types are unchanged. Verified: jscodeshift.d.ts:13; the authoring type file is untouched and the packed type surface check passes.
  • Claim: the reproduction prints both errors, finds 0 changes and ends with Upgrade failed (exit 1). Verified: the errors appear under the five codemods that parse those files.
  • Claim: after the change both files parse, a codemod with declared words skips them, one without reads them, and one that changes them rewrites them in place. Verified: the new tests pass on the head and fail on the base; the same upgrade run exits 0.
  • Claim: .tsx, .jsx and .js keep their parsers and the codemod, upgrade API and upgrade command suites pass unchanged (109 files, 1,291 tests). Verified: 109 files, 1,291 passed, 2 expected failures; a CLI test outside those suites fails (first finding).
  • Claim: the strict CLI typecheck and the published type-surface check pass. Verified for the changed files; the type-surface check passes.
  • Claim: no new public API, default or interaction model, and no internal context. Verified.
  • File .changeset/upgrade-typescript-grammar.md: first finding.
  • File packages/cli/assets/codemods/run-codemod.mjs: all three findings (:57 comment, :64 declaration-file test, :88-89 unlisted requires).
  • File packages/cli/assets/codemods/run-codemod.test.mjs: clear apart from the generic-arrow wording in the first finding.
  • File packages/cli/assets/codemods/runner.mjs: clear.
  • File packages/cli/assets/codemods/integration-runner.mjs: clear.
  • File packages/cli/assets/codemods/jscodeshift.d.ts: clear.

Automated review (maintainer link)

A .ts file is TypeScript without JSX and a .d.ts file holds declarations,
but the codemod runner parsed both with the TSX grammar. A type assertion
(<Item>value), a generic arrow (<T>(value: T) => value) or a declaration
without a value (export const limit: number;) failed to parse, and a file
that fails to parse fails the upgrade even when no codemod would change it.

Each file now parses in its own grammar: TSX for .tsx, TypeScript for
.ts/.mts/.cts, TypeScript in declaration mode for .d.ts/.d.mts/.d.cts, and
Babel for JavaScript, as before.
The declaration-file grammar loads jscodeshift's Babel parser and its
TypeScript parser options on first use; the runtime-load list names them.
@josephfarina
josephfarina force-pushed the fix/codemods-typescript-grammar branch from b3f0c3c to 0d29c5a Compare November 15, 2026 11:41
…-arrow claim

A .ts file whose name holds .d. (an arbitrary-extension declaration file,
such as styles.d.css.ts) is a declaration file too. The TSX grammar already
read a generic arrow, so the fix and its tests name only the type assertion
and declarations without values.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving, pending CI: some required CI jobs had not finished on this head when this review was written.

All three points from the previous review are fixed: the load-inventory test now lists the two new requires, the generic-arrow claim is gone from the changeset, description and comment, and arbitrary-extension declaration files such as styles.d.css.ts now parse. On the base, astryx upgrade fails on a .ts type assertion or a value-less declaration in a declaration file; on this head the same run finishes cleanly, and the existing codemod and upgrade suites pass unchanged.

Claims and files checked

Review mode: full; reason: rebase

  • Changeset: upgrade reads a .ts file as TypeScript without JSX and a declaration file as declarations, as TypeScript does. Verified: grammarOf and parserFor in run-codemod.mjs, and the grammar table test, follow TypeScript's declaration-file naming rule.
  • Changeset: a type assertion in a .ts file, or a value-less declaration in a .d.ts, .d.mts, .d.cts or arbitrary-extension declaration file, no longer stops the run. Verified: an upgrade over .ts, .d.ts and .d.css.ts fixtures fails on the base and succeeds on the head; .d.mts and .d.cts files, which integration codemods that list those extensions read, fail on the base and parse on the head.
  • Changeset: a codemod changes such a file like any other. Verified: the rename test rewrites a .ts type assertion and a .d.ts declaration in place.
  • Changeset: .tsx and JavaScript read as before. Verified: .tsx, .jsx, .js, .mjs and .cjs bind the same parsers.
  • Description: valid TypeScript makes the upgrade fail with exit 1 even when no codemod would change the file. Verified on the base.
  • Description: the cause is the TSX grammar for every .ts file, declaration files included. Verified: the base chose tsx for .ts in both codemod paths.
  • Description: each file gets its own grammar (TSX, TypeScript without JSX for .ts/.mts/.cts, declaration mode for declaration files as TypeScript names them, Babel for JavaScript). Verified: grammar table test and the code.
  • Description: TypeScript allows JSX only in .tsx, so a .ts file never needs the TSX grammar. Verified: no repository TypeScript file that parsed before fails in the new grammar.
  • Description: the runner chose TSX for .ts files when it moved off the plain Babel grammar. Verified: that earlier change replaced a Babel-only choice for .ts with the TSX grammar.
  • Description: one grammarOf decides, both codemod paths bind with it, and the declaration parser is built once on first use. Verified: run-codemod.mjs:65-105, :324 and :551.
  • Description: the CLI's own jscodeshift declaration accepts a parser object, the runners type the module with it, and the published authoring types are unchanged. Verified: jscodeshift.d.ts:13, runner.mjs:578, integration-runner.mjs:43; the packaged type-surface check passes.
  • Description: on current main the reproduction prints both errors under every codemod, finds 0 changes and ends with Upgrade failed (exit 1). Verified: the errors appear under each of the five codemods that read those files.
  • Description: after the change both files parse; a codemod with declared words skips them, one without reads them, and one that changes them writes them in their own grammar. Verified: the new tests fail on the base and pass on the head.
  • Description: .tsx, .jsx and .js bind the same parsers, and the codemod, upgrade API and upgrade command suites pass unchanged (109 files, 1,291 tests). Verified: 109 files and 1,291 tests pass, with 2 expected failures.
  • Description: the regression tests add a grammar table, error-free runs and an in-place rename, and doc-loads.test.mjs lists the two parser modules. Verified: the inventory test passes on the head.
  • Description: the strict CLI typecheck and the published type-surface check pass. Verified: CI's typecheck job passed on this head, and the type-surface check passes.
  • Description: one defect is restored, with no tagalong, no new public API, default or interaction model, and no internal context. Verified.
  • File .changeset/upgrade-typescript-grammar.md: clear.
  • File packages/cli/assets/codemods/run-codemod.mjs: clear.
  • File packages/cli/assets/codemods/run-codemod.test.mjs: clear.
  • File packages/cli/assets/codemods/runner.mjs: clear.
  • File packages/cli/assets/codemods/integration-runner.mjs: clear.
  • File packages/cli/assets/codemods/jscodeshift.d.ts: clear.
  • File packages/cli/foundation/doc-compiler/doc-loads.test.mjs: clear.

Automated review (maintainer link)

@josephfarina
josephfarina merged commit ca9fee5 into main Nov 15, 2026
84 checks passed
@github-actions
github-actions Bot deleted the fix/codemods-typescript-grammar branch November 16, 2026 06:04

This branch was successfully deployed

1 active deployment
Preview — 7f23ec81 Deployed Nov 15, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant