declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/utils/defineExpectedNpmrcContents.ts

@@ -0,0 +1,103 @@
+/**
+ * .what = the base `.npmrc` lines every node repo carries, order-inert
+ * .why  = one source for both `check` and `fix`, so the gate and the repair can
+ *         never disagree about what the file should hold. inlined here rather than
+ *         read from a sibling template so there is a single source (mirrors
+ *         `defineExpectedGitignoreContents`, whose declaration carries no template
+ *         file either).
+ */
+export const npmrcBaseLines: readonly string[] = [
+  'engine-strict=true',
+  'save-exact=true',
+  'message=%s 🎉',
+];
+
+/**
+ * .what = the hoisted-linker lines an expo repo layers atop the base `.npmrc`
+ * .why  = `node-linker=hoisted` flattens node_modules — create-expo-app's OWN
+ *         default for pnpm, and the documented fallback when isolated installs
+ *         break metro/react-native native-module lookup. SDK 54+ supports pnpm's
+ *         isolated default for most packages, so the forced-vs-opt-in POLICY is a
+ *         wisher-deferred fulcrum (see `howto.pnpm-expo-hoisted-linker.md`); the
+ *         findsert delivers create-expo-app's default shape append-only until the
+ *         wisher rules. these are findserted PER-LINE (append each absent line),
+ *         like `npmrcBaseLines` and `defineExpectedGitignoreContents` — so a line
+ *         ADDED here later (e.g. a new `public-hoist-pattern[]`) still reaches an
+ *         already-hoisted consumer on the next `declapract fix`, rather than a skip
+ *         because a block-level sentinel was already present. no line's ORDER
+ *         carries load (unlike `.gitignore`'s negations), so a per-line union is
+ *         safe and removes the asymmetry with the base-line findsert below.
+ */
+export const npmrcExpoHoistLines: readonly string[] = [
+  '# hoisted linker flattens node_modules — create-expo-app default for pnpm,',
+  '# the documented fallback when isolated installs break metro native lookup',
+  'node-linker=hoisted',
+  'public-hoist-pattern[]=*expo*',
+  'public-hoist-pattern[]=*react-native*',
+  'public-hoist-pattern[]=@react-native/*',
+  'public-hoist-pattern[]=metro*',
+  'public-hoist-pattern[]=*metro-*',
+];
+
+/**
+ * .what = emits the `.npmrc` the node practice declares, given the repo's extant one
+ * .why  = a FINDSERT by construction — the file's own lines are preserved and only
+ *         MISSING declared lines are appended, so no line is ever dropped. this is
+ *         what forecloses the narrow-scope strip: under `declapract fix --practice
+ *         node` the expo signal goes dark (`projectPractices === ['node']`), so the
+ *         declared set is just the base lines — but because the fix only APPENDS
+ *         what is absent (never overwrites), a correctly-hoisted `.npmrc` is left
+ *         intact rather than reverted to base. the whole hazard class is gone, not
+ *         merely characterized.
+ * .why  = mirrors `defineExpectedGitignoreContents` (union-not-clobber). a repo's
+ *         own custom `.npmrc` lines survive for the same reason a repo's custom
+ *         `.gitignore` ignores do.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own
+ *         output — without both, `declapract fix` would rewrite this file forever.
+ */
+export const defineExpectedNpmrcContents = (input: {
+  contents: string | null;
+  projectPractices: string[];
+}): string => {
+  const isExpo = input.projectPractices.includes('cicd-app-react-native-expo');
+
+  // the repo's extant lines, trailing blank(s) dropped (one trailing newline re-added below)
+  const extant = (input.contents ?? '').replace(/\n+$/, '');
+  const lines = extant === '' ? [] : extant.split('\n');
+
+  // findsert each base line (append if absent — never remove, never reorder)
+  const withBase = npmrcBaseLines.reduce<string[]>(
+    (acc, line) => (acc.includes(line) ? acc : [...acc, line]),
+    lines,
+  );
+
+  // a consumer who explicitly set a NON-hoisted linker (e.g. `node-linker=isolated`,
+  // pnpm's SDK-54 default) has OPTED OUT — respect it. do NOT append `node-linker=hoisted`
+  // (which would leave two rival `node-linker=` directives), and skip the whole hoist block:
+  // the hoist is create-expo-app's default, OFFERED not imposed over an explicit choice.
+  const hasOptedOutLinker = withBase.some(
+    (line) => line.startsWith('node-linker=') && line !== 'node-linker=hoisted',
+  );
+  const wantsHoist = isExpo && !hasOptedOutLinker;
+
+  // findsert each expo hoist line PER-LINE when wanted (append if absent). a blank
+  // separator precedes the block ONLY on a fresh insert — i.e. when NONE of the
+  // hoist lines are present yet — so an already-hoisted file gains a newly-added
+  // hoist line at the tail without a second separator, and a bare file gets the
+  // block set off from the base lines exactly once.
+  const anyHoistPresent = npmrcExpoHoistLines.some((line) =>
+    withBase.includes(line),
+  );
+  const withSeparator =
+    wantsHoist && !anyHoistPresent && withBase.length > 0
+      ? [...withBase, '']
+      : withBase;
+  const withHoist = wantsHoist
+    ? npmrcExpoHoistLines.reduce<string[]>(
+        (acc, line) => (acc.includes(line) ? acc : [...acc, line]),
+        withSeparator,
+      )
+    : withSeparator;
+
+  return `${withHoist.join('\n')}\n`;
+};

package/dist/utils/getAllPracticesForUsecase.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'fs';
+import yaml from 'yaml';
+
+/**
+ * .what = expands a usecase's FULL practice set, per `extends`, exactly as declapract's
+ *         `readUseCaseDeclarations` does.
+ * .why  = both the platform-baseline drift guard and the extends-refactor characterization
+ *         test must reason about a usecase's RESOLVED practices, not its raw `.practices`
+ *         list. declapract's `extends` is a NON-TRANSITIVE union: a usecase that extends X
+ *         pulls X's OWN base `.practices` (never X's own resolved-with-extends set), then
+ *         dedupes by name (readUseCaseDeclarations.js: `hydratedPractices.push(...extendedUseCase.practices)`
+ *         + `uniqBy(..., name)`). this util mirrors that one algorithm so a test can never
+ *         drift from the tool's real expansion.
+ * .note = non-transitive is the subtlety that carries the load: if A extends B and B extends
+ *         C, then A does NOT inherit C through B — A must extend C directly. this is why
+ *         `lambda-service-with-rds` carries a `# declapract#17` double-extends today.
+ */
+
+interface UsecaseDefinition {
+  extends?: string[];
+  practices: string[];
+}
+
+const readUsecases = (usecasesYmlPath: string): Record<string, UsecaseDefinition> =>
+  yaml.parse(readFileSync(usecasesYmlPath, 'utf-8'))['use-cases'];
+
+/**
+ * .what = the resolved, deduped practice-name set for one usecase (extends applied)
+ */
+export const getAllPracticesForUsecase = (input: {
+  usecasesYmlPath: string;
+  usecase: string;
+}): string[] => {
+  const usecases = readUsecases(input.usecasesYmlPath);
+  const definition = usecases[input.usecase];
+  if (!definition)
+    throw new Error(`no usecase named '${input.usecase}' in ${input.usecasesYmlPath}`);
+
+  // each extended usecase contributes its OWN base practices (non-transitive), exactly
+  // as declapract does — flatMap keeps this immutable (no push onto a const array)
+  const extendedPractices = (definition.extends ?? []).flatMap((extendedName) => {
+    const extended = usecases[extendedName];
+    if (!extended)
+      throw new Error(
+        `usecase '${input.usecase}' extends non-existent usecase '${extendedName}'`,
+      );
+    return extended.practices;
+  });
+
+  // the usecase's own base practices come first, then the extended ones; dedupe by name
+  // (order-independent — callers compare as sorted sets)
+  return [...new Set([...definition.practices, ...extendedPractices])];
+};

package/dist/utils/isDeferredToDeprecatedDirMove.ts

@@ -0,0 +1,37 @@
+/**
+ * .what = the deprecated source dirs whose files a peer dir-move bad-practice
+ *         RELOCATES (logic-dir, data-dir, domain-dir, model-dir, services-dir,
+ *         nonpublished-modules-dir).
+ * .why  = a file still under one of these gets MOVED this pass; any in-place
+ *         rewrite of that same file (import-path rewrite) must DEFER to the next
+ *         pass, when the file sits at its new location. otherwise declapract
+ *         applies a relocate AND an in-place rewrite to one file in one apply —
+ *         the move unlinks the source, then the rewrite throws ENOENT against it.
+ *         one source for both declarers that must defer (mirrors
+ *         `defineExpectedGitignoreContents` / `defineExpectedNpmrcContents`), so
+ *         the guard cannot drift between them.
+ */
+export const DEPRECATED_SRC_DIR_PATTERNS: readonly RegExp[] = [
+  /\/logic\//,
+  /\/data\//,
+  /\/domain\//,
+  /\/model\//,
+  /\/services\//,
+  /\/__nonpublished_modules__\//,
+];
+
+/**
+ * .what = true when a file still sits under a deprecated src dir, so an in-place
+ *         rewrite of it must DEFER to the peer dir-move's next pass.
+ * .why  = the shared predicate both `old-import-paths` (directory-structure-src)
+ *         and `relative-imports` (typescript-any) gate their in-place import
+ *         rewrite on — so neither rewrites a file the same apply relocates.
+ */
+export const isDeferredToDeprecatedDirMove = (input: {
+  relativeFilePath: string | undefined;
+}): boolean => {
+  const relativeFilePath = input.relativeFilePath ?? '';
+  return DEPRECATED_SRC_DIR_PATTERNS.some((pattern) =>
+    pattern.test(relativeFilePath),
+  );
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.49.9",
+  "version": "0.49.11",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -76,13 +76,13 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.44.4",
+    "rhachet": "1.45.1",
     "rhachet-brains-anthropic": "0.4.3",
     "rhachet-brains-fireworksai": "0.1.3",
     "rhachet-brains-xai": "0.3.3",
-    "rhachet-roles-bhrain": "0.31.3",
+    "rhachet-roles-bhrain": "0.32.1",
     "rhachet-roles-bhrowser": "0.1.0",
-    "rhachet-roles-bhuild": "0.21.31",
+    "rhachet-roles-bhuild": "0.21.32",
     "rhachet-roles-ehmpathy": "1.38.6",
     "rhachet-roles-ghlitch": "0.2.10",
     "rhachet-roles-rhachet": "0.1.7",

package/dist/practices/tests/bad-practices/deprecated-test-deps/package.json.declapract.ts

@@ -1,39 +0,0 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
-
-export const check = FileCheckType.CONTAINS;
-
-const deprecatedDeps = [
-  'babel-jest',
-  '@babel/core',
-  '@babel/preset-env',
-  'core-js',
-  'ts-jest',
-];
-
-export const fix: FileFixFunction = (contents) => {
-  if (!contents) return { contents }; // do nothing if no contents
-  const packageJSON = JSON.parse(contents);
-
-  // Remove deprecated deps from devDependencies
-  const updatedDevDeps = { ...packageJSON.devDependencies };
-  for (const dep of deprecatedDeps) {
-    delete updatedDevDeps[dep];
-  }
-
-  // Remove deprecated deps from dependencies (in case they're there)
-  const updatedDeps = { ...packageJSON.dependencies };
-  for (const dep of deprecatedDeps) {
-    delete updatedDeps[dep];
-  }
-
-  const updatedPackageJSON = {
-    ...packageJSON,
-    dependencies: Object.keys(updatedDeps).length > 0 ? updatedDeps : undefined,
-    devDependencies:
-      Object.keys(updatedDevDeps).length > 0 ? updatedDevDeps : undefined,
-  };
-
-  return {
-    contents: JSON.stringify(updatedPackageJSON, null, 2),
-  };
-};

package/dist/practices/tests/best-practice/jest.unit.env.ts.declapract.ts

@@ -1,35 +0,0 @@
-// eslint-disable-next-line import/no-extraneous-dependencies
-
-import type { FileContentsFunction } from 'declapract';
-import { FileCheckType } from 'declapract';
-
-import { readFile } from '../../../utils/readFile';
-
-/**
- * declare the expected contents
- */
-export const contents: FileContentsFunction = async (context) => {
-  // grab the superset of best practices content
-  const contentsSuperset = await readFile(`${__dirname}/jest.unit.env.ts`);
-
-  // remove things that are irrelevant, based on other practices in use in project
-  let contents = contentsSuperset;
-  if (!context.projectPractices.includes('config'))
-    contents = contents.replace(
-      `// mock that getConfig just returns plaintext test env config in unit tests
-jest.mock('./src/utils/config/getConfig', () => ({
-  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')),
-}));
-
-`,
-      '',
-    );
-
-  // return the narrowed contents
-  return contents;
-};
-
-/**
- * check that they're contained in the file
- */
-export const check: FileCheckType = FileCheckType.CONTAINS;

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

@@ -1,27 +0,0 @@
-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/best-practice/.declapract.readme.md

@@ -1,15 +0,0 @@
-this bundle defines best practices for tsconfig
-
-namely:
-- build vs test config
-- default name as test config, so that ide's automatically typecheck test files for you
-  - otherwise, they exclude them, and you only find ts errors _after_ you run tsc - not while looking at file
-- strict
-  - 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.declapract.ts

@@ -1,18 +0,0 @@
-import { FileCheckType, type FileContentsFunction } from 'declapract';
-
-import { readFile } from '../../../utils/readFile';
-
-export const contents: FileContentsFunction = async (context) => {
-  // grab the superset of best practices content
-  const contentsSuperset = await readFile(`${__dirname}/package.json`);
-
-  // remove things that are irrelevant, based on other practices in use in project
-  let contents = contentsSuperset;
-  if (!context.projectPractices.includes('artifact'))
-    contents = contents.replace(` && npm run build:artifact`, '');
-
-  // return the narrowed contents
-  return contents;
-};
-
-export const check = FileCheckType.CONTAINS;