declapract-typescript-ehmpathy 0.47.18 → 0.47.20

package/dist/.test/infra/withApikeysContext.ts

@@ -0,0 +1,31 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * .what = creates a mock context with apikeys config in a temp directory
+ * .why = enables testing buildWorkflowSecretsBlock with different apikey configs
+ */
+export const withApikeysContext = async (
+  input: { apikeys: string[] },
+  fn: (context: { getProjectRootDirectory: () => string }) => Promise<void>,
+): Promise<void> => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
+  const configDir = path.join(
+    tempDir,
+    '.agent',
+    'repo=.this',
+    'role=any',
+    'skills',
+  );
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(configDir, 'use.apikeys.json'),
+    JSON.stringify({ apikeys: { required: input.apikeys } }, null, 2),
+  );
+  try {
+    await fn({ getProjectRootDirectory: () => tempDir });
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+};

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

@@ -0,0 +1,32 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = check that use.apikeys.json exists
+ * .why = enables projects to declare which api keys are required for integration tests
+ */
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = creates default use.apikeys.json structure if file doesn't exist
+ * .why = ensures all projects have the config file with proper schema
+ */
+export const fix: FileFixFunction = (contents) => {
+  // if file already exists, preserve its content
+  if (contents) {
+    return { contents };
+  }
+
+  // create default structure
+  return {
+    contents:
+      JSON.stringify(
+        {
+          apikeys: {
+            required: [],
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+  };
+};

package/dist/practices/cicd-common/best-practice/.github/workflows/.test.yml

@@ -25,7 +25,7 @@ jobs:
   # run tests in parallel
   test-commits:
     runs-on: ubuntu-24.04
-    needs: [install]
+    needs: [install, test-shards-omit]
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -48,7 +48,7 @@ jobs:
 
   test-types:
     runs-on: ubuntu-24.04
-    needs: [install]
+    needs: [install, test-shards-omit]
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -69,7 +69,7 @@ jobs:
 
   test-format:
     runs-on: ubuntu-24.04
-    needs: [install]
+    needs: [install, test-shards-omit]
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -93,7 +93,7 @@ jobs:
 
   test-lint:
     runs-on: ubuntu-24.04
-    needs: [install]
+    needs: [install, test-shards-omit]
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -114,7 +114,7 @@ jobs:
 
   test-unit:
     runs-on: ubuntu-24.04
-    needs: [install]
+    needs: [install, test-shards-omit]
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -133,9 +133,56 @@ jobs:
       - name: test:unit
         run: THOROUGH=true npm run test:unit
 
-  test-integration:
+  # shard setup job
+  enshard:
+    name: enshard
+    runs-on: ubuntu-24.04
+    outputs:
+      integration-matrix: ${{ steps.integration.outputs.matrix }}
+      integration-patterns: ${{ steps.integration.outputs.patterns }}
+      acceptance-matrix: ${{ steps.acceptance.outputs.matrix }}
+      acceptance-patterns: ${{ steps.acceptance.outputs.patterns }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            jest.integration.shards.jsonc
+            jest.acceptance.shards.jsonc
+            .github/actions/test-shards-setup
+          sparse-checkout-cone-mode: false
+
+      - name: setup integration shards
+        id: integration
+        uses: ./.github/actions/test-shards-setup
+        with:
+          config-file: jest.integration.shards.jsonc
+          test-type: integration
+
+      - name: setup acceptance shards
+        id: acceptance
+        uses: ./.github/actions/test-shards-setup
+        with:
+          config-file: jest.acceptance.shards.jsonc
+          test-type: acceptance
+
+  # placeholder job for github actions visualization alignment
+  # note: github actions has no column position controls;
+  #       this job pushes test-* jobs one column right to align with test-shards-* column
+  test-shards-omit:
     runs-on: ubuntu-24.04
     needs: [install]
+    steps:
+      - run: echo "👌 placeholder for column alignment"
+
+  # shard runner jobs
+  test-shards-integration:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard]
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: ${{ fromJson(needs.enshard.outputs.integration-matrix) }}
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -164,12 +211,44 @@ jobs:
       - name: start:livedb:dev
         run: npm run start:livedb:dev --if-present
 
-      - name: test:integration
-        run: THOROUGH=true npm run test:integration
-
-  test-acceptance-locally:
+      - name: build
+        run: npm run build
+
+      - name: test:integration (explicit ${{ matrix.shard.index }})
+        if: matrix.shard.type == 'explicit'
+        run: |
+          patterns='${{ join(matrix.shard.patterns, '|') }}'
+          THOROUGH=true npm run test:integration -- --testPathPattern="$patterns" --json --outputFile=jest-results.json
+
+      - name: test:integration (dynamic ${{ matrix.shard.shard }}/${{ matrix.shard.total }})
+        if: matrix.shard.type == 'dynamic'
+        run: |
+          exclude='${{ needs.enshard.outputs.integration-patterns }}'
+          if [[ -n "$exclude" ]]; then
+            THOROUGH=true npm run test:integration -- --testPathIgnorePatterns="$exclude" --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          else
+            THOROUGH=true npm run test:integration -- --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          fi
+
+      - name: report slow tests
+        if: always() && hashFiles('jest-results.json') != ''
+        run: |
+          jq -r '.testResults[] | "\(.name):\(.perfStats.runtime)"' jest-results.json | while IFS=: read -r name runtime; do
+            seconds=$((runtime / 1000))
+            if [[ $seconds -ge 30 ]]; then
+              echo "::warning file=${name}::slow test: ${seconds}s"
+            elif [[ $seconds -ge 10 ]]; then
+              echo "::notice file=${name}::test duration: ${seconds}s"
+            fi
+          done
+
+  test-shards-acceptance:
     runs-on: ubuntu-24.04
-    needs: [install]
+    needs: [install, enshard]
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: ${{ fromJson(needs.enshard.outputs.acceptance-matrix) }}
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -198,5 +277,63 @@ jobs:
       - name: start:livedb:dev
         run: npm run start:livedb:dev --if-present
 
-      - name: test:acceptance:locally
-        run: THOROUGH=true npm run test:acceptance:locally --if-present
+      - name: build
+        run: npm run build
+
+      - name: test:acceptance (explicit ${{ matrix.shard.index }})
+        if: matrix.shard.type == 'explicit'
+        run: |
+          patterns='${{ join(matrix.shard.patterns, '|') }}'
+          THOROUGH=true npm run test:acceptance -- --testPathPattern="$patterns" --json --outputFile=jest-results.json
+
+      - name: test:acceptance (dynamic ${{ matrix.shard.shard }}/${{ matrix.shard.total }})
+        if: matrix.shard.type == 'dynamic'
+        run: |
+          exclude='${{ needs.enshard.outputs.acceptance-patterns }}'
+          if [[ -n "$exclude" ]]; then
+            THOROUGH=true npm run test:acceptance -- --testPathIgnorePatterns="$exclude" --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          else
+            THOROUGH=true npm run test:acceptance -- --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          fi
+
+      - name: report slow tests
+        if: always() && hashFiles('jest-results.json') != ''
+        run: |
+          jq -r '.testResults[] | "\(.name):\(.perfStats.runtime)"' jest-results.json | while IFS=: read -r name runtime; do
+            seconds=$((runtime / 1000))
+            if [[ $seconds -ge 30 ]]; then
+              echo "::warning file=${name}::slow test: ${seconds}s"
+            elif [[ $seconds -ge 10 ]]; then
+              echo "::notice file=${name}::test duration: ${seconds}s"
+            fi
+          done
+
+  # union job: aggregates shard results into single status for pr merge constraints
+  test-integration:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard, test-shards-integration]
+    if: always() && needs.install.result == 'success' && needs.enshard.result == 'success'
+    steps:
+      - name: report shard results
+        run: |
+          if [[ "${{ needs.test-shards-integration.result }}" == "success" ]]; then
+            echo "👌 all integration test shards passed"
+          else
+            echo "::error::some integration test shards failed"
+            exit 1
+          fi
+
+  # union job: aggregates shard results into single status for pr merge constraints
+  test-acceptance-locally:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard, test-shards-acceptance]
+    if: always() && needs.install.result == 'success' && needs.enshard.result == 'success'
+    steps:
+      - name: report shard results
+        run: |
+          if [[ "${{ needs.test-shards-acceptance.result }}" == "success" ]]; then
+            echo "👌 all acceptance test shards passed"
+          else
+            echo "::error::some acceptance test shards failed"
+            exit 1
+          fi

package/dist/practices/cicd-common/best-practice/.github/workflows/.test.yml.declapract.ts

@@ -0,0 +1,91 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { readUseApikeysConfig } from '../../../../../utils/readUseApikeysConfig';
+
+/**
+ * .what = builds the expected .test.yml content with apikey secrets injected
+ * .why = single source of truth for both check and fix
+ */
+export const buildExpectedContent = (input: {
+  template: string;
+  apikeys: string[];
+}): string => {
+  let result = input.template;
+
+  // if no apikeys, return template as-is
+  if (!input.apikeys.length) {
+    return result;
+  }
+
+  // build secrets declaration block for workflow_call
+  const secretsDeclaration = input.apikeys
+    .map(
+      (key) =>
+        `      ${key}:\n        description: "api key for ${key.toLowerCase().replace(/_/g, ' ')}"\n        required: false`,
+    )
+    .join('\n');
+
+  // build env block for test-integration job
+  const envBlock = input.apikeys
+    .map((key) => `          ${key}: \${{ secrets.${key} }}`)
+    .join('\n');
+
+  // insert secrets declaration after workflow_call inputs
+  // look for the pattern: inputs: ... (multiline) followed by blank line or permissions:
+  result = result.replace(
+    /(on:\n  workflow_call:\n    inputs:\n(?:      [^\n]+\n)+)/,
+    `$1    secrets:\n${secretsDeclaration}\n\n`,
+  );
+
+  // insert env block to test-integration job
+  // add env block after needs: [install] line
+  result = result.replace(
+    /(test-integration:\n    runs-on: ubuntu-24\.04\n    needs: \[install\]\n)/,
+    `$1    env:\n${envBlock}\n`,
+  );
+
+  return result;
+};
+
+/**
+ * .what = ensures .test.yml matches expected content with apikey secrets
+ * .why = enables integration tests to access required api keys via github secrets
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // read apikeys from project
+  const apikeysConfig = await readUseApikeysConfig({
+    projectRootDirectory: context.getProjectRootDirectory(),
+  });
+
+  // build expected content from template + apikeys
+  const expected = buildExpectedContent({
+    template: context.declaredFileContents ?? '',
+    apikeys: apikeysConfig?.apikeys?.required ?? [],
+  });
+
+  // if contents match expected, file passes (throw)
+  if (contents === expected) {
+    throw new Error('file matches expected content');
+  }
+
+  // return = file differs from expected (bad practice detected)
+};
+
+/**
+ * .what = fixes .test.yml to include apikey secrets declaration and env vars
+ * .why = ensures integration tests have access to required api keys
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // read apikeys from project
+  const apikeysConfig = await readUseApikeysConfig({
+    projectRootDirectory: context.getProjectRootDirectory(),
+  });
+
+  // build expected content from template + apikeys
+  const expected = buildExpectedContent({
+    template: context.declaredFileContents ?? '',
+    apikeys: apikeysConfig?.apikeys?.required ?? [],
+  });
+
+  return { contents: expected };
+};

package/dist/practices/cicd-common/best-practice/.github/workflows/test.yml.declapract.ts

@@ -0,0 +1,40 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import { buildWorkflowSecretsBlock } from '../../../../../utils/buildWorkflowSecretsBlock';
+
+/**
+ * .what = ensures test.yml matches expected content with apikey secrets block
+ * .why = enables the reusable workflow to access github secrets
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  if (contents === expected) throw new Error('file matches expected content');
+};
+
+/**
+ * .what = fixes test.yml to include apikey secrets block
+ * .why = ensures the reusable workflow receives required api keys
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  return { contents: expected };
+};

package/dist/practices/cicd-package/best-practice/.github/workflows/publish.yml.declapract.ts

@@ -0,0 +1,40 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import { buildWorkflowSecretsBlock } from '../../../../../utils/buildWorkflowSecretsBlock';
+
+/**
+ * .what = ensures publish.yml matches expected content with apikey secrets block
+ * .why = enables the reusable workflow to access github secrets during publish
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  if (contents === expected) throw new Error('file matches expected content');
+};
+
+/**
+ * .what = fixes publish.yml to include apikey secrets block
+ * .why = ensures the reusable workflow receives required api keys during publish
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  return { contents: expected };
+};

package/dist/practices/cicd-service/best-practice/.github/workflows/deploy.yml.declapract.ts

@@ -0,0 +1,40 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import { buildWorkflowSecretsBlock } from '../../../../../utils/buildWorkflowSecretsBlock';
+
+/**
+ * .what = ensures deploy.yml matches expected content with apikey secrets block
+ * .why = enables the reusable workflow to access github secrets during deploy
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  if (contents === expected) throw new Error('file matches expected content');
+};
+
+/**
+ * .what = fixes deploy.yml to include apikey secrets block
+ * .why = enables the reusable workflow receives required api keys during deploy
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  return { contents: expected };
+};

package/dist/utils/buildWorkflowSecretsBlock.ts

@@ -0,0 +1,35 @@
+import { readUseApikeysConfig } from './readUseApikeysConfig';
+
+/**
+ * .what = builds workflow content with apikey secrets block for .test.yml
+ * .why = single source of truth for test.yml, publish.yml, deploy.yml check+fix
+ */
+export const buildWorkflowSecretsBlock = async (
+  input: { template: string },
+  context: { getProjectRootDirectory: () => string },
+): Promise<string> => {
+  // read apikeys from project
+  const apikeysConfig = await readUseApikeysConfig({
+    projectRootDirectory: context.getProjectRootDirectory(),
+  });
+  const apikeys = apikeysConfig?.apikeys?.required ?? [];
+
+  // if no apikeys, return template as-is
+  if (!apikeys.length) {
+    return input.template;
+  }
+
+  // build secrets block
+  const secretsBlock = apikeys
+    .map((key) => `      ${key}: \${{ secrets.${key} }}`)
+    .join('\n');
+
+  // find jobs that call .test.yml with 'with:' block and add secrets block after
+  // handle cases with optional 'if:' before 'with:'
+  const result = input.template.replace(
+    /(uses: \.\/\.github\/workflows\/\.test\.yml\n(?:    if: [^\n]+\n)?    with:\n(?:      [^\n]+\n)+)/g,
+    `$1    secrets:\n${secretsBlock}\n`,
+  );
+
+  return result;
+};

package/dist/utils/readUseApikeysConfig.ts

@@ -0,0 +1,43 @@
+import fs from 'fs';
+import path from 'path';
+import util from 'util';
+
+/**
+ * .what = configuration structure for use.apikeys.json
+ * .why = defines which api keys are required for integration tests
+ */
+export interface UseApikeysConfig {
+  apikeys: {
+    required: string[];
+  };
+}
+
+const USE_APIKEYS_PATH = '.agent/repo=.this/role=any/skills/use.apikeys.json';
+
+/**
+ * .what = reads and parses use.apikeys.json from target project
+ * .why = centralizes apikey config access for all workflow practices
+ */
+export const readUseApikeysConfig = async (input: {
+  projectRootDirectory: string;
+}): Promise<UseApikeysConfig | null> => {
+  // build full path to config file
+  const configPath = path.join(input.projectRootDirectory, USE_APIKEYS_PATH);
+
+  // check if file exists
+  const exists = await util
+    .promisify(fs.access)(configPath, fs.constants.F_OK)
+    .then(() => true)
+    .catch(() => false);
+  if (!exists) return null;
+
+  // read and parse the file
+  try {
+    const contents = await util.promisify(fs.readFile)(configPath, 'utf-8');
+    const parsed = JSON.parse(contents) as UseApikeysConfig;
+    return parsed;
+  } catch {
+    // handle malformed json gracefully
+    return null;
+  }
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.47.18",
+  "version": "0.47.20",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -76,7 +76,7 @@
     "husky": "8.0.3",
     "jest": "30.2.0",
     "rhachet": "1.20.5",
-    "rhachet-roles-bhrain": "0.5.8",
+    "rhachet-roles-bhrain": "0.5.9",
     "rhachet-roles-bhuild": "0.5.6",
     "rhachet-roles-ehmpathy": "1.17.11",
     "tsc-alias": "1.8.10",

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

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