declapract-typescript-ehmpathy 0.44.1 → 0.45.0

package/dist/practices/typescript/bad-practices/relative-imports/.declapract.readme.md

@@ -0,0 +1,27 @@
+this bad practice detects relative imports that traverse up directories (`../`) and can be replaced with the `@src/` path alias.
+
+why this matters:
+- relative paths are fragile and break when files are moved or reorganized
+- `@src/` alias provides stable, absolute imports from the src root
+- enables easier refactoring and code navigation
+- imports remain correct regardless of file location
+
+what it catches:
+- imports using `../` (e.g., `from '../utils/helper'`)
+- deeply nested relative imports (e.g., `from '../../../domain/objects'`)
+
+what it ignores:
+- same-directory imports (`./`) which are appropriate for local modules
+- files outside `src/` directory
+- imports already using `@src/` alias
+
+the fix automatically rewrites:
+```typescript
+// before
+import { helper } from '../utils/helper';
+import { thing } from '../../shared/thing';
+
+// after
+import { helper } from '@src/utils/helper';
+import { thing } from '@src/shared/thing';
+```

package/dist/practices/typescript/bad-practices/relative-imports/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,59 @@
+import { type FileCheckFunction, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects relative imports that should use @src alias
+ * .why = relative paths are fragile and break when files move
+ */
+
+// matches relative imports that go up directories (../)
+const RELATIVE_IMPORT_PATTERN = /from\s+['"](\.\.\/)+(.*?)['"]/g;
+
+export const check: FileCheckFunction = (contents, { relativeFilePath }) => {
+  if (!contents) throw new Error('does not match bad practice');
+
+  // skip if file is not in src/
+  if (!relativeFilePath?.startsWith('src/')) {
+    throw new Error('does not match bad practice');
+  }
+
+  // check for relative imports that go up directories (../)
+  const matches = contents.match(RELATIVE_IMPORT_PATTERN);
+  if (matches && matches.length > 0) {
+    return; // matches bad practice
+  }
+
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents, { relativeFilePath }) => {
+  if (!contents) return {};
+  if (!relativeFilePath?.startsWith('src/')) return {};
+
+  // calculate the path parts of the current file
+  const pathParts = relativeFilePath.split('/');
+  const srcIndex = pathParts.indexOf('src');
+
+  // replace relative imports with @src imports
+  const fixed = contents.replace(
+    /from\s+['"]((\.\.\/)+)(.*?)['"]/g,
+    (match, dots, _, importPath) => {
+      // count how many ../ we have
+      const upCount = (dots.match(/\.\.\//g) || []).length;
+
+      // get the directories between src/ and the current file
+      const currentDirParts = pathParts.slice(srcIndex + 1, -1);
+
+      // if going up more levels than we have directories, just use @src/importPath
+      if (upCount >= currentDirParts.length) {
+        return `from '@src/${importPath}'`;
+      }
+
+      // otherwise, calculate the remaining path after going up
+      const remainingParts = currentDirParts.slice(0, -upCount);
+      const targetPath = [...remainingParts, importPath].join('/');
+      return `from '@src/${targetPath}'`;
+    },
+  );
+
+  return { contents: fixed };
+};

package/dist/practices/typescript/best-practice/.declapract.readme.md

@@ -8,3 +8,8 @@ namely:
   - strict mode on tsc prevents a _ton_ of errors
   - without it, `Type | null` -> `Type` -> so you have a bunch of bugs whenever a value could be null but you dont expect it to be / realize it could be
     - it defeats the point of typechecking, really
+- absolute imports via @src/* path alias
+  - eliminates fragile relative paths (../../..)
+  - imports are stable regardless of file location
+  - easier refactoring and code navigation
+  - uses tsc-alias post-compilation to rewrite paths for node runtime

package/dist/practices/typescript/best-practice/package.json

@@ -1,13 +1,14 @@
 {
   "devDependencies": {
     "typescript": "@declapract{check.minVersion('5.4.5')}",
+    "tsc-alias": "@declapract{check.minVersion('1.8.10')}",
     "@tsconfig/node20": "@declapract{check.minVersion('20.1.5')}",
     "@tsconfig/strictest": "@declapract{check.minVersion('2.0.5')}",
     "@types/node": "@declapract{check.minVersion('22.15.21')}"
   },
   "scripts": {
     "build:clean": "rm dist/ -rf",
-    "build:compile": "tsc -p ./tsconfig.build.json",
+    "build:compile": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
     "build": "npm run build:clean && npm run build:compile && npm run build:artifact",
     "test:types": "tsc -p ./tsconfig.json --noEmit"
   }

package/dist/practices/typescript/best-practice/tsconfig.json

@@ -4,6 +4,10 @@
     "@tsconfig/node20/tsconfig.json"
   ],
   "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["src/*"]
+    },
     "importsNotUsedAsValues": "remove",
     "noPropertyAccessFromIndexSignature": false,
     "noUnusedLocals": false, // this is something a linter should warn on, not something a compiler should fail on

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -39,7 +39,7 @@
     "preversion": "npm run prepush",
     "postversion": "git push origin HEAD --tags --no-verify",
     "prepare:husky": "npx husky install && chmod ug+x .husky/*",
-    "prepare": "[ -d .git ] && npm run prepare:husky || exit 0"
+    "prepare": "[ -e .git ] && npm run prepare:husky || exit 0"
   },
   "dependencies": {
     "chalk": "4.1.2",
@@ -47,6 +47,8 @@
     "expect": "29.4.2",
     "flat": "5.0.2",
     "helpful-errors": "1.5.3",
+    "rhachet": "1.13.1",
+    "rhachet-roles-ehmpathy": "1.13.7",
     "simple-log-methods": "0.5.0",
     "yaml": "1.10.2"
   },