declapract-typescript-ehmpathy 0.49.1 → 0.49.3

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

@@ -2,6 +2,6 @@
   "dependencies": {
     "@aws-sdk/client-account": "@declapract{check.minVersion('3.1042.0')}",
     "@aws-sdk/client-iam": "@declapract{check.minVersion('3.1042.0')}",
-    "sdk-environment": "@declapract{check.minVersion('0.1.4')}"
+    "sdk-environment": "@declapract{check.minVersion('0.1.5')}"
   }
 }

package/dist/practices/logs/bad-practices/simple-log-methods/src/<star><star>/<star>.ts.declapract.ts

@@ -1,15 +1,46 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
+/**
+ * .what = migrates simple-log-methods to sdk-logs with commit flow
+ * .why = sdk-logs with commit flow enables traceability in production logs
+ *
+ * .note = declapract semantics:
+ *   - check returns = bad practice detected (file will be flagged)
+ *   - check throws = bad practice not detected (file will be skipped)
+ *   - fix returns {} = no changes needed
+ */
+
 export const check: FileCheckFunction = (contents) => {
+  // detect files that import from simple-log-methods
   if (contents?.includes("from 'simple-log-methods'")) return;
   throw new Error('does not match bad practice');
 };
 
 export const fix: FileFixFunction = (contents) => {
+  // no contents means no file to fix
   if (!contents) return {};
-  return {
-    contents: contents
-      .replace(/from 'simple-log-methods'/g, "from 'sdk-logs'")
-      .replace(/generateLogMethods/g, 'genLogMethods'),
-  };
+
+  // step 1: replace package import and method name
+  const withSdkLogs = contents
+    .replace(/from 'simple-log-methods'/g, "from 'sdk-logs'")
+    .replace(/generateLogMethods/g, 'genLogMethods');
+
+  // step 2: add sdk-environment import if not already present (idempotent)
+  const needsEnvImport = !withSdkLogs.includes("from 'sdk-environment'");
+  const withEnvImport = needsEnvImport
+    ? withSdkLogs.replace(
+        /import { genLogMethods } from 'sdk-logs';/g,
+        "import { getEnvironment } from 'sdk-environment';\nimport { genLogMethods } from 'sdk-logs';",
+      )
+    : withSdkLogs;
+
+  // step 3: flow commit through env (only for no-arg calls)
+  const withCommitFlow = withEnvImport.replace(
+    /genLogMethods\(\)/g,
+    `genLogMethods({
+  env: { commit: getEnvironment.static().commit },
+})`,
+  );
+
+  return { contents: withCommitFlow };
 };

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

@@ -1,5 +1,6 @@
 {
   "dependencies": {
+    "sdk-environment": "@declapract{check.minVersion('0.1.5')}",
     "sdk-logs": "@declapract{check.minVersion('0.9.2')}"
   }
 }

package/dist/practices/logs/best-practice/src/utils/logger.ts

@@ -1,3 +1,6 @@
+import { getEnvironment } from 'sdk-environment';
 import { genLogMethods } from 'sdk-logs';
 
-export const log = genLogMethods();
+export const log = genLogMethods({
+  env: { commit: getEnvironment.static().commit },
+});

package/dist/practices/node-service/bad-practices/simple-lambda-client/.declapract.readme.md

@@ -0,0 +1,55 @@
+# simple-lambda-client
+
+## what
+
+detects and transforms simple-lambda-client usage to sdk-aws-lambda.
+
+## why
+
+sdk-aws-lambda provides modern lambda client patterns:
+- context-based configuration
+- trail.exid auto-propagation through call chain
+- better cache support
+
+## transforms
+
+| old | new |
+|-----|-----|
+| `import { invokeLambdaFunction } from 'simple-lambda-client'` | `import { askLambdaEndpoint } from 'sdk-aws-lambda'` |
+| `invokeLambdaFunction(...)` | `askLambdaEndpoint(...)` |
+
+## limitations
+
+these patterns require manual migration:
+
+- `{ service, function, stage, event }` → `{ which: { service, function }, event }, context`
+- `stage: string` → `context.env.access: string`
+- `logDebug?: LogMethod` → `context.log: LogMethods` (required)
+- `cache?: SimpleCache<O>` → `context.cache?: { response?, dedupe? }`
+
+## example
+
+before:
+```ts
+import { invokeLambdaFunction } from 'simple-lambda-client';
+
+const result = await invokeLambdaFunction({
+  service: 'svc-users',
+  function: 'getUser',
+  stage: 'prod',
+  event: { userId: '123' },
+});
+```
+
+after (requires manual refinement):
+```ts
+import { askLambdaEndpoint } from 'sdk-aws-lambda';
+
+const result = await askLambdaEndpoint(
+  {
+    which: { service: 'svc-users', function: 'getUser' },
+    event: { userId: '123' },
+  },
+  { log, env: { access: 'prod' } },
+);
+```

package/dist/practices/node-service/bad-practices/simple-lambda-client/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "simple-lambda-client": "@declapract{check.minVersion('0.0.0')}"
+  }
+}

package/dist/practices/node-service/bad-practices/simple-lambda-client/package.json.declapract.ts

@@ -0,0 +1,27 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+/**
+ * .what = removes simple-lambda-client and adds sdk-aws-lambda
+ * .why = sdk-aws-lambda is the modern replacement with better patterns
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON = JSON.parse(contents);
+
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: {
+      ...packageJSON.dependencies,
+      'simple-lambda-client': undefined,
+      'sdk-aws-lambda':
+        packageJSON.dependencies?.['sdk-aws-lambda'] ?? '^0.1.0',
+    },
+  };
+
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/practices/node-service/bad-practices/simple-lambda-client/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,44 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects simple-lambda-client imports in source files
+ * .why = simple-lambda-client should be replaced with sdk-aws-lambda
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match if file imports from simple-lambda-client
+  if (contents?.includes("from 'simple-lambda-client'")) return;
+  if (contents?.includes('from "simple-lambda-client"')) return;
+
+  // no match
+  throw new Error('does not import from simple-lambda-client');
+};
+
+/**
+ * .what = transforms simple-lambda-client imports to sdk-aws-lambda
+ * .why = automated migration reduces manual toil
+ *
+ * .note = basic transforms only; complex patterns require manual fix
+ *
+ * API map:
+ * - invokeLambdaFunction → askLambdaEndpoint
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  const updated = contents
+    // transform imports
+    .replace(
+      /import\s+\{([^}]*)\}\s+from\s+['"]simple-lambda-client['"]/g,
+      (match, imports) => {
+        const updatedImports = imports.replace(
+          /invokeLambdaFunction/g,
+          'askLambdaEndpoint',
+        );
+        return `import {${updatedImports}} from 'sdk-aws-lambda'`;
+      },
+    )
+    // transform function calls
+    .replace(/invokeLambdaFunction/g, 'askLambdaEndpoint');
+
+  return { contents: updated };
+};

package/dist/practices/node-service/bad-practices/simple-lambda-handlers/.declapract.readme.md

@@ -0,0 +1,52 @@
+# simple-lambda-handlers
+
+## what
+
+detects and transforms simple-lambda-handlers usage to sdk-aws-lambda.
+
+## why
+
+sdk-aws-lambda provides modern lambda handler patterns:
+- better schema validation with zod (input + output)
+- log context passed to invoke function
+- trail.exid auto-propagation
+
+## transforms
+
+| old | new |
+|-----|-----|
+| `import { createStandardHandler } from 'simple-lambda-handlers'` | `import { genLambdaEndpoint } from 'sdk-aws-lambda'` |
+| `import { createApiGatewayHandler } from 'simple-lambda-handlers'` | `import { genLambdaEndpoint } from 'sdk-aws-lambda'` |
+| `createStandardHandler(...)` | `genLambdaEndpoint(...)` |
+| `createApiGatewayHandler(...)` | `genLambdaEndpoint.for.apiGateway(...)` |
+
+## limitations
+
+these patterns require manual migration:
+
+- `schema` (single joi) → `schema: { input, output }` (split zod)
+- `logic: (event) => O` → `invoke: ({ event }, { log }) => O`
+- `log` passed at creation → `log` also received in invoke context
+
+## example
+
+before:
+```ts
+import { createStandardHandler } from 'simple-lambda-handlers';
+
+export const handler = createStandardHandler({
+  log,
+  schema,
+  logic: async (event) => doStuff(event),
+});
+```
+
+after (requires manual refinement):
+```ts
+import { genLambdaEndpoint } from 'sdk-aws-lambda';
+
+export const handler = genLambdaEndpoint({
+  schema: { input: inputSchema, output: outputSchema },
+  invoke: async ({ event }, { log }) => doStuff(event),
+}, { log });
+```

package/dist/practices/node-service/bad-practices/simple-lambda-handlers/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "simple-lambda-handlers": "@declapract{check.minVersion('0.0.0')}"
+  }
+}

package/dist/practices/node-service/bad-practices/simple-lambda-handlers/package.json.declapract.ts

@@ -0,0 +1,27 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+/**
+ * .what = removes simple-lambda-handlers and adds sdk-aws-lambda
+ * .why = sdk-aws-lambda is the modern replacement with better patterns
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON = JSON.parse(contents);
+
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: {
+      ...packageJSON.dependencies,
+      'simple-lambda-handlers': undefined,
+      'sdk-aws-lambda':
+        packageJSON.dependencies?.['sdk-aws-lambda'] ?? '^0.1.0',
+    },
+  };
+
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/practices/node-service/bad-practices/simple-lambda-handlers/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,50 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects simple-lambda-handlers imports in source files
+ * .why = simple-lambda-handlers should be replaced with sdk-aws-lambda
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match if file imports from simple-lambda-handlers
+  if (contents?.includes("from 'simple-lambda-handlers'")) return;
+  if (contents?.includes('from "simple-lambda-handlers"')) return;
+
+  // no match
+  throw new Error('does not import from simple-lambda-handlers');
+};
+
+/**
+ * .what = transforms simple-lambda-handlers imports to sdk-aws-lambda
+ * .why = automated migration reduces manual toil
+ *
+ * .note = basic transforms only; complex patterns require manual fix
+ *
+ * API map:
+ * - createStandardHandler → genLambdaEndpoint
+ * - createApiGatewayHandler → genLambdaEndpoint.for.apiGateway
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  const updated = contents
+    // transform imports (dedupe to avoid duplicate genLambdaEndpoint)
+    .replace(
+      /import\s+\{([^}]*)\}\s+from\s+['"]simple-lambda-handlers['"]/g,
+      (match, imports) => {
+        // split, replace, dedupe, join
+        const importList = imports.split(',').map((s: string) => s.trim());
+        const transformed = importList.map((name: string) => {
+          if (name === 'createStandardHandler') return 'genLambdaEndpoint';
+          if (name === 'createApiGatewayHandler') return 'genLambdaEndpoint';
+          return name;
+        });
+        const deduped = [...new Set(transformed)];
+        return `import { ${deduped.join(', ')} } from 'sdk-aws-lambda'`;
+      },
+    )
+    // transform function calls
+    .replace(/createStandardHandler/g, 'genLambdaEndpoint')
+    .replace(/createApiGatewayHandler/g, 'genLambdaEndpoint.for.apiGateway');
+
+  return { contents: updated };
+};

package/dist/practices/node-service/best-practice/package.json

@@ -1,3 +1,6 @@
 {
-  "private": true
+  "private": true,
+  "dependencies": {
+    "sdk-aws-lambda": "@declapract{check.minVersion('0.0.1')}"
+  }
 }

package/dist/practices/rhachet/bad-practices/review-peer-artifacts/.behavior/<star><star>/.reviews/<star><star>/<star>peer-review<star>.md.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects committed peer-review artifacts under .behavior/**\/.reviews
+ * .why = peer-review files are noise; far less important than the root behavior
+ *        files, so they should not be tracked in git
+ *
+ * .note = matches the old flat shape, where peer-review files sit directly in
+ *         .reviews with `peer-review` in the filename
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};

package/dist/practices/rhachet/bad-practices/review-peer-artifacts/.behavior/<star><star>/.reviews/peer/<star><star>/<star>.md.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects committed peer-review artifacts under .behavior/**\/.reviews/peer
+ * .why = peer-review files are noise; far less important than the root behavior
+ *        files, so they should not be tracked in git
+ *
+ * .note = matches the new shape, where all peer-review files live under a
+ *         dedicated `peer` directory
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};

package/dist/practices/rhachet/bad-practices/review-peer-artifacts/.declapract.readme.md

@@ -0,0 +1,12 @@
+peer review artifacts should not be committed to git
+
+these files live under `.behavior/**/.reviews/` and capture peer-review feedback
+from the behavior build lifecycle. they are noise for the most part — far less
+important than the root behavior files themselves.
+
+two path shapes are removed:
+
+- old (flat): `.behavior/**/.reviews/**/*peer-review*.md`
+- new (peer dir): `.behavior/**/.reviews/peer/**/*.md`
+
+self-reviews and other non-peer artifacts under `.reviews/` are intentionally left alone.

package/dist/practices/{runtime-type-checking → runtime-schemas}/bad-practices/joi/package.json.declapract.ts

@@ -12,6 +12,10 @@ export const fix: FileFixFunction = (contents) => {
       joi: undefined,
       zod: packageJSON.dependencies?.zod ?? '^3.24.0',
     },
+    devDependencies: {
+      ...packageJSON.devDependencies,
+      '@types/joi': undefined,
+    },
   };
   return {
     contents: JSON.stringify(updatedPackageJSON, null, 2),

package/dist/practices/runtime-schemas/bad-practices/joi/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,50 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects joi imports in source files
+ * .why = joi should be replaced with zod for better typescript integration
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match if file imports from joi
+  if (contents?.includes("from 'joi'")) return;
+  if (contents?.includes('from "joi"')) return;
+
+  // no match
+  throw new Error('does not import from joi');
+};
+
+/**
+ * .what = transforms joi imports and basic schema patterns to zod
+ * .why = automated migration reduces manual toil
+ *
+ * .note = basic transforms only; complex patterns require manual fix
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  const updated = contents
+    // transform imports: import Joi from 'joi' → import { z } from 'zod'
+    .replace(/import\s+Joi\s+from\s+['"]joi['"]/g, "import { z } from 'zod'")
+    // transform imports: import * as Joi from 'joi' → import { z } from 'zod'
+    .replace(
+      /import\s+\*\s+as\s+Joi\s+from\s+['"]joi['"]/g,
+      "import { z } from 'zod'",
+    )
+    // transform imports: import { ... } from 'joi' → import { z } from 'zod'
+    .replace(
+      /import\s+\{[^}]*\}\s+from\s+['"]joi['"]/g,
+      "import { z } from 'zod'",
+    )
+    // transform basic schema patterns: Joi.* → z.*
+    .replace(/Joi\.object/g, 'z.object')
+    .replace(/Joi\.string/g, 'z.string')
+    .replace(/Joi\.number/g, 'z.number')
+    .replace(/Joi\.boolean/g, 'z.boolean')
+    .replace(/Joi\.array/g, 'z.array')
+    .replace(/Joi\.date/g, 'z.date')
+    .replace(/Joi\.any/g, 'z.any')
+    // transform .required() → remove (zod is required by default)
+    .replace(/\.required\(\)/g, '');
+
+  return { contents: updated };
+};

package/dist/useCases.yml

@@ -38,11 +38,9 @@ use-cases:
       - dates-and-times
       - environments
       - environments-aws
-      - lambda-clients
-      - lambda-handlers
       - logs
       - node-service
-      - runtime-type-checking
+      - runtime-schemas
       - serverless
       - provision-github
       - terraform-common

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.49.1",
+  "version": "0.49.3",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -76,12 +76,13 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.41.21",
+    "rhachet": "1.42.2",
     "rhachet-brains-anthropic": "0.4.1",
+    "rhachet-brains-fireworksai": "0.1.3",
     "rhachet-brains-xai": "0.3.3",
-    "rhachet-roles-bhrain": "0.29.2",
-    "rhachet-roles-bhuild": "0.21.16",
-    "rhachet-roles-ehmpathy": "1.35.15",
+    "rhachet-roles-bhrain": "0.29.10",
+    "rhachet-roles-bhuild": "0.21.18",
+    "rhachet-roles-ehmpathy": "1.37.0",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",
     "type-fns": "1.21.2",

package/dist/practices/lambda-clients/bad-practices/lambda-service-client-package/.declapract.readme.md

@@ -1 +0,0 @@
-our `simple-lambda-client` package used to be called `lambda-service-client`. its no longer maintained, but may still be used in some services. it shouldn't be anymore though

package/dist/practices/lambda-clients/bad-practices/lambda-service-client-package/package.json

@@ -1,5 +0,0 @@
-{
-  "dependencies": {
-    "lambda-service-client": "@declapract{check.minVersion('0.0.0')}"
-  }
-}

package/dist/practices/lambda-clients/bad-practices/lambda-service-client-package/package.json.declapract.ts

@@ -1,16 +0,0 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
-
-export const check = FileCheckType.CONTAINS;
-
-export const fix: FileFixFunction = (contents) => {
-  if (!contents) return {}; // should not reach here, file should exist; if doesnt though, do nothing
-  const parsedContents = JSON.parse(contents);
-  const fixedParsedContents = {
-    ...parsedContents,
-    dependencies: {
-      ...parsedContents.dependencies,
-      'lambda-service-client': undefined, // remove this module
-    },
-  };
-  return { contents: JSON.stringify(fixedParsedContents, null, 2) };
-};

package/dist/practices/lambda-clients/best-practice/package.json

@@ -1,5 +0,0 @@
-{
-  "dependencies": {
-    "simple-lambda-client": "@declapract{check.minVersion('2.1.3')}"
-  }
-}

package/dist/practices/lambda-clients/best-practice/src/data/clients/<star>.ts

@@ -1 +0,0 @@
-import { invokeLambdaFunction } from 'simple-lambda-client';

package/dist/practices/lambda-clients/best-practice/src/data/clients/<star>.ts.declapract.ts

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

package/dist/practices/lambda-handlers/best-practice/package.json

@@ -1,6 +0,0 @@
-{
-  "dependencies": {
-    "simple-lambda-handlers": "@declapract{check.minVersion('0.10.3')}"
-  },
-  "devDependencies": {}
-}

package/dist/practices/lambda-handlers/best-practice/package.json.declapract.ts

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

package/dist/practices/lambda-handlers/best-practice/src/contract/handlers/<star><star>/<star>.declapract.ts

@@ -1,3 +0,0 @@
-import { FileCheckType } from 'declapract';
-
-export const check = FileCheckType.EXISTS; // we should have atleast one handler

package/dist/practices/runtime-type-checking/bad-practices/joi-types/package.json

@@ -1,5 +0,0 @@
-{
-  "devDependencies": {
-    "@types/joi": "@declapract{check.minVersion('0.0.0')}"
-  }
-}

package/dist/practices/runtime-type-checking/bad-practices/joi-types/package.json.declapract.ts

@@ -1,18 +0,0 @@
-import { FileCheckType, type FileFixFunction } from 'declapract';
-
-export const check = FileCheckType.CONTAINS;
-
-export const fix: FileFixFunction = (contents) => {
-  if (!contents) return { contents }; // do nothing if no contents
-  const packageJSON = JSON.parse(contents);
-  const updatedPackageJSON = {
-    ...packageJSON,
-    devDependencies: {
-      ...packageJSON.devDependencies,
-      '@types/joi': undefined,
-    },
-  };
-  return {
-    contents: JSON.stringify(updatedPackageJSON, null, 2),
-  };
-};

package/dist/practices/runtime-type-checking/bad-practices/old-joi-syntax-valid-input-cant-be-array/.declapract.readme.md

@@ -1 +0,0 @@
-joi updated their syntax and now throws an error if `.valid([])`, instead we need to give `.valid(...[])`

package/dist/practices/runtime-type-checking/bad-practices/old-joi-syntax-valid-input-cant-be-array/src/<star><star>/<star>.ts.declapract.ts

@@ -1,15 +0,0 @@
-import type { FileCheckFunction, FileFixFunction } from 'declapract';
-
-export const check: FileCheckFunction = (contents) => {
-  if (contents?.includes('.valid(Object.values(')) return; // matches bad practice if this is found
-  throw new Error('passes, does not match bad practice');
-};
-export const fix: FileFixFunction = (contents) => {
-  if (!contents) return {};
-  return {
-    contents: contents.replace(
-      /\.valid\(Object\.values/g,
-      '.valid(...Object.values',
-    ),
-  };
-};

package/dist/practices/runtime-type-checking/best-practice/package.json.declapract.ts

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