obsidian-livesync/utilsdeno

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:

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:

  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:

  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:

  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:

  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:

  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:

  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:

  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.