declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/utils/actionPins/bumpActionPins.ts

@@ -0,0 +1,172 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+import { getAllPathsUnderDir } from '../getAllPathsUnderDir';
+import { asActionPinTargetTag } from './asActionPinTargetTag';
+
+/**
+ * .what = re-reads every sha-pinned action ref on both github surfaces and moves each pin to the
+ *         newest commit inside its pinned major (#556)
+ * .why  = the workflow templates are delivered by EQUALS, so a consumer cannot bump a pin — the
+ *         next apply reverts it. the bump must happen here, at the source. this is the command the
+ *         scheduled `bump-action-pins.yml` runs; a human may run it too
+ * .how  = node -r esbuild-register src/utils/actionPins/bumpActionPins.ts [--mode plan|apply]
+ *           - plan (default) prints each bump and writes no file
+ *           - apply rewrites `@<sha.old> # <tag.old>` → `@<sha.new> # <tag.new>` in every file
+ *             under `src/practices` and `.github`, which is the same two-glob procedure the
+ *             actionPins clamp documents; then re-record its pin table and read the diff
+ * .note = an annotated tag's ref names a tag OBJECT, not a commit. each ref is dereferenced when
+ *         `.object.type` reads `tag`, or the pin would name no commit and github would reject it
+ */
+
+const REPO_ROOT = join(__dirname, '..', '..', '..');
+const SURFACES = [join(REPO_ROOT, 'src/practices'), join(REPO_ROOT, '.github')];
+
+interface ActionPin {
+  repo: string;
+  sha: string;
+  tag: string;
+}
+
+interface TagRef {
+  ref: string;
+  object: { sha: string; type: string };
+}
+
+/**
+ * .what = the unique pins named across a set of texts
+ * .why  = a pin is `uses: <owner>/<repo>[/<path>]@<40-hex> # <tag>`; the subpath folds into its repo
+ */
+const ACTION_PIN_PATTERN =
+  /uses:\s*(?<repo>[\w.-]+\/[\w.-]+)(?:\/[\w./-]+)?@(?<sha>[0-9a-f]{40})\s+#\s*(?<tag>\S+)/g;
+const asActionPinsFromTexts = (input: { texts: string[] }): ActionPin[] => {
+  // each group is required by the pattern, so a match always carries all three
+  const found = input.texts.flatMap((text) =>
+    [...text.matchAll(ACTION_PIN_PATTERN)].map((match) => ({
+      repo: match.groups!.repo!,
+      sha: match.groups!.sha!,
+      tag: match.groups!.tag!,
+    })),
+  );
+  return [
+    ...new Map(found.map((pin) => [`${pin.repo}@${pin.sha}#${pin.tag}`, pin])).values(),
+  ].sort((a, b) => a.repo.localeCompare(b.repo));
+};
+
+/**
+ * .what = every file under the two surfaces, save installed modules
+ */
+const getAllSurfacePaths = (): string[] =>
+  SURFACES.flatMap((dir) => getAllPathsUnderDir({ dir, skip: ['node_modules'] }));
+
+/**
+ * .what = the workflow and action yaml under the two surfaces, outside fixture dirs
+ * .why  = the pins to re-read live in real templates; a fixture holds stale refs on purpose
+ */
+const getAllWorkflowPaths = (): string[] =>
+  getAllSurfacePaths()
+    .filter((path) => /\/\.github\/(workflows|actions)\//.test(path))
+    .filter((path) => /\.ya?ml$/.test(path))
+    .filter((path) => !/\/(__snapshots__|\.test)\//.test(path));
+
+/**
+ * .what = a gh api read, parsed as json
+ */
+const getGhApiJson = (input: { route: string }): unknown =>
+  JSON.parse(execFileSync('gh', ['api', '-X', 'GET', input.route], { encoding: 'utf-8' }));
+
+/**
+ * .what = the tag refs a repo publishes under a prefix
+ */
+const getAllTagRefs = (input: { repo: string; prefix: string }): TagRef[] =>
+  getGhApiJson({
+    route: `repos/${input.repo}/git/matching-refs/tags/${input.prefix}`,
+  }) as TagRef[];
+
+/**
+ * .what = the commit a tag ref names, with an annotated tag dereferenced
+ */
+const getOneCommitShaForTagRef = (input: { repo: string; tagRef: TagRef }): string => {
+  if (input.tagRef.object.type === 'commit') return input.tagRef.object.sha;
+  const tagObject = getGhApiJson({
+    route: `repos/${input.repo}/git/tags/${input.tagRef.object.sha}`,
+  }) as { object: { sha: string; type: string } };
+  return tagObject.object.sha;
+};
+
+/**
+ * .what = the pin a repo should hold now, inside its pinned major
+ */
+const getOneActionPinTarget = (input: { pin: ActionPin }): ActionPin => {
+  const prefix = /^(v?\d+)/.exec(input.pin.tag)?.[1] ?? input.pin.tag;
+  const tagRefs = getAllTagRefs({ repo: input.pin.repo, prefix });
+  const tagsAvailable = tagRefs.map((tagRef) => tagRef.ref.replace(/^refs\/tags\//, ''));
+  const tag = asActionPinTargetTag({ tagPinned: input.pin.tag, tagsAvailable });
+  const tagRef = tagRefs.find((row) => row.ref === `refs/tags/${tag}`);
+  if (!tagRef)
+    throw new ConstraintError('the pinned tag is absent upstream', {
+      repo: input.pin.repo,
+      tag,
+      hint: 'repin this action by hand to a tag that exists',
+    });
+  return { repo: input.pin.repo, tag, sha: getOneCommitShaForTagRef({ repo: input.pin.repo, tagRef }) };
+};
+
+/**
+ * .what = rewrite one pin across every file of both surfaces; returns the files it touched
+ * .note = each file is written to a temp file beside it, then renamed over the original, so an
+ *         interrupted write leaves the file wholly old or wholly new. a run cut short between files
+ *         converges on the next run, since targets are re-derived from the text each time
+ */
+const setActionPinAcrossSurfaces = (input: { from: ActionPin; into: ActionPin }): string[] => {
+  const needle = `@${input.from.sha} # ${input.from.tag}`;
+  const replacement = `@${input.into.sha} # ${input.into.tag}`;
+  return getAllSurfacePaths().flatMap((path) => {
+    const text = readFileSync(path, 'utf-8');
+    if (!text.includes(needle)) return [];
+    const pathTemp = `${path}.bump.tmp`;
+    writeFileSync(pathTemp, text.split(needle).join(replacement));
+    renameSync(pathTemp, path);
+    return [relative(REPO_ROOT, path)];
+  });
+};
+
+/**
+ * .what = the bump procedure: read pins, find targets, report, and in apply mode rewrite
+ * .why  = one call moves every sha-pinned action to the newest tag inside its pinned major, across
+ *         the workflows and the practice templates alike, so the two surfaces never drift apart
+ */
+export const bumpActionPins = (input: { mode: 'plan' | 'apply' }): { bumps: number } => {
+  const pins = asActionPinsFromTexts({
+    texts: getAllWorkflowPaths().map((path) => readFileSync(path, 'utf-8')),
+  });
+  console.log(`🐚 bumpActionPins --mode ${input.mode}`);
+  console.log(`   ├─ pins: ${pins.length}`);
+
+  const bumps = pins
+    .map((pin) => ({ from: pin, into: getOneActionPinTarget({ pin }) }))
+    .filter((row) => row.from.sha !== row.into.sha || row.from.tag !== row.into.tag);
+
+  bumps.forEach((row) => {
+    console.log(
+      `   ├─ ${row.from.repo}: ${row.from.tag} ${row.from.sha.slice(0, 7)} → ${row.into.tag} ${row.into.sha.slice(0, 7)}`,
+    );
+    if (input.mode !== 'apply') return;
+    setActionPinAcrossSurfaces(row).forEach((path) => console.log(`   │  └─ ${path}`));
+  });
+
+  console.log(`   └─ bumps: ${bumps.length}${input.mode === 'apply' ? '' : ' (plan; no file written)'}`);
+  return { bumps: bumps.length };
+};
+
+// run as a command
+if (require.main === module) {
+  const modeArg = process.argv[process.argv.indexOf('--mode') + 1];
+  const mode = process.argv.includes('--mode') ? modeArg : 'plan';
+  if (mode !== 'plan' && mode !== 'apply')
+    throw new ConstraintError('--mode must be plan or apply', { mode });
+  bumpActionPins({ mode });
+}

package/dist/utils/asBareDeprecatedDirSpecifierReplacement.ts

@@ -0,0 +1,83 @@
+import path from 'node:path';
+
+/**
+ * .what = each deprecated src dir, and the dir its barrel moved into.
+ */
+const DEPRECATED_DIR_REPLACEMENTS: Record<string, string> = {
+  domain: 'domain.objects',
+  model: 'domain.objects',
+  data: 'access',
+  logic: 'domain.operations',
+  services: 'domain.operations',
+  __nonpublished_modules__: '_topublish',
+};
+
+/**
+ * .what = the module specifiers of a file — static, side-effect, dynamic, and require forms.
+ * .note = group 2 = the quote, group 3 = the specifier.
+ * .note = global (`/g`), so `.test()` and `.exec()` carry `lastIndex` across calls; use it only via
+ *         `.replace` / `.matchAll`, or copy it with `new RegExp(MODULE_SPECIFIER_PATTERN)` first.
+ */
+export const MODULE_SPECIFIER_PATTERN =
+  /(\bfrom\s+|\bimport\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)(['"])([^'"\n]+)\2/g;
+
+/**
+ * .what = the replacement for a module specifier that ends at a deprecated src dir's barrel
+ *         (`'@src/domain'`, `'../../domain'`), or null when the specifier is not such a one.
+ * .why  = ONE specifier set for the old-import-paths check AND fix (#655, #671), so the check
+ *         cannot pass a bare barrel import the fix would skip. the extant patterns all need a
+ *         `/` after the dir, so a bare barrel import matched neither.
+ * .note = only the repo's own src dirs count: `@src/<dir>`, or a relative specifier that lands on
+ *         exactly `src/<dir>` from the importer's path. a package subpath (`some-pkg/domain`) and
+ *         a relative specifier with no importer path to land it from are left alone.
+ */
+export const asBareDeprecatedDirSpecifierReplacement = (input: {
+  specifier: string;
+  relativeFilePath: string | null;
+}): string | null => {
+  // the alias form: '@src/<dir>'
+  const aliasDir = input.specifier.match(/^@src\/([^/]+)$/)?.[1];
+  if (aliasDir !== undefined) {
+    const into = DEPRECATED_DIR_REPLACEMENTS[aliasDir];
+    return into ? `@src/${into}` : null;
+  }
+
+  // the relative form: lands on exactly 'src/<dir>' from the importer (posix.join collapses `..`)
+  if (!input.specifier.startsWith('.') || !input.relativeFilePath) return null;
+  const landed = path.posix.join(
+    path.posix.dirname(input.relativeFilePath),
+    input.specifier,
+  );
+  const relativeDir = landed.match(/^src\/([^/]+)$/)?.[1];
+  if (relativeDir === undefined) return null;
+  const into = DEPRECATED_DIR_REPLACEMENTS[relativeDir];
+  if (!into) return null;
+  return input.specifier.replace(/[^/]+$/, into);
+};
+
+/**
+ * .what = a file's contents with each bare deprecated-dir barrel specifier repointed.
+ */
+export const withBareDeprecatedDirSpecifiersRepointed = (input: {
+  contents: string;
+  relativeFilePath: string | null;
+}): string =>
+  input.contents.replace(
+    MODULE_SPECIFIER_PATTERN,
+    (whole, prefix: string, quote: string, specifier: string) => {
+      const replacement = asBareDeprecatedDirSpecifierReplacement({
+        specifier,
+        relativeFilePath: input.relativeFilePath,
+      });
+      return replacement ? `${prefix}${quote}${replacement}${quote}` : whole;
+    },
+  );
+
+/**
+ * .what = whether a file holds any bare deprecated-dir barrel specifier.
+ */
+export const hasBareDeprecatedDirSpecifier = (input: {
+  contents: string;
+  relativeFilePath: string | null;
+}): boolean =>
+  withBareDeprecatedDirSpecifiersRepointed(input) !== input.contents;

package/dist/utils/asDatabaseClusterName.ts

@@ -0,0 +1,37 @@
+import { ConstraintError } from 'helpful-errors';
+
+import { isJsonObject } from './asJsonMergedDeep';
+
+/**
+ * .what = the rds cluster name the vpc tunnel targets, for one env
+ * .why  = the tunnel's `cluster.name` must name the rds CLUSTER, never the logical database
+ *         inside it — the two differ in every repo that shares a cluster (#638). the first label
+ *         of an rds cluster endpoint (`<cluster>.cluster-<id>.<region>.rds.amazonaws.com`) is the
+ *         cluster identifier, so the name derives from the host the practice already requires.
+ *         an optional `databaseClusterName` variable (a string, or one per env) overrides it, for
+ *         an endpoint behind a custom dns alias. a required new variable was declined: it would
+ *         throw `Variable … was not defined` in every adopter that has not declared it (F22).
+ */
+export const asDatabaseClusterName = (input: {
+  variables: Record<string, unknown>;
+  env: 'prep' | 'prod';
+}): string => {
+  // an explicit override wins, either one name for every env or one per env
+  const override = input.variables.databaseClusterName;
+  if (typeof override === 'string' && override) return override;
+  const overrideForEnv = isJsonObject(override) ? override[input.env] : null;
+  if (typeof overrideForEnv === 'string' && overrideForEnv) return overrideForEnv;
+
+  // else the first label of the cluster endpoint
+  const hosts = input.variables.databaseClusterHost;
+  const host = isJsonObject(hosts) ? hosts[input.env] : undefined;
+  if (typeof host !== 'string' || !host)
+    throw new ConstraintError(
+      `persist-with-rds needs databaseClusterHost.${input.env} to derive the tunnel cluster name`,
+      {
+        env: input.env,
+        hint: `declare variables.databaseClusterHost.${input.env} (or variables.databaseClusterName) in declapract.use.yml`,
+      },
+    );
+  return host.split('.')[0]!;
+};

package/dist/utils/asInputToContextReviewMarker.ts

@@ -0,0 +1,14 @@
+/**
+ * .what = the one `// @declapract:review:` line that names the `(input)` → `(input, context)` move.
+ * .why  = two retired wrappers fail the same way: `withDatabaseConnection` took `dbConnection` in
+ *         the INPUT (#626), and the vendored `withLogTrail` fork took a variadic arg list with a
+ *         module-singleton log (#635). both move to the `(input, context)` shape, often at the same
+ *         call sites, so one marker text names the move once and an adopter pays one rewrite.
+ *         the shape change touches each op body and each caller, which a regex cannot rewrite
+ *         safely, so the fix names the move and never half-migrates it.
+ */
+export const asInputToContextReviewMarker = (input: {
+  from: string;
+  into: string;
+}): string =>
+  `// @declapract:review: ${input.from} is retired — move to ${input.into}, the (input, context) shape: each op becomes \`(input, context) => …\`, a dependency (dbConnection, log) moves out of the input into the context arg, and each caller passes it as the 2nd arg. then delete this marker`;

package/dist/utils/asJsonMergedDeep.ts

@@ -0,0 +1,69 @@
+/**
+ * .what = a rule that says whether a found json leaf may stand in for the declared one
+ * .why  = some leaves accept more than one value (an extant password, a hand-set name); the
+ *         merge keeps such a found value, and the drift check accepts it
+ */
+export type JsonLeafKeepRule = (input: {
+  path: string[];
+  declared: unknown;
+  found: unknown;
+}) => boolean;
+
+/**
+ * .what = whether a value is a plain json object (never an array or null)
+ */
+export const isJsonObject = (
+  value: unknown,
+): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * .what = deep-merge declared json into found json: each declared key wins, every found key the
+ *         declaration lacks is kept, and a found leaf the keep rule accepts is kept
+ * .why  = a shallow `{ ...found, ...declared }` replaces a whole subtree, so a repo's own nested
+ *         keys (a hand-set tunnel name, an extra database key) vanish on every apply (#539 7c)
+ * .note = key order: found keys first, in found order, then declared keys found lacked. so a
+ *         second merge over its own output returns the same bytes (idempotent).
+ */
+export const asJsonMergedDeep = (input: {
+  declared: unknown;
+  found: unknown;
+  path: string[];
+  isLeafKept: JsonLeafKeepRule;
+}): unknown => {
+  // a declared object merges key by key into a found object
+  if (isJsonObject(input.declared) && isJsonObject(input.found)) {
+    const declared = input.declared;
+    const found = input.found;
+    const keys = [
+      ...Object.keys(found),
+      ...Object.keys(declared).filter((key) => !(key in found)),
+    ];
+    return Object.fromEntries(
+      keys.map((key) => [
+        key,
+        key in declared
+          ? asJsonMergedDeep({
+              declared: declared[key],
+              found: found[key],
+              path: [...input.path, key],
+              isLeafKept: input.isLeafKept,
+            })
+          : found[key],
+      ]),
+    );
+  }
+
+  // a declared object over a non-object takes the declared shape
+  if (isJsonObject(input.declared)) return input.declared;
+
+  // a leaf: keep the found value where the rule accepts it, else the declared value
+  const isKept =
+    input.found !== undefined &&
+    input.isLeafKept({
+      path: input.path,
+      declared: input.declared,
+      found: input.found,
+    });
+  return isKept ? input.found : input.declared;
+};

package/dist/utils/asObjectLiteralProps.ts

@@ -0,0 +1,44 @@
+import { getOneSourceScanEnd } from './getOneSourceScanEnd';
+
+/**
+ * .what = split the body of an object literal (the text between its braces) into its top-level
+ *         properties, each with its key (null for a spread or a computed key) and its raw text
+ * .why  = a codemod that moves one call shape onto another (`{ service, function, event }` →
+ *         `{ which: { service, function }, event }`) must read the properties one by one, with a
+ *         nested object or a string that holds a comma left whole
+ * .note = a shorthand property (`locally`) yields `{ key: 'locally', value: null }`; a keyed one
+ *         (`event: { … }`) yields its value text, trimmed
+ * .note = deliberate mutation: the scan holds a local cursor (`from`) and a local segment list,
+ *         scoped to this call, as `getOneSourceScanEnd` does; no input or shared value is mutated
+ */
+export const asObjectLiteralProps = (input: {
+  body: string;
+}): { key: string | null; value: string | null; raw: string }[] => {
+  const segments: string[] = [];
+  let from = 0;
+  while (from < input.body.length) {
+    const end = getOneSourceScanEnd({
+      contents: input.body,
+      from,
+      mode: 'expression',
+    });
+    segments.push(input.body.slice(from, end));
+    from = end + 1;
+  }
+  return segments
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0)
+    .map((raw) => {
+      // a lead `//` comment line rides with its property, but never names its key
+      const code = raw.replace(/^(?:\/\/[^\n]*\n\s*)+/, '');
+      const shorthand = code.match(/^([A-Za-z_$][\w$]*)$/);
+      if (shorthand) return { key: shorthand[1]!, value: null, raw };
+      const keyed = code.match(/^([A-Za-z_$][\w$]*|'[^']*'|"[^"]*")\s*:\s*/);
+      if (!keyed) return { key: null, value: null, raw };
+      return {
+        key: keyed[1]!.replace(/^['"]|['"]$/g, ''),
+        value: code.slice(keyed[0].length).trim(),
+        raw,
+      };
+    });
+};

package/dist/utils/asPresenceCheck.ts

@@ -0,0 +1,18 @@
+/**
+ * .what = a best-practice check that passes when the declared path (or glob) found a file, and
+ *         otherwise names the file a human must author.
+ * .why  = a bare `FileCheckType.EXISTS` reports only "Expected file to exist" on a plan's
+ *         `FIX_MANUAL` line, so an adopter on a fresh repo must guess what the practice wants and
+ *         why. the check has no fix either way; the message is the whole of the guidance.
+ * .how  = declapract hands the check each file the declared glob found; with zero matches it
+ *         hands one `null`. any found file means the practice is satisfied.
+ */
+export const asPresenceCheck =
+  (input: { expected: string; hint: string }) =>
+  (contents: string | null): void => {
+    // a file matched the declared path
+    if (contents !== null) return;
+
+    // else, name what to author
+    throw new Error(`expected ${input.expected}; ${input.hint}`);
+  };

package/dist/utils/asSourceOnRunLambdaEndpoint.declapract.integration.test.ts

@@ -0,0 +1,84 @@
+import { ConstraintError } from 'helpful-errors';
+import {
+  asApiGatewayResponseSchema,
+  asLambdaEvent,
+  genLambdaEndpoint,
+  runLambdaEndpoint,
+} from 'sdk-aws-lambda';
+import { given, then, useThen, when } from 'test-fns';
+import { z } from 'zod';
+
+import { asSourceOnRunLambdaEndpoint } from './asSourceOnRunLambdaEndpoint';
+
+/**
+ * .what = proves, by real use, that the #650 codemod owes no ancient pin
+ * .why  = the pin existed only because sdk-aws-lambda 0.7.1 answered a contemp api gateway frame
+ *         with a 500. on 0.7.2 (sdk-aws-lambda#51) the contemp default frames it right, so the
+ *         nested read the codemod writes must pass against a real forApiGateway handler, run via
+ *         runLambdaEndpoint with no struct. on 0.7.1 this suite goes red (the 500)
+ */
+describe('asSourceOnRunLambdaEndpoint, by real use on sdk-aws-lambda', () => {
+  given('[case1] a forApiGateway endpoint that rejects an absent thread', () => {
+    const handler = genLambdaEndpoint.forApiGateway({
+      schema: {
+        input: z.object({ payload: z.object({ threadUuid: z.string() }) }),
+        output: asApiGatewayResponseSchema({
+          payload: z.object({ sent: z.boolean() }),
+        }),
+      },
+      invoke: async ({ payload }) => {
+        throw new ConstraintError('thread does not exist', {
+          threadUuid: payload.threadUuid,
+        });
+      },
+    });
+
+    when('[t0] the codemod moves a flat 400 read', () => {
+      const flatSource = `import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';
+
+it('rejects an absent thread', async () => {
+  const result = await invokeLambdaForTesting({ service: 'svc-gateway', function: 'sendChatMessage', event });
+  expect(JSON.parse(result.body).errorMessage).toContain('thread does not exist');
+  expect(JSON.parse(result.body).errorType).toEqual('ConstraintError');
+});
+`;
+      const movedSource = asSourceOnRunLambdaEndpoint({ contents: flatSource });
+
+      then('the read is nested, and no call is pinned', () => {
+        expect(movedSource).toContain(
+          "expect(JSON.parse(result.body).error.message).toContain('thread does not exist');",
+        );
+        expect(movedSource).toContain(
+          "expect(JSON.parse(result.body).error.class).toEqual('ConstraintError');",
+        );
+        expect(movedSource).not.toContain('struct:');
+      });
+    });
+
+    when('[t1] the endpoint runs via runLambdaEndpoint, with no struct', () => {
+      const result = useThen('the run returns', async () =>
+        runLambdaEndpoint.onReferenced({
+          event: asLambdaEvent.fromApiGateway({
+            body: { threadUuid: 'absent' },
+            httpMethod: 'POST',
+          }),
+          handler,
+        }),
+      );
+
+      then('the wire answers a 400, not a 500', () => {
+        expect((result as { statusCode: number }).statusCode).toEqual(400);
+      });
+
+      then('the rewritten reads pass against the real body', () => {
+        // the exact assertions the codemod wrote in [t0]
+        expect(JSON.parse((result as { body: string }).body).error.message).toContain(
+          'thread does not exist',
+        );
+        expect(JSON.parse((result as { body: string }).body).error.class).toEqual(
+          'ConstraintError',
+        );
+      });
+    });
+  });
+});