declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/practices/domain/bad-practices/schema-over-contract/src/contract/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,78 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = a value import from a `domain.objects` module: `import { A, B as C } from '…domain.objects…'`.
+ * .why  = only a dobj class carries `.contract()`, so the rewrite is scoped to names this file
+ *         imports from a domain.objects path; a zod schema or a sdk type that also has `.schema`
+ *         is left alone. an `import type { … }` is skipped — a type-only name cannot be a value.
+ */
+const DOBJ_IMPORT_PATTERN =
+  /import\s+(?!type\b)\{([^}]*)\}\s*from\s*['"][^'"]*domain\.objects[^'"]*['"]/g;
+
+/**
+ * .what = the local names a file imports as values from a `domain.objects` module.
+ */
+export const getDobjNamesImported = (input: { contents: string }): string[] =>
+  [...input.contents.matchAll(DOBJ_IMPORT_PATTERN)]
+    .flatMap((match) => (match[1] ?? '').split(','))
+    .map((specifier) => specifier.trim())
+    .filter((specifier) => specifier && !specifier.startsWith('type '))
+    .map(
+      (specifier) =>
+        specifier
+          .split(/\s+as\s+/)
+          .pop()
+          ?.trim() ?? '',
+    )
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+
+/**
+ * .what = the two shapes a published contract must not carry for a dobj `X`.
+ * .why  =
+ *   - `X.schema` validates, but emits no dobj identity into the json-schema a consumer reads (#565)
+ *   - `X.contract` with no call is a type error since domain-objects@0.34.0, where `contract`
+ *     became a getter that returns a function to CALL on the class (#634, defect 1)
+ * .note = `X.schema.parse(…)` (and its kin) is internal validation, never a published shape, so
+ *         it is left alone; so is `typeof X.schema`, since `typeof X.contract()` is not a type query.
+ */
+const asOutdatedMemberPattern = (input: { name: string }): RegExp =>
+  new RegExp(
+    `(?<!typeof\\s+)(?<![\\w$.])${input.name.replace(/\$/g, '\\$')}\\.(?:schema\\b(?!\\s*\\.\\s*(?:parse|safeParse|parseAsync|safeParseAsync)\\b)|contract\\b(?!\\s*\\())`,
+    'g',
+  );
+
+/**
+ * .what = flags a published contract file that refers to a dobj via `X.schema` or a bare `X.contract`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents &&
+    getDobjNamesImported({ contents }).some((name) =>
+      asOutdatedMemberPattern({ name }).test(contents),
+    )
+  )
+    return; // bad practice detected
+  throw new Error(
+    'does not match bad practice: each dobj in this contract is referred to via X.contract()',
+  );
+};
+
+/**
+ * .what = rewrites each `X.schema` / bare `X.contract` to `X.contract()`.
+ * .why  = `X.contract()` is the same zod schema stamped with the dobj's identity, so it composes
+ *         exactly as `X.schema` did (`z.array(X.contract())`, `X.contract().nullable()`).
+ * .note = idempotent: `X.contract()` matches neither shape, so a second pass changes no byte.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return {
+    contents: getDobjNamesImported({ contents }).reduce(
+      (rewritten, name) =>
+        rewritten.replace(
+          asOutdatedMemberPattern({ name }),
+          `${name}.contract()`,
+        ),
+      contents,
+    ),
+  };
+};

package/dist/practices/domain/best-practice/src/domain.objects/index.ts.declapract.ts

@@ -1,4 +1,4 @@
-import { FileCheckType } from 'declapract';
+import { asPresenceCheck } from '../../../../../utils/asPresenceCheck';
 
 // a project should declare domain objects — otherwise, what does the service operate on?
 //
@@ -9,4 +9,7 @@ import { FileCheckType } from 'declapract';
 // its own kin — `domain-dir`'s fix moved the required file away, so a repo reached a terminal,
 // unrepairable state. keyed on the go-forward layout, the two practices agree: `domain-dir`'s fix
 // produces exactly this path.
-export const check = FileCheckType.EXISTS;
+export const check = asPresenceCheck({
+  expected: 'src/domain.objects/index.ts',
+  hint: 'create it as the entry for the domain objects this service declares',
+});

package/dist/practices/domain/contract.declapract.integration.test.ts

@@ -0,0 +1,61 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the `X.contract()` migration (#565, #634), through the REAL apply.
+ * .why  = `schema-over-contract` rewrites each published `X.schema` / bare `X.contract` to
+ *   `X.contract()`, and must leave internal `.schema.safeParse` alone. only the pipeline proves the
+ *   declared glob reaches the handler.
+ * .note = the handler is snapshotted before AND after.
+ */
+describe('domain X.contract() migration', () => {
+  given('[case1] a repo whose handler refers to dobjs via .schema and a bare .contract', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-domain-contract',
+      clone: './src/.test/assets/domain-contract/repo-with-contract',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/domain-contract/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const handlerPath = 'src/contract/handlers/getChatThread.ts';
+    const readHandler = () => fs.readFile(path.join(tempDir, handlerPath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'domain',
+        file: handlerPath,
+      });
+
+    when('[t0] the fix is applied, then applied again', () => {
+      const result = useThen('apply twice', async () => {
+        const before = await readHandler();
+        await applyFix();
+        const once = await readHandler();
+        await applyFix();
+        const twice = await readHandler();
+        return { before, once, twice };
+      });
+
+      then('the handler refers to each dobj via X.contract(), and keeps internal .schema.safeParse', () => {
+        expect(result.once).toContain("thread: ChatThread.contract().ref('primary'),");
+        expect(result.once).toContain('thread: ChatThread.contract().nullable(),');
+        expect(result.once).toContain('z.array(Transmission.contract())');
+        expect(result.once).toContain('ChatThread.schema.safeParse(input)');
+        expect(result.before).toMatchSnapshot('getChatThread.ts — before');
+        expect(result.once).toMatchSnapshot('getChatThread.ts — after');
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(result.twice).toEqual(result.once);
+      });
+    });
+  });
+});

package/dist/practices/environments/.declapract.integration.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 
 import { given, then, useBeforeAll, when } from 'test-fns';
-import ts from 'typescript';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
 
 /**
  * .what = holds the `sdkAwsLambdaEnvAccess{Ancient,Contemp}` helper templates — the
@@ -40,19 +40,13 @@ const runHelperFile = (input: {
   name: string;
   access: 'test' | 'prep' | 'prod';
 }): (() => string) => {
-  const source = readFileSync(input.path, 'utf8');
-  const transpiled = ts.transpileModule(source, {
-    compilerOptions: {
-      module: ts.ModuleKind.CommonJS,
-      target: ts.ScriptTarget.ES2020,
-    },
-  }).outputText;
-  const moduleExports: Record<string, () => string> = {};
   const requireStub = (id: string): unknown =>
     id.includes('environment') ? { envStatic: { access: input.access } } : {};
-  // eslint-disable-next-line no-new-func
-  new Function('exports', 'require', transpiled)(moduleExports, requireStub);
-  return moduleExports[input.name];
+  const moduleExports = getModuleExportsFromTsSource<Record<string, () => string>>({
+    source: readFileSync(input.path, 'utf8'),
+    requireStub,
+  });
+  return moduleExports[input.name]!;
 };
 
 describe('environments practice — the EnvAccess helper primitive (north-star clamp)', () => {
@@ -87,6 +81,15 @@ describe('environments practice — the EnvAccess helper primitive (north-star c
         expect(scene.ancient).not.toContain('as EnvironmentAccessTier');
       });
 
+      then('the ancient target returns the exact set it can emit — prod | dev, never the family (#636)', () => {
+        // the family `LambdaEnvSlug` admits `test` and `prep`, which this helper never returns; a
+        // caller that narrows on the result would then handle two values that cannot arrive
+        expect(scene.ancient).toContain(
+          "export type LambdaEnvSlugAncient = Extract<LambdaEnvSlug, 'prod' | 'dev'>;",
+        );
+        expect(scene.ancient).toMatch(/\): LambdaEnvSlugAncient => \{/);
+      });
+
       then('the ancient file source matches snapshot (a structural edit vibechecks in a review)', () => {
         // the toContain asserts above catch a named regression; the full-source snapshot catches an
         // UNnamed one — an added param, a changed import, a dropped comment — that trips no assert

package/dist/practices/environments/__snapshots__/.declapract.integration.test.ts.snap

@@ -14,6 +14,13 @@ import { envStatic } from '@src/utils/environment';
  */
 export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
 
+/**
+ * .what = the exact slugs an ancient peer publishes under: \`prod\`, or the legacy \`dev\`.
+ * .why  = the ancient helper never emits \`test\` or \`prep\`, so its return type says so — a caller
+ *         that narrows on it handles only the two values that can arrive.
+ */
+export type LambdaEnvSlugAncient = Extract<LambdaEnvSlug, 'prod' | 'dev'>;
+
 /**
  * .what = address an **ancient** peer — one that publishes \`-dev-\` only.
  * .why  = \`askLambdaEndpoint\` builds its target as \`\${service}-\${access}-\${function}\`.
@@ -24,12 +31,13 @@ export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
  * .note = the helper choice IS the migration ledger: \`grep AccessAncient\` lists every
  *         peer still published under \`-dev-\` only. once zero remain, this ancient branch
  *         — and the divergent \`dev\` slug — retire together, alongside its contemp
- *         counterpart \`sdkAwsLambdaEnvAccessContemp\`. the return type is \`LambdaEnvSlug\`,
- *         so the \`dev\` slug flows with a compiler-tracked type — no cast, no lie.
+ *         counterpart \`sdkAwsLambdaEnvAccessContemp\`. the return type is the exact set
+ *         \`LambdaEnvSlugAncient\`, so the \`dev\` slug flows with a compiler-tracked type — no
+ *         cast, no lie.
  */
-export const sdkAwsLambdaEnvAccessAncient = (
-  input?: { access: EnvironmentAccessTier | null },
-): LambdaEnvSlug => {
+export const sdkAwsLambdaEnvAccessAncient = (input?: {
+  access: EnvironmentAccessTier | null;
+}): LambdaEnvSlugAncient => {
   const access = input?.access ?? envStatic.access;
   return access === 'prod' ? 'prod' : 'dev';
 };
@@ -48,8 +56,8 @@ import { envStatic } from '@src/utils/environment';
  *         \`sdkAwsLambdaEnvAccessAncient\`: as peers migrate, a caller flips
  *         \`Ancient → Contemp\` per peer, and \`grep AccessAncient\` at zero is the exit.
  */
-export const sdkAwsLambdaEnvAccessContemp = (
-  input?: { access: EnvironmentAccessTier | null },
-): EnvironmentAccessTier => input?.access ?? envStatic.access;
+export const sdkAwsLambdaEnvAccessContemp = (input?: {
+  access: EnvironmentAccessTier | null;
+}): EnvironmentAccessTier => input?.access ?? envStatic.access;
 "
 `;

package/dist/practices/environments/bad-practices/old-dev-scripts/.declapract.integration.test.ts

@@ -0,0 +1,97 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the environments/old-dev-scripts fix, run through the REAL declapract
+ *   apply pipeline against a genTempDir clone of a consumer repo whose package.json still names
+ *   scripts with a `:dev` segment — at the end (`deploy:dev`, `start:livedb:dev`) and in the
+ *   middle (`build:dev:ios`).
+ * .why  = the fix renames keys with a regex over parsed json. a unit test of the transformer is
+ *   necessary but NOT sufficient (`rule.require.declapract-integration-tests`): only the pipeline
+ *   proves declapract matches the declaration to the consumer's package.json, that a bad-practice
+ *   `check` that RETURNS gates the `fix`, and that a second apply is a no-op on the real file.
+ * .note = the scoped apply runs the WHOLE `environments` practice (the `file` filter narrows which
+ *   file is written, not which declarers evaluate), so the after-state also carries the
+ *   environments best-practice package.json — a CONTAINS check whose merge-fix stamps its declared
+ *   dependencies. the assertions target only the script renames, which this bad-practice owns; the
+ *   full-content snapshots show both, for the reviewer's eye.
+ */
+describe('environments/old-dev-scripts rename', () => {
+  given('[case1] a repo whose scripts carry a :dev segment', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-environments-old-dev-scripts',
+      clone:
+        './src/practices/environments/bad-practices/old-dev-scripts/.test/assets/demo-repo-with-dev-scripts',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+
+    const pkgPath = 'package.json';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'environments',
+        file: pkgPath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the package.json input matches snapshot', async () => {
+        expect(await read(pkgPath)).toMatchSnapshot('package.json — before');
+      });
+    });
+
+    when('[t1] the old-dev-scripts fix is applied', () => {
+      const result = useThen('the apply succeeds', async () => {
+        await applyFix();
+        const contents = await read(pkgPath);
+        return { contents, pkg: JSON.parse(contents) };
+      });
+
+      then('each :dev segment is renamed to :prep, with its value untouched', () => {
+        expect(result.pkg.scripts['deploy:prep']).toEqual('npm run deploy:release');
+        expect(result.pkg.scripts['start:livedb:prep']).toEqual('npm run start:db');
+        expect(result.pkg.scripts['build:prep:ios']).toEqual('npm run build:ios');
+      });
+
+      then('no script name holds a :dev segment any more', () => {
+        const devNames = Object.keys(result.pkg.scripts).filter(
+          (key) => key.endsWith(':dev') || key.includes(':dev:'),
+        );
+        expect(devNames).toEqual([]);
+      });
+
+      then('the scripts without a :dev segment are preserved', () => {
+        expect(result.pkg.scripts.build).toEqual('tsc');
+        expect(result.pkg.scripts['test:unit']).toEqual('jest');
+      });
+
+      then('the package.json matches snapshot', () => {
+        expect(result.contents).toMatchSnapshot('package.json — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // .note = we assert the `scripts` block — the part this bad-practice owns — is a fixed
+      //   point, not full-file byte equality: the environments best-practice package.json (a
+      //   separate CONTAINS declarer) writes a raw `@declapract{check.minVersion(...)}` marker
+      //   into `dependencies` on the first pass and resolves it to a bare version on the second.
+      //   that marker quirk is the same one logs/.declapract.integration.test.ts records; it is
+      //   not the rename under test.
+      const result = useThen('a second apply over its own output', async () => {
+        const before = JSON.parse(await read(pkgPath));
+        await applyFix();
+        return { before, after: JSON.parse(await read(pkgPath)) };
+      });
+
+      then('the second apply renames zero scripts — same names, values, and order', () => {
+        expect(Object.entries(result.after.scripts)).toEqual(
+          Object.entries(result.before.scripts),
+        );
+      });
+    });
+  });
+});

package/dist/practices/environments/bad-practices/old-dev-scripts/.test/assets/demo-repo-with-dev-scripts/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: declarations/examples
+  practices: declarations/practices
+  use-cases: declarations/useCases.yml

package/dist/practices/environments/bad-practices/old-dev-scripts/.test/assets/demo-repo-with-dev-scripts/declapract.use.yml

@@ -0,0 +1,9 @@
+declarations: './'
+useCase: lambda-service
+# executeApply({ practice: 'environments' }) evaluates the WHOLE environments practice before the
+# `file` filter narrows it (rule.require.declapract-integration-tests gotcha). no environments file
+# references a @declapract{variable.*} today; the two below are the usecase's baseline, set so a
+# future template that adds one does not break this apply with `Variable … was not defined`.
+variables:
+  projectName: svc-example
+  organizationName: ehmpathy

package/dist/practices/environments/bad-practices/old-dev-scripts/.test/assets/demo-repo-with-dev-scripts/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "svc-example",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc",
+    "build:dev:ios": "npm run build:ios",
+    "start:livedb:dev": "npm run start:db",
+    "deploy:dev": "npm run deploy:release",
+    "test:unit": "jest"
+  }
+}

package/dist/practices/environments/bad-practices/old-dev-scripts/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,36 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`environments/old-dev-scripts rename given: [case1] a repo whose scripts carry a :dev segment when: [t0] the input (before any fix) then: the package.json input matches snapshot: package.json — before 1`] = `
+"{
+  "name": "svc-example",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc",
+    "build:dev:ios": "npm run build:ios",
+    "start:livedb:dev": "npm run start:db",
+    "deploy:dev": "npm run deploy:release",
+    "test:unit": "jest"
+  }
+}
+"
+`;
+
+exports[`environments/old-dev-scripts rename given: [case1] a repo whose scripts carry a :dev segment when: [t1] the old-dev-scripts fix is applied then: the package.json matches snapshot: package.json — after 1`] = `
+"{
+  "name": "svc-example",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc",
+    "test:unit": "jest",
+    "build:prep:ios": "npm run build:ios",
+    "start:livedb:prep": "npm run start:db",
+    "deploy:prep": "npm run deploy:release"
+  },
+  "dependencies": {
+    "@aws-sdk/client-account": "@declapract{check.minVersion('3.1042.0')}",
+    "@aws-sdk/client-iam": "@declapract{check.minVersion('3.1042.0')}",
+    "sdk-environment": "@declapract{check.minVersion('0.1.5')}"
+  }
+}
+"
+`;

package/dist/practices/environments/best-practice/.declapract.readme.md

@@ -3,10 +3,10 @@
 a critical part of an application's environment is its `access` — which deployment's resources
 the runtime may reach, and with what weight.
 
-ehmpathy recognizes three standard tiers in which applications run throughout their development cycle
+ehmpathy recognizes three standard accesses with which applications run throughout their development cycle
 - `prod` — a deployed production stack the business depends on, which serves real customers
 - `prep` — a deployed pre-production stack where applications interact for cross-service tests
-- `test` — an ephemeral, primarily local, developer-only tier for local code
+- `test` — an ephemeral, primarily local, developer-only access for local code
 
 `access` is the one canonical axis (`test | prep | prod`). the runtime reads it via
 `getEnvironment.static().access` (sdk-environment), which derives it from the `ACCESS` env var, then

package/dist/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessAncient.ts

@@ -11,6 +11,13 @@ import { envStatic } from '@src/utils/environment';
  */
 export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
 
+/**
+ * .what = the exact slugs an ancient peer publishes under: `prod`, or the legacy `dev`.
+ * .why  = the ancient helper never emits `test` or `prep`, so its return type says so — a caller
+ *         that narrows on it handles only the two values that can arrive.
+ */
+export type LambdaEnvSlugAncient = Extract<LambdaEnvSlug, 'prod' | 'dev'>;
+
 /**
  * .what = address an **ancient** peer — one that publishes `-dev-` only.
  * .why  = `askLambdaEndpoint` builds its target as `${service}-${access}-${function}`.
@@ -21,12 +28,13 @@ export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
  * .note = the helper choice IS the migration ledger: `grep AccessAncient` lists every
  *         peer still published under `-dev-` only. once zero remain, this ancient branch
  *         — and the divergent `dev` slug — retire together, alongside its contemp
- *         counterpart `sdkAwsLambdaEnvAccessContemp`. the return type is `LambdaEnvSlug`,
- *         so the `dev` slug flows with a compiler-tracked type — no cast, no lie.
+ *         counterpart `sdkAwsLambdaEnvAccessContemp`. the return type is the exact set
+ *         `LambdaEnvSlugAncient`, so the `dev` slug flows with a compiler-tracked type — no
+ *         cast, no lie.
  */
-export const sdkAwsLambdaEnvAccessAncient = (
-  input?: { access: EnvironmentAccessTier | null },
-): LambdaEnvSlug => {
+export const sdkAwsLambdaEnvAccessAncient = (input?: {
+  access: EnvironmentAccessTier | null;
+}): LambdaEnvSlugAncient => {
   const access = input?.access ?? envStatic.access;
   return access === 'prod' ? 'prod' : 'dev';
 };

package/dist/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts

@@ -9,6 +9,6 @@ import { envStatic } from '@src/utils/environment';
  *         `sdkAwsLambdaEnvAccessAncient`: as peers migrate, a caller flips
  *         `Ancient → Contemp` per peer, and `grep AccessAncient` at zero is the exit.
  */
-export const sdkAwsLambdaEnvAccessContemp = (
-  input?: { access: EnvironmentAccessTier | null },
-): EnvironmentAccessTier => input?.access ?? envStatic.access;
+export const sdkAwsLambdaEnvAccessContemp = (input?: {
+  access: EnvironmentAccessTier | null;
+}): EnvironmentAccessTier => input?.access ?? envStatic.access;

package/dist/practices/environments-aws/best-practice/.declapract.readme.md

@@ -1 +1,5 @@
 the aws environments provisioned here follow the `environments` best practices
+
+this practice declares no file of its own: `terraform-aws` owns `provision/aws/environments/{test,prep,prod}/`.
+an EXISTS-only claim here could never be fixed (an EXISTS check carries no fix), so on a fresh repo it
+marked the file manual and blocked the owner's fix too (#630, #607).