declapract-typescript-ehmpathy 0.47.8 → 0.47.10

package/dist/practices/tests/bad-practices/old-acceptance-dir-location/.declapract.readme.md

@@ -0,0 +1,22 @@
+# old-acceptance-dir-location
+
+## .what
+
+detects test files located in `acceptance/` directory and migrates them to `blackbox/`.
+
+## .why
+
+the term "blackbox" makes the testing philosophy explicit:
+- blackbox tests interact only through public contracts (APIs, CLIs, SDKs)
+- no access to internal implementation details
+- tests validate behavior from the caller's perspective
+
+the rename from `acceptance/` to `blackbox/` clarifies this intent.
+
+## .fix
+
+moves all files from `acceptance/` to `blackbox/` while preserving the directory structure.
+
+## .note
+
+the `.acceptance.test.ts` file extension is preserved — it communicates the test type while the directory name communicates the testing philosophy.

package/dist/practices/tests/bad-practices/old-acceptance-dir-location/acceptance/<star><star>/<star>.acceptance.test.ts.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files exist in acceptance/, flag as bad practice
+
+/**
+ * .what = moves acceptance test files from acceptance/ to blackbox/
+ * .why = blackbox/ naming makes the testing philosophy explicit
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // move from acceptance/ to blackbox/
+  const newPath = context.relativeFilePath.replace(
+    /^acceptance\//,
+    'blackbox/',
+  );
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/tests/bad-practices/old-acceptance-dir-location/acceptance/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if any ts files exist in acceptance/, flag as bad practice
+
+/**
+ * .what = moves ts files from acceptance/ to blackbox/
+ * .why = blackbox/ naming makes the testing philosophy explicit
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // move from acceptance/ to blackbox/
+  const newPath = context.relativeFilePath.replace(
+    /^acceptance\//,
+    'blackbox/',
+  );
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/tests/bad-practices/old-acceptance-import-paths/.declapract.readme.md

@@ -0,0 +1,31 @@
+# old-acceptance-import-paths
+
+## .what
+
+detects import statements that reference the old `acceptance/` directory path.
+
+## .why
+
+the `acceptance/` directory has been renamed to `blackbox/` to make the testing philosophy explicit:
+- blackbox tests interact only through public contracts
+- no access to internal implementation details
+
+import paths must be updated to reference `blackbox/` instead of `acceptance/`.
+
+## .fix
+
+replaces all occurrences of `acceptance/` with `blackbox/` in import paths.
+
+## .examples
+
+before:
+```typescript
+import { locally } from '../acceptance/environment';
+import { stage } from '../../acceptance/utils/environment';
+```
+
+after:
+```typescript
+import { locally } from '../blackbox/environment';
+import { stage } from '../../blackbox/utils/environment';
+```

package/dist/practices/tests/bad-practices/old-acceptance-import-paths/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,25 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects imports that reference acceptance/ directory
+ * .why = acceptance/ has been renamed to blackbox/
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match imports that reference acceptance/ directory
+  if (contents?.match(/from ['"]\.\.?\/.*acceptance\//)) return; // matches bad practice
+  if (contents?.match(/from ['"]acceptance\//)) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = replaces acceptance/ with blackbox/ in import paths
+ * .why = blackbox/ naming makes the testing philosophy explicit
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents
+      .replace(/(['"])(.*)\/acceptance\//g, '$1$2/blackbox/')
+      .replace(/(['"])acceptance\//g, '$1blackbox/'),
+  };
+};

package/dist/practices/tests/bad-practices/old-test-utils-and-assets-location/.declapract.readme.md

@@ -5,4 +5,4 @@ the `.test.utils/` directory replaces `__test_utils__` and `.test.assets/` repla
 examples:
 - `src/domain/__test_utils__/exampleUser.ts` → `src/domain/.test.utils/exampleUser.ts`
 - `src/logic/__test_assets__/fixtures.json` → `src/logic/.test.assets/fixtures.json`
-- `acceptance/__test_utils__/environment.ts` → `acceptance/.test.utils/environment.ts`
+- `blackbox/__test_utils__/environment.ts` → `blackbox/.test.utils/environment.ts`

package/dist/practices/tests/best-practice/.agent/repo=.this/role=any/skills/use.apikeys.json

@@ -0,0 +1,5 @@
+{
+  "apikeys": {
+    "required": []
+  }
+}

package/dist/practices/tests/best-practice/.agent/repo=.this/role=any/skills/use.apikeys.json.declapract.ts

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// check that the file exists; contents are user-defined
+export const check = FileCheckType.EXISTS;

package/dist/practices/tests/best-practice/.agent/repo=.this/role=any/skills/use.apikeys.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = export api keys for integration tests
+# .why = enables running integration tests that require api keys
+#
+# usage:
+#   source .agent/repo=.this/role=any/skills/use.apikeys.sh
+#
+# note:
+#   - must be called with `source` to export vars to current shell
+#   - loads from ~/.config/rhachet/apikeys.env if available
+#   - falls back to .env.local (gitignored) in repo root
+######################################################################
+
+# fail if not sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  echo "error: this script must be sourced, not executed"
+  echo "usage: source ${BASH_SOURCE[0]}"
+  exit 1
+fi
+
+# try loading from user config first
+if [[ -f ~/.config/rhachet/apikeys.env ]]; then
+  source ~/.config/rhachet/apikeys.env
+  echo "✓ loaded api keys from ~/.config/rhachet/apikeys.env"
+
+# fallback to local gitignored file
+elif [[ -f .env.local ]]; then
+  source .env.local
+  echo "✓ loaded api keys from .env.local"
+
+else
+  echo "⚠ no api keys file found"
+  echo ""
+  echo "create one of:"
+  echo "  ~/.config/rhachet/apikeys.env"
+  echo "  .env.local (in repo root)"
+  echo ""
+  echo "with contents like:"
+  echo "  export OPENAI_API_KEY=sk-..."
+  echo "  export ANTHROPIC_API_KEY=sk-..."
+  return 1
+fi
+
+# read required keys from json config if present
+APIKEYS_CONFIG=".agent/repo=.this/role=any/skills/use.apikeys.json"
+if [[ -f "$APIKEYS_CONFIG" ]]; then
+  # extract required keys using jq
+  REQUIRED_KEYS=$(jq -r '.apikeys.required[]?' "$APIKEYS_CONFIG" 2>/dev/null)
+
+  # verify each required key is set
+  for KEY in $REQUIRED_KEYS; do
+    if [[ -z "${!KEY}" ]]; then
+      echo "⚠ $KEY not set (required by $APIKEYS_CONFIG)"
+      return 1
+    fi
+    echo "✓ $KEY set"
+  done
+fi

package/dist/practices/tests/best-practice/.agent/repo=.this/role=any/skills/use.apikeys.sh.declapract.ts

@@ -0,0 +1,4 @@
+import { FileCheckType } from 'declapract';
+
+// check that the file contains the core structure
+export const check = FileCheckType.CONTAINS;

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

@@ -32,3 +32,38 @@ if (
   throw new Error(
     'no aws credentials present. please authenticate with aws to run acceptance tests',
   );
+
+/**
+ * .what = verify that required api keys are present; otherwise, fail fast
+ * .why =
+ *   - prevent time wasted waiting on tests to fail due to missing api keys
+ *   - prevent agents from giving up when they have access to credentials
+ */
+const apikeysConfigPath = join(
+  process.cwd(),
+  '.agent/repo=.this/role=any/skills/use.apikeys.json',
+);
+if (existsSync(apikeysConfigPath)) {
+  // direct import via require (json resolves automatically)
+  const config = require(apikeysConfigPath);
+  const requiredKeys: string[] = config?.apikeys?.required ?? [];
+  const keysAbsent = requiredKeys.filter((key) => !process.env[key]);
+
+  if (keysAbsent.length > 0) {
+    throw new Error(`
+⛈️  apikeys required to run these acceptance tests were not supplied.
+
+   absent keys: ${keysAbsent.join(', ')}
+
+   you have access to these keys - you just forgot to source them.
+
+   run:
+     source .agent/repo=.this/role=any/skills/use.apikeys.sh && npm run test:acceptance
+
+   you must run these tests with these api keys.
+   you're forbidden to give up.
+   if you don't have privs to run use.apikeys.sh, ask a human for support.
+   chances are, you already have privs to do so though.
+`);
+  }
+}

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

@@ -82,3 +82,38 @@ if (requiresTestDb) {
     );
   }
 }
+
+/**
+ * .what = verify that required api keys are present; otherwise, fail fast
+ * .why =
+ *   - prevent time wasted waiting on tests to fail due to missing api keys
+ *   - prevent agents from giving up when they have access to credentials
+ */
+const apikeysConfigPath = join(
+  process.cwd(),
+  '.agent/repo=.this/role=any/skills/use.apikeys.json',
+);
+if (existsSync(apikeysConfigPath)) {
+  // direct import via require (json resolves automatically)
+  const config = require(apikeysConfigPath);
+  const requiredKeys: string[] = config?.apikeys?.required ?? [];
+  const keysAbsent = requiredKeys.filter((key) => !process.env[key]);
+
+  if (keysAbsent.length > 0) {
+    throw new Error(`
+⛈️  apikeys required to run these integration tests were not supplied.
+
+   absent keys: ${keysAbsent.join(', ')}
+
+   you have access to these keys - you just forgot to source them.
+
+   run:
+     source .agent/repo=.this/role=any/skills/use.apikeys.sh && npm run test:integration
+
+   you must run these tests with these api keys.
+   you're forbidden to give up.
+   if you don't have privs to run use.apikeys.sh, ask a human for support.
+   chances are, you already have privs to do so though.
+`);
+  }
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.47.8",
+  "version": "0.47.10",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",