declapract-typescript-ehmpathy 0.49.9 → 0.49.10

package/dist/practices/cicd-common/.test/assets/repo-with-unpinned-workflow/.github/workflows/consumer-owned.yml

@@ -0,0 +1,21 @@
+# .what = a workflow NO practice declares — it belongs to the consumer alone
+# .why = wish constraint 2: "the template's reach ends at the refs it owns. do not silently
+#        rewrite what the practice does not own."
+# .note = the tag refs below are DELIBERATE and must NOT be pinned. they are what the test
+#         asserts survives untouched. a "helpful" pin here makes the clamp vacuous
+name: consumer-owned
+
+on:
+  workflow_dispatch:
+
+jobs:
+  whatever:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20

package/dist/practices/cicd-common/.test/assets/repo-with-unpinned-workflow/.github/workflows/review.yml

@@ -0,0 +1,26 @@
+name: review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pullreq-title:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: test:pullreq:title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # https://github.com/commitizen/conventional-commit-types
+          types: |
+            fix
+            feat
+            chore

package/dist/practices/cicd-common/.test/assets/repo-with-unpinned-workflow/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test
+# .why  = `typescript-project` here carries `cicd-common` ALONE, so the apply exercises
+#         the workflow declarations and no others. the claim under test is about one
+#         file's delivery, not about a full scaffold
+declarations: 'declarations/declapract.declare.yml'
+useCase: typescript-project

package/dist/practices/cicd-common/.test/assets/repo-with-unpinned-workflow/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/cicd-common/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,550 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`cicd-common workflow templates given: [case1] a consumer repo whose workflow still carries a tag ref when: [t0] before any apply then: the input file matches snapshot: review.yml -- before 1`] = `
+"name: review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pullreq-title:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: test:pullreq:title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        with:
+          # https://github.com/commitizen/conventional-commit-types
+          types: |
+            fix
+            feat
+            chore
+"
+`;
+
+exports[`cicd-common workflow templates given: [case1] a consumer repo whose workflow still carries a tag ref when: [t1] the cicd-common practice is applied then: the settled file matches snapshot: review.yml -- after 1`] = `
+"name: review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pullreq-title:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: test:pullreq:title
+        uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        with:
+          # https://github.com/commitizen/conventional-commit-types
+          types: |
+            fix
+            feat
+            chore
+"
+`;
+
+exports[`cicd-common workflow templates given: [case2] a consumer whose .test.yml is stale, on the custom-fix path when: [t0] before any apply then: the input file matches snapshot: .test.yml -- before 1`] = `
+"name: .test
+
+on:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: test:unit
+        run: npm run test:unit
+"
+`;
+
+exports[`cicd-common workflow templates given: [case2] a consumer whose .test.yml is stale, on the custom-fix path when: [t1] the cicd-common practice is applied then: the settled file matches snapshot: .test.yml -- after 1`] = `
+"name: .test
+
+on:
+  workflow_call:
+    inputs:
+      creds-aws-role-arn:
+        description: "creds for aws, specifies the role to assume via oidc. if not provided, aws auth is skipped"
+        required: false
+        type: string
+      creds-aws-region:
+        description: "creds for aws, specifies the region. defaults to us-east-1"
+        required: false
+        type: string
+        default: "us-east-1"
+
+permissions:
+  id-token: write # required for oidc
+  contents: read
+
+jobs:
+  # install the dependencies
+  install:
+    uses: ./.github/workflows/.install.yml
+
+  # run tests in parallel
+  test-commits:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:commits
+        run: npm run test:commits
+
+  test-types:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: build
+        run: npm run build # build before test:types, to ensure .dist/ artifacts are importable for blackbox tests
+
+      - name: test:types
+        run: npm run test:types
+
+  test-format:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: set terraform version
+        uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:format
+        run: npm run test:format
+
+  test-lint:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:lint
+        run: npm run test:lint
+
+  test-unit:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:unit
+        run: THOROUGH=true npm run test:unit
+
+  # 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@11d5960a326750d5838078e36cf38b85af677262 # 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@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      # .why = keyrack.yml can extend other manifests via symlinks (e.g., .agent/repo=ehmpathy/role=mechanic/keyrack.yml)
+      #        prepare:rhachet creates these symlinks so keyrack.source() can hydrate extended keys
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      # .why = keyrack firewall translates and validates secrets before tests run
+      #        - filters to declared keys in keyrack.yml
+      #        - translates mechanisms (e.g., GitHub App → ghs_* token)
+      #        - blocks dangerous patterns (ghp_*, AKIA*, etc.)
+      #        - exports to $GITHUB_ENV with mask applied
+      - name: keyrack firewall
+        run: npx rhachet keyrack firewall --env test --from 'json(env://SECRETS_JSON)' --into github.actions
+        env:
+          SECRETS_JSON: \${{ toJSON(secrets) }}
+
+      - name: get aws auth, if creds supplied
+        if: \${{ inputs.creds-aws-role-arn }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: \${{ inputs.creds-aws-role-arn }}
+          aws-region: \${{ inputs.creds-aws-region }}
+
+      - name: start:testdb
+        run: npm run start:testdb --if-present
+
+      - name: start:livedb:prep
+        run: npm run start:livedb:prep --if-present
+
+      - name: build
+        run: npm run build
+
+      - name: test:integration (explicit \${{ matrix.shard.index }})
+        if: matrix.shard.type == 'explicit'
+        run: |
+          set -eu
+          patterns='\${{ join(matrix.shard.patterns, '|') }}'
+          THOROUGH=true npm run test:integration -- --testPathPatterns="$patterns" --json --outputFile=jest-results.json
+
+      - name: test:integration (dynamic \${{ matrix.shard.shard }}/\${{ matrix.shard.total }})
+        if: matrix.shard.type == 'dynamic'
+        run: |
+          set -eu
+          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: |
+          set -eu
+          jq -r '.testResults[] | select(.perfStats.runtime != null) | "\\(.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, enshard]
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: \${{ fromJson(needs.enshard.outputs.acceptance-matrix) }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: \${{ needs.install.outputs.node-modules-cache-key }}
+
+      # .why = keyrack.yml can extend other manifests via symlinks (e.g., .agent/repo=ehmpathy/role=mechanic/keyrack.yml)
+      #        prepare:rhachet creates these symlinks so keyrack.source() can hydrate extended keys
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      # .why = keyrack firewall translates and validates secrets before tests run
+      #        - filters to declared keys in keyrack.yml
+      #        - translates mechanisms (e.g., GitHub App → ghs_* token)
+      #        - blocks dangerous patterns (ghp_*, AKIA*, etc.)
+      #        - exports to $GITHUB_ENV with mask applied
+      - name: keyrack firewall
+        run: npx rhachet keyrack firewall --env test --from 'json(env://SECRETS_JSON)' --into github.actions
+        env:
+          SECRETS_JSON: \${{ toJSON(secrets) }}
+
+      - name: get aws auth, if creds supplied
+        if: \${{ inputs.creds-aws-role-arn }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: \${{ inputs.creds-aws-role-arn }}
+          aws-region: \${{ inputs.creds-aws-region }}
+
+      - name: start:testdb
+        run: npm run start:testdb --if-present
+
+      - name: start:livedb:prep
+        run: npm run start:livedb:prep --if-present
+
+      - name: build
+        run: npm run build
+
+      - name: test:acceptance (explicit \${{ matrix.shard.index }})
+        if: matrix.shard.type == 'explicit'
+        run: |
+          set -eu
+          patterns='\${{ join(matrix.shard.patterns, '|') }}'
+          THOROUGH=true npm run test:acceptance -- --testPathPatterns="$patterns" --json --outputFile=jest-results.json
+
+      - name: test:acceptance (dynamic \${{ matrix.shard.shard }}/\${{ matrix.shard.total }})
+        if: matrix.shard.type == 'dynamic'
+        run: |
+          set -eu
+          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: |
+          set -eu
+          jq -r '.testResults[] | select(.perfStats.runtime != null) | "\\(.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: |
+          set -eu
+          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: |
+          set -eu
+          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
+"
+`;
+
+exports[`cicd-common workflow templates given: [case3] a consumer repo that also has a workflow of its OWN when: [t0] the whole practice is applied, unscoped then: and both halves of the untouched file match snapshot: consumer-owned.yml -- after 1`] = `
+"# .what = a workflow NO practice declares — it belongs to the consumer alone
+# .why = wish constraint 2: "the template's reach ends at the refs it owns. do not silently
+#        rewrite what the practice does not own."
+# .note = the tag refs below are DELIBERATE and must NOT be pinned. they are what the test
+#         asserts survives untouched. a "helpful" pin here makes the clamp vacuous
+name: consumer-owned
+
+on:
+  workflow_dispatch:
+
+jobs:
+  whatever:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+"
+`;
+
+exports[`cicd-common workflow templates given: [case3] a consumer repo that also has a workflow of its OWN when: [t0] the whole practice is applied, unscoped then: and both halves of the untouched file match snapshot: consumer-owned.yml -- before 1`] = `
+"# .what = a workflow NO practice declares — it belongs to the consumer alone
+# .why = wish constraint 2: "the template's reach ends at the refs it owns. do not silently
+#        rewrite what the practice does not own."
+# .note = the tag refs below are DELIBERATE and must NOT be pinned. they are what the test
+#         asserts survives untouched. a "helpful" pin here makes the clamp vacuous
+name: consumer-owned
+
+on:
+  workflow_dispatch:
+
+jobs:
+  whatever:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+"
+`;
+
+exports[`cicd-common workflow templates given: [case4] a consumer repo where the declared workflow is ABSENT when: [t0] before any apply, with the workflow removed then: the before-state reads as absent: review.yml -- before (absent) 1`] = `"absent"`;
+
+exports[`cicd-common workflow templates given: [case4] a consumer repo where the declared workflow is ABSENT when: [t1] the cicd-common practice is applied then: the created file matches snapshot: review.yml -- after (created) 1`] = `
+"name: review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pullreq-title:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: test:pullreq:title
+        uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        with:
+          # https://github.com/commitizen/conventional-commit-types
+          types: |
+            fix
+            feat
+            chore
+"
+`;

package/dist/practices/cicd-common/best-practice/.declapract.readme.md

@@ -1,3 +1,8 @@
 flows:
 - test on every commit
 - create please-release pull requests on every commit to main
+
+every third-party `uses:` here is pinned to a full-length commit sha with the tag it came from
+(`actions/checkout@11d5960… # v4`), because the ehmpathy org sets `sha_pinning_required`. the shape
+is held by `src/actionPins.declapract.integration.test.ts`, which also carries the note on how to derive a sha
+for a bump.