declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/.test/assets/expo-fullusecase/declarations/practices/node/best-practice/.npmrc.declapract.ts

@@ -0,0 +1,64 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { defineExpectedNpmrcContents } from '../../../utils/defineExpectedNpmrcContents';
+
+/**
+ * .what = the `.npmrc` the node practice declares, usecase-aware for the expo runtime
+ * .why  = a flat node_modules (hoisted linker) is 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 isolated, but hoisted is the trodden
+ *         default). so an expo repo layers the hoisted-linker block atop the base `.npmrc`
+ *         every node repo gets, rather than fork a separate practice
+ *         (rule.avoid.runtime-forks). the forced-vs-opt-in call is flagged for the wisher
+ *         in `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md`.
+ * .why  = a FINDSERT (check/fix union), NOT an EQUALS overwrite. the fix only APPENDS
+ *         absent declared lines and never removes a line, so a repo's own `.npmrc`
+ *         settings — and, crucially, a correctly-hoisted expo `.npmrc` under a narrow
+ *         `declapract fix --practice node` (where the expo signal goes dark) — are
+ *         preserved rather than clobbered. the algorithm lives in
+ *         `defineExpectedNpmrcContents`, shared by `check` and `fix` so the gate and the
+ *         repair can never disagree (mirrors the repo-root `.gitignore`).
+ * .note = best-practice check semantics are inverted — a THROW means the practice is
+ *         violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
+const defineExpectedContents = (
+  contents: string | null,
+  projectPractices: string[],
+): string => defineExpectedNpmrcContents({ contents, projectPractices });
+
+/**
+ * .what = throws when the repo's `.npmrc` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. the expected value UNIONS the repo's extant lines in, so a repo
+ *         that already carries the declared lines (plus any of its own) passes — the
+ *         check mandates PRESENCE of the declared lines, never EQUALITY, so it can never
+ *         demand a custom line be removed.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  // a plain comparison + clear throw, NOT an `expect` assertion: declapract runs
+  // `check` outside any test runner, so a test-diff-shaped throw is a friction hazard
+  // (rule.forbid.friction-hazards) — the caller only needs a clean, stable signal.
+  const expected = defineExpectedContents(contents, context.projectPractices);
+  if (contents !== expected)
+    throw new ConstraintError(
+      '.npmrc does not carry the declared node/expo lines; run `declapract apply` to findsert them',
+      { relativeFilePath: context.relativeFilePath },
+    );
+};
+
+/**
+ * .what = unions this practice's declared `.npmrc` lines into the repo's extant one
+ * .why  = a findsert by construction — a line already present stays present once, a
+ *         repo's own settings survive, and (the fix this closes) a hoisted expo
+ *         `.npmrc` is never stripped by a narrow-scope apply.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own output.
+ *         clamped by `.npmrc.declapract.test.ts` -> `idempotency` and by the pipeline
+ *         test's narrow-scope `[case2]`.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: defineExpectedContents(contents, context.projectPractices),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/node/best-practice/.nvmrc

@@ -0,0 +1 @@
+v22.21.0

package/dist/.test/assets/expo-fullusecase/declarations/practices/node/best-practice/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@declapract{variable.projectName}",
+  "author": "@declapract{variable.organizationName}",
+  "version": "@declapract{check.minVersion('0.0.0')}",
+  "repository": "@declapract{variable.organizationName}/@declapract{variable.projectName}",
+  "homepage": "https://github.com/@declapract{variable.organizationName}/@declapract{variable.projectName}",
+  "bugs": "https://github.com/@declapract{variable.organizationName}/@declapract{variable.projectName}/issues",
+  "scripts": {
+    "fix": "npm run fix:format && npm run fix:lint",
+    "prepare": "if [ -e .git ] && [ -z \"${CI:-}\" ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
+    "prepush": "npm run test && npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/node/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/node/best-practice/readme.md

@@ -0,0 +1 @@
+# @declapract{variable.projectName}

package/dist/.test/assets/expo-fullusecase/declarations/practices/node/best-practice/readme.md.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // i.e., check that the contents of the file contains what's declared (default is equals)

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/.declapract.readme.md

@@ -0,0 +1,5 @@
+nonpublished modules are used when we are testing out some new functionality and have not yet generalized it sufficiently to warrant creating a npm module of its own yet (e.g., follow W.E.T and have not written it twice already)
+
+however, when modules do graduate and get published, we want to make sure we start using them and stop using the "nonpublished" one
+
+this practice consists of bad-practice checks that make sure whenever we publish one (or deprecate one) we dont keep using the old one

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/.declapract.readme.md

@@ -0,0 +1 @@
+was published under `standard-lambda-handlers` package

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/__nonpublished_modules__/ahbode-standard-lambda-handler/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.integration.test.ts

@@ -0,0 +1 @@
+import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents
+      .replace(
+        `import { promiseLambdaInvocation } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';`,
+        `import { invokeHandlerForTesting } from 'simple-lambda-testing-methods';`,
+      )
+      .replace(/promiseLambdaInvocation/g, 'invokeHandlerForTesting'),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.ts

@@ -0,0 +1 @@
+import { createStandardHandler } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/ahbode-standard-lambda-handler/src/contract/handlers/<star>.ts.declapract.ts

@@ -0,0 +1,13 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents.replace(
+      `import { createStandardHandler } from '../../__nonpublished_modules__/ahbode-standard-lambda-handler';`,
+      `import { createStandardHandler } from 'simple-lambda-handlers';`,
+    ),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/deep-omit/.declapract.readme.md

@@ -0,0 +1 @@
+was replaced with `domain-objects#omitAutogeneratedValues`

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/deep-omit/src/__nonpublished_modules__/deep-omit/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/deep-omit/src/data/dao/<star><star>/<star>.integration.test.ts

@@ -0,0 +1 @@
+import { deepOmit } from '../../../__nonpublished_modules__/deep-omit';

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/deep-omit/src/data/dao/<star><star>/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,18 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents
+      .replace(
+        `import { deepOmit } from '../../../__nonpublished_modules__/deep-omit';`,
+        `import { omitAutogeneratedValues } from 'domain-objects';`,
+      )
+      .replace(
+        /deepOmit\(([\w|!|?|.]+), \[[\w'", ]+\]\)/g,
+        'omitAutogeneratedValues($1)',
+      ),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/simple-dynamodb-client/.declapract.readme.md

@@ -0,0 +1 @@
+was published under `simple-dynamodb-client` package

package/dist/.test/assets/expo-fullusecase/declarations/practices/nonpublished-modules/bad-practices/simple-dynamodb-client/src/__nonpublished_modules__/simple-dynamodb-client/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/package-json-order/best-practice/.declapract.readme.md

@@ -0,0 +1,3 @@
+technically json order doesn't matter
+
+but aesthetically it does - so lets define the order that we want to see

package/dist/.test/assets/expo-fullusecase/declarations/practices/package-json-order/best-practice/package.json.declapract.ts

@@ -0,0 +1,233 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * define the relative key order of keys we care about
+ *
+ * relative meaning: things can be between them or more keys can be defined that we wont reorder - but these ones must have the correct relative order
+ */
+export const desiredRelativeKeyOrder = {
+  root: [
+    'name',
+    'author',
+    'description',
+    'private',
+    'version',
+    'license',
+    'main',
+    'module',
+    'scripts',
+    'dependencies',
+    'devDependencies',
+    'config',
+  ],
+  scripts: [
+    'commit:with-cli',
+    'fix:format:biome',
+    'fix:format:prettier',
+    'fix:format:terraform',
+    'fix:format',
+    'fix:deps',
+    'fix:eslint',
+    'fix:lint',
+    'fix',
+    'generate:schema',
+    'generate:types-from-sql',
+    'generate:dao:dynamodb',
+    'generate:dao:postgres',
+    'build:artifact',
+    'build:clean:bun',
+    'build:clean:tsc',
+    'build:clean',
+    'build:compile:bun',
+    'build:compile:tsc',
+    'build:compile',
+    'build',
+    'provision:schema:plan',
+    'provision:schema:apply',
+    'provision:schema:sync',
+    'provision:testdb:docker:clear',
+    'provision:testdb:docker:prepare',
+    'provision:testdb:docker:up',
+    'provision:testdb:docker:await',
+    'provision:testdb:docker:down',
+    'provision:testdb',
+    'start:testdb',
+    'start:livedb:prep',
+    'test:auth',
+    'test:commits',
+    'test:types',
+    'test:format:prettier',
+    'test:format:terraform',
+    'test:format:biome',
+    'test:format',
+    'test:lint:deps',
+    'test:lint:biome',
+    'test:lint:biome:all',
+    'test:lint:eslint',
+    'test:lint',
+    'test:unit',
+    'test:integration',
+    'test:acceptance:locally',
+    'test',
+    'test:acceptance',
+    'prepush',
+    'prepublish',
+    'preversion',
+    'postversion',
+    'postinstall',
+    'prepare:husky',
+    'prepare:rhachet',
+    'prepare',
+    'deploy:prune',
+    'deploy:release:ancient',
+    'deploy:release:contemp',
+    'deploy:release',
+    'deploy:send-notification',
+    'deploy:prep',
+    'deploy:prod',
+    'deploy',
+
+    // from app-react-native-expo
+    'start:hot:proxy',
+    'start:hot:prep',
+    'start:hot:prep:link',
+    'start:hot:prep:proxy',
+    'start:hot:prod',
+    'start:hot:prod:link',
+    'start:hot:prod:proxy',
+    'start:cold:proxy',
+    'start:cold:prep',
+    'start:cold:prep:link',
+    'start:cold:prep:proxy',
+    'start:cold:prod',
+    'start:cold:prod:link',
+    'register:device:apple:info',
+    'register:device:apple:inclusions:rebuild:prod',
+    'register:device:apple:inclusions:rebuild:prep',
+    'register:device:apple:add',
+    'register:device:apple:list',
+    'register:device:apple:delete',
+    'register:device:apple:rename',
+    'register:profile:apple:list',
+    'build:prep:ios',
+    'build:prep:android',
+    'build:web',
+    'deploy:prod:ios:metadata',
+    'open:store:android',
+    'open:store:ios',
+    'android',
+    'ios',
+  ],
+};
+
+/**
+ * function which sorts keys in an object based on relative sort order given
+ *
+ * when a key is not in the array, its relative position in the array is not changed
+ *
+ * note: we're forced to write our own sorting function because `.sort()` assumes that `if a > b` and `b > c` then `a > c`, which does not hold in our case (because some relative ranks are not defined)
+ */
+const sortObjectByRelativeKeyOrder = ({
+  object,
+  order,
+}: {
+  object: Record<string, any>;
+  order: string[];
+}) => {
+  const objectKeys = Object.keys(object);
+  const objectKeysWithRelativePositionDefined = objectKeys.filter((key) =>
+    order.includes(key),
+  );
+  const objectKeysWithoutRelativePositionDefined = objectKeys.filter(
+    (key) => !order.includes(key),
+  );
+
+  // sort the keys that have relative order to eachother
+  const sortedRelativeOrderOnesOnly =
+    objectKeysWithRelativePositionDefined.sort((a, b) =>
+      order.indexOf(a) < order.indexOf(b) ? -1 : 1,
+    );
+
+  // then stick the ones that did not have relative order defined into the order (after the ones we relatively defined, when more than one option of position)
+  const sortedKeys = [
+    ...sortedRelativeOrderOnesOnly,
+    ...objectKeysWithoutRelativePositionDefined,
+  ].sort((a, b) => {
+    // lookup the relative orders
+    const relativeOrderIndexOfKeyA = order.indexOf(a);
+    const relativeOrderIndexOfKeyB = order.indexOf(b);
+
+    // if the relative order of both are defined, then  we can use that to sort
+    if (relativeOrderIndexOfKeyA > -1 && relativeOrderIndexOfKeyB > -1)
+      return relativeOrderIndexOfKeyA < relativeOrderIndexOfKeyB ? -1 : 1;
+
+    // lookup the index of each in original array
+    const originalOrderIndexOfKeyA = objectKeys.indexOf(a);
+    const originalOrderIndexOfKeyB = objectKeys.indexOf(b);
+
+    // otherwise keep the original order
+    return originalOrderIndexOfKeyA < originalOrderIndexOfKeyB ? -1 : 1;
+  });
+
+  // create a new object with the sorted keys
+  const newObject: Record<string, any> = {};
+  for (const key of sortedKeys) {
+    newObject[key] = object[key];
+  }
+
+  // return it
+  return newObject;
+};
+
+const sortPackageJSONObjectKeys = (packageJSONObject: Record<string, any>) => {
+  // sort the scripts
+  const sortedScripts = sortObjectByRelativeKeyOrder({
+    object: packageJSONObject.scripts ?? {},
+    order: desiredRelativeKeyOrder.scripts,
+  });
+
+  // sort the dependencies (alphabetical)
+  const sortedDeps = sortObjectByRelativeKeyOrder({
+    object: packageJSONObject.dependencies ?? {},
+    order: Object.keys(packageJSONObject.dependencies ?? {}).sort(), // alphabetical order
+  });
+  const sortedDevDeps = sortObjectByRelativeKeyOrder({
+    object: packageJSONObject.devDependencies ?? {},
+    order: Object.keys(packageJSONObject.devDependencies ?? {}).sort(), // alphabetical order
+  });
+
+  // sort the root
+  const sortedPackageJSONObject = sortObjectByRelativeKeyOrder({
+    object: {
+      ...packageJSONObject,
+      scripts: sortedScripts,
+      dependencies: sortedDeps,
+      devDependencies: sortedDevDeps,
+    },
+    order: desiredRelativeKeyOrder.root,
+  });
+
+  // return it
+  return sortedPackageJSONObject;
+};
+
+// define fix and check
+export const check: FileCheckFunction = (contents) => {
+  if (!contents)
+    throw new ConstraintError(
+      'package.json not defined; the repo must carry a package.json for key-order to apply',
+    );
+  const packageJSONObject = JSON.parse(contents);
+  const sortedPackageJSONObject = sortPackageJSONObjectKeys(packageJSONObject);
+  expect(JSON.stringify(packageJSONObject, null, 2)).toEqual(
+    JSON.stringify(sortedPackageJSONObject, null, 2),
+  );
+};
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {}; // cant do anything if not defined
+  const packageJSONObject = JSON.parse(contents);
+  const sortedPackageJSONObject = sortPackageJSONObjectKeys(packageJSONObject);
+  return { contents: JSON.stringify(sortedPackageJSONObject, null, 2) };
+};