ts-suppress 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 br0p0p
+
+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,70 @@
+# ts-suppress
+
+Incremental TypeScript strictness adoption via bulk error suppression.
+
+Instead of scattering `@ts-ignore` or `@ts-expect-error` comments throughout your codebase, `ts-suppress` captures all TypeScript errors into a single `.ts-suppressions.json` file. This lets you enable stricter compiler options immediately and fix errors at your own pace.
+
+## How It Works
+
+Each suppression is a fingerprint of a TypeScript error, consisting of:
+
+- **file** — relative path to the source file
+- **code** — TypeScript error code (e.g. `2322`)
+- **hash** — hex hash of the diagnostic message text
+- **scope** — dot-separated scope chain (e.g. `MyClass.myMethod`)
+
+The `check` command diffs the current diagnostics against the suppression file and reports:
+
+- **Unsuppressed errors** — new errors not yet in the suppression file
+- **Stale suppressions** — entries that no longer match any current error (i.e. errors that have been fixed)
+
+## Install
+
+```bash
+bun add -d ts-suppress
+```
+
+## Usage
+
+### `init`
+
+Create an empty `.ts-suppressions.json`:
+
+```bash
+bunx ts-suppress init
+```
+
+### `suppress`
+
+Snapshot all current TypeScript errors into `.ts-suppressions.json`:
+
+```bash
+bunx ts-suppress suppress
+```
+
+### `check`
+
+Verify that all errors are suppressed and no suppressions are stale. Exits non-zero on failure — useful in CI:
+
+```bash
+bunx ts-suppress check
+```
+
+### `update`
+
+Add new suppressions and remove stale ones in a single pass:
+
+```bash
+bunx ts-suppress update
+```
+
+Also available as `bunx ts-suppress fix`.
+
+## Typical Workflow
+
+1. Enable a stricter TypeScript option (e.g. `"strict": true`)
+2. Run `bunx ts-suppress suppress` to baseline all existing errors
+3. Commit `.ts-suppressions.json`
+4. Add `bunx ts-suppress check` to CI
+5. Fix errors over time — `check` will flag stale suppressions as you go
+6. Run `bunx ts-suppress update` to sync the suppression file after fixing errors

package/dist/cli.js

@@ -0,0 +1,63 @@
+import { parse } from "@bomb.sh/args";
+import { createProject } from "./project.js";
+import { runCheck } from "./commands/check.js";
+import { runInit } from "./commands/init.js";
+import { runSuppress } from "./commands/suppress.js";
+import { runUpdate } from "./commands/update.js";
+const VERSION = "0.2.0";
+const commands = [
+    ["init", "Create an empty .ts-suppressions.json file"],
+    ["suppress", "Snapshot all current TypeScript errors into .ts-suppressions.json"],
+    ["update", "Add new suppressions and remove stale ones (alias: fix)"],
+    ["check", "Check for unsuppressed errors and stale suppressions"],
+];
+function printHelp() {
+    const longest = Math.max(...commands.map(([name]) => name.length));
+    const lines = commands.map(([name, desc]) => `  ${name.padEnd(longest + 4)}${desc}`);
+    console.log(`ts-suppress v${VERSION}\nIncremental TypeScript strictness adoption via bulk error suppression\n\nCommands:\n${lines.join("\n")}\n\nRun ts-suppress <command> --help for details.`);
+}
+const args = parse(process.argv.slice(2), {
+    boolean: ["help", "version"],
+    alias: { h: "help", v: "version" },
+});
+const command = args._[0];
+if (args.version) {
+    console.log(VERSION);
+}
+else if (args.help || (!command && process.argv.length <= 2)) {
+    printHelp();
+}
+else if (command) {
+    switch (command) {
+        case "init": {
+            await runInit();
+            break;
+        }
+        case "suppress": {
+            const { project, projectRoot } = createProject(process.cwd());
+            await runSuppress(project, projectRoot);
+            break;
+        }
+        case "update":
+        case "fix": {
+            const { project, projectRoot } = createProject(process.cwd());
+            await runUpdate(project, projectRoot);
+            break;
+        }
+        case "check": {
+            const { project, projectRoot } = createProject(process.cwd());
+            const { exitCode } = await runCheck(project, projectRoot);
+            if (exitCode !== 0)
+                process.exit(exitCode);
+            break;
+        }
+        default: {
+            console.error(`Unknown command: ${command}`);
+            printHelp();
+            process.exit(1);
+        }
+    }
+}
+else {
+    printHelp();
+}

package/dist/commands/check.js

@@ -0,0 +1,28 @@
+import { collectDiagnostics } from "../diagnostics.js";
+import { readSuppressions, diffSuppressions } from "../suppressions.js";
+/**
+ * Core logic, extracted for testability.
+ * suppressionsRoot is where the suppression file is read from (may differ from projectRoot in tests).
+ */
+export async function runCheck(project, projectRoot, suppressionsRoot = projectRoot) {
+    const existing = await readSuppressions(suppressionsRoot);
+    const current = collectDiagnostics(project, projectRoot);
+    const { unsuppressed, stale } = diffSuppressions(existing, current);
+    if (unsuppressed.length > 0) {
+        console.error(`\n${unsuppressed.length} unsuppressed error(s):\n`);
+        for (const s of unsuppressed) {
+            console.error(`  TS${s.code} in ${s.file}`);
+        }
+    }
+    if (stale.length > 0) {
+        console.error(`\n${stale.length} stale suppression(s):\n`);
+        for (const s of stale) {
+            console.error(`  TS${s.code} in ${s.file}`);
+        }
+    }
+    const exitCode = unsuppressed.length > 0 || stale.length > 0 ? 1 : 0;
+    if (exitCode === 0) {
+        console.log("No unsuppressed errors or stale suppressions.");
+    }
+    return { exitCode, unsuppressed, stale };
+}

package/dist/commands/init.js

@@ -0,0 +1,5 @@
+import { writeSuppressions, SUPPRESSIONS_FILENAME } from "../suppressions.js";
+export async function runInit() {
+    await writeSuppressions(process.cwd(), []);
+    console.log(`Created ${SUPPRESSIONS_FILENAME}`);
+}

package/dist/commands/suppress.js

@@ -0,0 +1,12 @@
+import { collectDiagnostics } from "../diagnostics.js";
+import { writeSuppressions, SUPPRESSIONS_FILENAME } from "../suppressions.js";
+/**
+ * Core logic, extracted for testability.
+ * Accepts a ts-morph Project and roots separately so tests can pass in-memory projects.
+ * outputRoot is where the suppression file is written (may differ from projectRoot in tests).
+ */
+export async function runSuppress(project, projectRoot, outputRoot = projectRoot) {
+    const diagnostics = collectDiagnostics(project, projectRoot);
+    await writeSuppressions(outputRoot, diagnostics);
+    console.log(`Wrote ${diagnostics.length} suppression(s) to ${SUPPRESSIONS_FILENAME}`);
+}

package/dist/commands/update.js

@@ -0,0 +1,23 @@
+import { collectDiagnostics } from "../diagnostics.js";
+import { readSuppressions, writeSuppressions, diffSuppressions } from "../suppressions.js";
+/**
+ * Core logic, extracted for testability.
+ * Reads existing suppressions, diffs against current diagnostics,
+ * writes the updated file, and reports what changed.
+ */
+export async function runUpdate(project, projectRoot, outputRoot = projectRoot) {
+    const existing = await readSuppressions(outputRoot);
+    const current = collectDiagnostics(project, projectRoot);
+    const { unsuppressed: added, stale: removed } = diffSuppressions(existing, current);
+    await writeSuppressions(outputRoot, current);
+    if (added.length > 0) {
+        console.log(`Added ${added.length} new suppression(s)`);
+    }
+    if (removed.length > 0) {
+        console.log(`Removed ${removed.length} stale suppression(s)`);
+    }
+    if (added.length === 0 && removed.length === 0) {
+        console.log("Already up to date.");
+    }
+    return { added, removed, total: current.length };
+}

package/dist/diagnostics.js

@@ -0,0 +1,35 @@
+import { relative } from "node:path";
+import { hashMessage } from "./hash.js";
+import { buildScopePath } from "./scope.js";
+/**
+ * Collect all pre-emit diagnostics from a ts-morph Project as Suppression fingerprints.
+ * Project creation is the caller's responsibility — this enables in-memory testing.
+ */
+export function collectDiagnostics(project, projectRoot) {
+    const diagnostics = project.getPreEmitDiagnostics();
+    const suppressions = [];
+    for (const diag of diagnostics) {
+        const sourceFile = diag.getSourceFile();
+        if (!sourceFile)
+            continue;
+        const filePath = relative(projectRoot, sourceFile.getFilePath());
+        const code = diag.getCode();
+        const messageText = diag.getMessageText();
+        const message = typeof messageText === "string" ? messageText : messageText.getMessageText();
+        const start = diag.getStart();
+        let scope = "";
+        if (start != null) {
+            const node = sourceFile.getDescendantAtPos(start);
+            if (node) {
+                scope = buildScopePath(node);
+            }
+        }
+        suppressions.push({
+            file: filePath,
+            code,
+            hash: hashMessage(message),
+            scope,
+        });
+    }
+    return suppressions;
+}

package/dist/hash.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** Hash a diagnostic message text to a deterministic hex string */
+export function hashMessage(message) {
+    return createHash("sha256").update(message).digest("hex");
+}

package/dist/project.js

@@ -0,0 +1,24 @@
+import { Project } from "ts-morph";
+import ts from "typescript";
+import { dirname } from "node:path";
+/**
+ * Find the nearest tsconfig.json by walking up from the given directory.
+ * Uses TypeScript's own findConfigFile for correct resolution behavior.
+ */
+export function findTsConfig(cwd) {
+    const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json");
+    if (!configPath) {
+        throw new Error(`No tsconfig.json found starting from ${cwd}`);
+    }
+    return configPath;
+}
+/**
+ * Create a ts-morph Project from the nearest tsconfig.json.
+ * Returns the Project and the resolved project root (directory containing tsconfig.json).
+ */
+export function createProject(cwd) {
+    const tsConfigFilePath = findTsConfig(cwd);
+    const projectRoot = dirname(tsConfigFilePath);
+    const project = new Project({ tsConfigFilePath });
+    return { project, projectRoot };
+}

package/dist/scope.js

@@ -0,0 +1,54 @@
+// src/scope.ts
+import { Node } from "ts-morph";
+/**
+ * Build a dot-separated scope path by walking up the AST from a node.
+ * Returns empty string for module-level code.
+ *
+ * Examples:
+ *   - "MyClass.myMethod" for a method inside a class
+ *   - "processData" for a top-level function
+ *   - "handler" for an arrow function assigned to a const
+ *   - "MyClass.get:name" for a getter
+ *   - "" for module scope
+ */
+export function buildScopePath(node) {
+    const parts = [];
+    let current = node;
+    while (current) {
+        const name = getScopeName(current);
+        if (name != null) {
+            parts.unshift(name);
+        }
+        current = current.getParent();
+    }
+    return parts.join(".");
+}
+function getScopeName(node) {
+    if (Node.isFunctionDeclaration(node)) {
+        return node.getName() ?? null;
+    }
+    if (Node.isMethodDeclaration(node)) {
+        return node.getName();
+    }
+    if (Node.isClassDeclaration(node)) {
+        return node.getName() ?? null;
+    }
+    if (Node.isGetAccessorDeclaration(node)) {
+        return `get:${node.getName()}`;
+    }
+    if (Node.isSetAccessorDeclaration(node)) {
+        return `set:${node.getName()}`;
+    }
+    if (Node.isConstructorDeclaration(node)) {
+        return "constructor";
+    }
+    // Arrow function or function expression assigned to a variable
+    if (Node.isArrowFunction(node) || Node.isFunctionExpression(node)) {
+        const parent = node.getParent();
+        if (parent && Node.isVariableDeclaration(parent)) {
+            return parent.getName();
+        }
+        return null; // anonymous, no scope name
+    }
+    return null;
+}

package/dist/suppressions.js

@@ -0,0 +1,101 @@
+import { readFile, writeFile, access } from "node:fs/promises";
+import { resolve } from "node:path";
+export const SUPPRESSIONS_FILENAME = ".ts-suppressions.json";
+/** Compare function for deterministic sorting of suppressions */
+function compareSuppression(a, b) {
+    return (a.file.localeCompare(b.file) ||
+        a.code - b.code ||
+        a.hash.localeCompare(b.hash) ||
+        a.scope.localeCompare(b.scope));
+}
+/** Key without scope — used for grouping duplicates */
+function baseKey(s) {
+    return `${s.file}\0${s.code}\0${s.hash}`;
+}
+/** Key with scope — used for matching duplicates */
+function fullKey(s) {
+    return `${s.file}\0${s.code}\0${s.hash}\0${s.scope}`;
+}
+/** Count occurrences of each base key in a list */
+function countByBaseKey(list) {
+    const counts = new Map();
+    for (const s of list) {
+        const key = baseKey(s);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+}
+/** Read suppressions from .ts-suppressions.json in the given directory */
+export async function readSuppressions(projectRoot) {
+    const filePath = resolve(projectRoot, SUPPRESSIONS_FILENAME);
+    try {
+        await access(filePath);
+    }
+    catch {
+        return [];
+    }
+    const raw = await readFile(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    return data.suppressions;
+}
+/** Write suppressions to .ts-suppressions.json, sorted deterministically */
+export async function writeSuppressions(projectRoot, suppressions) {
+    const filePath = resolve(projectRoot, SUPPRESSIONS_FILENAME);
+    const sorted = [...suppressions].sort(compareSuppression);
+    const data = { suppressions: sorted };
+    await writeFile(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+/**
+ * Diff existing suppressions against current diagnostics.
+ *
+ * Matching strategy:
+ * - For unique { file, code, hash } tuples: match by base key only (scope is informational)
+ * - For duplicate { file, code, hash } tuples: match by full key including scope
+ *
+ * "Became duplicate" edge case: if existing has 1 entry for a base key but current has 2+,
+ * the existing suppression covers one occurrence; extras are reported as unsuppressed.
+ */
+export function diffSuppressions(existing, current) {
+    const existingCounts = countByBaseKey(existing);
+    const currentCounts = countByBaseKey(current);
+    // A base key is "duplicate" if EITHER list has more than one entry for it
+    const isDuplicate = (key) => (existingCounts.get(key) ?? 0) > 1 || (currentCounts.get(key) ?? 0) > 1;
+    // Build a pool of existing match counts keyed appropriately
+    const existingKeys = new Map();
+    for (const s of existing) {
+        const key = isDuplicate(baseKey(s)) ? fullKey(s) : baseKey(s);
+        existingKeys.set(key, (existingKeys.get(key) ?? 0) + 1);
+    }
+    // Match current diagnostics against existing suppressions
+    const unsuppressed = [];
+    const matchedKeys = new Map();
+    for (const s of current) {
+        const key = isDuplicate(baseKey(s)) ? fullKey(s) : baseKey(s);
+        const remaining = (existingKeys.get(key) ?? 0) - (matchedKeys.get(key) ?? 0);
+        if (remaining > 0) {
+            matchedKeys.set(key, (matchedKeys.get(key) ?? 0) + 1);
+        }
+        else {
+            unsuppressed.push(s);
+        }
+    }
+    // Find stale: existing entries not consumed by any current diagnostic
+    const currentKeySet = new Map();
+    for (const s of current) {
+        const key = isDuplicate(baseKey(s)) ? fullKey(s) : baseKey(s);
+        currentKeySet.set(key, (currentKeySet.get(key) ?? 0) + 1);
+    }
+    const staleConsumed = new Map();
+    const stale = [];
+    for (const s of existing) {
+        const key = isDuplicate(baseKey(s)) ? fullKey(s) : baseKey(s);
+        const available = (currentKeySet.get(key) ?? 0) - (staleConsumed.get(key) ?? 0);
+        if (available > 0) {
+            staleConsumed.set(key, (staleConsumed.get(key) ?? 0) + 1);
+        }
+        else {
+            stale.push(s);
+        }
+    }
+    return { unsuppressed, stale };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// src/types.ts
+export {};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "ts-suppress",
+  "version": "0.2.0",
+  "description": "Incremental TypeScript strictness adoption via bulk error suppression",
+  "keywords": [
+    "migration",
+    "strict",
+    "suppression",
+    "tanstack-intent",
+    "ts-ignore",
+    "typescript"
+  ],
+  "homepage": "https://github.com/br0p0p/ts-suppress#readme",
+  "bugs": {
+    "url": "https://github.com/br0p0p/ts-suppress/issues"
+  },
+  "license": "MIT",
+  "author": "br0p0p",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/br0p0p/ts-suppress.git"
+  },
+  "bin": {
+    "ts-suppress": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "prepublishOnly": "bun run build",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "knip": "knip",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "prepare": "husky",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bomb.sh/args": "^0.3.1",
+    "ts-morph": "^27.0.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^24",
+    "husky": "^9.1.7",
+    "knip": "^5.87.0",
+    "lint-staged": "^16.4.0",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.56.0",
+    "oxlint-tsgolint": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs}": "bun run lint",
+    "*": "oxfmt --no-error-on-unmatched-pattern"
+  }
+}

package/skills/ts-suppress/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ts-suppress
+description: Use when working with TypeScript error suppressions, enabling stricter tsconfig options incrementally, or managing .ts-suppressions.json files
+---
+
+# ts-suppress
+
+Incremental TypeScript strictness adoption via bulk error suppression. Instead of scattering `@ts-ignore` everywhere, ts-suppress captures all errors into a single `.ts-suppressions.json` file so you can enable strict options immediately and fix errors at your own pace.
+
+## Commands
+
+| Command                | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `ts-suppress init`     | Create an empty `.ts-suppressions.json` file                        |
+| `ts-suppress suppress` | Snapshot all current TypeScript errors into `.ts-suppressions.json` |
+| `ts-suppress check`    | Verify all errors are suppressed and none are stale (use in CI)     |
+| `ts-suppress update`   | Add new suppressions and remove stale ones (alias: `fix`)           |
+
+**Flags:** `--help` / `-h`, `--version` / `-v`
+
+## Typical Workflow
+
+1. Enable stricter TypeScript settings in `tsconfig.json` (e.g. `"strict": true`)
+2. Run `ts-suppress suppress` to capture all resulting errors as a baseline
+3. Commit `.ts-suppressions.json` to version control
+4. Add `ts-suppress check` to CI — fails on new unsuppressed errors or stale suppressions
+5. Fix errors incrementally; run `ts-suppress update` to sync the suppression file
+
+## Suppression File Format
+
+`.ts-suppressions.json` contains fingerprinted error entries:
+
+```json
+{
+  "suppressions": [
+    {
+      "file": "src/utils.ts",
+      "code": 2322,
+      "hash": "a1b2c3...",
+      "scope": "MyClass.myMethod"
+    }
+  ]
+}
+```
+
+- **file** — relative path to source file
+- **code** — TypeScript error code
+- **hash** — SHA256 of the diagnostic message text
+- **scope** — dot-separated scope chain (e.g. `MyClass.myMethod`, empty for module-level)
+
+## Requirements
+
+- TypeScript >= 5.9.3
+- A `tsconfig.json` in the project (ts-suppress walks up directories to find it)