declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/__snapshots__/provision.yml.declapract.integration.test.ts.snap

@@ -0,0 +1,76 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`expo provision.yml — merge-by-job, end to end (#608) given: [case4] an expo repo with a provision.yml that holds a terraform github job and an aws job when: [t0] declapract apply then: before + after match snapshot: provision.yml — after merge 1`] = `
+"name: provision
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+permissions:
+  id-token: write # required for oidc; a called workflow cannot exceed its caller's grant
+  contents: read
+
+jobs:
+  # the pre-migration github job: terraform over the provision/github/ dir the migration deletes
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/github.repo/resources.ts
+      scope: github
+      access: prod # github repo settings are inherently a prod resource
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: \${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply
+      creds-github-app-owner: \${{ github.repository_owner }}
+      creds-github-app-id: \${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
+    secrets:
+      creds-github-app-private-key: \${{ secrets.DECLASTRUCT_GITHUB_CONFORMER_APP_PRIVATE_KEY }}
+
+  # the repo's own aws job, which the practice never declares
+  aws:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/prod
+"
+`;
+
+exports[`expo provision.yml — merge-by-job, end to end (#608) given: [case4] an expo repo with a provision.yml that holds a terraform github job and an aws job when: [t0] declapract apply then: before + after match snapshot: provision.yml — before 1`] = `
+"name: provision
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+
+jobs:
+  # the pre-migration github job: terraform over the provision/github/ dir the migration deletes
+  github:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/github/product
+      github-environment: prod
+
+  # a second terraform job on the deleted dir, under another name
+  github-environment:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/github/environment
+
+  # the repo's own aws job, which the practice never declares
+  aws:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/prod
+"
+`;

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/best-practice/.github/workflows/.deploy-expo.yml

@@ -13,7 +13,7 @@ on:
         required: true
       github-environment:
         type: string
-        description: "github environment for the deploy jobs"
+        description: "the github environment for the deploy jobs; always declared, and one of the environments that provision/github.repo/resources.ts declares, e.g. preparation or production-on-main"
         required: true
       creds-aws-region:
         type: string
@@ -33,8 +33,8 @@ on:
         required: true
         description: required credentials to authenticate with expo eas
 
+# .why = least privilege: only the jobs that assume the aws role grant id-token, at job scope
 permissions:
-  id-token: write # required for oidc
   contents: read
 
 jobs:
@@ -50,6 +50,9 @@ jobs:
           - android
     name: ${{ matrix.platform }}
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so no
       # "deployed to <env>" status accretes on the PR timeline. the environment is ALWAYS
@@ -94,6 +97,9 @@ jobs:
   deploy-web:
     name: web
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write # required for oidc
     environment:
       # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so no
       # "deployed to <env>" status accretes on the PR timeline. the environment is ALWAYS
@@ -132,6 +138,8 @@ jobs:
 
       - name: compile
         run: npm run build:web
+        env:
+          ACCESS: ${{ inputs.access }} # the bundle inlines the access it was built with; never a guess
 
       - name: deploy
-        run: aws s3 sync ./dist ${{ inputs.app-web-deployment-s3-bucket }} --delete --cache-control max-age=60,stale-while-revalidate=604800 # todo: fine tune the cache control; https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate
+        run: aws s3 sync ./dist ${{ inputs.app-web-deployment-s3-bucket }} --delete --cache-control max-age=60,stale-while-revalidate=604800 # a deploy shows within 60s; stale-while-revalidate serves the prior build while it refreshes

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/best-practice/.github/workflows/provision.yml

@@ -0,0 +1,33 @@
+name: provision
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+permissions:
+  id-token: write # required for oidc; a called workflow cannot exceed its caller's grant
+  contents: read
+
+jobs:
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/github.repo/resources.ts
+      scope: github
+      access: prod # github repo settings are inherently a prod resource
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply
+      creds-github-app-owner: ${{ github.repository_owner }}
+      creds-github-app-id: ${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
+    secrets:
+      creds-github-app-private-key: ${{ secrets.DECLASTRUCT_GITHUB_CONFORMER_APP_PRIVATE_KEY }}

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/best-practice/.github/workflows/provision.yml.declapract.ts

@@ -0,0 +1,75 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
+
+import { asWorkflowMergedByJob } from '../../../../../utils/asWorkflowMergedByJob';
+import { getAllWorkflowJobDrifts } from '../../../../../utils/getAllWorkflowJobDrifts';
+
+/**
+ * .what = whether a found workflow job still points at the `provision/github/` terraform dir
+ * .why  = `provision-github`'s migration deletes that dir; a job that still reads it fails
+ *         `terraform validate` on every branch, so it is obsolete and must leave with the dir.
+ *         `provision/github.repo/` (the declastruct wish) is a distinct path and never matches.
+ */
+const isJobOnTerraformGithubDir = (input: { job: unknown }): boolean =>
+  JSON.stringify(input.job ?? null).includes('provision/github/');
+
+/**
+ * .what = the declared contents this check and fix read, or a loud failure where none arrived
+ * .why  = this declaration ships a template beside it, so an absent body is a pipeline
+ *         malfunction, never a consumer input
+ */
+const asDeclaredContents = (input: {
+  declaredFileContents: string | null;
+  relativeFilePath: string;
+}): string => {
+  if (input.declaredFileContents === null)
+    throw new MalfunctionError(
+      'the cicd-app-react-native-expo practice emitted no declared provision.yml',
+      {
+        practice: 'cicd-app-react-native-expo',
+        relativeFilePath: input.relativeFilePath,
+      },
+    );
+  return input.declaredFileContents;
+};
+
+/**
+ * .what = pass when the declared `github` job (and each declared top-level key) holds its
+ *         declared shape, and no job still points at the deleted `provision/github/` dir
+ * .why  = the expo usecase composes `provision-github`, whose migration deletes
+ *         `provision/github/**` and leaves no caller for its declastruct replacement (#608). an
+ *         EQUALS template would reach the expo repo and delete any other provision job it holds
+ *         (e.g. an aws job), so this declaration merges by job: the `github` job is the
+ *         practice's; every other job is the repo's, kept as found — except a job that still
+ *         reads the deleted terraform dir.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents) throw new Error('provision.yml is absent');
+  const drift = getAllWorkflowJobDrifts({
+    found: contents,
+    declared: asDeclaredContents(context),
+    dropJobWhen: isJobOnTerraformGithubDir,
+  });
+  if (drift.length > 0)
+    throw new Error(
+      `provision.yml drifts from its declaration:\n- ${drift.join('\n- ')}`,
+    );
+};
+
+/**
+ * .what = create the file where absent; else replace the `github` job, drop each job on the
+ *         deleted terraform dir, and keep every other job as it stands
+ * .why  = see `check`. the merge returns the found text untouched where no drift remains, so a
+ *         second apply changes zero bytes.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  const declared = asDeclaredContents(context);
+  if (!contents) return { contents: declared };
+  return {
+    contents: asWorkflowMergedByJob({
+      found: contents,
+      declared,
+      dropJobWhen: isJobOnTerraformGithubDir,
+    }),
+  };
+};

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/best-practice/package.json

@@ -4,19 +4,22 @@
     "expo-dev-client": "@declapract{check.minVersion('4.0.20')}",
     "expo-updates": "@declapract{check.minVersion('0.25.21')}"
   },
+  "devDependencies": {
+    "wait-on": "@declapract{check.minVersion('9.5.1')}"
+  },
   "scripts": {
-    "start:hot:proxy": "npx local-ssl-proxy --source 3447 --target 8081",
-    "start:hot:prep": "ACCESS=prep npx expo start --clear --dev-client",
+    "start:hot:proxy": "wait-on tcp:8081 && npx local-ssl-proxy --source 3447 --target 8081",
+    "start:hot:prep": "ACCESS=prep expo start --clear --dev-client",
     "start:hot:prep:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prep}:@declapract{variable.app.web.port.hot}'",
     "start:hot:prep:proxy": "npm run start:hot:prep:link && npm run start:hot:proxy",
-    "start:hot:prod": "ACCESS=prod npx expo start --clear --dev-client",
+    "start:hot:prod": "ACCESS=prod expo start --clear --dev-client",
     "start:hot:prod:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prod}:@declapract{variable.app.web.port.hot}'",
     "start:hot:prod:proxy": "npm run start:hot:prod:link && npm run start:hot:proxy",
-    "start:cold:proxy": "npx local-ssl-proxy --source 3449 --target 3000",
-    "start:cold:prep": "npm run build:web && npx serve dist --single",
+    "start:cold:proxy": "wait-on tcp:3000 && npx local-ssl-proxy --source 3449 --target 3000",
+    "start:cold:prep": "ACCESS=prep npm run build:web && npx serve dist --single",
     "start:cold:prep:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prep}:@declapract{variable.app.web.port.cold}'",
-    "start:cold:prep:proxy": "echo npm run start:cold:prep:link && npm run start:cold:proxy",
-    "start:cold:prod": "npm run build:web && npx serve dist --single",
+    "start:cold:prep:proxy": "npm run start:cold:prep:link && npm run start:cold:proxy",
+    "start:cold:prod": "ACCESS=prod npm run build:web && npx serve dist --single",
     "start:cold:prod:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prod}:@declapract{variable.app.web.port.cold}'",
     "register:device:apple:info": "echo 'learn more here https://docs.expo.dev/build/internal-distribution/'",
     "register:device:apple:inclusions:rebuild:prod": "npx eas build --platform ios --clear-cache",

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/package.json.declapract.integration.test.ts

@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import { parse } from 'yaml';
+
+/**
+ * .what = clamps on the expo start/proxy commands and the web deploy compile step: each names
+ *         the access it builds with, and each proxy waits on its target
+ * .why  = `start:cold:prep` and `start:cold:prod` were byte-identical and both reached prod
+ *         (#620, #653); the deploy compile step held `inputs.access` and dropped it (#619); and a
+ *         proxy that starts before its target listens hangs every request (#676). none of that
+ *         is visible to a green typecheck or build, so these clamps read the shipped templates.
+ * .note = a filesystem read of the templates → integration grain, per
+ *         rule.forbid.unit.remote-boundaries; no credential, no network
+ */
+
+/**
+ * .what = the npm run commands and devDependencies the template declares
+ * .why  = one read of the shipped template, named by what the clamps consume
+ */
+const getTemplateCommands = (): {
+  commands: Record<string, string>;
+  devDependencies: Record<string, string>;
+} => {
+  const template = JSON.parse(
+    readFileSync(path.join(__dirname, 'best-practice/package.json'), 'utf-8'),
+  );
+  return {
+    commands: template.scripts ?? {},
+    devDependencies: template.devDependencies ?? {},
+  };
+};
+
+/**
+ * .what = the access a command sets inline (`ACCESS=<access> …`), or null where it sets none
+ * .why  = names the read so each clamp states which access a command builds with
+ */
+const asAccessOfCommand = (input: { command: string }): string | null =>
+  /(?:^|\s)ACCESS=([a-z]+)\b/.exec(input.command)?.[1] ?? null;
+
+/**
+ * .what = the `--target` port a local-ssl-proxy command forwards to
+ * .why  = names the read so the wait-on clamp can pair each proxy with its own target
+ */
+const asProxyTargetPort = (input: { command: string }): string | null =>
+  /local-ssl-proxy .*--target (\d+)/.exec(input.command)?.[1] ?? null;
+
+describe('cicd-app-react-native-expo package.json — access + proxy clamps', () => {
+  given('[case1] the shipped start commands', () => {
+    const { commands, devDependencies } = getTemplateCommands();
+
+    when('[t0] each cold build is paired with its hot twin (#653)', () => {
+      const envsCold = Object.keys(commands)
+        .map((name) => /^start:cold:([a-z]+)$/.exec(name)?.[1] ?? null)
+        .filter((env): env is string => env !== null && env !== 'proxy');
+
+      then('both access envs have a cold build', () => {
+        expect([...envsCold].sort()).toEqual(['prep', 'prod']);
+      });
+
+      then('each start:cold:<env> sets the same ACCESS as its start:hot:<env>, and that ACCESS is <env>', () => {
+        for (const env of envsCold) {
+          const accessCold = asAccessOfCommand({
+            command: commands[`start:cold:${env}`] ?? '',
+          });
+          const accessHot = asAccessOfCommand({
+            command: commands[`start:hot:${env}`] ?? '',
+          });
+          expect({ env, accessCold }).toEqual({ env, accessCold: env });
+          expect({ env, accessHot }).toEqual({ env, accessHot: env });
+        }
+      });
+
+      then('start:cold:prep and start:cold:prod differ (#620)', () => {
+        expect(commands['start:cold:prep']).not.toEqual(
+          commands['start:cold:prod'],
+        );
+      });
+    });
+
+    when('[t1] each proxy gates on its target port (#676)', () => {
+      const proxies = Object.entries(commands).filter(([, command]) =>
+        command.includes('local-ssl-proxy'),
+      );
+
+      then('there is a hot and a cold proxy', () => {
+        expect(proxies.map(([name]) => name).sort()).toEqual([
+          'start:cold:proxy',
+          'start:hot:proxy',
+        ]);
+      });
+
+      then('each proxy waits on tcp:<its own target> before it listens', () => {
+        for (const [name, command] of proxies) {
+          const port = asProxyTargetPort({ command });
+          expect({ name, port }).toEqual({ name, port: expect.any(String) });
+          expect({
+            name,
+            gated: command.startsWith(`wait-on tcp:${port} && `),
+          }).toEqual({ name, gated: true });
+        }
+      });
+
+      then('wait-on is a declared devDependency', () => {
+        expect(devDependencies['wait-on']).toBeDefined();
+      });
+
+      then('no command echoes a run in place of the run itself (#620)', () => {
+        for (const command of Object.values(commands))
+          expect(command.startsWith('echo npm run')).toEqual(false);
+      });
+    });
+
+    when('[t2] the start commands are snapshotted for review', () => {
+      then('the start:* commands match snapshot', () => {
+        const starts = Object.fromEntries(
+          Object.entries(commands).filter(([name]) => name.startsWith('start:')),
+        );
+        expect(starts).toMatchSnapshot('start:* commands');
+      });
+    });
+  });
+
+  given('[case2] the deploy workflow web compile step (#619)', () => {
+    const workflow = parse(
+      readFileSync(
+        path.join(__dirname, 'best-practice/.github/workflows/.deploy-expo.yml'),
+        'utf-8',
+      ),
+    );
+    const steps: {
+      name?: string;
+      run?: string;
+      env?: Record<string, string>;
+    }[] = workflow.jobs['deploy-web'].steps;
+    const compile = steps.find((step) => step.name === 'compile');
+
+    when('[t0] the web compile step runs', () => {
+      then('it runs build:web', () => {
+        expect(compile?.run).toEqual('npm run build:web');
+      });
+
+      then('its env passes ACCESS from the access input', () => {
+        expect(compile?.env?.ACCESS).toEqual('${{ inputs.access }}');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/provision.yml.declapract.integration.test.ts

@@ -0,0 +1,131 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+import { parse } from 'yaml';
+
+// executeApply is slow (usecase evaluation), so widen the jest budget
+jest.setTimeout(240_000);
+
+/**
+ * .what = end-to-end proof of the expo provision.yml merge-by-job declaration (#608)
+ * .why  = the expo usecase composes `provision-github`, whose migration deletes
+ *         `provision/github/**`; before this declaration no expo practice owned the
+ *         `provision.yml` caller, so the repo kept a terraform job over an empty dir and its
+ *         `github / plan` check failed on every branch. only a real apply proves declapract wires
+ *         the custom check + fix to this file: the `github` job lands as the declastruct call,
+ *         each job on the deleted dir leaves, and the repo's own aws job stays.
+ * .note = the lean declarations mirror holds only cicd-app-react-native-expo + typescript-expo,
+ *         so the apply evaluates two practices, not the full usecase
+ */
+
+const FIXTURE = './src/.test/assets/cicd-app-react-native-expo/demo-repo-expo';
+const DECLARATIONS_MIRROR =
+  './src/.test/assets/cicd-app-react-native-expo/declarations';
+const PROVISION_PATH = '.github/workflows/provision.yml';
+
+const genDemoRepo = (slug: string) =>
+  genTempDir({
+    slug,
+    clone: FIXTURE,
+    symlink: [
+      { at: 'declarations', to: DECLARATIONS_MIRROR },
+      { at: 'node_modules', to: 'node_modules' },
+    ],
+  });
+
+describe('expo provision.yml — merge-by-job, end to end (#608)', () => {
+  given('[case4] an expo repo with a provision.yml that holds a terraform github job and an aws job', () => {
+    const tempDir = genDemoRepo('declapract-expo-provision-merge');
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const apply = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: PROVISION_PATH,
+      });
+
+    const state = useBeforeAll(async () => {
+      const before = await read(PROVISION_PATH);
+      await apply();
+      const after1 = await read(PROVISION_PATH);
+      await apply();
+      const after2 = await read(PROVISION_PATH);
+      return { before, after1, after2 };
+    }, 230_000);
+
+    when('[t0] declapract apply', () => {
+      then('the github job calls the declastruct workflow with the github.repo wish', () => {
+        const github = parse(state.after1).jobs.github;
+        expect(github.uses).toEqual('./.github/workflows/.declastruct.yml');
+        expect(github.with['wish-path']).toEqual(
+          'provision/github.repo/resources.ts',
+        );
+      });
+
+      then('no job still points at the deleted provision/github/ dir', () => {
+        // read the parsed jobs, since a found comment may still name the dir as prose
+        const jobsBefore = JSON.stringify(parse(state.before).jobs);
+        const jobsAfter = JSON.stringify(parse(state.after1).jobs);
+        expect(jobsBefore).toContain('provision/github/');
+        expect(jobsAfter).not.toContain('provision/github/');
+        expect(parse(state.after1).jobs['github-environment']).toBeUndefined();
+      });
+
+      then('the aws job survives, unchanged', () => {
+        expect(parse(state.after1).jobs.aws).toEqual(
+          parse(state.before).jobs.aws,
+        );
+        expect(state.after1).toContain(
+          "# the repo's own aws job, which the practice never declares",
+        );
+      });
+
+      then('the oidc permissions block lands for the declastruct call', () => {
+        expect(parse(state.after1).permissions['id-token']).toEqual('write');
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.before).toMatchSnapshot('provision.yml — before');
+        expect(state.after1).toMatchSnapshot('provision.yml — after merge');
+      });
+    });
+
+    when('[t1] declapract apply again', () => {
+      then('zero bytes change', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+  });
+
+  given('[case5] an expo repo with no provision.yml', () => {
+    const tempDir = genDemoRepo('declapract-expo-provision-absent');
+    const read = (rel: string) =>
+      fs.readFile(path.join(tempDir, rel), 'utf-8').catch(() => null);
+
+    const state = useBeforeAll(async () => {
+      await fs.rm(path.join(tempDir, PROVISION_PATH));
+      const before = await read(PROVISION_PATH);
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: PROVISION_PATH,
+      });
+      const after = await read(PROVISION_PATH);
+      const template = await fs.readFile(
+        'src/practices/cicd-app-react-native-expo/best-practice/.github/workflows/provision.yml',
+        'utf-8',
+      );
+      return { before, after, template };
+    }, 230_000);
+
+    when('[t0] declapract apply', () => {
+      then('provision.yml exists with the github job, equal to the template', () => {
+        expect(state.before).toBeNull();
+        expect(state.after).toEqual(state.template);
+        expect(parse(state.after!).jobs.github.with['wish-path']).toEqual(
+          'provision/github.repo/resources.ts',
+        );
+      });
+    });
+  });
+});