ts-abbr-skill 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# ts-abbr-skill
+
+<p align="center">
+  <img src="assets/logo.png" alt="ts-abbr-skill" width="480">
+</p>
+
+<p align="center">
+  <a href="README.zh-CN.md">🇨🇳 简体中文</a> |
+  <a href="README.md">🇺🇸 English</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/aShu-guo/ts-abbreviation-skill/releases"><img src="https://img.shields.io/github/v/release/aShu-guo/ts-abbreviation-skill?style=for-the-badge&color=blue" alt="GitHub Release"></a>
+  <a href="https://www.npmjs.com/package/ts-abbr-skill"><img src="https://img.shields.io/npm/v/ts-abbr-skill?style=for-the-badge&logo=npm&color=red" alt="npm version"></a>
+  <a href="https://github.com/aShu-guo/ts-abbreviation-skill/blob/main/LICENSE"><img src="https://img.shields.io/github/license/aShu-guo/ts-abbreviation-skill?style=for-the-badge&color=green" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ts-abbr-skill"><img src="https://img.shields.io/npm/dm/ts-abbr-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/aShu-guo/ts-abbreviation-skill/stargazers"><img src="https://img.shields.io/github/stars/aShu-guo/ts-abbreviation-skill?style=flat-square&logo=github" alt="GitHub stars"></a>
+</p>
+
+A Claude Code skill that makes generated/refactored TypeScript naming follow a shared abbreviation dictionary (`business` → `biz`, `context` → `ctx`, `configuration` → `cfg`, ...) instead of verbose full words.
+
+## Install
+
+```bash
+npx ts-abbr-skill
+```
+
+You'll be asked where to install:
+
+- **Project** — `./.claude/skills/ts-abbr-skill/` (recommended for team-shared conventions, commit this to your repo)
+- **Global** — `~/.claude/skills/ts-abbr-skill/` (applies to all your projects)
+
+Both can be selected at once. Re-running the installer is safe: your customized `config/default.config.json` and `dictionary/default.json` are never overwritten.
+
+## What it does
+
+- **When generating new code**: Claude checks the abbreviation dictionary before naming local variables/parameters and uses the abbreviated form when a match exists.
+- **When refactoring existing code**: batch renames go through an AST-aware rename script (`ts-morph`-based), never plain-text find/replace, so cross-file references stay correct. A `tsc --noEmit` check is required afterward before the rename is considered done.
+
+See [`skill/SKILL.md`](skill/SKILL.md) for the full rules Claude follows.
+
+## Built-in Dictionary (excerpt)
+
+| Full word | Abbreviation |
+|-----------|--------------|
+| business | biz |
+| context | ctx |
+| configuration / config | cfg |
+| parameter / parameters | param / params |
+| response | res |
+| request | req |
+| temporary | tmp |
+| reference | ref |
+| element | el |
+| repository | repo |
+| service | svc |
+| database | db |
+| application | app |
+| ... | ... |
+
+Full dictionary: [`skill/dictionary/default.json`](skill/dictionary/default.json)
+
+## Customize
+
+**Scope** — edit `<install target>/config/default.config.json`:
+
+```json
+{ "scope": ["variable", "parameter"], "exported": false }
+```
+
+`scope` accepts `variable`, `parameter`, `localFunction`, `class`. `exported` controls whether public/exported symbols are eligible (default `false`).
+
+**Project-specific additions** — add `.claude/ts-abbr.local.json` at your repo root; entries are merged on top of the default dictionary:
+
+```json
+{
+  "warehouse": "wh",
+  "department": "dept"
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run build   # bundles src/cli.ts -> dist/cli.js
+node dist/cli.js  # try the installer locally
+```
+
+For iterating on skill content, use a symlink instead of rebuilding:
+
+```bash
+ln -sfn /path/to/ts-abbreviation-skill/skill \
+  your-test-project/.claude/skills/ts-abbr-skill
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,102 @@
+# ts-abbr-skill
+
+<p align="center">
+  <img src="assets/logo.png" alt="ts-abbr-skill" width="480">
+</p>
+
+<p align="center">
+  <a href="README.zh-CN.md">🇨🇳 简体中文</a> |
+  <a href="README.md">🇺🇸 English</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/aShu-guo/ts-abbreviation-skill/releases"><img src="https://img.shields.io/github/v/release/aShu-guo/ts-abbreviation-skill?style=for-the-badge&color=blue" alt="GitHub Release"></a>
+  <a href="https://www.npmjs.com/package/ts-abbr-skill"><img src="https://img.shields.io/npm/v/ts-abbr-skill?style=for-the-badge&logo=npm&color=red" alt="npm version"></a>
+  <a href="https://github.com/aShu-guo/ts-abbreviation-skill/blob/main/LICENSE"><img src="https://img.shields.io/github/license/aShu-guo/ts-abbreviation-skill?style=for-the-badge&color=green" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ts-abbr-skill"><img src="https://img.shields.io/npm/dm/ts-abbr-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/aShu-guo/ts-abbreviation-skill/stargazers"><img src="https://img.shields.io/github/stars/aShu-guo/ts-abbreviation-skill?style=flat-square&logo=github" alt="GitHub stars"></a>
+</p>
+
+一个 Claude Code Skill，让生成/重构的 TypeScript 代码命名遵循统一的缩写词典（`business` → `biz`、`context` → `ctx`、`configuration` → `cfg` 等），而不是冗长的全称。
+
+## 安装
+
+```bash
+npx ts-abbr-skill
+```
+
+安装时会询问装到哪里：
+
+- **项目级** — `./.claude/skills/ts-abbr-skill/`（推荐团队共享，提交到仓库）
+- **全局** — `~/.claude/skills/ts-abbr-skill/`（适用于你所有的项目）
+
+两个选项可以同时勾选。重复运行安装器是安全的：目标路径下已存在的 `config/default.config.json` 和 `dictionary/default.json` 不会被覆盖。
+
+## 效果
+
+- **生成新代码时**：Claude 在命名局部变量/参数之前查缩写词典，有匹配则使用缩写形式。
+- **重构已有代码时**：批量改名强制走基于 AST 的重命名脚本（`ts-morph`），不允许纯文本替换，避免误改字符串字面量和跨作用域同名变量。改名后必须跑 `tsc --noEmit` 校验，不通过不算完成。
+
+完整规则见 [`skill/SKILL.md`](skill/SKILL.md)。
+
+## 内置词典摘录
+
+| 全称 | 缩写 |
+|------|------|
+| business | biz |
+| context | ctx |
+| configuration / config | cfg |
+| parameter / parameters | param / params |
+| response | res |
+| request | req |
+| temporary | tmp |
+| reference | ref |
+| element | el |
+| repository | repo |
+| service | svc |
+| database | db |
+| application | app |
+| ... | ... |
+
+完整词典见 [`skill/dictionary/default.json`](skill/dictionary/default.json)。
+
+## 自定义
+
+**调整生效范围** — 修改安装目录里的 `config/default.config.json`：
+
+```json
+{ "scope": ["variable", "parameter"], "exported": false }
+```
+
+`scope` 可选值：`variable`、`parameter`、`localFunction`、`class`。`exported` 控制是否对导出/公共符号生效（默认 `false`）。
+
+**添加项目专属缩写** — 在仓库根目录放 `.claude/ts-abbr.local.json`，词条会合并覆盖默认词典：
+
+```json
+{
+  "warehouse": "wh",
+  "department": "dept"
+}
+```
+
+## 本地开发
+
+```bash
+npm install
+npm run build        # 构建 src/cli.ts -> dist/cli.js
+node dist/cli.js     # 本地测试安装器
+```
+
+迭代调试 Skill 内容时，用 symlink 代替每次重新构建：
+
+```bash
+ln -sfn /path/to/ts-abbreviation-skill/skill \
+  your-test-project/.claude/skills/ts-abbr-skill
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import prompts from "prompts";
+
+// src/install.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var SKILL_NAME = "ts-abbreviation-skill";
+var PROTECTED_RELATIVE_PATHS = ["config/default.config.json", "dictionary/default.json"];
+function getSkillSourceDir() {
+  return path.join(__dirname, "..", "skill");
+}
+function getTargetDir(scope, cwd) {
+  const base = scope === "project" ? path.join(cwd, ".claude", "skills") : path.join(os.homedir(), ".claude", "skills");
+  return path.join(base, SKILL_NAME);
+}
+function copyRecursive(srcDir, destDir, protectedRelPaths, relPrefix = "") {
+  const skipped = [];
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      skipped.push(...copyRecursive(srcPath, destPath, protectedRelPaths, relPath));
+      continue;
+    }
+    if (protectedRelPaths.has(relPath) && fs.existsSync(destPath)) {
+      skipped.push(relPath);
+      continue;
+    }
+    fs.copyFileSync(srcPath, destPath);
+  }
+  return skipped;
+}
+function installSkill(scope, cwd = process.cwd()) {
+  const srcDir = getSkillSourceDir();
+  const targetDir = getTargetDir(scope, cwd);
+  const skippedExisting = copyRecursive(srcDir, targetDir, new Set(PROTECTED_RELATIVE_PATHS));
+  return { targetDir, skippedExisting };
+}
+
+// src/cli.ts
+async function main() {
+  console.log("ts-abbreviation-skill installer\n");
+  const { scopes } = await prompts({
+    type: "multiselect",
+    name: "scopes",
+    message: "Where should this skill be installed?",
+    choices: [
+      { title: "This project (./.claude/skills/)", value: "project", selected: true },
+      { title: "Global (~/.claude/skills/)", value: "global" }
+    ],
+    min: 1
+  });
+  if (!scopes || scopes.length === 0) {
+    console.log("No install scope selected, aborting.");
+    process.exit(1);
+  }
+  for (const scope of scopes) {
+    const { targetDir, skippedExisting } = installSkill(scope);
+    console.log(`
+\u2714 Installed to ${targetDir}`);
+    if (skippedExisting.length > 0) {
+      console.log(`  Kept existing customizations (not overwritten): ${skippedExisting.join(", ")}`);
+    }
+  }
+  console.log("\nNext steps:");
+  console.log("  - Restart/reopen Claude Code so it picks up the new skill.");
+  console.log("  - Customize scope/exported in <target>/config/default.config.json if needed.");
+  console.log("  - Add project-specific abbreviations via .claude/ts-abbreviation.local.json in your repo.");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "ts-abbr-skill",
+  "version": "1.0.0",
+  "description": "Claude Code skill that applies a configurable abbreviation dictionary (business→biz, context→ctx, ...) to TypeScript variable/parameter naming.",
+  "type": "module",
+  "bin": {
+    "ts-abbr-skill": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "keywords": [
+    "claude-code",
+    "skill",
+    "typescript",
+    "naming",
+    "abbreviation"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/prompts": "^2.4.9",
+    "ts-morph": "^23.0.0",
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ts-abbreviation-skill
+description: Use when writing or refactoring TypeScript variable, parameter, function, or class names — applies a configurable abbreviation dictionary (business→biz, context→ctx, configuration→cfg, etc.) so generated and refactored code matches the team's naming conventions.
+---
+
+# TS Abbreviation Skill
+
+## Overview
+
+Generated TypeScript code tends to use full, verbose English words for local names (`business`, `context`, `configuration`). This skill applies a shared abbreviation dictionary so naming stays short and consistent, in both newly generated code and refactors of existing code.
+
+## Config and Dictionary Lookup Order
+
+Before naming anything, resolve config and dictionary by merging, most specific first:
+
+1. Project override: `.claude/ts-abbreviation.local.json` in the current repo root (if present) — entries here are merged on top of the default dictionary/config, not a full replacement.
+2. Default config/dictionary shipped with this skill: `config/default.config.json`, `dictionary/default.json`.
+
+Default config (`config/default.config.json`):
+```json
+{
+  "scope": ["variable", "parameter"],
+  "exported": false
+}
+```
+
+- `scope`: which kinds of identifiers this applies to. Possible values: `variable`, `parameter`, `localFunction`, `class`. Only apply abbreviations to kinds listed here.
+- `exported`: whether exported/public symbols (exported consts, public class members, public function names) are in scope. Default `false` — never abbreviate a symbol that's part of a public API unless the project config explicitly sets `exported: true`.
+
+If the project has no `.claude/ts-abbreviation.local.json`, use the defaults as-is.
+
+## Mode 1: Generating New Code
+
+When about to name a new local variable, parameter, (optionally) local function, or class — per the resolved `scope` — look it up in the merged dictionary. If a whole-word match exists (case-sensitively adapting to camelCase/PascalCase as needed), use the abbreviation instead of the full word. Compound identifiers should abbreviate the matched segment only, keeping the rest of the identifier as-is (e.g. `businessContext` → `bizCtx`, `userConfiguration` → `userCfg`).
+
+Do not abbreviate:
+- Symbols outside the configured `scope`
+- Exported/public symbols unless `exported: true` is configured
+- Identifiers where abbreviating would collide with an existing name in the same scope
+
+**This is a two-pass task, not a one-pass one.** First draft the code naturally. Then, before finishing, do a second pass: enumerate *every* declared identifier in what you just wrote — every parameter, and every local variable (`const`/`let` inside the function body), regardless of whether that word appeared in the user's request — and check each one against the dictionary independently. It's easy to abbreviate the parameters (because they're named right there in the request) and forget local variables the code introduces on its own (intermediate results, loop variables, destructured values). Both are in the default `scope` and both need the same check.
+
+For example, in a function that takes `configuration` and an `identifier` and returns a `message`, the parameters *and* any local variable holding an intermediate value (e.g. a fetched record, a formatted string) all need the same dictionary lookup — not just the ones named in the prompt. Type/class names and exported symbol names are the only things that stay full by default (see `scope`/`exported` above).
+
+## Mode 2: Refactoring Existing Code (batch rename)
+
+Renaming an existing identifier across a codebase is only safe if every reference updates together. **Never use plain-text `grep`/`sed`/find-and-replace to rename identifiers** — it will corrupt string literals, comments, unrelated identically-named locals in other scopes, and any partial-word matches.
+
+Instead:
+
+1. Identify the exact declaration site (file, line, column) of the symbol to rename.
+2. Use `scripts/rename-with-ts-morph.ts` to perform an AST-aware rename — it resolves the symbol via the TypeScript compiler API and updates every reference consistently.
+   ```bash
+   npx tsx scripts/rename-with-ts-morph.ts --file src/foo.ts --line 12 --col 7 --newName bizCtx
+   ```
+   (Requires `ts-morph` as a dependency in the target project — install with `npm i -D ts-morph` if not already present.)
+3. After renaming, run `tsc --noEmit` in the target project and confirm it exits with no errors before considering the rename complete. Do not report a rename as done without this check passing — if it fails, fix the fallout (e.g. missed re-export) before finishing.
+
+## Common Mistakes
+
+- Abbreviating an exported API name because it "looked local" — check `scope`/`exported` config first.
+- Using sed/grep-based renames for "just one variable" — even single renames can hit false positives (e.g. a `context` string literal or an unrelated `context` param in another function).
+- Skipping the `tsc --noEmit` check after a rename because "it looked like a simple change."

package/skill/config/default.config.json

@@ -0,0 +1,4 @@
+{
+  "scope": ["variable", "parameter"],
+  "exported": false
+}

package/skill/config/schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ts-abbreviation-skill config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "scope": {
+      "type": "array",
+      "description": "Identifier kinds this skill is allowed to abbreviate.",
+      "items": {
+        "type": "string",
+        "enum": ["variable", "parameter", "localFunction", "class"]
+      },
+      "minItems": 1
+    },
+    "exported": {
+      "type": "boolean",
+      "description": "Whether exported/public symbols may be abbreviated. Defaults to false."
+    }
+  }
+}

package/skill/dictionary/default.json

@@ -0,0 +1,100 @@
+{
+  "business": "biz",
+  "context": "ctx",
+  "configuration": "cfg",
+  "config": "cfg",
+  "parameter": "param",
+  "parameters": "params",
+  "argument": "arg",
+  "arguments": "args",
+  "temporary": "tmp",
+  "reference": "ref",
+  "references": "refs",
+  "element": "el",
+  "elements": "els",
+  "index": "idx",
+  "indexes": "idxs",
+  "indices": "idxs",
+  "value": "val",
+  "values": "vals",
+  "message": "msg",
+  "messages": "msgs",
+  "response": "res",
+  "request": "req",
+  "callback": "cb",
+  "attribute": "attr",
+  "attributes": "attrs",
+  "property": "prop",
+  "properties": "props",
+  "environment": "env",
+  "directory": "dir",
+  "directories": "dirs",
+  "document": "doc",
+  "documents": "docs",
+  "component": "comp",
+  "utility": "util",
+  "utilities": "utils",
+  "controller": "ctrl",
+  "repository": "repo",
+  "database": "db",
+  "identifier": "id",
+  "identifiers": "ids",
+  "number": "num",
+  "numbers": "nums",
+  "string": "str",
+  "strings": "strs",
+  "object": "obj",
+  "objects": "objs",
+  "array": "arr",
+  "arrays": "arrs",
+  "boolean": "bool",
+  "booleans": "bools",
+  "function": "fn",
+  "functions": "fns",
+  "variable": "var",
+  "variables": "vars",
+  "current": "cur",
+  "previous": "prev",
+  "initialize": "init",
+  "initialization": "init",
+  "authentication": "auth",
+  "authorization": "authz",
+  "administrator": "admin",
+  "application": "app",
+  "package": "pkg",
+  "source": "src",
+  "destination": "dest",
+  "description": "desc",
+  "information": "info",
+  "language": "lang",
+  "library": "lib",
+  "libraries": "libs",
+  "specification": "spec",
+  "specifications": "specs",
+  "structure": "struct",
+  "synchronize": "sync",
+  "synchronization": "sync",
+  "transaction": "txn",
+  "transactions": "txns",
+  "coordinate": "coord",
+  "coordinates": "coords",
+  "column": "col",
+  "columns": "cols",
+  "position": "pos",
+  "dimension": "dim",
+  "dimensions": "dims",
+  "maximum": "max",
+  "minimum": "min",
+  "average": "avg",
+  "total": "sum",
+  "increment": "inc",
+  "decrement": "dec",
+  "expression": "expr",
+  "statement": "stmt",
+  "declaration": "decl",
+  "definition": "def",
+  "implementation": "impl",
+  "instance": "inst",
+  "namespace": "ns",
+  "seconds": "secs"
+}

package/skill/scripts/rename-with-ts-morph.ts

@@ -0,0 +1,74 @@
+import path from 'node:path'
+import { Project, SyntaxKind } from 'ts-morph'
+
+interface RenameArgs {
+  file: string
+  line: number
+  col: number
+  newName: string
+  tsconfig?: string
+}
+
+function parseArgs(): RenameArgs {
+  const argv = process.argv.slice(2)
+  const raw: Record<string, string> = {}
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg.startsWith('--')) {
+      raw[arg.slice(2)] = argv[i + 1]
+      i++
+    }
+  }
+
+  const { file, line, col, newName, tsconfig } = raw
+  if (!file || !line || !col || !newName) {
+    console.error(
+      'Usage: rename-with-ts-morph --file <path> --line <n> --col <n> --newName <name> [--tsconfig <path>]',
+    )
+    process.exit(1)
+  }
+
+  return {
+    file,
+    line: Number(line),
+    col: Number(col),
+    newName,
+    tsconfig,
+  }
+}
+
+function main() {
+  const { file, line, col, newName, tsconfig } = parseArgs()
+
+  const project = new Project({
+    tsConfigFilePath: path.resolve(tsconfig ?? 'tsconfig.json'),
+  })
+
+  const filePath = path.resolve(file)
+  const sourceFile = project.getSourceFileOrThrow(filePath)
+
+  const pos = sourceFile.compilerNode.getPositionOfLineAndCharacter(line - 1, col - 1)
+  const node = sourceFile.getDescendantAtPos(pos)
+  if (!node) {
+    console.error(`No node found at ${file}:${line}:${col}`)
+    process.exit(1)
+  }
+
+  const identifierNode =
+    node.getKind() === SyntaxKind.Identifier ? node : node.getFirstAncestorByKind(SyntaxKind.Identifier)
+  if (!identifierNode) {
+    console.error(`No identifier found at ${file}:${line}:${col}`)
+    process.exit(1)
+  }
+
+  const identifier = identifierNode.asKindOrThrow(SyntaxKind.Identifier)
+  const oldName = identifier.getText()
+  identifier.rename(newName)
+  project.saveSync()
+
+  console.log(`Renamed "${oldName}" -> "${newName}" at ${file}:${line}:${col} (all references updated).`)
+  console.log('Next: run `tsc --noEmit` to confirm the rename did not break anything.')
+}
+
+main()