declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/ancientTargetPublished.declapract.integration.test.ts

@@ -1,12 +1,13 @@
 import { readFileSync } from 'node:fs';
 
+import { MalfunctionError } from 'helpful-errors';
 import { given, then, useBeforeAll, when } from 'test-fns';
-import ts from 'typescript';
+import { getModuleExportsFromTsSource } from './utils/getModuleExportsFromTsSource';
 
 /**
  * .what = exercises case=2's no-404 promise at the reachable grain: the fleet slug an
- *         `sdkAwsLambdaEnvAccess{Ancient,Contemp}` target op RETURNS, for any DEPLOYED access
- *         tier, must be a stage the serverless dual-publish scaffold actually deploys under —
+ *         `sdkAwsLambdaEnvAccess{Ancient,Contemp}` target op RETURNS, for any DEPLOYED access,
+ *         must be a stage the serverless dual-publish scaffold actually deploys under —
  *         so a caller that builds `${service}-${slug}-${fn}` addresses a name a fleet answers
  *         to, never a 404.
  * .why  = case=2 (cross-service-call-never-404s) is a demoed critipath whose core promise is
@@ -51,25 +52,25 @@ const runTargetSlug = (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,
+  });
+  const targetOp =
+    moduleExports[input.name] ??
+    MalfunctionError.throw('the target-op template no longer exports this op', {
+      path: input.path,
+      name: input.name,
+    });
+  return targetOp();
 };
 
 /**
  * .what = the `accessByStage` map, read from the serverless template as { stage: access }.
  * .why  = its KEYS are the `--stage` slugs the scaffold deploys under (the published fleet
- *         slugs); its VALUES are the accesses those deploys reach (the deployed tiers).
+ *         slugs); its VALUES are the accesses those deploys run with (the deployed accesses).
  *         serverless.yml carries `@declapract{...}` vars elsewhere, so a full yaml parse would
  *         choke — the block is clean, so a scoped line-scan reads it exactly.
  */
@@ -93,8 +94,8 @@ describe('the EnvAccess target op emits only slugs the dual-publish scaffold pub
     const state = useBeforeAll(() => {
       const accessByStage = readAccessByStage();
       const publishedStages = Object.keys(accessByStage); // the --stage slugs a deploy publishes
-      const deployedTiers = [...new Set(Object.values(accessByStage))]; // accesses that reach a fleet
-      return { accessByStage, publishedStages, deployedTiers };
+      const deployedAccesses = [...new Set(Object.values(accessByStage))]; // accesses that reach a fleet
+      return { accessByStage, publishedStages, deployedAccesses };
     });
 
     when('the scaffold is read', () => {
@@ -110,18 +111,18 @@ describe('the EnvAccess target op emits only slugs the dual-publish scaffold pub
         expect({
           accessByStage: state.accessByStage,
           publishedStages: [...state.publishedStages].sort(),
-          deployedTiers: [...state.deployedTiers].sort(),
+          deployedAccesses: [...state.deployedAccesses].sort(),
         }).toMatchSnapshot('dual-publish scaffold shape');
       });
     });
 
     when('each deployed access is walked through the ancient target op', () => {
       then('the emitted slug is a stage the scaffold publishes (no 404 by construction)', () => {
-        for (const tier of state.deployedTiers) {
+        for (const deployedAccess of state.deployedAccesses) {
           const slug = runTargetSlug({
             path: ANCIENT_PATH,
             name: 'sdkAwsLambdaEnvAccessAncient',
-            access: tier as 'test' | 'prep' | 'prod',
+            access: deployedAccess as 'test' | 'prep' | 'prod',
           });
           // slug ∈ publishedStages ⟺ the caller's target `${service}-${slug}-${fn}` names a
           // fleet the scaffold actually deploys ⟺ the invoke lands, never a 404
@@ -132,42 +133,42 @@ describe('the EnvAccess target op emits only slugs the dual-publish scaffold pub
 
     when('each deployed access is walked through the contemp target op', () => {
       then('the emitted slug is a stage the scaffold publishes (no 404 by construction)', () => {
-        for (const tier of state.deployedTiers) {
+        for (const deployedAccess of state.deployedAccesses) {
           const slug = runTargetSlug({
             path: CONTEMP_PATH,
             name: 'sdkAwsLambdaEnvAccessContemp',
-            access: tier as 'test' | 'prep' | 'prod',
+            access: deployedAccess as 'test' | 'prep' | 'prod',
           });
           expect(state.publishedStages).toContain(slug);
         }
       });
     });
 
-    when('the per-tier emitted slugs are derived for both target ops', () => {
+    when('the per-access emitted slugs are derived for both target ops', () => {
       // the caller-faced contract of the no-404 invariant: which slug each op emits per deployed
-      // tier, and the published set it must land within. snapshot so a reword that keeps the
-      // membership green (a re-mapped tier, a re-shaped scaffold) reddens a vibecheck.
+      // access, and the published set it must land within. snapshot so a reword that keeps the
+      // membership green (a re-mapped access, a re-shaped scaffold) reddens a vibecheck.
       then('the target-slug shape matches snapshot', () => {
-        const perTier = state.deployedTiers
+        const perAccess = state.deployedAccesses
           .slice()
           .sort()
-          .map((tier) => ({
-            access: tier,
+          .map((deployedAccess) => ({
+            access: deployedAccess,
             ancient: runTargetSlug({
               path: ANCIENT_PATH,
               name: 'sdkAwsLambdaEnvAccessAncient',
-              access: tier as 'test' | 'prep' | 'prod',
+              access: deployedAccess as 'test' | 'prep' | 'prod',
             }),
             contemp: runTargetSlug({
               path: CONTEMP_PATH,
               name: 'sdkAwsLambdaEnvAccessContemp',
-              access: tier as 'test' | 'prep' | 'prod',
+              access: deployedAccess as 'test' | 'prep' | 'prod',
             }),
           }));
         expect({
-          perTier,
+          perAccess,
           publishedStages: [...state.publishedStages].sort(),
-        }).toMatchSnapshot('per-tier target slug vs published stages');
+        }).toMatchSnapshot('per-access target slug vs published stages');
       });
     });
   });

package/dist/bestPracticeTemplateParse.declapract.integration.test.ts

@@ -0,0 +1,223 @@
+import { readFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import * as ts from 'typescript';
+
+import {
+  getAllPathsUnderDir,
+  PRACTICE_TREE_SKIP_DIRS,
+} from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = clamps that every `.ts`/`.tsx` TEMPLATE a practice ships parses as valid typescript,
+ *         and that no multi-line jsdoc inside one closes itself mid-line.
+ * .why  = a template is copied verbatim into a consumer repo, where it is real source that the
+ *         consumer's biome parses on every `pnpm fix`. a template that does not parse breaks
+ *         `pnpm fix` in EVERY adopter at once, and no adopter can repair it for itself —
+ *         `declapract apply` restores the shipped bytes (#613). this repo's own biome cannot
+ *         catch it: `biome.jsonc` excludes the practice provision tree because templates carry
+ *         `@declapract{}` syntax, so the templates are the one tree with no parse gate on it.
+ *         this clamp is that gate.
+ * .note = the hazard class is wider than any one line: ANY template may carry a glob or an arn
+ *         inside a block comment, and a `*` immediately before a `/` there terminates the comment
+ *         mid-prose. every character after it is read as code. that is how #613 shipped:
+ *         `persist-with-rds`'s `resources.parameters.ts` emitted 17 parse errors in every
+ *         adopter. so this clamps the CLASS (all templates), never the instance.
+ * .teeth = write an iam arn or a glob into any template's jsdoc with a literal `*` immediately
+ *          before a `/` — the shape #613 shipped in
+ *          `persist-with-rds/best-practice/provision/aws/resources.parameters.ts` — and BOTH
+ *          cases redden, with the offending path in the diff.
+ * .note = the two cases are separate nets over one defect class, deliberately. case1 (parse)
+ *         reads the property an adopter actually suffers. case2 (jsdoc shape) catches the
+ *         silent variant case1 cannot see: a comment that self-closes and whose prose tail
+ *         happens to parse as valid code, so the file is green and the note is corrupted.
+ * .note = scope excludes `*.declapract.*` basenames — those are declapract MACHINERY (check
+ *         declarations, unit clamps), never templates, and this repo's biome already parses
+ *         the `*.declapract.ts` declarations. `bad-practices/` is excluded by construction:
+ *         only `best-practice/` holds what ships.
+ * .note = this is an INTEGRATION test (`readdirSync` + `readFileSync` cross the filesystem
+ *         boundary, per `rule.forbid.unit.remote-boundaries`), and it lives at `src/` — not
+ *         under any practice — so declapract never walks it for emission (#583).
+ */
+
+// anchored on `__dirname` (this file sits at `src/`) rather than cwd, so a nested-scope jest run
+// cannot silently walk the wrong tree and assert on zero files (a vacuous green).
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+
+const isShippedTsTemplate = (path: string): boolean =>
+  /\.tsx?$/.test(path) &&
+  path.includes('/best-practice/') &&
+  !basename(path).includes('.declapract.');
+
+const asDiagnosticSite = (diagnostic: ts.Diagnostic): string => {
+  if (!diagnostic.file) return '';
+  if (diagnostic.start === undefined) return '';
+  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(
+    diagnostic.start,
+  );
+  return `:${line + 1}:${character + 1}`;
+};
+
+const asParseErrorLabel = (input: {
+  path: string;
+  diagnostic: ts.Diagnostic;
+}): string =>
+  [
+    relative(repoRoot, input.path),
+    asDiagnosticSite(input.diagnostic),
+    ' ',
+    ts.flattenDiagnosticMessageText(input.diagnostic.messageText, ' '),
+  ].join('');
+
+/**
+ * .what = every syntactic error typescript reports for one template's source.
+ * .why  = `transpileModule` runs the PARSER only — no type check, no module resolution — so a
+ *         template that references packages the consumer installs (but this repo does not) is
+ *         not a false red. the `@declapract{…}` placeholders sit inside string and template
+ *         literals in every ts template, so they parse as ordinary string content.
+ */
+const getAllParseErrors = (input: { path: string; source: string }): string[] =>
+  getAllSyntacticDiagnostics(input)
+    .filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
+    .map((diagnostic) => asParseErrorLabel({ path: input.path, diagnostic }));
+
+/**
+ * .what = the parser's diagnostics for one template, by the route its kind allows.
+ * .why  = `transpileModule` cannot emit a declaration file, so a `.d.ts` template (an ambient
+ *         module, e.g. tests-expo `src/.test/assets/test-fns.autoprune.d.ts`) throws "Output generation failed"
+ *         rather than report. a one-file program's `getSyntacticDiagnostics` reads the same parser
+ *         and accepts a `.d.ts`; it still resolves no module and checks no type.
+ */
+const getAllSyntacticDiagnostics = (input: {
+  path: string;
+  source: string;
+}): readonly ts.Diagnostic[] => {
+  // a declaration file: parse via a one-file program, since it has no emit
+  if (input.path.endsWith('.d.ts')) {
+    const host = ts.createCompilerHost({});
+    const program = ts.createProgram({
+      rootNames: [input.path],
+      options: { noResolve: true, noLib: true },
+      host: {
+        ...host,
+        getSourceFile: (fileName, languageVersion) =>
+          fileName === input.path
+            ? ts.createSourceFile(fileName, input.source, languageVersion)
+            : undefined,
+      },
+    });
+    return program.getSyntacticDiagnostics();
+  }
+
+  // every other template: parse via transpile, which runs the parser only
+  return (
+    ts.transpileModule(input.source, {
+      fileName: input.path,
+      reportDiagnostics: true,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2020,
+        jsx: ts.JsxEmit.Preserve,
+      },
+    }).diagnostics ?? []
+  );
+};
+
+const asLineNumber = (input: { source: string; at: number }): number =>
+  input.source.slice(0, input.at).split('\n').length;
+
+/**
+ * .what = every multi-line jsdoc in one template whose closing delimiter lands mid-line instead
+ *         of on a line of its own.
+ * .why  = the house jsdoc shape closes on its own line, always. a close anywhere else on a
+ *         multi-line block means the comment ended somewhere its author did not intend — which is
+ *         exactly what a glob or an arn in the prose does.
+ * .note = only a jsdoc that OPENS a line counts. the same opener sequence mid-line is almost
+ *         always a glob inside a string literal, and to read that as a comment would red on a
+ *         non-defect. a single-line jsdoc is left to the parse case, which sees its tail as code.
+ */
+const getAllJsdocSelfCloses = (input: {
+  path: string;
+  source: string;
+}): string[] =>
+  [...input.source.matchAll(/^[ \t]*\/\*\*/gm)].flatMap((opener) => {
+    const openAt = opener.index ?? 0;
+    // search from the final asterisk of the opener, so an empty block closes where it really does
+    const closeAt = input.source.indexOf('*/', openAt + opener[0].length - 1);
+    if (closeAt === -1) return []; // unterminated — the parse case owns that
+    const openLine = asLineNumber({ source: input.source, at: openAt });
+    const closeLine = asLineNumber({ source: input.source, at: closeAt });
+    if (openLine === closeLine) return []; // single-line jsdoc — the parse case owns it
+    const prefix = input.source.slice(
+      input.source.lastIndexOf('\n', closeAt) + 1,
+      closeAt,
+    );
+    if (/^[ \t]*$/.test(prefix)) return []; // the house shape: the delimiter alone on its line
+    return [
+      `${relative(repoRoot, input.path)}:${closeLine} jsdoc opened at line ${openLine} closes mid-line after «${prefix.trimStart()}»`,
+    ];
+  });
+
+describe('every shipped ts template parses as valid typescript (#613)', () => {
+  const templates = getAllPathsUnderDir({
+    dir: practicesDir,
+    skip: PRACTICE_TREE_SKIP_DIRS,
+  })
+    .filter(isShippedTsTemplate)
+    .sort();
+
+  const sources = templates.map((path) => ({
+    path,
+    source: readFileSync(path, 'utf8'),
+  }));
+
+  given('[case0] the src/practices best-practice tree', () => {
+    when('[t0] the ts templates are walked', () => {
+      // guards against a vacuous green: a walk that found zero files would pass both cases below
+      then('at least one shipped ts template is found', () => {
+        expect(templates.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  given('[case1] every shipped ts template', () => {
+    when('[t0] each is handed to the typescript parser', () => {
+      then('none reports a syntactic error', () => {
+        const offenders = sources.flatMap(getAllParseErrors);
+        expect(offenders).toEqual([]);
+      });
+    });
+  });
+
+  given('[case3] a declaration-file template (no emit, so no transpile)', () => {
+    when('[t0] a valid ambient module is parsed', () => {
+      then('it reports no error, rather than throw "Output generation failed"', () => {
+        const offenders = getAllParseErrors({
+          path: '/virtual/ok.d.ts',
+          source: "declare module 'x' {\n  export const y: number;\n}\n",
+        });
+        expect(offenders).toEqual([]);
+      });
+    });
+    when('[t1] a broken ambient module is parsed', () => {
+      then('the parser still reports its syntactic error', () => {
+        const offenders = getAllParseErrors({
+          path: '/virtual/broken.d.ts',
+          source: "declare module 'x' {\n  export const y: number\n",
+        });
+        expect(offenders.length).toBeGreaterThan(0);
+        expect(offenders.join('\n')).toContain("'}' expected");
+      });
+    });
+  });
+
+  given('[case2] every multi-line jsdoc inside a shipped ts template', () => {
+    when('[t0] each block comment is located', () => {
+      then('none closes itself mid-line', () => {
+        const offenders = sources.flatMap(getAllJsdocSelfCloses);
+        expect(offenders).toEqual([]);
+      });
+    });
+  });
+});

package/dist/huskyCommitMsgHook.declapract.integration.test.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import yaml from 'yaml';
+
+import { getAllPracticesForUsecase } from './utils/getAllPracticesForUsecase';
+
+/**
+ * .what = clamps the commit-message hook across every usecase: the `husky` practice ships
+ *         `.husky/commit-msg` + `.husky/check.commit.sh`, and every usecase that holds `husky`
+ *         resolves at least one practice that ships both.
+ * .why  = the commit-msg hook is a hard requirement — it is the one gate that holds every commit
+ *         to the conventional-commits shape the changelog and release version are derived from.
+ *         a dedupe that drops it from one practice without a home in another ships a repo whose
+ *         commits are never linted, and no apply reports the loss.
+ * .teeth = delete either file from `husky/best-practice/.husky/`, or unwire `check.commit.sh` from
+ *          `commit-msg`, and this reddens with the usecase named.
+ */
+
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+const usecasesYmlPath = join(repoRoot, 'src/useCases.yml');
+const HOOK_FILES = ['.husky/commit-msg', '.husky/check.commit.sh'] as const;
+
+/**
+ * .what = the hook files a practice ships from its best-practice dir
+ */
+const getHookFilesShipped = (input: { practice: string }): string[] =>
+  HOOK_FILES.filter((file) =>
+    existsSync(join(practicesDir, input.practice, 'best-practice', file)),
+  );
+
+describe('huskyCommitMsgHook', () => {
+  const usecases = Object.keys(
+    yaml.parse(readFileSync(usecasesYmlPath, 'utf8'))['use-cases'],
+  );
+  const usecasesWithHusky = usecases.filter((usecase) =>
+    getAllPracticesForUsecase({ usecasesYmlPath, usecase }).includes('husky'),
+  );
+
+  given('[case0] the husky practice, the owner of every .husky/ hook', () => {
+    then('it ships commit-msg and check.commit.sh', () => {
+      expect(getHookFilesShipped({ practice: 'husky' })).toEqual([...HOOK_FILES]);
+    });
+
+    then('commit-msg runs check.commit.sh, which runs commitlint on the message', () => {
+      const hookDir = join(practicesDir, 'husky/best-practice/.husky');
+      const commitMsg = readFileSync(join(hookDir, 'commit-msg'), 'utf8');
+      const checkCommit = readFileSync(join(hookDir, 'check.commit.sh'), 'utf8');
+      expect(commitMsg).toContain('/check.commit.sh"');
+      expect(checkCommit).toContain('commitlint --edit "$1"');
+    });
+  });
+
+  given('[case1] each usecase that holds husky', () => {
+    then('at least the core usecase holds it', () => {
+      expect(usecasesWithHusky).toContain('typescript-project-core');
+    });
+
+    when('[t0] its resolved practices are read', () => {
+      then('some practice ships both commit hook files', () => {
+        const offenses = usecasesWithHusky.flatMap((usecase) => {
+          const shipped = getAllPracticesForUsecase({ usecasesYmlPath, usecase })
+            .flatMap((practice) => getHookFilesShipped({ practice }));
+          return HOOK_FILES.filter((file) => !shipped.includes(file)).map(
+            (file) => `${usecase}: no practice ships ${file}`,
+          );
+        });
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});

package/dist/integrationApplyScopedOverRealSrc.declapract.integration.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = the argument text of each `<callee>(...)` call in a source, up to its balanced `)`
+ * .why  = the clamp asks of each call what it links or scopes; a balanced scan reads the whole
+ *         argument object, nested braces included, without a parser
+ */
+const getAllCallArgs = (input: { source: string; callee: string }): string[] =>
+  input.source
+    .split(`${input.callee}(`)
+    .slice(1)
+    .map((rest) => {
+      // scan for the `)` that closes this call: depth counts nested `(`, `at` locks the first match
+      const end = [...rest].reduce<{ depth: number; at: number | null }>(
+        (acc, char, index) => {
+          if (acc.at !== null) return acc;
+          if (char === '(') return { ...acc, depth: acc.depth + 1 };
+          if (char !== ')') return acc;
+          if (acc.depth === 0) return { ...acc, at: index };
+          return { ...acc, depth: acc.depth - 1 };
+        },
+        { depth: 0, at: null },
+      ).at;
+      return rest.slice(0, end ?? rest.length);
+    });
+
+/**
+ * .what = whether a genTempDir call mounts a link into this repo's src INSIDE the dir it makes
+ * .why  = a link into src — `src` itself, or a declarations mirror whose `practices/<p>` links back
+ *         to a real practice tree — is a write-through path only where an apply walks it. a mount
+ *         whose slug ends `-declarations` is a separate temp dir beside the applied repo (the
+ *         genTempRepoWithDeclarationsOutside convention), so no apply walks it
+ */
+const isTempDirWithSrcLinkInside = (input: { args: string }): boolean =>
+  /to:\s*'(\.\/)?src\b/.test(input.args) &&
+  !/slug:\s*[`'][^`']*-declarations[`']/.test(input.args);
+
+/**
+ * .what = clamps the write-through class: no integration test mounts a link into this repo's real
+ *         `src` inside a temp repo AND runs an `executeApply` that names no `file`
+ * .why  = an apply walks every path of the repo it applies to, links included, and a fix that
+ *         rewrites `**\/*.ts` writes through the link into this repo's own source.
+ *         old-acceptance-dir-location's test did exactly that: tests-any's `__test_utils__/` →
+ *         `.test.utils/` rewrite reached a fixture and a test file in src. scope each apply with
+ *         `file`, or mount the declarations outside the repo (genTempRepoWithDeclarationsOutside)
+ * .teeth = restore `symlink: [{ at: 'src', to: 'src' }]` in old-acceptance-dir-location's test and
+ *          drop its `file` scope; case1 reddens with that file named.
+ */
+describe('integrationApplyScopedOverRealSrc', () => {
+  const repoRoot = join(__dirname, '..');
+
+  given('[case1] every integration test under src/', () => {
+    when('[t0] each is read', () => {
+      then('none mounts a src link inside its repo and runs an apply with no file scope', () => {
+        const tests = getAllPathsUnderDir({
+          dir: join(repoRoot, 'src'),
+          skip: ['node_modules', '.test'],
+        }).filter((file) => file.endsWith('.integration.test.ts'));
+        expect(tests.length).toBeGreaterThan(10);
+        const offenses = tests
+          .filter((file) => file !== __filename) // this clamp names the pattern it hunts
+          .filter((file) => {
+            const source = readFileSync(file, 'utf8');
+            const linksSrcInside = getAllCallArgs({
+              source,
+              callee: 'genTempDir',
+            }).some((args) => isTempDirWithSrcLinkInside({ args }));
+            if (!linksSrcInside) return false;
+            // a helper that spreads its input is scoped only where that input REQUIRES `file`
+            const spreadIsScoped = /\bfile:\s*string\b/.test(source);
+            return getAllCallArgs({ source, callee: 'executeApply' }).some(
+              (args) => {
+                if (/\bfile\b/.test(args)) return false;
+                if (args.includes('...') && spreadIsScoped) return false;
+                return true;
+              },
+            );
+          })
+          .map((file) => relative(repoRoot, file));
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});

package/dist/integrationMountsDeclarationsOutsideSrc.declapract.integration.test.ts

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = the argument text of each `<callee>(...)` call in a source, up to its balanced `)`
+ * .why  = the clamp asks of each call what it mounts; a balanced scan reads the whole argument
+ *         object, nested braces included, without a parser
+ */
+const getAllCallArgs = (input: { source: string; callee: string }): string[] =>
+  input.source
+    .split(`${input.callee}(`)
+    .slice(1)
+    .map((rest) => {
+      // scan for the `)` that closes this call: depth counts nested `(`, `at` locks the first match
+      const end = [...rest].reduce<{ depth: number; at: number | null }>(
+        (acc, char, index) => {
+          if (acc.at !== null) return acc;
+          if (char === '(') return { ...acc, depth: acc.depth + 1 };
+          if (char !== ')') return acc;
+          if (acc.depth === 0) return { ...acc, at: index };
+          return { ...acc, depth: acc.depth - 1 };
+        },
+        { depth: 0, at: null },
+      ).at;
+      return rest.slice(0, end ?? rest.length);
+    });
+
+/**
+ * .what = whether a genTempDir call mounts this repo's `src` at the demo repo's own `src`
+ * .why  = that mount is the one shape that makes the demo repo's `src` BE this whole library
+ */
+const isTempDirWithSrcMountedAtSrc = (input: { args: string }): boolean =>
+  /at:\s*'src'\s*,\s*to:\s*'(\.\/)?src'/.test(input.args);
+
+/**
+ * .what = clamps the mount class: no integration test mounts this repo's `src` at the demo repo's
+ *         own `src`; the declarations mount at `declarations` instead
+ * .why  = a demo repo whose `src` IS this repo's src makes every `src/**` wildcard declaration scan
+ *         the whole library, so each apply runs minutes and times out under suite load
+ *         (legacy-change-id: 899s → 66s once re-mounted at `declarations`)
+ * .teeth = restore `symlink: [{ at: 'src', to: 'src' }]` in any one converted suite (e.g. logs) and
+ *          case1 reddens with that file named.
+ */
+describe('integrationMountsDeclarationsOutsideSrc', () => {
+  const repoRoot = join(__dirname, '..');
+
+  given('[case1] every integration test under src/', () => {
+    when('[t0] each is read', () => {
+      then('none mounts this repo src at the demo repo src', () => {
+        const tests = getAllPathsUnderDir({
+          dir: join(repoRoot, 'src'),
+          skip: ['node_modules', '.test'],
+        }).filter((file) => file.endsWith('.integration.test.ts'));
+        expect(tests.length).toBeGreaterThan(10);
+        const offenses = tests
+          .filter((file) => file !== __filename) // this clamp names the pattern it hunts
+          .filter((file) =>
+            getAllCallArgs({
+              source: readFileSync(file, 'utf8'),
+              callee: 'genTempDir',
+            }).some((args) => isTempDirWithSrcMountedAtSrc({ args })),
+          )
+          .map((file) => relative(repoRoot, file));
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});