declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/format/declarations/practices/format/.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';
+
+// executeApply is slow (full usecase evaluation), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = pipeline test for the usecase-aware format package.json `contents` fn (r001.b3)
+ * .why  = a unit test proves the `contents` fn in isolation against a mocked context; only the
+ *         real executeApply pipeline proves that declapract:
+ *         - matches the package.json declaration to the consumer's package.json
+ *         - feeds context.projectPractices with the terraform signal derived through a REAL usecase
+ *           (terraform-common present vs absent), NOT a hand-built context object
+ *         - emits the chained fix:format / test:format the branch builds, into the file on disk
+ *         per rule.require.declapract-integration-tests, a usecase-aware `contents` fn that silently
+ *         changes what a consumer receives owes an executeApply pipeline test, not a unit test alone.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads the filesystem + runs
+ *         executeApply against a temp clone. no credential, no network. the fixtures live under a
+ *         `.test` dot-dir (excluded from tsconfig/jest globs); a lean declarations mirror symlinks
+ *         only format + terraform-common so the whole-usecase compile does not blow the hook timeout.
+ * .note = the confound: terraform-common's OWN package.json also declares a standalone
+ *         `fix:format:terraform` command, so a bare "contains fix:format:terraform" assertion could
+ *         not isolate the format branch. the DISTINGUISHING signal for format's branch is the
+ *         CHAINED `fix:format` value (`... && npm run fix:format:terraform`), which only format emits.
+ *         so every assertion reads the `fix:format` chain value, never the standalone key.
+ * .teeth = with-terraform: the emitted `fix:format` chain MUST include the terraform sub-command —
+ *          a revert of the branch to biome-only reddens it. without-terraform: the chain MUST be
+ *          biome-only — a branch that fired on the wrong (absent) signal reddens it.
+ */
+describe('format practice — the usecase-aware package.json contents fn (r001.b3)', () => {
+  const readCommands = async (
+    tempDir: string,
+  ): Promise<Record<string, string>> => {
+    const raw = await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+    return JSON.parse(raw).scripts as Record<string, string>;
+  };
+
+  given('[case1] a consumer on a terraform usecase', () => {
+    const tempDir = genTempDir({
+      slug: 'format-pkgjson-with-terraform',
+      clone: './src/.test/assets/format/repo-with-terraform',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/format/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    // useBeforeAll RETURNS the captured reads (no in-place mutation of a shared const).
+    // .note = filter by file ONLY, never by practice. the practice filter narrows
+    //         projectPractices too (getDesiredPractices), which would strip terraform-common
+    //         and silence the branch. file-only keeps every usecase practice in projectPractices
+    //         while it applies just the package.json plan.
+    const commands = useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+      return readCommands(tempDir);
+    }, 170_000);
+
+    when('[t0] the format package.json is applied', () => {
+      then('the fix:format chain includes the terraform sub-command', () => {
+        expect(commands['fix:format']).toContain('npm run fix:format:terraform');
+      });
+
+      then('the fix:format chain still leads with biome', () => {
+        expect(commands['fix:format']).toContain('npm run fix:format:biome');
+      });
+
+      then('the test:format chain includes the terraform sub-command', () => {
+        expect(commands['test:format']).toContain(
+          'npm run test:format:terraform',
+        );
+      });
+
+      then('the emitted commands block matches snapshot', () => {
+        expect(commands).toMatchSnapshot('with-terraform — commands');
+      });
+    });
+  });
+
+  given('[case2] a consumer on a non-terraform usecase', () => {
+    const tempDir = genTempDir({
+      slug: 'format-pkgjson-without-terraform',
+      clone: './src/.test/assets/format/repo-without-terraform',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/format/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const commands = useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+      return readCommands(tempDir);
+    }, 170_000);
+
+    when('[t0] the format package.json is applied', () => {
+      then('the fix:format chain is biome-only', () => {
+        expect(commands['fix:format']).toEqual('npm run fix:format:biome');
+      });
+
+      then('the fix:format chain omits the terraform sub-command (the teeth)', () => {
+        expect(commands['fix:format']).not.toContain(
+          'npm run fix:format:terraform',
+        );
+      });
+
+      then('the test:format chain omits the terraform sub-command', () => {
+        expect(commands['test:format']).not.toContain(
+          'npm run test:format:terraform',
+        );
+      });
+
+      then('the emitted commands block matches snapshot', () => {
+        expect(commands).toMatchSnapshot('without-terraform — commands');
+      });
+    });
+  });
+});

package/dist/.test/assets/format/declarations/practices/format/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`format practice — the usecase-aware package.json contents fn (r001.b3) given: [case1] a consumer on a terraform usecase when: [t0] the format package.json is applied then: the emitted commands block matches snapshot: with-terraform — commands 1`] = `
+{
+  "fix:format": "npm run fix:format:biome && npm run fix:format:terraform",
+  "fix:format:terraform": "terraform fmt -recursive provision",
+  "test:format": "npm run test:format:biome && npm run test:format:terraform",
+  "test:format:terraform": "terraform fmt -recursive -check provision",
+}
+`;
+
+exports[`format practice — the usecase-aware package.json contents fn (r001.b3) given: [case2] a consumer on a non-terraform usecase when: [t0] the format package.json is applied then: the emitted commands block matches snapshot: without-terraform — commands 1`] = `
+{
+  "fix:format": "npm run fix:format:biome",
+  "test:format": "npm run test:format:biome",
+}
+`;

package/dist/.test/assets/format/declarations/practices/format/bad-practices/format-script/package.json.declapract.ts

@@ -0,0 +1,26 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('fine, does not match bad practice'); // if not defined, doesn't have the script
+  const parsedContents = JSON.parse(contents);
+  if (typeof parsedContents.scripts.format === 'string') return; // matches bad practice file
+  throw new Error('fine, does not have format script');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  // parse the contents
+  if (!contents) return {}; // do nothing if no contents, shouldn't have reached here to begin with
+  const parsedContents = JSON.parse(contents);
+
+  // remove "format"
+  const fixedContents = {
+    ...parsedContents,
+    scripts: {
+      ...parsedContents.scripts,
+      format: undefined, // remove format
+    },
+  };
+
+  // and return the fixed json
+  return { contents: JSON.stringify(fixedContents, null, 2) };
+};

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/.declapract.readme.md

@@ -0,0 +1,6 @@
+Prettier is no longer used - biome or other tools are preferred. This bad practice removes:
+
+- prettier.config.js
+- .prettierignore
+- prettier and @trivago/prettier-plugin-sort-imports devDependencies
+- fix:format:prettier and test:format:prettier scripts

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/.prettierignore

@@ -0,0 +1,3 @@
+*.md
+.yalc/
+dist/

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/.prettierignore.declapract.ts

@@ -0,0 +1,8 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  // Remove the file by returning null contents
+  return { contents: null };
+};

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/package.json

@@ -0,0 +1,10 @@
+{
+  "devDependencies": {
+    "prettier": "@declapract{check.minVersion('2.8.1')}",
+    "@trivago/prettier-plugin-sort-imports": "@declapract{check.minVersion('4.3.0')}"
+  },
+  "scripts": {
+    "fix:format:prettier": "prettier --write '**/*.ts' --config ./prettier.config.js",
+    "test:format:prettier": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js"
+  }
+}

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/package.json.declapract.ts

@@ -0,0 +1,35 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+const depsToRemove = ['prettier', '@trivago/prettier-plugin-sort-imports'];
+
+const scriptsToRemove = ['fix:format:prettier', 'test:format:prettier'];
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON = JSON.parse(contents);
+
+  // Remove prettier devDependencies
+  const updatedDevDeps = { ...packageJSON.devDependencies };
+  for (const dep of depsToRemove) {
+    delete updatedDevDeps[dep];
+  }
+
+  // Remove prettier scripts
+  const updatedScripts = { ...packageJSON.scripts };
+  for (const script of scriptsToRemove) {
+    delete updatedScripts[script];
+  }
+
+  const fixedPackageJSON = {
+    ...packageJSON,
+    devDependencies:
+      Object.keys(updatedDevDeps).length > 0 ? updatedDevDeps : undefined,
+    scripts:
+      Object.keys(updatedScripts).length > 0 ? updatedScripts : undefined,
+  };
+
+  return { contents: JSON.stringify(fixedPackageJSON, null, 2) };
+};

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/prettier.config.js

@@ -0,0 +1,10 @@
+// ref: http://json.schemastore.org/prettierrc
+
+module.exports = {
+  trailingComma: 'all',
+  tabWidth: 2,
+  singleQuote: true,
+  plugins: ['@trivago/prettier-plugin-sort-imports'],
+  importOrder: ['^[./]'],
+  importOrderSeparation: true,
+};

package/dist/.test/assets/format/declarations/practices/format/bad-practices/prettier/prettier.config.js.declapract.ts

@@ -0,0 +1,8 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  // remove the file: a null contents result deletes it
+  return { contents: null };
+};

package/dist/.test/assets/format/declarations/practices/format/best-practice/package.json.declapract.ts

@@ -0,0 +1,50 @@
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+import { isPresent } from 'type-fns';
+
+/**
+ * .what = the active formatter set for a repo — `biome` always, `terraform` only when a terraform
+ *         practice is in use.
+ * .why  = names the set derivation as one intent, so `contents` reads what-not-how rather than an
+ *         inline conditional-null-in-array + filter pipeline a reader must mentally simulate
+ *         (`rule.forbid.inline-decode-friction`).
+ */
+const asActiveFormatters = (input: { usesTerraform: boolean }): string[] =>
+  ['biome', input.usesTerraform ? 'terraform' : null].filter(isPresent);
+
+/**
+ * .what = build the `fix:format` / `test:format` npm commands from the active formatter list — each
+ *         a ` && `-joined chain of per-formatter sub-commands.
+ * .why  = names the derivation as one intent, so `contents` reads what-not-how rather than an
+ *         inline filter/map/join pipeline a reader must mentally simulate (`rule.require.named-transformers`).
+ */
+const asFormatScripts = (input: {
+  formatters: string[];
+}): Record<string, string> => ({
+  'fix:format': input.formatters
+    .map((formatter) => `npm run fix:format:${formatter}`)
+    .join(' && '),
+  'test:format': input.formatters
+    .map((formatter) => `npm run test:format:${formatter}`)
+    .join(' && '),
+});
+
+/**
+ * declare the expected contents
+ */
+export const contents: FileContentsFunction = (context) => {
+  // only include the terraform formatter if a terraform practice is in use.
+  // the practices are named `terraform-common` / `terraform-aws` (see useCases.yml) —
+  // a check for the bare `terraform` matches NO practice, so the formatter would never run.
+  const usesTerraform =
+    context.projectPractices.includes('terraform-common') ||
+    context.projectPractices.includes('terraform-aws');
+
+  const formatters = asActiveFormatters({ usesTerraform });
+
+  return JSON.stringify({ scripts: asFormatScripts({ formatters }) }, null, 2);
+};
+
+/**
+ * check that they're contained in the file
+ */
+export const check: FileCheckType = FileCheckType.CONTAINS;

package/dist/.test/assets/format/declarations/practices/terraform-common/bad-practices/terraform-dir/.declapract.readme.md

@@ -0,0 +1,8 @@
+having a `/provision/terraform` dir is bad practice since we use the tool terraform to provision multiple things:
+- aws resources
+- github resources
+- etc
+
+instead, those should be separately identified and managed with separate tf projects
+
+we used to just manage aws-resources in each repo, so thats why this pattern originally existed

package/dist/.test/assets/format/declarations/practices/terraform-common/bad-practices/terraform-dir/provision/terraform/<star><star>/<star>.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = moves any file from provision/terraform/ to provision/aws/
+ * .why = ensures all files are moved, not just .tf/.hcl files — prevents silent data loss for hidden paths
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: contents ?? null,
+    relativeFilePath: context.relativeFilePath.replace(
+      'provision/terraform/',
+      'provision/aws/',
+    ),
+  };
+};

package/dist/.test/assets/format/declarations/practices/terraform-common/best-practice/.terraform-version

@@ -0,0 +1 @@
+0.14.11

package/dist/.test/assets/format/declarations/practices/terraform-common/best-practice/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "fix:format:terraform": "terraform fmt -recursive provision",
+    "test:format:terraform": "terraform fmt -recursive -check provision"
+  }
+}

package/dist/.test/assets/format/declarations/practices/terraform-common/best-practice/package.json.declapract.ts

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

package/dist/.test/assets/format/declarations/useCases.yml

@@ -0,0 +1,13 @@
+# minimal use cases for the format package.json (b3) pipeline test.
+# .why = the format `contents` branch fires on
+#        `context.projectPractices.includes('terraform-common')`. these two lean use cases carry the
+#        one signal the branch reads (terraform present vs absent) while each evaluates only 1-2
+#        practices — not the ~40 of the real declarations tree, which blows the jest hook timeout.
+use-cases:
+  with-terraform:
+    practices:
+      - format
+      - terraform-common
+  without-terraform:
+    practices:
+      - format

package/dist/.test/assets/format/repo-with-terraform/declapract.use.yml

@@ -0,0 +1,8 @@
+# .note = declarations dir is symlinked by the test to src/practices/format/.test/assets/declarations
+# .why  = a consumer on a terraform usecase, used to prove the format practice's package.json
+#         `contents` fn chains the terraform formatter into fix:format / test:format when a
+#         terraform practice is in play.
+declarations: 'declarations/declapract.declare.yml'
+useCase: with-terraform
+# .note = format + terraform-common reference NO @declapract{variable.*}, so no variables block
+#         is owed here (grep both best-practice dirs to confirm).

package/dist/.test/assets/format/repo-with-terraform/package.json

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

package/dist/.test/assets/format/repo-without-terraform/declapract.use.yml

@@ -0,0 +1,6 @@
+# .note = declarations dir is symlinked by the test to src/practices/format/.test/assets/declarations
+# .why  = a consumer on a NON-terraform usecase, used to prove the format practice's package.json
+#         `contents` fn OMITS the terraform formatter (fix:format is biome-only) when no terraform
+#         practice is in play.
+declarations: 'declarations/declapract.declare.yml'
+useCase: without-terraform

package/dist/.test/assets/format/repo-without-terraform/package.json

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

package/dist/.test/assets/node-service/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# minimal declarations for the node-service practice integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/node-service/declarations/practices/node-service/bad-practices/license/package.json.declapract.ts

@@ -0,0 +1,22 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+export const check: FileCheckFunction = async (contents) => {
+  expect(JSON.parse(contents ?? 'null')).toEqual(
+    expect.objectContaining({
+      license: expect.any(String), // we shouldn't have a license declared for service code
+    }),
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // do nothing if no contents
+  const packageJSON = JSON.parse(contents);
+  const updatedPackageJSON = {
+    ...packageJSON,
+    license: undefined,
+  };
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/.test/assets/node-service/declarations/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/.test/assets/node-service/declarations/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/.test/assets/node-service/declarations/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/.test/assets/node-service/declarations/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 };
+};