Skip to content

CLAUDE.md

Latest commit

 

History

History
72 lines (52 loc) · 3.6 KB

CLAUDE.md

File metadata and controls

72 lines (52 loc) · 3.6 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A VS Code extension that adds customizable aliases and tooltips to files/folders in the explorer tree. Aliases are stored in JSON config files (folder-alias.json / private-folder-alias.json) at the workspace root or .vscode/ directory.

Commands

pnpm build          # Build with tsdown → dist/index.cjs
pnpm dev            # Build in watch mode with sourcemaps
pnpm lint           # ESLint (antfu config, double quotes, semicolons)
pnpm typecheck      # tsc --noEmit
pnpm test           # vitest
pnpm pack           # Package .vsix (no dependencies bundled)

Architecture

The extension uses reactive-vscode for lifecycle and reactive state management.

Entry (src/index.ts): defineExtension iterates workspace folders, creates a useFileAlias instance per folder, and registers commands.

Core flow:

  • src/file-alias.ts — useFileAlias() wires up a FileSystemWatcher (via useFileSystemWatcher) on the workspace folder to detect config file changes, creates a FileDecorationProvider that reads merged config to supply badges/tooltips, and exposes an event emitter for decoration updates.
  • src/hooks/useConfig.ts — useConfig() loads public and private JSON configs into reactive refs, provides resetConfig() (re-read from disk), and savePublic()/savePrivate() (write back, preferring .vscode/ location if the file already exists there).
  • src/utils/file.util.ts — Low-level file I/O: reads config with .vscode priority over root, writes JSON with destr for safe parsing.
  • src/command/add-alias.command.ts — Prompts user for scope (public/private) and alias text via QuickPick + InputBox, updates the appropriate config ref, saves, and fires the decoration change event.
  • src/command/refresh-aliases.command.ts — Re-reads both config files from disk.

Generated code: src/generated/meta.ts is auto-generated by vscode-ext-gen (runs during pnpm install via the prepare script). Do not edit manually.

Key Conventions

  • Build tool: tsdown (outputs CJS to dist/index.cjs; package.json main must match)
  • Linting: @antfu/eslint-config with stylistic (double quotes, semicolons) and JSONC support
  • Reactive primitives (ref, computed, useCommand, useFileSystemWatcher, defineLogger) come from reactive-vscode
  • The vscode module is externalized at build time (never bundled)

Commit Convention

This project enforces Conventional Commits via commitlint and husky. Every commit message MUST follow this format:

<type>(<scope>): <subject>

<body>

<footer>

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Rules:

  • The subject line MUST start with a type followed by : (e.g., feat: add new feature)
  • The scope is optional but must be in parentheses after the type (e.g., fix(config): fix .vscode path)
  • The body is optional but MUST be separated from the subject by a blank line
  • The footer is optional but MUST be separated from the body by a blank line
  • The commit-msg hook will REJECT any commit that does not follow this convention
  • ALL commits, including those made by Claude Code, must pass commitlint validation

Examples:

feat: add delete alias command
fix: decode URI-encoded path segments
docs: update README with current architecture
refactor: simplify findInstanceByUri with es-toolkit maxBy
build: add changelogen and configure release flow
chore(release): v1.0.3