declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/utils/isConfigShapeDivergent.ts

@@ -0,0 +1,61 @@
+import flatten from 'flat';
+
+/**
+ * .what = the flattened leaf keys of a config object, and those whose value is null
+ */
+const asConfigLeaves = (input: {
+  config: object;
+}): { keys: string[]; nullKeys: string[] } => {
+  const flat: Record<string, unknown> = flatten(input.config);
+  const keys = Object.keys(flat);
+  return { keys, nullKeys: keys.filter((key) => flat[key] === null) };
+};
+
+/**
+ * .what = whether a leaf of one config is matched in a peer config
+ * .why  = an env with no such resource declares it `null` (e.g. test has no lambda tunnel:
+ *         `"lambda": null`), while a peer env declares the object (`{ host, port }`). that is one
+ *         shape, so a null leaf `x` and a peer subtree `x.*` match each other, in each direction
+ */
+const isLeafMatched = (input: {
+  key: string;
+  isNull: boolean;
+  peer: { keys: string[]; nullKeys: string[] };
+}): boolean =>
+  input.peer.keys.includes(input.key) ||
+  input.peer.nullKeys.some((nullKey) => input.key.startsWith(`${nullKey}.`)) ||
+  (input.isNull &&
+    input.peer.keys.some((key) => key.startsWith(`${input.key}.`)));
+
+/**
+ * .what = whether every leaf of one config is matched in a peer config
+ */
+const isEveryLeafMatched = (input: {
+  leaves: { keys: string[]; nullKeys: string[] };
+  peer: { keys: string[]; nullKeys: string[] };
+}): boolean =>
+  input.leaves.keys.every((key) =>
+    isLeafMatched({
+      key,
+      isNull: input.leaves.nullKeys.includes(key),
+      peer: input.peer,
+    }),
+  );
+
+/**
+ * .what = whether two env configs declare different shapes
+ * .why  = every env config must declare the same keys as config/test.json, so a key added to one
+ *         env is never absent at runtime in another. a null leaf is an absent subtree, which
+ *         matches the peer's subtree (see isLeafMatched)
+ */
+export const isConfigShapeDivergent = (input: {
+  expected: object;
+  found: object;
+}): boolean => {
+  const expected = asConfigLeaves({ config: input.expected });
+  const found = asConfigLeaves({ config: input.found });
+  return (
+    !isEveryLeafMatched({ leaves: expected, peer: found }) ||
+    !isEveryLeafMatched({ leaves: found, peer: expected })
+  );
+};

package/dist/utils/isPackageImportedInRepo.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { getAllPathsUnderDir } from './getAllPathsUnderDir';
+
+const CODE_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const WALK_SKIP_DIRS = ['node_modules', 'dist', 'build', '.git', 'coverage'];
+
+/**
+ * .what = whether any code file under the named dirs of a repo imports (or requires) a package.
+ * .why  = a fix must never remove a dependency while a live import of it remains — that leaves
+ *         a tree that does not build (#642, #643, #663). this scan is the gate such a fix consults.
+ * .note = matches a static import, a side-effect import, a `require(…)`, and a dynamic `import(…)`
+ *         of the package or any of its subpaths. a dir absent from the repo is skipped.
+ */
+export const isPackageImportedInRepo = (input: {
+  projectRoot: string;
+  packageName: string;
+  dirs: string[];
+}): boolean => {
+  // the escaped name, so a scope `@` or a `.` reads literally
+  const escaped = input.packageName.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+  const importPattern = new RegExp(
+    `(?:\\bfrom\\s+|\\bimport\\s+|\\brequire\\(\\s*|\\bimport\\(\\s*)['"]${escaped}(?:/[^'"]*)?['"]`,
+  );
+
+  // every code file under each named dir that exists
+  const codeFiles = input.dirs
+    .map((dir) => path.join(input.projectRoot, dir))
+    .filter((dir) => existsSync(dir))
+    .flatMap((dir) => getAllPathsUnderDir({ dir, skip: WALK_SKIP_DIRS }))
+    .filter((file) =>
+      CODE_FILE_EXTENSIONS.some((extension) => file.endsWith(extension)),
+    );
+
+  return codeFiles.some((file) =>
+    importPattern.test(readFileSync(file, 'utf-8')),
+  );
+};

package/dist/utils/isVersionBelowFloor.ts

@@ -0,0 +1,33 @@
+/**
+ * .what = the first `major.minor.patch` triple of a version or range, as numbers.
+ * .why  = a package.json value may carry a range operator (`^4.3.6`, `~3.23.8`, `>=1.0.0`); the
+ *         floor comparison reads the lowest version the range admits, which is its first triple.
+ * .note = null when no numeric version heads the value (`latest`, `workspace:*`, `link:.`) — such a
+ *         value cannot be judged against a floor, so the caller must not flag it.
+ */
+const asVersionTriple = (input: {
+  version: string;
+}): [number, number, number] | null => {
+  const found = input.version.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!found) return null;
+  return [Number(found[1]), Number(found[2] ?? 0), Number(found[3] ?? 0)];
+};
+
+/**
+ * .what = whether a declared version (or range) sits below a floor version.
+ * .why  = several fixes raise a dependency only when it undercuts a floor, and keep a higher
+ *         adopter choice untouched. one comparator keeps that judgment identical across them.
+ * .note = false for a value with no numeric version (it cannot be judged; never flag a guess).
+ */
+export const isVersionBelowFloor = (input: {
+  version: string;
+  floor: string;
+}): boolean => {
+  const version = asVersionTriple({ version: input.version });
+  const floor = asVersionTriple({ version: input.floor });
+  if (!version || !floor) return false;
+  const [delta] = [0, 1, 2]
+    .map((index) => version[index]! - floor[index]!)
+    .filter((difference) => difference !== 0);
+  return (delta ?? 0) < 0;
+};

package/dist/utils/migrateDevConfigToPrep.ts

@@ -1,8 +1,8 @@
 /**
- * .what = migrate a `config/dev.json`'s ONE unambiguous tier token from `dev` to `prep`: the
+ * .what = migrate a `config/dev.json`'s ONE unambiguous access token from `dev` to `prep`: the
  *         `"access": "dev"` key. every HOST value is preserved verbatim.
  * .why  = ONE source for the two `old-dev-config-location` declarers (config +
- *         persist-with-rds), so the tier-migration cannot drift between them —
+ *         persist-with-rds), so the access migration cannot drift between them —
  *         mirrors `defineExpectedGitignoreContents` / `isDeferredToDeprecatedDirMove`.
  *         both declarers relocate `config/dev.json` → `config/prep.json` and migrate
  *         the access; this holds the shared byte-identical core so a future edit
@@ -13,20 +13,20 @@
  *
  *         a HOST is NEVER rewritten — this util runs on a CONSUMER's real `config/dev.json`,
  *         whose host values are the consumer's own. a `.dev` label is axis-ambiguous WHEREVER
- *         it sits: `auth.myapp.dev` may be a public `.dev` gTLD or an internal tier host, and
+ *         it sits: `auth.myapp.dev` may be a public `.dev` gTLD or an internal per-access host, and
  *         `api.dev.paypal.com` carries a mid-dotted `dev` that is a FOREIGN host's own label,
- *         not a tier segment. the migration cannot tell a tier host from a foreign host by
+ *         not an access segment. the migration cannot tell a per-access host from a foreign host by
  *         structure, so per the wish's guard #3 (a rewrite that cannot verify its output must
  *         NOT guess) it rewrites NO host at all — the earlier mid-dotted rewrite guessed one
  *         position over from the terminal case, and silently corrupted a foreign public host
  *         (`api.dev.paypal.com` → `api.prep.paypal.com`) whose only signal was a human reading
  *         the apply diff. dropping it applies guard #3 uniformly.
  *
- *         the residual: a consumer whose OWN tier host is a bare `.dev` (`mydb.dev`) keeps it
+ *         the residual: a consumer whose OWN per-access host is a bare `.dev` (`mydb.dev`) keeps it
  *         after the migrate, so it must set the prep host by hand. that is correct by guard #3
  *         — the util cannot know the consumer's prep host (the real template keys it as a
  *         `@declapract{variable.databaseClusterHost.prep}`, a per-consumer value), so host
- *         migration is out of this util's scope. a stranded tier host fails LOUD at connect
+ *         migration is out of this util's scope. a stranded per-access host fails LOUD at connect
  *         time (a connection error, never silent wrong data), and the apply diff shows the
  *         access flip so the host review is visible.
  *

package/dist/utils/withEachCallRewritten.ts

@@ -0,0 +1,53 @@
+import { getOneSourceScanEnd } from './getOneSourceScanEnd';
+
+/**
+ * .what = rewrite every `<callee>(…)` call through a per-call transform of its argument text
+ * .why  = a codemod that moves a call onto a successor whose shape differs by more than a name
+ *         must read each call's argument list whole (strings and nested brackets skipped by the
+ *         scanner) and rebuild it. one source for every declaration that does so.
+ * .note = the rewrite emits its call relative to column 0; each later line is re-indented to the
+ *         line the call starts on, and the args it reads are de-indented by the same amount, so a
+ *         multi-line value keeps its own shape. the rewrite must not emit `<callee>(` again, or
+ *         the walk would not end.
+ */
+export const withEachCallRewritten = (input: {
+  contents: string;
+  callee: string;
+  rewrite: (args: { argsText: string }) => string;
+}): string => {
+  const found = new RegExp(
+    `(?<![.\\w$])${input.callee.replace(/[.$]/g, '\\$&')}\\s*\\(`,
+  ).exec(input.contents);
+  if (!found) return input.contents;
+  const parenOpen = found.index + found[0].length - 1;
+  const parenClose = getOneSourceScanEnd({
+    contents: input.contents,
+    from: parenOpen,
+    mode: 'close',
+  });
+
+  // the new call's later lines sit at the indent of the line the call starts on
+  const lineStart = input.contents.lastIndexOf('\n', found.index) + 1;
+  const indent = input.contents.slice(lineStart).match(/^[ \t]*/)?.[0] ?? '';
+
+  // the args are read relative to that indent, so a multi-line value keeps its own shape
+  const argsText = input.contents
+    .slice(parenOpen + 1, parenClose)
+    .split('\n')
+    .map((line, index) =>
+      index > 0 && line.startsWith(indent) ? line.slice(indent.length) : line,
+    )
+    .join('\n');
+  const callText = input
+    .rewrite({ argsText })
+    .split('\n')
+    .map((line, index) => (index === 0 ? line : `${indent}${line}`))
+    .join('\n');
+
+  // splice the call in, then walk on to the next
+  const rewritten =
+    input.contents.slice(0, found.index) +
+    callText +
+    input.contents.slice(parenClose + 1);
+  return withEachCallRewritten({ ...input, contents: rewritten });
+};

package/dist/utils/withGetDatabaseConnectionRepointed.ts

@@ -0,0 +1,121 @@
+import ts from 'typescript';
+
+/**
+ * .what = whether a module specifier names the retired `getDatabaseConnection` module, by any path
+ *         (`./getDatabaseConnection`, `@src/utils/database/getDatabaseConnection`, …)
+ * .why = the retired module is found by its file name; the path to it varies per importer
+ */
+const isRetiredModuleSpecifier = (input: { specifier: string }): boolean =>
+  /(^|\/)getDatabaseConnection$/.test(input.specifier) &&
+  input.specifier.includes('/');
+
+/**
+ * .what = the import declarations of a source that reach the retired module
+ * .why = both the check and the fix key on these, via the parser, so a comment or a string that
+ *        mentions the path is never mistaken for an import
+ */
+const getRetiredModuleImports = (input: {
+  file: ts.SourceFile;
+}): ts.ImportDeclaration[] =>
+  input.file.statements.filter(
+    (statement): statement is ts.ImportDeclaration =>
+      ts.isImportDeclaration(statement) &&
+      ts.isStringLiteral(statement.moduleSpecifier) &&
+      isRetiredModuleSpecifier({ specifier: statement.moduleSpecifier.text }),
+  );
+
+const asSourceFile = (input: { source: string }): ts.SourceFile =>
+  ts.createSourceFile(
+    'repoint.ts',
+    input.source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+
+/**
+ * .what = whether a source imports from the retired `getDatabaseConnection` module
+ * .why = the repoint fires only on a file that reaches the retired module
+ */
+export const isGetDatabaseConnectionImporter = (input: {
+  source: string;
+}): boolean =>
+  getRetiredModuleImports({ file: asSourceFile(input) }).length > 0;
+
+/**
+ * .what = repoints a source from the retired `getDatabaseConnection` module onto
+ *         `getOneDatabaseConnection`: the module specifier, and the factory's local name
+ * .why = persist-with-rds renamed the factory, and the old file still reads a config shape the
+ *        practice removed. both modules export `DatabaseConnection` and `DatabaseQueryError` by the
+ *        same names, so only the specifier and the factory name move
+ * .note = the factory name moves only where the retired import binds it unaliased; a
+ *         `getDatabaseConnection` imported from some other module (as the property name of an
+ *         aliased import) is never touched. a source that reaches no retired module is returned
+ *         unchanged, and a second pass is a no-op
+ */
+export const withGetDatabaseConnectionRepointed = (input: {
+  source: string;
+}): string => {
+  const file = asSourceFile(input);
+  const retiredImports = getRetiredModuleImports({ file });
+  if (retiredImports.length === 0) return input.source;
+
+  // the factory is renamed only where a retired import binds it under its own name
+  const bindsFactory = retiredImports.some((declaration) => {
+    const bindings = declaration.importClause?.namedBindings;
+    return (
+      !!bindings &&
+      ts.isNamedImports(bindings) &&
+      bindings.elements.some(
+        (element) =>
+          element.name.text === 'getDatabaseConnection' &&
+          !element.propertyName,
+      )
+    );
+  });
+
+  // collect each span to rewrite: the retired specifiers, then the factory's identifiers
+  const spans: { start: number; end: number; text: string }[] = [];
+  retiredImports.forEach((declaration) => {
+    const specifier = declaration.moduleSpecifier as ts.StringLiteral;
+    const start = specifier.getStart(file) + 1; // inside the quote
+    const end = specifier.getEnd() - 1;
+    spans.push({
+      start,
+      end,
+      text: specifier.text.replace(
+        /getDatabaseConnection$/,
+        'getOneDatabaseConnection',
+      ),
+    });
+  });
+
+  // walk the tree for each factory identifier, skip the property name of an aliased import
+  const visit = (node: ts.Node): void => {
+    const isForeignPropertyName =
+      ts.isImportSpecifier(node.parent ?? node) &&
+      (node.parent as ts.ImportSpecifier).propertyName === node;
+    if (
+      bindsFactory &&
+      ts.isIdentifier(node) &&
+      node.text === 'getDatabaseConnection' &&
+      !isForeignPropertyName
+    )
+      spans.push({
+        start: node.getStart(file),
+        end: node.getEnd(),
+        text: 'getOneDatabaseConnection',
+      });
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+
+  // splice bottom-up, so the earlier offsets stay valid
+  return spans
+    .sort((a, b) => b.start - a.start)
+    .reduce(
+      (text, span) =>
+        `${text.slice(0, span.start)}${span.text}${text.slice(span.end)}`,
+      input.source,
+    );
+};

package/dist/utils/withPgClientSslDeclared.ts

@@ -0,0 +1,190 @@
+import ts from 'typescript';
+
+/**
+ * .what = the review pointer stamped above a file whose pg client cannot be given tls safely
+ * .why = the fix can only name a cluster endpoint where the file already reads the app config;
+ *        elsewhere a human must choose it, so the file is flagged and `plan` stays red
+ */
+export const PG_CLIENT_SSL_REVIEW_MARKER =
+  '// @declapract:review: a pg Client here connects with no tls. pass `ssl: asDatabaseClientSsl({ clusterEndpoint })` from @src/utils/database/asDatabaseClientSsl';
+
+const SSL_PROPERTY =
+  'ssl: asDatabaseClientSsl({ clusterEndpoint: config.database.tunnel.lambda?.host ?? null }),';
+const SSL_IMPORT =
+  "import { asDatabaseClientSsl } from '@src/utils/database/asDatabaseClientSsl';";
+
+const asSourceFile = (input: { source: string }): ts.SourceFile =>
+  ts.createSourceFile(
+    'client.ts',
+    input.source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+
+/**
+ * .what = the local names a source binds to the `pg` module: the name(s) its `Client` class goes
+ *         by, and the name(s) of the module itself
+ * .why = only a client constructed through a `pg` import is a pg client; an elasticsearch or
+ *        opensearch `Client` must never get a postgres tls option or a review pointer
+ */
+const getPgBindings = (input: {
+  file: ts.SourceFile;
+}): { clientNames: string[]; moduleNames: string[] } => {
+  const pgImports = input.file.statements
+    .filter(ts.isImportDeclaration)
+    .filter(
+      (statement) =>
+        ts.isStringLiteral(statement.moduleSpecifier) &&
+        statement.moduleSpecifier.text === 'pg',
+    )
+    .map((statement) => statement.importClause)
+    .filter((clause): clause is ts.ImportClause => !!clause);
+  const clientNames = pgImports.flatMap((clause) => {
+    const bindings = clause.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) return [];
+    return bindings.elements
+      .filter((element) => (element.propertyName ?? element.name).text === 'Client')
+      .map((element) => element.name.text);
+  });
+  const moduleNames = pgImports.flatMap((clause) => [
+    ...(clause.name ? [clause.name.text] : []),
+    ...(clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)
+      ? [clause.namedBindings.name.text]
+      : []),
+  ]);
+  return { clientNames, moduleNames };
+};
+
+/**
+ * .what = whether a `new X(...)` expression constructs a pg Client, through a `pg` import:
+ *         `new Client` (named import) or `new pg.Client` (default or namespace import)
+ */
+const isPgClientConstruction = (input: {
+  node: ts.NewExpression;
+  pg: { clientNames: string[]; moduleNames: string[] };
+}): boolean =>
+  (ts.isIdentifier(input.node.expression) &&
+    input.pg.clientNames.includes(input.node.expression.text)) ||
+  (ts.isPropertyAccessExpression(input.node.expression) &&
+    input.node.expression.name.text === 'Client' &&
+    ts.isIdentifier(input.node.expression.expression) &&
+    input.pg.moduleNames.includes(input.node.expression.expression.text));
+
+/**
+ * .what = whether an options object declares an explicit `ssl` property
+ */
+const hasSslProperty = (input: {
+  options: ts.ObjectLiteralExpression;
+}): boolean =>
+  input.options.properties.some(
+    (property) =>
+      !!property.name &&
+      ts.isIdentifier(property.name) &&
+      property.name.text === 'ssl',
+  );
+
+/**
+ * .what = the options object of each pg Client the source constructs with no explicit `ssl`
+ * .why = both the check and the fix key on these, via the parser, so a comment or a string that
+ *        mentions `new Client` is never mistaken for a construction
+ */
+const getAllPgClientOptionsWithoutSsl = (input: {
+  file: ts.SourceFile;
+}): ts.ObjectLiteralExpression[] => {
+  const pg = getPgBindings({ file: input.file });
+  const found: ts.ObjectLiteralExpression[] = [];
+  const visit = (node: ts.Node): void => {
+    const options = ts.isNewExpression(node) ? node.arguments?.[0] : undefined;
+    if (
+      ts.isNewExpression(node) &&
+      isPgClientConstruction({ node, pg }) &&
+      options &&
+      ts.isObjectLiteralExpression(options) &&
+      !hasSslProperty({ options })
+    )
+      found.push(options);
+    ts.forEachChild(node, visit);
+  };
+  visit(input.file);
+  return found;
+};
+
+/**
+ * .what = whether a source constructs a pg Client with no explicit tls options
+ */
+export const isPgClientWithoutSsl = (input: { source: string }): boolean =>
+  getAllPgClientOptionsWithoutSsl({ file: asSourceFile(input) }).length > 0;
+
+/**
+ * .what = where and what to insert so one options object declares the ssl property
+ * .why = the property lands after the last one, at its indent, with the comma it needs
+ * .note = three shapes: an empty object takes the property inline; a comma already after the last
+ *         property takes it after that comma; else a comma is added before it
+ */
+const asSslPropertyInsert = (input: {
+  source: string;
+  file: ts.SourceFile;
+  options: ts.ObjectLiteralExpression;
+}): { at: number; text: string } => {
+  const last = input.options.properties[input.options.properties.length - 1];
+  if (!last)
+    return {
+      at: input.options.getStart(input.file) + 1,
+      text: ` ${SSL_PROPERTY} `,
+    };
+  const lineStart = input.source.lastIndexOf('\n', last.getStart(input.file));
+  const indent = /^[ \t]*/.exec(input.source.slice(lineStart + 1))?.[0] ?? '  ';
+  const commaAt = input.options.properties.hasTrailingComma
+    ? input.source.indexOf(',', last.getEnd())
+    : -1;
+  if (commaAt >= 0)
+    return { at: commaAt + 1, text: `\n${indent}${SSL_PROPERTY}` };
+  return { at: last.getEnd(), text: `,\n${indent}${SSL_PROPERTY}` };
+};
+
+/**
+ * .what = gives every pg Client in a source the verified tls options of asDatabaseClientSsl
+ * .why = a client with no `ssl` connects in plaintext, and fails outright on a cluster that
+ *        forces ssl (the postgres 17 default)
+ * .note = the fix names the endpoint as `config.database.tunnel.lambda?.host`, so it applies only
+ *         where the source already reads `config.database.tunnel`. any other source gets the review
+ *         pointer once instead. a second pass is a no-op
+ */
+export const withPgClientSslDeclared = (input: { source: string }): string => {
+  const file = asSourceFile(input);
+  const optionsAll = getAllPgClientOptionsWithoutSsl({ file });
+  if (optionsAll.length === 0) return input.source;
+
+  // stamp the review pointer once where the endpoint cannot be named safely
+  if (!input.source.includes('config.database.tunnel'))
+    return input.source.includes(PG_CLIENT_SSL_REVIEW_MARKER)
+      ? input.source
+      : `${PG_CLIENT_SSL_REVIEW_MARKER}\n${input.source}`;
+
+  // insert the ssl property into each options object
+  const spans = optionsAll.map((options) =>
+    asSslPropertyInsert({ source: input.source, file, options }),
+  );
+
+  // add the import after the last import, unless the source already imports it
+  const imports = file.statements.filter(ts.isImportDeclaration);
+  const importAt = imports[imports.length - 1]?.getEnd() ?? 0;
+  const importSpans = input.source.includes('asDatabaseClientSsl')
+    ? []
+    : [
+        {
+          at: importAt,
+          text: importAt ? `\n${SSL_IMPORT}` : `${SSL_IMPORT}\n`,
+        },
+      ];
+
+  // splice bottom-up, so the earlier offsets stay valid
+  return [...spans, ...importSpans]
+    .sort((a, b) => b.at - a.at)
+    .reduce(
+      (text, span) =>
+        `${text.slice(0, span.at)}${span.text}${text.slice(span.at)}`,
+      input.source,
+    );
+};

package/dist/utils/withReviewMarkerAbove.ts

@@ -0,0 +1,43 @@
+/**
+ * .what = insert a `// @declapract:review: …` line directly above each line that matches, once.
+ * .why  = a fix that cannot safely rewrite a line (a shape move, a contract change, a design call)
+ *         must still leave the tree pointed at the move, never silent and never half-migrated. the
+ *         marker lands beside the line tsc or a reviewer will name, so the instruction sits in the
+ *         file rather than in a readme no `plan` output prints. ONE source for every declaration
+ *         that stamps a line-scoped marker, so the idempotency guard cannot drift between them.
+ * .note = idempotent: the contiguous `//` comment block above a matched line is scanned, and a line
+ *         whose block already holds this exact marker is left alone. so a re-apply is a no-op.
+ * .note = `lineMatcher` may carry any flags; a global flag is stripped from a private copy, so the
+ *         caller's regex is never mutated and no `lastIndex` state leaks between lines.
+ */
+export const withReviewMarkerAbove = (input: {
+  contents: string;
+  lineMatcher: RegExp;
+  marker: string;
+}): string => {
+  // a per-line test must not carry `lastIndex` state between lines, so drop any global flag
+  const matcher = new RegExp(
+    input.lineMatcher.source,
+    input.lineMatcher.flags.replace('g', ''),
+  );
+  const lines = input.contents.split('\n');
+
+  // scan the contiguous `//` comment block above a line for this exact marker
+  const isMarkedAbove = (index: number): boolean => {
+    const prior = lines[index - 1];
+    if (prior === undefined) return false;
+    if (!prior.trimStart().startsWith('//')) return false;
+    if (prior.includes(input.marker)) return true;
+    return isMarkedAbove(index - 1);
+  };
+
+  // stamp each matched line that does not yet carry the marker, at the line's own indent
+  return lines
+    .flatMap((line, index) => {
+      if (!matcher.test(line)) return [line];
+      if (isMarkedAbove(index)) return [line];
+      const indent = line.match(/^[ \t]*/)?.[0] ?? '';
+      return [`${indent}${input.marker}`, line];
+    })
+    .join('\n');
+};

package/dist/utils/zodVersionPinned.ts

@@ -0,0 +1,9 @@
+/**
+ * .what = the one zod version every zod writer in these practices emits: the exact zod that
+ *         `sdk-aws-lambda` pins (0.7.1 pins `zod@4.4.3`).
+ * .why  = two zod copies in one tree make tsc reconcile two near-identical `ZodType` graphs, which
+ *         exhausts the heap (#545). the joi fixer's direct pin (#654) and the runtime-schemas
+ *         `pnpm.overrides.zod` (#545) must name ONE version, so both read this constant.
+ * .note = bump it in step with the sdk-aws-lambda floor; a lag here re-opens the two-copy tree.
+ */
+export const ZOD_VERSION_PINNED = '4.4.3';