ts-explainer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tsclear contributors
+
+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.

package/README.md

@@ -0,0 +1,160 @@
+# ts-explainer
+
+[![CI](https://github.com/woxlo1/ts-explainer/actions/workflows/ci.yml/badge.svg)](https://github.com/woxlo1/ts-explainer/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ts-explainer.svg)](https://www.npmjs.com/package/ts-explainer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> TypeScript compiler errors, explained in plain English.
+
+`ts-explainer` pipes between `tsc` and your terminal and rewrites cryptic TypeScript errors into clear, actionable explanations — without losing any information.
+
+---
+
+## The problem
+
+```
+src/api.ts(23,5): error TS2345: Argument of type '{ id: string; name: string; }' is not
+assignable to parameter of type 'User'. Type '{ id: string; name: string; }' is missing
+the following properties from type 'User': email, createdAt, updatedAt
+```
+
+What does that actually mean? What should you fix first?
+
+## The solution
+
+```
+$ npx tsc --noEmit | npx ts-explainer
+
+TS2345  src/api.ts:23:5
+  → You're calling a function with an argument of type '{ id: string; name: string; }',
+    but it expects type 'User'. Double-check the value you're passing in, or the
+    function's parameter type.
+```
+
+Same information, actually readable.
+
+---
+
+## Install
+
+```bash
+npm install -D ts-explainer
+```
+
+Or run without installing:
+
+```bash
+npx tsc --noEmit | npx ts-explainer
+```
+
+## Usage
+
+Pipe any `tsc` output into `ts-explainer`:
+
+```bash
+npx tsc --noEmit | npx ts-explainer
+```
+
+Works with any `tsc` flags you're already using:
+
+```bash
+npx tsc --noEmit --strict | npx ts-explainer
+npx tsc -p tsconfig.prod.json | npx ts-explainer
+```
+
+### Add to package.json
+
+```json
+{
+  "scripts": {
+    "typecheck": "tsc --noEmit | ts-explainer"
+  }
+}
+```
+
+Then run with:
+
+```bash
+npm run typecheck
+```
+
+### Unknown errors
+
+Errors that `ts-explainer` doesn't recognize yet are passed through unchanged — you never lose information from the original `tsc` output.
+
+---
+
+## Use as a library
+
+`ts-explainer` also exports its parser and explainer for programmatic use:
+
+```typescript
+import { parseTscOutput, explainAll } from "ts-explainer";
+
+const raw = `src/index.ts(1,1): error TS2304: Cannot find name 'fetchUser'.`;
+
+const diagnostics = parseTscOutput(raw);
+const explained = explainAll(diagnostics);
+
+console.log(explained[0].explanation);
+// → 'fetchUser' isn't defined anywhere TypeScript can see. This is usually
+//   a missing import, a typo, or a missing @types package for a third-party library.
+```
+
+Available exports:
+
+```typescript
+import {
+  parseTscOutput,      // string → ParsedDiagnostic[]
+  explainAll,          // ParsedDiagnostic[] → ClearedDiagnostic[]
+  explainDiagnostic,   // ParsedDiagnostic → ClearedDiagnostic
+  patterns,            // ErrorPattern[] — the full list of known patterns
+} from "ts-explainer";
+```
+
+---
+
+## Supported error codes
+
+| Code     | Meaning                                          |
+| -------- | ------------------------------------------------- |
+| TS2304   | Cannot find name (missing import / typo)          |
+| TS2307   | Cannot find module or its type declarations       |
+| TS2322   | Type is not assignable to target type             |
+| TS2339   | Property does not exist on type                   |
+| TS2345   | Argument type mismatch in a function call         |
+| TS2349   | Expression is not callable                        |
+| TS2352   | Type conversion may be a mistake                  |
+| TS2366   | Function missing ending return statement          |
+| TS2367   | Condition always returns same value (no overlap)  |
+| TS2511   | Cannot instantiate an abstract class              |
+| TS2531   | Object is possibly `null`                         |
+| TS2532   | Object is possibly `undefined`                    |
+| TS2540   | Cannot assign to a read-only property             |
+| TS2551   | Property doesn't exist — did you mean X?          |
+| TS2554   | Wrong number of arguments in a call               |
+| TS2741   | Required property missing on an object            |
+| TS2769   | No function overload matches the call             |
+| TS7006   | Parameter implicitly has an `any` type            |
+| TS7053   | Expression can't be used to index type            |
+| TS18048  | Value is possibly `undefined`                     |
+
+More patterns are added with every release. Open an issue or PR if you keep running into an error that isn't covered yet — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://www.conventionalcommits.org/). Version numbers are bumped at release time only — not on every commit. See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## Contributing
+
+Contributions are welcome! The most valuable thing you can add is a new error pattern explanation. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to add one, run tests, and how releases are cut.
+
+## License
+
+MIT © [woxlo1](https://github.com/woxlo1)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { parseTscOutput } from "./parser.js";
+import { explainAll } from "./explainer.js";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RED = "\x1b[31m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function main() {
+    const raw = await readStdin();
+    if (!raw.trim()) {
+        console.error(`${RED}ts-explainer:${RESET} no input received. Pipe tsc's output into this command, e.g.:\n  npx tsc --noEmit | npx ts-explainer`);
+        process.exit(1);
+    }
+    const diagnostics = parseTscOutput(raw);
+    if (diagnostics.length === 0) {
+        console.log(`${GREEN}ts-explainer:${RESET} no recognizable tsc errors found in input.`);
+        return;
+    }
+    const cleared = explainAll(diagnostics);
+    for (const d of cleared) {
+        console.log(`${BOLD}${RED}${d.code}${RESET} ${DIM}${d.file}:${d.line}:${d.column}${RESET}`);
+        console.log(`  ${CYAN}→${RESET} ${d.explanation}`);
+        if (!d.matchedPatternId) {
+            console.log(`  ${DIM}(no plain-language pattern for this one yet — raw message shown)${RESET}`);
+        }
+        console.log("");
+    }
+    console.log(`${DIM}${cleared.length} error(s) explained.${RESET}`);
+}
+main().catch((err) => {
+    console.error(`${RED}ts-explainer: unexpected error${RESET}`, err);
+    process.exit(1);
+});

package/dist/explainer.d.ts

@@ -0,0 +1,3 @@
+import type { ClearedDiagnostic, ParsedDiagnostic } from "./types.js";
+export declare function explainDiagnostic(diag: ParsedDiagnostic): ClearedDiagnostic;
+export declare function explainAll(diags: ParsedDiagnostic[]): ClearedDiagnostic[];

package/dist/explainer.js

@@ -0,0 +1,22 @@
+import { patterns } from "./patterns.js";
+export function explainDiagnostic(diag) {
+    const candidate = patterns.find((p) => p.code === diag.code);
+    if (candidate) {
+        const matched = diag.rawMessage.match(candidate.match);
+        if (matched) {
+            return {
+                ...diag,
+                explanation: candidate.explain(matched),
+                matchedPatternId: candidate.id,
+            };
+        }
+    }
+    return {
+        ...diag,
+        explanation: diag.rawMessage,
+        matchedPatternId: null,
+    };
+}
+export function explainAll(diags) {
+    return diags.map(explainDiagnostic);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { parseTscOutput } from "./parser.js";
+export { explainDiagnostic, explainAll } from "./explainer.js";
+export { patterns } from "./patterns.js";
+export type { ErrorPattern, ParsedDiagnostic, ClearedDiagnostic } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { parseTscOutput } from "./parser.js";
+export { explainDiagnostic, explainAll } from "./explainer.js";
+export { patterns } from "./patterns.js";

package/dist/parser.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedDiagnostic } from "./types.js";
+export declare function parseTscOutput(raw: string): ParsedDiagnostic[];

package/dist/parser.js

@@ -0,0 +1,23 @@
+// Matches tsc's default output format, e.g.:
+// src/index.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.
+const TSC_LINE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.+)$/;
+export function parseTscOutput(raw) {
+    const results = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trimEnd();
+        if (!trimmed)
+            continue;
+        const matched = trimmed.match(TSC_LINE);
+        if (!matched)
+            continue;
+        const [, file, lineStr, colStr, code, message] = matched;
+        results.push({
+            file,
+            line: Number(lineStr),
+            column: Number(colStr),
+            code,
+            rawMessage: message,
+        });
+    }
+    return results;
+}

package/dist/patterns.d.ts

@@ -0,0 +1,2 @@
+import type { ErrorPattern } from "./types.js";
+export declare const patterns: ErrorPattern[];

package/dist/patterns.js

@@ -0,0 +1,141 @@
+export const patterns = [
+    {
+        id: "type-not-assignable",
+        code: "TS2322",
+        match: /Type '(.+)' is not assignable to type '(.+)'\.?$/,
+        explain: (m) => `You're trying to use a value of type '${m[1]}' where type '${m[2]}' is expected. ` +
+            `Check the value you're assigning, or update the target type if '${m[1]}' should actually be allowed there.`,
+    },
+    {
+        id: "property-does-not-exist",
+        code: "TS2339",
+        match: /Property '(.+)' does not exist on type '(.+)'\.?$/,
+        explain: (m) => `You're accessing '.${m[1]}' on something typed as '${m[2]}', but that type has no such property. ` +
+            `This usually means a typo, a missing type definition, or the object hasn't been narrowed to the right type yet.`,
+    },
+    {
+        id: "possibly-undefined",
+        code: "TS18048",
+        match: /'(.+)' is possibly 'undefined'\.?$/,
+        explain: (m) => `'${m[1]}' might be 'undefined' at this point. ` +
+            `Add a check (like 'if (${m[1]})' or optional chaining '?.'), or use a non-null assertion '!' if you're certain it's always defined here.`,
+    },
+    {
+        id: "argument-mismatch",
+        code: "TS2345",
+        match: /Argument of type '(.+)' is not assignable to parameter of type '(.+)'\.?$/,
+        explain: (m) => `You're calling a function with an argument of type '${m[1]}', but it expects type '${m[2]}'. ` +
+            `Double-check the value you're passing in, or the function's parameter type.`,
+    },
+    {
+        id: "cannot-find-name",
+        code: "TS2304",
+        match: /Cannot find name '(.+)'\.?$/,
+        explain: (m) => `'${m[1]}' isn't defined anywhere TypeScript can see. ` +
+            `This is usually a missing import, a typo, or a missing @types package for a third-party library.`,
+    },
+    {
+        id: "object-possibly-null",
+        code: "TS2531",
+        match: /Object is possibly 'null'\.?$/,
+        explain: () => `This value could be 'null' here. ` +
+            `Add a check (like 'if (value !== null)') or optional chaining '?.' before using it, or use a non-null assertion '!' if you're certain it can't be null at this point.`,
+    },
+    {
+        id: "missing-required-properties",
+        code: "TS2741",
+        match: /Property '(.+)' is missing in type '(.+)' but required in type '(.+)'\.?$/,
+        explain: (m) => `The object you're providing (of type '${m[2]}') is missing the required property '${m[1]}' that '${m[3]}' expects. ` +
+            `Add '${m[1]}' to the object, or make it optional in the type definition if it shouldn't be required.`,
+    },
+    {
+        id: "wrong-argument-count",
+        code: "TS2554",
+        match: /Expected (\d+) arguments?, but got (\d+)\.?$/,
+        explain: (m) => `This function expects ${m[1]} argument(s), but it's being called with ${m[2]}. ` +
+            `Check the function's signature and make sure you're passing the right number of arguments.`,
+    },
+    {
+        id: "implicit-any-parameter",
+        code: "TS7006",
+        match: /Parameter '(.+)' implicitly has an '(.+)' type\.?$/,
+        explain: (m) => `The parameter '${m[1]}' doesn't have an explicit type, so TypeScript is falling back to '${m[2]}'. ` +
+            `Add a type annotation (e.g. '${m[1]}: string') to get proper type checking here.`,
+    },
+    {
+        id: "no-overload-matches",
+        code: "TS2769",
+        match: /No overload matches this call\.?$/,
+        explain: () => `None of this function's overloads accept the arguments you're passing. ` +
+            `Check the function's available signatures (hover over it in your editor) and compare them against what you're passing in — usually one argument's type is slightly off.`,
+    },
+    {
+        id: "did-you-mean",
+        code: "TS2551",
+        match: /Property '(.+)' does not exist on type '(.+)'\. Did you mean '(.+)'\?\.?$/,
+        explain: (m) => `'.${m[1]}' doesn't exist on type '${m[2]}'. TypeScript thinks you meant '.${m[3]}' — check for a typo.`,
+    },
+    {
+        id: "not-callable",
+        code: "TS2349",
+        match: /This expression is not callable\./,
+        explain: () => `You're trying to call something as a function, but its type says it isn't callable. ` +
+            `Check whether the variable actually holds a function, or if you're missing parentheses somewhere.`,
+    },
+    {
+        id: "possibly-undefined-access",
+        code: "TS2532",
+        match: /Object is possibly 'undefined'\.?$/,
+        explain: () => `This value might be 'undefined' at this point. ` +
+            `Add a check (like 'if (value !== undefined)') or use optional chaining '?.' before accessing it.`,
+    },
+    {
+        id: "readonly-cannot-assign",
+        code: "TS2540",
+        match: /Cannot assign to '(.+)' because it is a read-only property\.?$/,
+        explain: (m) => `'${m[1]}' is marked as 'readonly' and cannot be reassigned after initialization. ` +
+            `If you need to change this value, remove the 'readonly' modifier from the type definition.`,
+    },
+    {
+        id: "cannot-find-module",
+        code: "TS2307",
+        match: /Cannot find module '(.+)' or its corresponding type declarations\.?$/,
+        explain: (m) => `TypeScript can't find the module '${m[1]}'. ` +
+            `Check that the package is installed ('npm install ${m[1]}'), and if it's a third-party library, you may also need '@types/${m[1]}' for type declarations.`,
+    },
+    {
+        id: "type-has-no-index-signature",
+        code: "TS7053",
+        match: /Element implicitly has an 'any' type because expression of type '(.+)' can't be used to index type '(.+)'\./,
+        explain: (m) => `You're indexing into '${m[2]}' with a key of type '${m[1]}', but that type has no index signature. ` +
+            `Either add an index signature to the type, or use 'keyof' to constrain the key type.`,
+    },
+    {
+        id: "union-not-narrowed",
+        code: "TS2367",
+        match: /This condition will always return '(.+)' since the types '(.+)' and '(.+)' have no overlap\.?$/,
+        explain: (m) => `Comparing '${m[2]}' and '${m[3]}' will always be '${m[1]}' because these two types can never be equal. ` +
+            `This is usually a sign that a variable was narrowed to an unexpected type, or there's a logic error in your condition.`,
+    },
+    {
+        id: "missing-return-type",
+        code: "TS2366",
+        match: /Function lacks ending return statement and return type does not include 'undefined'\.?$/,
+        explain: () => `Not all code paths in this function return a value, but the return type doesn't include 'undefined'. ` +
+            `Either add a return statement at the end, or update the return type to include '| undefined'.`,
+    },
+    {
+        id: "abstract-class-instantiation",
+        code: "TS2511",
+        match: /Cannot create an instance of an abstract class\.?$/,
+        explain: () => `You're trying to use 'new' on an abstract class, which isn't allowed. ` +
+            `Abstract classes are meant to be extended, not instantiated directly — create a concrete subclass and instantiate that instead.`,
+    },
+    {
+        id: "conversion-may-be-mistake",
+        code: "TS2352",
+        match: /Conversion of type '(.+)' to type '(.+)' may be a mistake because neither type sufficiently overlaps with the other\./,
+        explain: (m) => `Casting '${m[1]}' to '${m[2]}' looks suspicious because these types don't share enough in common. ` +
+            `If you're sure about the cast, use 'unknown' as an intermediate step: '(value as unknown) as ${m[2]}'. Otherwise double-check your types.`,
+    },
+];

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export interface ErrorPattern {
+    /** Unique id for this pattern, used internally and in tests */
+    id: string;
+    /** TypeScript error code, e.g. TS2322 */
+    code: string;
+    /** Regex used to detect and capture details from the raw tsc message */
+    match: RegExp;
+    /** Builds a human-readable explanation from the regex match */
+    explain: (m: RegExpMatchArray) => string;
+}
+export interface ParsedDiagnostic {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    rawMessage: string;
+}
+export interface ClearedDiagnostic extends ParsedDiagnostic {
+    explanation: string;
+    matchedPatternId: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ts-explainer",
+  "version": "0.1.0",
+  "description": "Turns confusing TypeScript compiler errors into clear, human-readable explanations.",
+  "type": "module",
+  "bin": {
+    "ts-explainer": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["typescript", "cli", "error", "compiler", "devtools", "tsc", "errors"],
+  "license": "MIT",
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsx": "^4.19.0",
+    "vitest": "^2.1.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0"
+  }
+}