mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2026-06-18 20:30:15 +00:00
vorotamoroz
115 lines
5.0 KiB
Markdown
115 lines
5.0 KiB
Markdown
# Refactoring and Code Quality Utilities
|
|
|
|
This directory contains Deno-based scripts that utilise `ts-morph` to perform codebase-wide refactoring, code quality clean-up, and static analysis.
|
|
|
|
These utilities are designed to help maintain code quality, resolve compiler warnings, and ensure popout window compatibility in the Obsidian plug-in environment.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
To execute these scripts, you must have Deno installed on your system.
|
|
|
|
---
|
|
|
|
## General Usage
|
|
|
|
By default, all refactoring scripts run in **dry-run mode**. They will output the proposed changes to the console without modifying any files.
|
|
|
|
To apply the changes to the files, append the `'--run'` flag:
|
|
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env <script_name>.ts --run
|
|
```
|
|
|
|
---
|
|
|
|
## Utilities Reference
|
|
|
|
### 1. Global Wrapper Refactoring (`refactor-globals.ts`)
|
|
Converts standard global variable usages to compatibility wrappers to ensure safe operation when running in Obsidian popout windows (which run in separate window contexts).
|
|
|
|
* **Targets**: `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `requestAnimationFrame`, `cancelAnimationFrame`, `localStorage`, `navigator`, `location`, `window`, `globalThis`, and `document`.
|
|
* **Actions**:
|
|
* Replaces global namespace references (like `window` and `globalThis`) with `compatGlobal`.
|
|
* Replaces `document` with `_activeDocument` (from `@lib/common/coreEnvFunctions.ts`).
|
|
* Injects or updates the necessary imports in modified files.
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env refactor-globals.ts
|
|
```
|
|
|
|
### 2. Element Style Normalisation (`refactor-styles.ts`)
|
|
Converts direct style assignments on HTML/SVG elements to use the plug-in's `setCssStyles` helper.
|
|
|
|
* **Actions**:
|
|
* Replaces statements like `element.style.color = 'red';` with `element.setCssStyles({ color: 'red' });`.
|
|
* Groups multiple consecutive style assignments on the same element into a single call.
|
|
* Supports both static keys and computed bracket properties.
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env refactor-styles.ts
|
|
```
|
|
|
|
### 3. Redundant Assertions Cleanup (`refactor-assertions.ts`)
|
|
Finds and removes type assertions that are redundant because the expression already evaluates to the asserted type.
|
|
|
|
* **Actions**:
|
|
* Removes redundant `as Type` or `<Type>` assertions.
|
|
* Preserves critical literal assertions such as `as const` and `<const>`.
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env refactor-assertions.ts
|
|
```
|
|
|
|
### 4. Unused Code Refactoring (`refactor-unused.ts`)
|
|
Cleans up unused imports and catch variables to reduce bundle size and warnings.
|
|
|
|
* **Actions**:
|
|
* Converts unused catch variables to simple catch statements (e.g. `catch (error)` -> `catch`).
|
|
* Removes unused items in named imports, handling alias bindings (e.g. `import { A as B }`) correctly.
|
|
* Deletes empty import declarations resulting from the named import clean-up.
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env refactor-unused.ts
|
|
```
|
|
|
|
### 5. Explicit Any Detection (`detect-any.ts`)
|
|
Scans the codebase and logs all occurrences of explicit `any` types.
|
|
|
|
* **Actions**:
|
|
* Identifies uses of the `any` keyword in TypeScript and Svelte files.
|
|
* Logs the filename, line number, and matching code line for audit purposes.
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-env detect-any.ts
|
|
```
|
|
|
|
### 6. Import Normalisation (`normalise-imports.ts`)
|
|
Ensures that all import statements are standardised across the codebase, resolving paths to aliases such as `@lib/` and `@/` where applicable.
|
|
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env normalise-imports.ts
|
|
```
|
|
|
|
### 7. CLI Node.js Import Redirection (`refactor-cli-node-imports.ts`)
|
|
Redirects direct Node.js built-in module imports (like `fs` and `path`) within the CLI codebase to use a single barrel file (`src/apps/cli/node-compat.ts`).
|
|
|
|
* **Actions**:
|
|
* Finds imports of Node.js built-in APIs (`fs`, `fs/promises`, `path`, and `readline/promises`) in CLI source files.
|
|
* Replaces them with imports from the local `node-compat.ts` barrel file.
|
|
* This eliminates duplicate browser-targeted linter warnings on Node.js built-ins in the CLI workspace, keeping linter ignores consolidated.
|
|
* **Command**:
|
|
```bash
|
|
deno run --allow-read --allow-write --allow-env refactor-cli-node-imports.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Safety and Exclusions
|
|
|
|
* **Tests Excluded**: All scripts automatically skip files located in `_test/` or `testdeno/` folders, as well as files ending with `.spec.ts` or `.test.ts`.
|
|
* **Submodule Caution**: Some tools will run against the `src/lib/` submodule. Ensure you verify changes inside the submodule prior to committing.
|
|
* **Verification**: Always run `npm run check` and `npm run test:unit` after performing refactoring tasks to verify that type safety and tests remain intact.
|